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
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:element name="RedStarArticles" type="OpenCmsRedStarArticles"/>
type="OpenCmsRedStarArticle" minOccurs="0" maxOccurs="unbounded"/>
<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:attribute name="language" type="OpenCmsLocale" use="required"/>
<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" />
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:
- Modify the opencms-modules.xml file.
- Provide language translations and icons for display in the workplace
- 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
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
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
<explorertype name="redstararticle" key="fileicon.redstararticle"
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.
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
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.
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.
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.