Creating your own OpenCms document types

In OpenCms, you usualy create your content documents in the workplace. You choose the type of content you want to create, E.g. a 'Page with free text' or an 'Article' (a subtype of 'Structured content'). The subtypes of 'Structured content' are meant for documents with structured information. E.g. the subtype 'Article' contains the following fields: title, teaser text, article text, release date and author. In the JSP template that you write to show an Article, you can address the fields individually and show them on the webpage. In this article I will discuss how you can create and use your own subtype of 'Structured content'.

Registering document types

Document types must be registered with OpenCms before they can be used by a content editor. You can register them either on system level or on module level. You define them in the OpenCms configuration files (opencms-vfs.xml to define them on system level and opencms-modules.xml to define them on module level) or you can add them dynamically through an Action class. The Action class can only be used to define document types on module level. However, creating document types dynamically falls outside the scope of this article.

In general, it is never a good idea to define your document types on system level. When you upgrade your OpenCms to a new release, the opencms-vfs.xml will be overwritten and your custom document types will be vanished. Also when you export your module, your document types defined on system level will not be included in the export file, making your module less portable.

The development work in this article will make use of the info.rsdev.template module that was created in a previous article called " Create your own module".

Define your custom document types through opencms-modules.xml

In this article I will show you how to add your custom document type through the OpenCms configuration files. The document type we will add is a document type called 'RedStarArticle'. It is a specification of the build in XmlContent document type. The XmlContent document type is probably the most obvious candidate to pick as a base document type for defining your own type.

In the schema below you find the definition of the RedStarArticle document structure. The xsd file will be stored in the schemas folder of our info.rsdev.template module.

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
<xsd:include schemaLocation="opencms://opencms-xmlcontent.xsd"/>
<xsd:element name="RedStarArticles" type="OpenCmsRedStarArticles"/>
<xsd:complexType name="OpenCmsRedStarArticles">
<xsd:sequence>
<xsd:element name="RedStarArticle"
type="OpenCmsRedStarArticle" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="OpenCmsRedStarArticle">
<xsd:sequence>
<xsd:element name="Author" type="OpenCmsString" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="Date" type="OpenCmsDateTime" minOccurs="1" maxOccurs="1"/>
<xsd:element name="MultiPage" type="OpenCmsBoolean" minOccurs="1" maxOccurs="1"/>
<xsd:element name="ShowIndex" type="OpenCmsBoolean" minOccurs="1" maxOccurs="1"/>
<xsd:element name="Title" type="OpenCmsString" minOccurs="0" maxOccurs="1"/>
<xsd:element name="NavigationText" type="OpenCmsString" minOccurs="0" maxOccurs="1"/>
<xsd:element name="Summary" type="OpenCmsHtml" minOccurs="0" maxOccurs="1"/>
<xsd:element name="Chapter" type="OpenCmsHtml" minOccurs="1" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="language" type="OpenCmsLocale" use="required"/>
</xsd:complexType>
<xsd:annotation>
<xsd:appinfo>
<layouts>
<layout element="Summary" widget="HtmlWidget"
configuration="source, link, anchor, formatselect, imagegallery, downloadgallery,
linkgallery, htmlgallery, tablegallery, height:200px" />
<layout element="Chapter" widget="HtmlWidget"
configuration="source, link, anchor, formatselect, imagegallery, downloadgallery,
linkgallery, htmlgallery, tablegallery, height:300px" />
</layouts>
</xsd:appinfo>
</xsd:annotation>
</xsd:schema>

In a XmlContent document schema, you can only define one new element type. In the schema above, this is the RedStarArticle element. The elements that it is made up of, are all build-in elements defined by OpenCms. Although our schema includes the opencms-xmlcontent.xsd schema, there is no such file. The opencms-xmlcontent.xsd schema is defined in Java code in the class org.opencms.xml.CmsXmlContentDefinition and not in a schema file.

When you need nested document types, that is, define more than one element in an XmlContent document type schema definition, then you must create a separate file for each element and place an xsd:include reference at the top of your schema definition. However, nested schemas fall outside the scope of this document.

For our RedStarArticle document type to be available through the new document wizard in the workplace, we must take the following steps:

  1. Modify the opencms-modules.xml file.
  2. Provide language translations and icons for display in the workplace
  3. Define export points and module resources for the resources that are specific for our document type, such as the file icon and properties files and then publish the module.

Modify opencms-modules.xml file

First we will modify the opencms-modules.xml configuration file. This file contains everything about all your installed modules. Open the file with your favorite text editor and browse through the file to locate our module info.rsdev.template that we created in a previous article. Position the cursor after the empty parameter element and insert the resourcetypes-element as displayed below.

<parameters/>
<resourcetypes>
  <type class="org.opencms.file.types.CmsResourceTypeXmlContent" name="redstararticle" id="301">
    <properties />
    <param name="schema">
      /system/modules/info.rsdev.template/schemas/article.xsd
    </param>
  </type>
</resourcetypes>
</module>

In the xml snippet above, we register our RedStarArticle as a new type to OpenCms. We tell OpenCms to use the CmsResourceTypeXmlContent class when creating a new RedStarArticle document. The type will be known by OpenCms with type name redstararticle and will have a typeid of 301. Both type name as well as typeid must be unique. The chances that the name will be used in some other module is smaller when we put our name into it. However, sometimes the typeid can be used by another module. So you have to take care when choosing that id.

The param only has meaning to the type class implementation. In our case, the class (CmsResourceTypeXmlContent) expects to be passed on the location of the schema for our document type.

Now OpenCms knows about our custom document type, but in order to use the new document wizard in the workplace to create RedStarArticles, we need to add a little more information to the opencms-modules.xml configuration document directly under the resourcetypes element we just added. Below you find an xml snippet with all the necessary modifications to the modules configuration document.

<parameters/>
<resourcetypes>
  <type class="org.opencms.file.types.CmsResourceTypeXmlContent" name="redstararticle" id="301">
    <properties />
    <param name="schema">
      /system/modules/info.rsdev.template/schemas/article.xsd
    </param>
  </type>
</resourcetypes>
<explorertypes>
  <explorertype name="redstararticle" key="fileicon.redstararticle" icon="redstararticle.png" reference="xmlcontent">
    <newresource page="structurecontent" uri="newresource_xmlcontent.jsp?newresourcetype=redstararticle" order="301" autosetnavigation="false" autosettitle="false"/>
    <accesscontrol>
      <accessentry principal="GROUP.Administrators" permissions="+r+v+w+c"/>
      <accessentry principal="GROUP.Projectmanagers" permissions="+r+v+w+c"/>
      <accessentry principal="GROUP.Users" permissions="+r+v+w+c"/>
    </accesscontrol>
  </explorertype>
</explorertypes>
</module>

The explorertype maps to the resourcetype by name, i.c. redstararticle. The key-attribute of the explorertype refers to a key in a properties file that we will create next. This properties file will provide the description in the new document wizard to the workplace. This mechanism utilizes the standard Java localization mechanism of property resource bundles. You can easily provide translations for different languages. The page-attribute of the newresource-element will show our RedStarArticle as a sub item of 'Structured content' in the new document wizard. When you want to show your document type directly in the first page of the new document wizard, all you have to do is to leave out the page-attribute.

Add resources

Now I must create the resources that I defined in the modules configuration file. They are: the redstararticle.png and the localizations.

I will create them in the resources folder of the info.rsdev.template module and then create export points to export them to the places where OpenCms expects them.

To keep my stuff organized, I create a propertyfiles sub folder in the resources folder. I create a new text file in the propertyfiles folder called workplace.properties. You can not make up your own filename for the properties file, because OpenCms will be looking for a workplace.properties file. The content of the workplace.properties file consists of one line (for now):

fileicon.redstararticle=Red Star Article

Then I copy this file (or better: create a sibling to this file) to workplace_en.properties to provide for the English translation (ergo: the default language of my module is English, because the default template contains English translations). You can create additional files to provide more translations to the workplace.

Now we need to create the necessary export point in the Administration view of the workplace. Go to Module Management and open our module by clicking on the info.rsdev.template module. Then click on the icon Module exportpoints | New exportpoint. Add the property files folder to the exportpoints. They must be exported to a sub folder in the WEB-INF/classes folder. The sub folder is the path of your module name. In our case, our module is called info.rsdev.template, so then the sub folder must be WEB-INF/classes/info/ rsdev/template/. The trailing slash in the destination path is important! See next screenshot.
NewExportpoint
We need to publish the module in order to place the properties files in the WEB-INF/classes directory of our web container. Only then, OpenCms will pick up our resource descriptions in the various languages. Switch to the Explorer view, browse to the folder /system/modules and choose 'Publish directly' from the pop up menu after right clicking on the info.rsdev.template folder to export our properties files to the WEB-INF/classes folder.

Finally, we need to upload our redstararticle.png icon and place it in the vfs folder /system/workplace/resources/filetypes, because this is where the workplace expects to find our icon. So, unfortunately it is not possible to keep all resources within our module, but we can define a Module resource that points to our icon file. This will include our resource when we export the module and install it on another OpenCms server. See the following screenshot.
NewModuleResources
This concludes this article on creating your own document type. If you have any comments, please send them to me by e-mail. Your comment will influence the existence of future articles.