XMLContent

From OpenCms Wiki
(Difference between revisions)
Jump to: navigation, search
m (minor fix)
(Simplify text, add missing widgets)
 
(15 intermediate revisions by 12 users not shown)
Line 10: Line 10:
 
* [[OpenCmsString]]
 
* [[OpenCmsString]]
 
* [[OpenCmsVfsFile]]
 
* [[OpenCmsVfsFile]]
 +
* [[OpenCmsVarLink]] (since 7.0.0)
  
== Widgets ==
+
== Editor Widgets ==
 
Widgets are used to create a suitable content editor for XML content. The widgets to be used are defined in the [[Defining OpenCMS structured XML content|XML Schema Definition]] of your XML content type.
 
Widgets are used to create a suitable content editor for XML content. The widgets to be used are defined in the [[Defining OpenCMS structured XML content|XML Schema Definition]] of your XML content type.
 +
 +
=== Default Widgets ===
 +
The following widgets are available on a standard OpenCms installation:
  
 
* [[BooleanWidget]]
 
* [[BooleanWidget]]
Line 18: Line 22:
 
* [[ComboWidget]]
 
* [[ComboWidget]]
 
* [[DateTimeWidget]]
 
* [[DateTimeWidget]]
 +
* [[DisplayWidget]]
 
* [[DownloadGalleryWidget]]
 
* [[DownloadGalleryWidget]]
 +
* [[GroupWidget]]
 
* [[HtmlGalleryWidget]]
 
* [[HtmlGalleryWidget]]
 
* [[HtmlWidget]]
 
* [[HtmlWidget]]
 
* [[ImageGalleryWidget]]
 
* [[ImageGalleryWidget]]
 
* [[LinkGalleryWidget]]
 
* [[LinkGalleryWidget]]
 +
* [[MultiSelectWidget]]
 
* [[SelectorWidget]]
 
* [[SelectorWidget]]
 
* [[StringWidget]]
 
* [[StringWidget]]
 +
* [[StringWidgetPlaintext]]
 
* [[TableGalleryWidget]]
 
* [[TableGalleryWidget]]
 
* [[TextareaWidget]]
 
* [[TextareaWidget]]
 +
* [[TextareaWidgetPlaintext]]
 +
* [[UserWidget]]
 
* [[VfsFileWidget]]
 
* [[VfsFileWidget]]
 +
 +
=== Gallery-widgets ===
 +
All gallery widgets have some common configuration options:
 +
 +
* [[GalleryWidgets]]
 +
 +
=== Custom Widgets ===
 +
When the existing widget types are not sufficient, one can create [[Custom Widgets]].
  
 
== Basic OpenCms XML Schema Definition (opencms-xmlcontent.xsd) ==
 
== Basic OpenCms XML Schema Definition (opencms-xmlcontent.xsd) ==
Line 87: Line 105:
 
             <xsd:restriction base="xsd:string">
 
             <xsd:restriction base="xsd:string">
 
                 <xsd:pattern
 
                 <xsd:pattern
                     value="[a-z]{2,3}(_[A-Z]{2}(_[a-zA-Z0-9]+){0,1}){0,1}" />
+
                     value="[a-z]{2,3}(_[A-Z]{2}(_[a-zA-Z0-9] ){0,1}){0,1}" />
 
             </xsd:restriction>
 
             </xsd:restriction>
 
         </xsd:simpleType>
 
         </xsd:simpleType>
Line 112: Line 130:
 
You can edit and validate your XMLContent Schema Definition files with an external XSD editor if you save the above listing to a file and add it to your editor's XML catalog.
 
You can edit and validate your XMLContent Schema Definition files with an external XSD editor if you save the above listing to a file and add it to your editor's XML catalog.
  
== Editing XML Schema Definitions with Eclipse WTP ==
+
As reported by Alexander Kandzior the above XSD can also be acquired at runtime:
This information is about [http://www.eclipse.org/webtools/ Eclipse Web Tools Platform] version 1.5.2 and above.
+
  
If you have Eclipse WTP installed, it contains a great XML Schema editor with XML formatting and content assistance. You can edit the XSD files for your XMLContent there. By default, the editor does not know how to resolve the location of the <tt>opencms-xmlcontent.xsd</tt> referenced in your XSD:
+
  org.opencms.xml.CmsXmlEntityResolver resolver =
 +
      new org.opencms.xml.CmsXmlEntityResolver(null);
 +
  org.xml.sax.InputSource source = resolver.resolveEntity(
 +
      null,
 +
      org.opencms.xml.CmsXmlContentDefinition.XSD_INCLUDE_OPENCMS);
 +
  byte[] bytes =
 +
      org.opencms.util.CmsFileUtil.readFully(source.getByteStream());
 +
  String xsd =
 +
      org.opencms.i18n.CmsEncoder.createString(bytes, "UTF-8");
 +
 
 +
== Mapping elements to properties ==
 +
 
 +
An element's value may be mapped to a <tt>property</tt> and/or <tt>attribute</tt>:
 +
<source lang="xml">
 +
<mappings>
 +
  <mapping element="Title" mapto="property:Title" />
 +
  <mapping element="Release" mapto="attribute:datereleased" />
 +
</mappings>
 +
</source>
 +
 
 +
When this mapping is applied to an element that has multiple occurences, the last item wins.
 +
 
 +
To map multiple values to a property, use <tt>propertyList</tt>. All values will be stored on the specified property, and separated by the pipe symbol (<tt>|</tt>):
 +
<source lang="xml">
 +
<mappings>
 +
  <mapping element="Category" mapto="propertyList:collector.categories" />
 +
</mappings>
 +
</source>
 +
 
 +
== Editing XML Schema Definitions with an IDE ==
 +
When you try to edit OpenCms XML Schema Definitions, by default, your editor will not know how to resolve the location of the <tt>opencms-xmlcontent.xsd</tt> referenced in your XSD:
  
 
  <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
 
  <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
  
It will display errors marks for the type attributes like <tt>type="OpenCmsString"</tt>.
+
It will display errors marks for the type attributes like <tt>type="OpenCmsString"</tt>. To allow your editor to properly validate on the <tt>opencms-xmlcontent.xsd</tt> Schema, you will first have to create a version of this file in some location you can access. The contents of this file can be found in an [[XMLContent#Basic_OpenCms_XML_Schema_Definition_.28opencms-xmlcontent.xsd.29|above section]]. Following this, you will have to create a reference to this file in your IDE's settings.
  
To add the Schema to the editor you must first obtain the basic OpenCms XSD file, opencms-xmlcontent.xsd, as detailed in an above section.
+
=== Editing with Eclipse WTP ===
 +
This information is about [http://www.eclipse.org/webtools/ Eclipse Web Tools Platform] version 1.5.2 and above.
  
After that, modify the XML Catalog preferences in Eclipse. Open <em>Window/Preferences/Web and XML/XML Catalog</em>.
+
If you have Eclipse WTP installed, it contains a great XML Schema editor with XML formatting and content assistance. You can edit the XSD files for your XMLContent there. To add the <tt>opencms-xmlcontent.xsd</tt> Schema to the editor, modify the XML Catalog preferences in Eclipse. Open <em>Window/Preferences/Web and XML/XML Catalog</em>.
 
Add a new <em>User Specified Entry</em>. For the <em>URI</em> select the location where you store the <tt>opencms-xmlcontent.xsd</tt> file. Select a <em>Key Type</em> of "Schema Location" and enter "opencms://opencms-xmlcontent.xsd" for the <em>Key</em> value.  
 
Add a new <em>User Specified Entry</em>. For the <em>URI</em> select the location where you store the <tt>opencms-xmlcontent.xsd</tt> file. Select a <em>Key Type</em> of "Schema Location" and enter "opencms://opencms-xmlcontent.xsd" for the <em>Key</em> value.  
  
 
Now, you should be able to edit files without seeing the error marks.
 
Now, you should be able to edit files without seeing the error marks.
  
== External Links ==
+
=== Editing with IntelliJ IDEA ===
[http://www.opencms-forum.de/opencms-forum/viewthread?thread=625#1740 Creating XML Content Definitions]
+
These steps will work for IntelliJ IDEA 5.1.2 and above.
  
[http://www.opencms-forum.de/opencms-forum/viewthread?thread=1912 Extend Edit Options for HtmlWidget]
+
To add the <tt>opencms-xmlcontent.xsd</tt> Schema to the editor, go to <em>File/Settings/</em> then under your IDE settings (so not your Project settings) select <em>Resources</em>. In the Resources dialog, add a new external resource under the <em>Configure External Resources</em> section by clicking the <em>Add...</em> button. In the dialog box that pops up, enter <tt>opencms://opencms-xmlcontent.xsd</tt> as the <em>URI</em> and the path to your opencms-xmlcontent.xsd file as the <em>Path</em> and click Ok. Exit all the menus by clicking Ok.
  
[http://www.wdogsystems.com/opencms/opencms/demos/structured_content_editing.html Nice visual Tutorial for XML Content]
+
Your XML Content Schemas should now correctly validate against the opencms-xmlcontent.xsd Schema.

Latest revision as of 14:58, 24 October 2016

Contents

Data Types

When creating XML contents, different data types can be used according to the requirements of the desired content. To each data type, a default widget is mapped which creates the input element (e.g. a text input field) for the form based XML content editor.

OpenCms provides the following data types for XML contents:

Editor Widgets

Widgets are used to create a suitable content editor for XML content. The widgets to be used are defined in the XML Schema Definition of your XML content type.

Default Widgets

The following widgets are available on a standard OpenCms installation:

Gallery-widgets

All gallery widgets have some common configuration options:

Custom Widgets

When the existing widget types are not sufficient, one can create Custom Widgets.

Basic OpenCms XML Schema Definition (opencms-xmlcontent.xsd)

Below you find a copy of the basic XML Schema used by all XMLContent Schemas you define. It is referenced by your custom XMLContent Schema Definition files like this:

<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>

The OpenCms XML system has a custom schema location resolver which knows what to return when this schemaLocation is referenced.

This file actually does not to exist physically in the OpenCms distribution. However, someone found out what it should look like. (See this opencms-dev thread for more information).

   <?xml version="1.0" encoding="UTF-8"?>
   <xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
       elementFormDefault="qualified">
       <xsd:complexType name="OpenCmsHtml">
           <xsd:sequence>
               <xsd:element name="links" type="OpenCmsLinkTable" />
               <xsd:element name="content" type="OpenCmsHtmlContent" />
           </xsd:sequence>
           <xsd:attribute name="name" type="xsd:string" use="optional" />
           <xsd:attribute name="enabled" type="xsd:boolean" use="optional" />
       </xsd:complexType>
       <xsd:complexType name="OpenCmsHtmlContent">
           <xsd:simpleContent>
               <xsd:extension base="xsd:string">
                   <xsd:attribute name="enabled" type="xsd:string"
                       use="optional" />
               </xsd:extension>
           </xsd:simpleContent>
       </xsd:complexType>
       <xsd:complexType name="OpenCmsLinkTable">
           <xsd:sequence>
               <xsd:element name="link" type="OpenCmsLink" minOccurs="0"
                   maxOccurs="unbounded" />
           </xsd:sequence>
       </xsd:complexType>
       <xsd:complexType name="OpenCmsLink">
           <xsd:sequence>
               <xsd:element name="target" type="xsd:string" />
               <xsd:element name="anchor" type="xsd:string" minOccurs="0" />
               <xsd:element name="query" type="xsd:string" minOccurs="0" />
           </xsd:sequence>
           <xsd:attribute name="name" type="xsd:string" use="required" />
           <xsd:attribute name="type" type="OpenCmsLinkType"
               use="required" />
           <xsd:attribute name="internal" type="xsd:boolean"
               use="required" />
       </xsd:complexType>
       <xsd:simpleType name="OpenCmsLinkType">
           <xsd:restriction base="xsd:string">
               <xsd:enumeration value="A" />
               <xsd:enumeration value="IMG" />
           </xsd:restriction>
       </xsd:simpleType>
       <xsd:simpleType name="OpenCmsLocale">
           <xsd:restriction base="xsd:string">
               <xsd:pattern
                   value="[a-z]{2,3}(_[A-Z]{2}(_[a-zA-Z0-9] ){0,1}){0,1}" />
           </xsd:restriction>
       </xsd:simpleType>
       <xsd:simpleType name="OpenCmsDateTime">
           <xsd:restriction base="xsd:decimal" />
       </xsd:simpleType>
       <xsd:simpleType name="OpenCmsString">
           <xsd:restriction base="xsd:string" />
       </xsd:simpleType>
       <xsd:simpleType name="OpenCmsVfsFile">
           <xsd:restriction base="xsd:string" />
       </xsd:simpleType>
       <xsd:simpleType name="OpenCmsBoolean">
           <xsd:restriction base="xsd:boolean" />
       </xsd:simpleType>
       <xsd:simpleType name="OpenCmsColor">
           <xsd:restriction base="xsd:string">
               <xsd:pattern
                   value="#([a-f]|[A-F]|[0-9]){3}(([a-f]|[A-F]|[0-9]){3})?" />
           </xsd:restriction>
       </xsd:simpleType>
   </xsd:schema>

You can edit and validate your XMLContent Schema Definition files with an external XSD editor if you save the above listing to a file and add it to your editor's XML catalog.

As reported by Alexander Kandzior the above XSD can also be acquired at runtime:

 org.opencms.xml.CmsXmlEntityResolver resolver = 
     new org.opencms.xml.CmsXmlEntityResolver(null);
 org.xml.sax.InputSource source = resolver.resolveEntity(
     null,
     org.opencms.xml.CmsXmlContentDefinition.XSD_INCLUDE_OPENCMS);
 byte[] bytes = 
     org.opencms.util.CmsFileUtil.readFully(source.getByteStream());
 String xsd = 
     org.opencms.i18n.CmsEncoder.createString(bytes, "UTF-8");

Mapping elements to properties

An element's value may be mapped to a property and/or attribute:

<mappings>
  <mapping element="Title" mapto="property:Title" />
  <mapping element="Release" mapto="attribute:datereleased" />
</mappings>

When this mapping is applied to an element that has multiple occurences, the last item wins.

To map multiple values to a property, use propertyList. All values will be stored on the specified property, and separated by the pipe symbol (|):

<mappings>
  <mapping element="Category" mapto="propertyList:collector.categories" />
</mappings>

Editing XML Schema Definitions with an IDE

When you try to edit OpenCms XML Schema Definitions, by default, your editor will not know how to resolve the location of the opencms-xmlcontent.xsd referenced in your XSD:

<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>

It will display errors marks for the type attributes like type="OpenCmsString". To allow your editor to properly validate on the opencms-xmlcontent.xsd Schema, you will first have to create a version of this file in some location you can access. The contents of this file can be found in an above section. Following this, you will have to create a reference to this file in your IDE's settings.

Editing with Eclipse WTP

This information is about Eclipse Web Tools Platform version 1.5.2 and above.

If you have Eclipse WTP installed, it contains a great XML Schema editor with XML formatting and content assistance. You can edit the XSD files for your XMLContent there. To add the opencms-xmlcontent.xsd Schema to the editor, modify the XML Catalog preferences in Eclipse. Open Window/Preferences/Web and XML/XML Catalog. Add a new User Specified Entry. For the URI select the location where you store the opencms-xmlcontent.xsd file. Select a Key Type of "Schema Location" and enter "opencms://opencms-xmlcontent.xsd" for the Key value.

Now, you should be able to edit files without seeing the error marks.

Editing with IntelliJ IDEA

These steps will work for IntelliJ IDEA 5.1.2 and above.

To add the opencms-xmlcontent.xsd Schema to the editor, go to File/Settings/ then under your IDE settings (so not your Project settings) select Resources. In the Resources dialog, add a new external resource under the Configure External Resources section by clicking the Add... button. In the dialog box that pops up, enter opencms://opencms-xmlcontent.xsd as the URI and the path to your opencms-xmlcontent.xsd file as the Path and click Ok. Exit all the menus by clicking Ok.

Your XML Content Schemas should now correctly validate against the opencms-xmlcontent.xsd Schema.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox