The concept of content

A content item 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 content of these types.

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

Web pages in OpenCms are typically container pages and containers are filled with content. 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 item, 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 for 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.

In OpenCms all content has a type. A type defines the structure of the content. Hence, for each content item 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 item, 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 content of this type.
• Each content type 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.

The design of content types strongly depends on your website. You may, for example, set up a web shop and therefore design a content type that holds all the information for a single item you sell. You may like to set up a kind of blog and capture each blog entry in a single content item, saving the 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 a 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 the content definitions 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. Like the type definitions, the formatters are placed in modules. It is a matter of taste whether 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.

Up to now, we hid a small but quite important detail. There is another reason for placing content type definitions in modules. An XSD makes up a content type definition, but not a type as used in OpenCms. The content type must be configured as a 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 a resource and explorer type.

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

• First, not every 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 friendly name, etc. Resource and explorer type configurations add that information. 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.

Content items 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. Sometimes you really want to use them only on one page.

OpenCms stores content usually in a specific folder in the site. The site's main folder contains a special sub-folder named .content/. Content of different types 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.

You can also attach content to sub-sites of your main site. If you create a sub-sitemap for a 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.

If you run more than one web site with a single OpenCms installation and you want to share content between different sites, you can store content in the shared/ folder in the root site.

Last but not least, content can also be stored directly with a page. OpenCms will generate a .elements/ folder in the web page's folder where the content will be placed.

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.

• See how to configure where content is stored.

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 onto 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.

Content is rendered by so-called formatters. These are JSPs where the content is accessed to produce HTML snippets. Which formatter is used for which content and in which situation is specified by a formatter configuration. It links the formatter (JSP) and the type of content that should be rendered. Furthermore it specifies in which containers the formatter can be used. This is done by defining "Matches", either by the container's width or type attribute. Matching by types is preferrable.

• Learn more about formatters and their configuration.