OpenCms documentation
OpenCms documentation

Detail pages

Content publication on websites often works with the idea of teasers and detail pages. Teasers present a content such as a news in a compact form and with a link that targets to a detail page.

The detail page not only presents a content in any detail but also under a SEO-optimised URL, where the content's title is part of the URL.

With OpenCms, detail pages need not being created manually for each and every content. It is sufficient to create a virtual detail page for a content type. If such a virtual detail page is configured, any newly created content is automatically accessible under a detail page that has a SEO-optimised URL.

Virtual detail pages have other advantages. For example, display options can be set centrally such that all contents of a specific type are uniformly formatted on their detail page.

Above that, detail pages often contain additional information. For example, a news detail page may additionally show a list of related news. Additional information can be configured on the virtual detail page as well and is then shown for any detail content.

Adding a detail page

Adding a new detail page is done via the sitemap editor.

  • Open the sitemap editor
  • In the sitemap editor, click on the wand icon to open the Create page dialog
  • Switch to the tab Detail pages
  • Choose a detail page from the list and drag and drop the detail page to the sitemap

The first detail page in the list is always the so called 'Default' type detail page. The default detail page is a generic fallback detail page that is used to display contents without a type-specific detail page configured.

The rest of the list depends on the detail pages configured within your website template. The screenshot below shows the detail pages as available in the Mercury template.

Adding a detail page to the sitemap
Hide a page in navigation

In most cases it is not intended for the virtual detail page to appear in the navigation of a website. This is since showing the detail page without a concrete content will only show a more or less empty page.

For this reason, it is recommended to hide the virtual detail page for navigation directly after creating it.

  • To do so, open the sitemap editor
  • Click on the burger menu icon of the newly created detail page 
  • In the context menu that opens, select the menu item Hide in navigation

Setting up the page

Opening a detail page

In order to check whether your newly added detail page is working as expected, open a content folder in the explorer, for example the folder /.content/m-article/. Click on the resource icon of an article content and in the context menu that opens, select the menu entry Display. If your detail page is configured correctly, a detail page should show up.

The URI of the detail page consists of the path of the virtual page plus the title of the content currently opened, for example /article/opencms-is-great/, where /article/ is the path of the virtual page, and /opencms-is-great/ is the article's title "OpenCms is great" automatically mapped and optimized for URLs by the detail page mechanisms.

If you open a detail page as just described, it is possible that the URL appears correctly, but the detail content is still not displayed on the page. This is since your website template possibly offers different places where exactly on the page the detail content is displayed.

If the detail content does not appear, you may first need to declare a container as the detail container. Whether this problem occurs, and how the problem can be solved, depends on the website template.

In the Mercury template, for example, you have to open the element settings of a layout element and select the option "Main content as detail container":

  • navigate from the detail page to the virtual detail page, for example, from /article/opencms-is-great/ to just /article/
  • switch to the element view called Template elements
  • for each layout element on the detail page, there should now show up a red edit icon for element options
  • click on the gearwheel icon of the layout element, where detail contents shall be displayed
  • in the element settings dialog that opens, choose "Main content as detail container" for the detail page setting

If you navigate back from the virtual detail page /article/ to the detail page /article/opencms-is-great/, the detail content is then displayed in exactly this Mercury layout element where the setting was made.

Most templates offer more than one layout container on their detail pages. All other layout containers, that are not marked as the detail container, can be filled with additional contents that are then shown on every detail page.

Element settings for detail contents can be edited in the following way:

  • switch from the detail page to the virtual detail page, e.g., from /article/opencms-is-great/ to /article/
  • drag and drop an arbitrary content into the very container, you mared as the detail container in the last step
  • the content will be displayed crosshatched, which means, that this content is inactive and will not show up on a detail page, but just on the virtual detail page
  • edit the element settings as you will do for any other content element on a page

Using the sitemap editor is the most easiest way to create new detail pages. The sitemap editor in the background writes several configurations into the sitemap configuration file of a site.

The sitemap configuration file under the /content/.config path is also the right place if your aim is to do additional expert settings for detail pages.

Local detail pages

Global settings are relevant in a site subsite scenario where each site and subsite stores it's contents locally.

Local content elements. As a default in a site subsite scenario, OpenCms stores all newly created contents in the site and not locally in the subsite. Only if and if the checkbox Local content elements is selected, contents are stored locally into the subsite.

Prefer local detail pages. By default in a site subsite scenario, a detail content is shown in the detail page of the (sub-)site you currently are. For example, if both, the site and the (sub-) site have a detail page configured for news contents, and you currently navigate in the site, the detail content is shown on the detail page of the site. If you navigate through the subsite, contents are shown on the detail page of the subsite. This behaviour can be critical if ownership of contents plays an important role. If you check the option Prefer local detail pages, detail contents are always shown on the detail page of the (sub-)site where they are stored. In this way, one can better deal with ownership of contents per (sub-)site.

Disallow detail contents from other (sub-)sitemaps. This is the contrary setting for Prefer local detail pages. While it is not intended that "my content" is shown on the detail page of another (sub-)site, it is also not intended, that "contents of others" are shown on "my detail page". If the Disallow detail contents from other (sub-)sitemaps option is checked, it is not allowed for other contents to show up on my detail page.

Configuration of category based detail pages

Category based detail pages is a further specialization of the detail page mechanism. Sometimes it can be useful to show up contents of the same type on different detail pages depending on a category attached to a content. For example news shall be shown on another detail page than other background articles, although they are technically both articles.

In order to configure category based detail pages, do the following:

  • make sure that the desired categories to control the detail pages exist
  • make sure that all contents have the right categories attached
  • for each category, create a type specific detail page as described above
  • finally, link the detail pages to the categories:
    • open the sitemap configuration file
    • switch to the tab Detail Pages and look for the detail pages newly created in the last step
    • in the Type fields, add the category to the detail page configuration by adding the string "|category:" followed by the category path
Disable the detail page for a content element

It is possible to disable the detail page for a specific content type in the following way:

  • open the site or subsite configuration file
  • go to the tab Content elements
  • if not already present, add a new Content element configuration for the content type you want to disable detail pages for
  • select the option Detail pages disabled
detail page

The page that is configured to show the detailed prepresentation of contents. We mean the one container page to use for rendering the detail view of a content. E.g., the container page under URL "/detail-page/".

detail view

The detail view of a content is the "virtual page" that shows the content on the configured detail page. E.g., the detail view of the news "OpenCms is great" would be the "virtual page" under URL "/detail-page/opencms-is-great/".

detail content

The content shown in the detail view is called detail content. E.g., on the detail view of the news "OpenCms is great", this news is called the detail content.

detail formatter

The formatter to display the detail content. A formatter has to be marked as detail formatter in the formatter configuration.

attachment / detail-only content

A content added at the detail view of another content. It is attached to that content and shown only on the detail view of that content. Moreover it can be accessed in the content's formatter via special JSP API methods.

detail container

The container where the detail content is rendered in the detail view. The <cms:container>-tag rendering it has the attribute detailview="true".  If the detail page is called directly, i.e., without detail content, it behaves like a normal container.

attachment or detail-only container

A container only shown on detail views. Elements in this container are related to the detail content directly and stored in specific container pages. The <cms:container>-tag rendering the container has the attribute detailonly="true".

Opening a detail page on click

To link to a detail page, you need to link to the VFS URL of the content whose detail view should be shown. In a formatter, where the content is available as object content, the code <a href="<cms:link>${content.filename}</cms:link>">Link text</a> will create a link that points to the detail page of the content.

It is important, that the link to the detail page is sourrounded by the <cms:link>-tag. This tag will manage the redirect from the URL of the content to its detail page.

Linking to a specific detail page

Per sitemap only one detail page can be the "default" detail page for a content type. But, in some scenarios you might need more than one of these pages. OpenCms let's you define more than one detail page per type and sitemap. But how to link to a specific one?

To not use the default detail page, just add the URL to the detail page you like to the link, e.g.:

<a href="<cms:link detailPage="/sitepath/to/my/specific/detailpage/">${content.filename}</cms:link>">Link text</a>

Typically you link to detail pages from lists of contents. These lists may be loaded into your page via an AJAX call to a JSP in the system folder. Hence, your request is not to the "correct" site when you create the links to the detail pages and consequently the correct detail pages are not found. To solve this problem, use the baseUri attribute of the <cms:link>-tag, e.g.:

<a href="<cms:link baseUri="/sites/my-site/subsite/the-real-page/">${content.filename}</cms:link>">Link text</a>

Configuring the content-specific URL part

For each content shown on a detail page, the pages URL is extended by a content specific name. By default, the struture id of the content's resource is used as content-specific part of the generated URL, hence you get URLs like https://mypage.com/news/f40d6f9c-3a95-11e9-bd84-0242ac11002b/. But, this can be overwritten by a mapping configuration in the schema of the content type (the .xsd that defines the content's structure). To, e.g., use the "Title" element of a content as content-specific URL part, add the line:

<mapping element="Title" mapto="urlName" />

to the .xsd that defines the content's type. You can use any other content element as well.

The element's value is not mapped unchanged to the URL part. It is manipulated to make up a valid URL.
To make URLs unique, suffixes are added to the URLs if two contents would have the same "nice" detail page URL. E.g., you have two news with the title "OpenCms is great", then one will have the content specific URL part "opencms-is-great" and the second one "opencms-is-great-00001".
The content-specific URL part must be unique system wide, so even for contents of different types and on different sites in the OpenCms installation, the URL parts must be distinct. Avoid unnecessary usage of the mapping for contents without detail views to keep the set of used content-specific URLs as small as possible.

If you use mappings of type "urlName" to determine the content specific URL part, this part might change when you change the mapped value, e.g., you alter the title of your news. Now, what should happen? The link to the "old" nice URL might be sent to some person or indexed by a search engine, hence it might be inappropriate to delete it. On the other hand, the link that is adjusted to the new value would be "nicer".

By default, OpenCms handles the old and the new nice URL and takes you to the same contents detail view. If you want to get rid of the outdated nice URL, you can set the property urlname.replace to true at the content itself of a parent folder of it. Then, the old nice URL will be removed and only the updated one will work when the content is published.

On detail pages the detail content shows directly "in the right place" and noone ever dropped it there. Hence, the place must be determined automatically. Moreover, you may add content to the detail page specific only for one content. But how should that work, since there is not a real page for each of the contents? Both has to be taken care of when developing the template.

Configuring the place where the detail content should show

Add the attribute detailview="true" to the <cms:container>-tag in the template JSP, where the XML content should be displayed. Usually it is the container that contains the main content of a page, e.g:

<cms:container name="maincontent" type="main" detailview="true" .../>
You can have multiple containers with detailview="true". Then the content will render in each of teh containers. By using different container types and thereby triggering other formatters, this can be an interesting feature.
The container for the detail view can be part of a formatter as well if you work with nested container. This is interesting if you build your template with nested containers, building the page structure via "layout"-contents.

Configuring the formatter to use for the detail content

Since the detail content is not dropped to the detail view manually, but inserted automatically, the formatter has to be chosen automatically as well.

To chose the formatter used to render the detail content:

  • Choose the option "Use as detail formatter" in the formatters configuration

You can have more than one detail formatter for content of a certain type. Either, you choose to have detail containers with different type restrictions, such that the different formatters fit only for the different container types each, or you make use of a template detail content, as explained below.

Choosing detail formatter and settings via a template detail content

From OpenCms 11 onward, you can preset detail formatter and element settings used to render detail contents in detail views. Just place a dummy content of the detail content type directly into the detail container on the detail page. Choose the detail formatter and all the element settings to use at this dummy content. When a detail view for a "real" content is called, the dummy content will vanish, since the content in the detail container is replaced by the real content. But, the "real" content will use formatter and element settings as defined for the dummy content.

A side-effect of using the detail page to preset formatter and settings is, that the page itself does not contain valueable content. It should hence be hidden in the navigation and the search.exclude property should be set to true to prevent searches from finding the page. For the "dummy" content the search.exclude property should be set to true as well, unless you use a content that should be findable.

Attach additional content to a the detail view

In some cases you may want to add related content to a detail view of a content. The related content may be an image gallery or something alike. Since OpenCms 9 this is possible to use detail-only containers for such purposes. These containers will only be rendered in case the template is used for a detail view and the contained elements will be individual for each content item.

To use this feature, place additional container tags into your template with the attribute detailonly set to true like this:

<cms:container name="attachment" detailonly="true" type="attachment" />

Usually when placing a content element on a container page, the reference to this element is stored within the container page XML-content. With the elements in detail-only containers, this would not work, as there is only one detail page content for many content items.

When using the detail-only containers, OpenCms will automatically create and manage a new container page XML-content for each content item where additional related content is added in an detail-only container. Within this container page the element references will be stored. Since OpenCms 10, there will be one specific container page for each locale. In case the content is /.content/news/news_0001.html and locale is en this would be /.content/news/.detailContainers/en/news_0001.xml. So by convention the container page is placed in a subfolder of the content item's location called .detailContainers and it is named like the news itself. During the rendering process the same convention is used to look up detail container elements. So deleting a .detailContainers-folder will remove all related elements to the present news.

Since OpenCms 11 the JSP API on dealing with detail-only contents has been massively improved. In the formatter for a content you can get the  attached detail-only contents by "${content.attachments}" and more methods related to detail-only contents are available. Have a look at the JavaDoc for the CmsJspContentAccessBean to explore them.

The detail-only container can also be rendered by the detail formatter of the content itself.

Attached contents are conceptually treated like parts of the content itself. Hence:

  • They are indexed with the content, i.e., you are able to find the content even if you search for a word present only in an attachement
  • Attachments are treated as related contents when the detail content is published
  • The CmsJspContentAccessBean provides special methods to access attachments.

You may think of attachments as a way to add information to your content without altering the schema. And in the same manner as editing the content itself when adding an attachment.

As previously described, detail view links are composed of two parts, the detail page itself and the content-specific part at the end. Conversely, any URL composed of a detail page and the content-specific URL name for a detail content may be potentially interpreted as a detail view link, so that the same detail content can be shown in different detail pages. Depending on how your system is configured, some of these combinations may be valid (i.e. resulting in the detail view being opened in your browser for the given URL) or invalid (resulting in an HTTP 404 status code).

Restricting possible detail page / detail content combinations can be useful for SEO purposes. Some search engines penalize duplicate content available under different URLs. Also, the XML sitemap generator in OpenCms uses the information whether a combination of detail page and detail content is valid to eliminate superfluous detail view links.

However, allowing the same content on different detail pages also has valid uses. For example, on a website with multiple sub-sections, you might want to have individual detail pages for news articles in each of the sub-sections, but also be able to show the news articles in the context of the main site.

As a minimum requirement, a detail page must actually be registered as the detail page for the type of the detail content somewhere in a sitemap configuration - otherwise the combination is invalid.

The validity of various combinations is further controlled by the following configuration options:

  • The <restrict-detail-contents> option in WEB-INF/config/opencms-system.xml (see the DTD).
    This can be set to true (which is the default value) or false. If set to true, any combination of a detail page located in a proper site (i.e. not the shared folder or /system/ folder) and a detail content in a different proper site, will be rejected as invalid.
  • The "Prefer local detail pages" option in the sitemap configuration (.config). We already discussed how this option influences the generation of links.  If this is enabled for a (sub-)site, then any combinations of detail contents in the subsite and detail pages not configured for the subsite will be rejected as invalid, but only if there actually are detail pages configured for the detail content's type in the subsite.
    Note that this option is not inherited through levels of subsites; you have to configure it individually for subsites.
  • The "Disallow detail contents from other (sub)sitemap" option in the sitemap configuration (.config). If this is set, then combinations of detail pages inside the subsite and detail contents outside of it will be rejected as invalid.