Detail pages

When building lists of content, it's a typical requirement to link from a condensed view of the content to a more detailed view. For example, in a list of news, only title, teaser and maybe a date and author are displayed. You click on a news to get to a page showing the complete news article. Similarly, events, products or any other type of resource/content may be shown in a list with links to a detailed views added.

In OpenCms it is sufficient to create and configure one page to automatically get all pages for the detailed views of each content of a type - each under a separate, nice and configurable URL and even editable. The configured page is called detail page and since OpenCms 11, it is even possible to configure only one detail page for the detail views of contents of all types.

In this topic you learn how to configure a detail page, the special container tag attributes related to detail pages and how to link to a detail page.

The idea of detail pages

For content items like news or events usually a detail page is configured to display the most detailed information of the content. With detail pages, you don’t need to create a separate page for each and every new content item; but all content items of a specific resource type can be displayed using the same page arrangement. Detail pages can be created with the sitemap editor for all configured resource types.

Here's a detail page demo

Wording

New caption: Since one detail page lets you display various contents under different URLs it is good to clarify the wording used below:
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 "/detailpage/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".

Adding a detail page

To add a detail page to your site:

Open the "Create page" dialog in the sitemap editor.
From tab "Detail pages" drop the page for one of the listed resource types into the sitemap.

The detail page is automatically configured by OpenCms in the sitemap configuration file. Now links to a content of the detail page's content type should be redirected to an automatically generated URL that starts with the URL of the detail page and is extended by a content specific part (the filename, or, if configured a special urlName).

See here, to find out how to link to a detail page.

The default detail page

Up to OpenCms 11 a detail page had to be defined for each content type separately. Since OpenCms 11, a "fall-back" detail page can be added as well. If you add the "'Default' type detail page", it will be used for contents of all types that have detail pages enabled, unless there's a type specific detail page.

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>

Linking to detail pages in dynamically loaded JSPs

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>

Adding a detail page is simple, but some configuration is necessary upfront to get your detail pages working as expected. Below you learn about:

Enabling/Disabling detail pages for a resource type
Configuration of nice URLs
Template requirements to make your contents show as expected (detailview and detailonly containers)
Handling of multiple detail pages for one type
The default detail page mechanism (one detail page for all types)

Enabling or disabling detail pages for a content type

If detail pages can be added for a special content type or not can be configured in the module or the sitemap configuration:

In the module or sitemap configuration, open the tab "Content elements"
Add or edit the "Content element configuration" for your content type
Select or deselect the option "Detail pages disabled"

Preferring local detail pages

If you work with sub-sitemaps you may have a list of news in the main sitemap that collects news from the main sitemap and from the sub-sitemap. If you have a detail page for news in the main sitemap and in the sub-sitemap, where should the detail page link for a news from sub-sitemap go to?

By default, the link will target the detail page configured in the main sitemap, i.e., in the sitemap where you currently are. But, if you check the option "Prefer local detail pages" in the sitemap configuration of the sub-sitemap A, the detail page of sub-sitemap will be targeted, i.e., the (sub-)sitemap where the content is located.

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

Changeing the "nice URL"

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.

Preparing your template for detail pages

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.

Details on attachments

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.

Detail view URL validity

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.