Defining content fields by XSD elements

In this chapter we discuss how you can define your individual content fields in an content schema document. In essence, this is done by the XSD elements of the schema type. Such elements themselves can:

be optional
appear more than once
be of a complex type that makes up a nested content
provide an alternative of several different elements

In the end, each "leave" in the content's structure must be of a basic schema type that is provided by OpenCms.

General structure of a schema type

The general structure of an XSD content definition always is of type <xsd:sequence> followed by a language attribute. This means, that the fields of an XML content are always stored in the order they are defined in the XSD sequence and also in the Form editor appear in this order. Above that, XML contents are prepared to be multilingual:

<xsd:complexType name="OpenCmsBootstrapBlog">
    <xsd:sequence>
        <xsd:element name="Title" type="OpenCmsString" />
        <xsd:element name="Date" type="OpenCmsDateTime" />
        <xsd:element name="Teaser" type="OpenCmsString" minOccurs="0" />
        <xsd:element name="Paragraph" type="OpenCmsBootstrapParagraph" maxOccurs="5" />
        <xsd:element name="Category" type="OpenCmsDynamicCategory" minOccurs="0" />
        <xsd:element name="Author" type="OpenCmsString" />
        <xsd:element name="AuthorMail" type="OpenCmsString" minOccurs="0" />
        <xsd:element name="Availability" type="OpenCmsBootstrapAvailability" minOccurs="0" />
    </xsd:sequence>
    <xsd:attribute name="language" type="OpenCmsLocale" use="required" />
</xsd:complexType>

Each schema element has a name and a type attribute, optionally minOccurs and maxOccurs can be set. If not given, minOccurs and maxOccurs default to 1.

By setting minOccurs and maxOccurs, you can make schema elements optional or allow them to occur multiple times:

Setting minOccurs="0" makes a schema element optional in any XML content that complies with the schema.
Setting minOccurs="{minNum}" and maxOccurs="{maxNum}" specifies that the schema element must occur at least {minNum} times and at most {maxNum} times in any XML content that complies with the schema. Thus you can allow or force multiple occurrences of schema elements in sequence.

The types set in the type attribute of the <xsd:element> nodes must be defined when they are used. Allowed types are:

Schema types provided by OpenCms and included in the XSD via <xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/> in your XSD (see here). These types are so-called basic schema types. They store content like HTML, Strings, Links, Images or Boolean values and for these types (several) special editor widgets exist.
Schema types for nested contents defined in other XSDs that satisfy the special structure required to specify content types. These types define sub-structures of the main content, also called nested contents. The schemas for nested contents must be included into your XSD if you want to use them.

In the above example, the schema defines that each content complying to the schema has:

A Title node with a value of type OpenCmsString followed by,
a Date node with a value of type OpenCmsTimeDate followed by,
an optional Teaser node (i.e., the node can also be missing) of type OpenCmsString followed by,
one up to five Paragraph nodes of type OpenCmsBootstrapParagraph, which is a nested content defined by another schema (i.e., which has sub-nodes as defined in the separate schema) followed by,
an optional Category node of type OpenCmsCategory followed by,
and more

Here's how a content that complies to the above structure can look like:

<?xml version="1.0" encoding="UTF-8"?>

<BootstrapBlogs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="opencms://system/modules/com.alkacon.bootstrap.schemas/schemas/blog.xsd">
<BootstrapBlog language="en">
<Title><![CDATA[OpenCms is intuitive]]></Title>
    <Date>1400763600000</Date>
    <Paragraph>
      <Text name="Text0">
        <links/>
        <content><![CDATA[<p>At vero eos ...</p>]]></content>
      </Text>
      <Image>
        <Image>
          <link type="WEAK">
            <target><![CDATA[/sites/default/.galleries/samples/11.jpg]]></target>
            <uuid>c6d9d552-4705-11e3-8417-000c29d28104</uuid>
          </link>
        </Image>
        <Title><![CDATA[Vanilla]]></Title>
      </Image>
    </Paragraph>
    <Author><![CDATA[Jay Pritchett]]></Author>
  </BootstrapBlog>
</BootstrapBlogs>

The interesting part is wrapped in the <BootrapBlog language="en"> node. The surrounding structure is caused by the multi-language support. In the example we have the following schema element sequence:

Title
Date
Paragraph
Author

This is kind of the minimal sequence we can have. All optional schema elements are missing and each element that could occur more than once doesn't. Note that the Paragraph node has many subnodes as defined in the schema of the nested content (that is not given here).

Schemas for nested contents

In schemas that define the structure of nested contents, the part defining the nested content's structure can look very similar to that schema part for root contents. The only differences are:

In the language attribute, required should be set to optional.
Instead of <xsd:sequence> you can use <xsd:choice> to define alternative nodes. Read more about alternatives here.

Available basic schema types

OpenCms provides a set of basic schema types that are exposed via the opencms-xmlcontent.xsd. All of your leave elements have to be of such a basic schema type. These schema types are used to store atomic data. Some of the basic types have an internal structure, but when using them in the system, they behave like an atomic unit. There are types for strings, booleans, dates, but also for links, images, categories, etc. Here's a list of the available basic schema types.

The basic schema types

OpenCmsBoolean: Stores a Boolean value, i.e., true or false.
OpenCmsDynamicCategory: Stores multiple categories
OpenCmsColor: Stores a color value
OpenCmsHtml: Stores strings with HTML markup. In particular, it extracts links in HTML and adjusts (internal) links with the link substitution manager, such that for example also exported VFS resources are found. Furthermore, for links to VFS resources the link relationship engine is used - thus they are also correctly found when they moved.
OpenCmsLocale: Stores the name of a locale, e.g., "en" or "de".
OpenCmsPlainTextString: Stores arbitrary strings and stripes away HTML markup when indexing the value for search.
OpenCmsString: Stores arbitrary strings and does not further manipulate them.
OpenCmsDateTime: Stores a time stamp as long int.
OpenCmsVarLink: Stores internal and external links.
OpenCmsVfsFile: Stores links to VFS resources, i.e., internal links.
OpenCmsVfsImage: Stores links to an image and serveral extra information on the image. It is not necessary to use this type for images - unless you want all the extra information. You can also use OpenCmsVfsFile. Check the description of the image widgets (VfsImageWidget and ImageGalleryWidget) for further information.

For the basic schema types various special editor widgets exist. Check out which widgets support which types.