OpenCms has a clear concept of content and a strict separation of content and layout. We explain the concept of content and the OpenCms idea of how to get content into web pages.

Particular interesting questions are:

  • What is a content and how is it defined?
  • How is HTML produced from a content?
  • How is content placed on a web page?
  • Where is content stored?

The short story

A content in OpenCms is an XML file with a special structure. This structure is defined by the content's type definition, an XML Schema definition (XSD). You are free to define your own content types and add contents of these types.

Contents are rendered to HTML via, so called "formatters". A formatter is a Java Server Page (JSP) where you access the content and use it's elements to produce the HTML output. For each type several formatters can exist. They are "glued" the type by a formatter configuration that also describes in which situations a formatter should be used.

Web pages in OpenCms are typically container pages and containers are filled with contents. A container is a "hole" in the HTML page where content can be inserted. The container page keeps information about which content is placed in which container. Furthermore, for each content, it stores the link to the formatter that is used to render it.

The layout of the web page and the containers on the page are specified by container page templates. These templates are JSPs that build the "frame" of the page and define at which position a container is placed. When a web page in OpenCms is loaded, i.e., a container page is requested, the template that is configured for the page is rendered and each container in the template the content that should be placed in this hole is filled in. To fill content in, it is looked up in the container page which content is placed in the container and which formatter should be used for it. Then the content is rendered with the specified formatter and the produced HTML is inserted in the HTML structure produced by the template.

Why XML and typed content?

In OpenCms each content has a type. A type defines the structure of the content. Hence, for each content this structure is known when accessing it. OpenCms uses XML to structure content and XSDs to define content types. This has various advantages:

  • For each content, it is very clear how to access it. XML is widely used and known.
  • An editor for the content can be generated automatically based on the content's XML structure.
  • Content of different types can be handled differently when loading or storing contents of this type.
  • Each content you can think of naturally has a structure. XSDs provide an easy and powerful way to mirror that structure. Thus it is easy to define a type (exactly) mirroring structures.

Where are content types and formatters defined?

The design of content types strongly depends on your website. You may, for example, set up a web shop and therefore design a content that holds all the information for a single item you sale. You may like to set up kind of a blog and capture each blog entry in a single content, saving a title of the entry, the text written, the author, the creation date and maybe even more information. Potentially also optional information.

Since the suitability of a content type really depends on the web site you want to build, you will not find "your" type definitions shipped with OpenCms. But OpenCms offers the suitable place for them: You can place the stuff that is specific to your web site(s) in separate modules. Modules can be exported and imported in OpenCms and add new functionality - for example new content types. Typically content type definitions are placed in the VFS folder /system/modules/{the module's name}/schemas. Look up for the content defintions in the demo modules for example.

Even more individual than the content types are the formatters for the types. They will necessarily depend on the layout of your web site. While type definitions may be useful for various different websites, e.g., for different web shops. The formatters typically fit only for a single page. As the type definitions, also the formatters are placed in modules. It is a matter of taste, if you place formatters and type definitions in the same module or not. What is good practice is to place them in a module sub-folder named formatters, i.e., in /system/modules/{the module's name}/formatters, and to accompany them with a configuration.

How are content types known to the system?

Up to now, we hid a small but quite important detail. There is a second point in placing content type definitions in modules. An XSD makes up a content type definition, but not a type as you use it in OpenCms. The content type must be configured as resource and explorer type to become visible in OpenCms. For example, a content type is only visible in the "Add wizard" that is used to add new content, if it is configured as resource and explorer type.

The subtle distinction between content, resource and explorer type is necessary for mainly two reasons:

  • First, not each content type definition should make up a new type that is exposed in OpenCms. Sometimes content type defintions are only used nested in other definitions.
  • Second, the raw type defintion lacks some extra information that is necessary or at least useful. E.g., the type has no icon, no nice-name, etc. Resource and explorer type configurations add those informations. At the moment it is not necessary to distinguish the two configurations.

The most important information added by the type configurations are a unique type id and a unique name. These will be used by OpenCms to refer to a type.

In most cases it is not necessary to distinguish between content, resource and explorer type. Thus, we will simply say "type" and mean a content type that is configured as resource and explorer type. The type's name, id, etc. refers always to the values configured in the resource or explorer type configuration.

Where are contents stored?

Contents do not belong to a single web page. They may be placed on several pages and potentially on every single page of your site. Sometimes it is preferable to place them only on pages in a specific sub-site. Sometimes you may want to share them between different web sites.

OpenCms stores content usually in the web site. The site's main folder contains a special sub-folder named .content/. Content of different type is typically placed in separate sub-folders of .content/. For example, if there exists a type "article", there might be a folder .content/article/ where all the "article" contents are stored.

To attach content to sub-sites of your main site. If you create a sub-sitemap for the sub site in OpenCms, this sub-site's main folder will have a .content/ sub-folder as well. Here, content that is somehow specific to the sub-site can be placed

Last but not least, if you run more than one web site with a single OpenCms installation and you want to share content between differnt sites, you can store content in the shared/ folder in the root site.

Where you store content on your site is configurable. Also which contents are accessible in which sub-site. Your content may be placed at several of the locations mentioned above.

Independent of the folder where content is stored, the name given to a content file is an important issue. Content is usually created by dragging it on a web page. Hence, the file where the content is stored has to be created and named automatically. OpenCms names content files by the following scheme: {type name}_{number}.xml. The number is chosen automatically, such that it is unique in the folder where the file is stored. Prefix and suffix can be configured, if wanted.

If you look up a file that stores a content, have a look at it's type: The file has the type of content. Or, more precisely, the configured resource type.