In OpenCms contents are stored as XML files. Thus, the structure of a content of specific type, but also much of its behavior, is specified in an XML schema definition (XSD). Those XSDs themselves must comply to a special structure. In this topic you learn about the general structure of such schemas and learn how to create a new schema in OpenCms.
The structure of content types and much of the type's behavior is specified via XML schema definitions (XSDs). In general, an XSD specifies the structure of an XML document, but it usually also has to comply with a predefined structure. The XSDs that are used to define a content type must comply to such a specific structure.
Here is a very simple example XSD defining a schema for a content type:
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<!-- Include schema definitions -->
<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
<!-- Add includes for nested contents here -->
<!-- define the multi-language wrapper -->
<xsd:element name="SimpleExamples" type="OpenCmsSimpleExamples"/>
<xsd:complexType name="OpenCmsSimpleExamples">
<xsd:sequence>
<xsd:element name="SimpleExample" type="OpenCmsSimpleExample" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<!-- define the structure of the content for a single language -->
<xsd:complexType name="OpenCmsSimpleExample">
<xsd:sequence>
<xsd:element name="Title" type="OpenCmsString" />
<!-- add more elements -->
</xsd:sequence>
<xsd:attribute name="language" type="OpenCmsLocale" use="required"/>
</xsd:complexType>
<!-- configure the content's behavior (optional) -->
<xsd:annotation>
<xsd:appinfo>
<!-- place configuration here -->
<searchsettings containerPageOnly="true"/>
</xsd:appinfo>
</xsd:annotation>
</xsd:schema>
The schema definition for the content type includes various <xsd:element>
and <xsd:complexType>
nodes to define the structure of a content. The complex type that defines the structure of the content for one language, we call the schema type. In the above example, the schema type is named "SimpleExample". The structure of the schema type, and thus of the contents, is defined in the node <xsd:complexType name="OpenCmsSimpleExample">
. In the example, the content has just one (schema) element, named Title
.
The above schema definition has a second section wrapped in xsd:annotation/xsd:appinfo
. In this optional section, content specific behavior is specified. In the example, it is configured that the content should not be indexed for a search as its own, but it can be found in the index via the container pages where it is placed on.
The example highlights the basic structure of a schema definition for a content type. The whole definition is wrapped by the <xsd:schema>
node. This node is always the same for each content type definition. The attributes specify the namespace of the schema definition, i.e., which nodes are available and how they can be nested.
Inside the <xsd:schema>
node, the content type definition consists of four parts:
OpenCmsString
in the above example.<xsd:include schemaLocation="opencms://root/path/to/the/contentDefintion.xsd"/>
OpenCmsString
, i.e., an element that stores a string. Read more about the structure part here.Besides the special XML structure of the schema definition that is required for schemas that are used for content types, also the naming of elements and types has to comply to a certain scheme. It is best explained at the above example, where the schema type "SimpleType" is defined. In the description below, "SimpleType" can be replaced by any possible name you want give to your schema type. But the pre- and suffix parts are mandatory, as well as using the same schema type name at all the mentioned places in the schema.
The values of name and type attributes have to comply to the special name scheme at:
<xsd:element name="SimpleExamples" type="OpenCmsSimpleExamples"/>
name
attribute has to be {schema type}s
and the type
attribute OpenCms{schema type}s
.<xsd:complexType name="OpenCmsSimpleExamples">
<xsd:complexType>
node.<xsd:element name="SimpleExample" type="OpenCmsSimpleExample" minOccurs="0" maxOccurs="unbounded" />
name
attribute has to be {schema type name}
and the type
attribute OpenCms{schema type name}
. Also minOccurs
and maxOccurs
must always be given as in the example. Reading the schema from line 10 to 14, you can identify the "multi-language" wrapper: The lines say that we have zero or more (language specific) versions of a content stored.<xsd:complexType name="OpenCmsSimpleExample">
Use OpenCms{schema type name}
for the name
attribute here. In the node starting at line 17 you begin with the defintion of the content's structure for one language, i.e., with the definition of the type used for the elements defined in line 12.Schema definitions for content types are usually shipped with modules and placed in the module's subfolder named schemas/
. If you want to define a content type that should be exposed by a module, i.e., if you want to create contents of that type via the "Add wizard" of the page editor, than it is the easiest way to use the "Add resource type" function from the administration's "Module management". This will create a schema definition in the respective folder of your module (and does a lot more). To get the content type you want, just adjust the created example XSD.
If you want to add a new schema that should not make up a new content type then the XSD file can be added via the traditional workplace's explorer. Schemas that dp not directly make up a new content type are usually definitions of nested contents. Such schemas are by convention placed in the module's subfolder schemas/nested/
. XSDs are just text files (type plain). Click "New" and choose "Text file" in the explorer. Best practice is to copy the content of an existing XSD to your new file and adjust it to your needs.