XMLContent

Latest revision as of 14:58, 24 October 2016

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:

• OpenCmsBoolean
• OpenCmsColor
• OpenCmsDateTime
• OpenCmsHtml
• OpenCmsLocale
• OpenCmsString
• OpenCmsVfsFile
• OpenCmsVarLink (since 7.0.0)

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:

• BooleanWidget
• ColorpickerWidget
• ComboWidget
• DateTimeWidget
• DisplayWidget
• DownloadGalleryWidget
• GroupWidget
• HtmlGalleryWidget
• HtmlWidget
• ImageGalleryWidget
• LinkGalleryWidget
• MultiSelectWidget
• SelectorWidget
• StringWidget
• StringWidgetPlaintext
• TableGalleryWidget
• TextareaWidget
• TextareaWidgetPlaintext
• UserWidget
• 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)

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.