OpenCms documentation
OpenCms documentation

Traditional lists with OpenCms

Building lists of content items that are linked with its detail views is a common task when creating a website. For example, a typical list of news displays the title, the teaser and maybe the creation date or information about the author per entry/news. Moreover, a list might offer pagination or simple filter options to the website’s visitors. Those lists are realized by “Collectors” in OpenCms, whereby “Detail pages” are used to show the complete details of a news article, an event, a product or any other type of resource/content. This chapter introduces how to implement such lists using collectors and how to link from list entries to their detail pages.

OpenCms 11 provides an alternative recommended way to build lists.

In the following subsections, we describe how to build a list with a collector. The first subsection, and the section about the available collectors, is all you need to get a list. The other subsections just describe extra features.

OpenCms provides the tag <cms:contentload> to collect XML resources. The tag's body is rendered once for each collected content and <cms:contentaccess> is used to get access the content loaded in the current run:

<cms:contentload collector="..." param="..." editable="true">
   <cms:contentaccess var="content" /> ... 
</cms:contentload>
collector

The name of the collector that should be used.

param

Configuration parameter for the chosen collector. For standard collectors, the syntax is: [path]|[resource type]|[count] to specifiy from wich folder (path) how many (count) resources of which type (resource type) should be collected.

editable

Set this attribute to true, to enable the direct edit option for the list (entries can directly be added, removed or edited).

A very simple example of creating a list with links to detail pages looks as follows:

<%@page buffer="none" session="false" taglibs="c,cms" %> 
<%-- The JSP HTML should be surrounded by block element --%>
<div>	
  <%-- Read collector paramter, e.g. from request --%>
  <c:set var="folder" value="${param.folder}"/>
  <c:set var="type" value="${param.type}"/>
  <c:set var="count" value="${param.count}"/> 
    <ul>
    <%-- Use <cms:contentload> with new collector--%>
    <cms:contentload collector="myCollector" param="${folder}|${type}|${count}">
      <%-- Access the content --%>      
      <cms:contentaccess var="content" />
      <c:set var="link"><cms:link>${content.filename}</cms:link></c:set>
      <li><a href="${link}">${content.value.Title}</a></li>			
    </cms:contentload>
  </ul>
</div>

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.

Creating new content items using collectors

Typically a collector allows the creation of new content instances of the resource type it collects by clicking on the “plus” symbol of the flyout-menu a list entry. This functionality is available if the attribute editable is set to true in <cms:contentload> and the used collector is configured to allow for such editing. New resources are created inside a configured folder (see (sub-)sitemap configuration and module configuration), typically below a /.content/ folder. 

OpenCms ships with a whole bunch of collectors. The most useful are the Solr collectors.

  • All resources matching a user defined Solr query:
    • byQuery (executes the exact query)
    • byContext (considers the request context automatically, in particular locale and site root)
  • All resources in a folder or sub-tree:
    • allInFolder
    • allInSubTree
  • All resources in a folder or sub-tree, sorted by the value of the NavPos property:
    • allInFolderNavPos
    • allInSubTreeNavPos
  • All resources in a folder or sub-tree, sorted by the value of the release date:
    • allInFolderDateReleasedDesc
    • allInSubTreeDateReleasedDesc
  • All resources in a folder or sub-tree, sorted by collector.priority property and then by Title property:
    • allInFolderPriorityTitleDesc
    • allInSubTreePriorityTitleDesc
  • All resources in a folder or sub-tree, sorted by collector.priority property and then by collector.date property:
    • allInFolderPriorityDateAsc
    • allInSubTreePriorityDateAsc
    • allInFolderPriorityDateDesc
    • allInSubTreePriorityDateDesc
  • All resources in a folder or sub-tree, mapped to a given URI and sorted by the collector.priority property and then by the collector.date property:
    • allMappedToUriPriorityDateAsc
    • allMappedToUriPriorityDateDesc

Imagine a JSP providing a list of resources by the usage of the <cms:contentload>.  To drop JSPs directly into a container page OpenCms offers dynamic functions.

  • Create a new dynamic function. Usually this resource is a part of the module and should be created in folder /system/modules/{mymodule}/functions/.
  • Select the JSP containing the collector. 
  • To define the collector parameters set the initial request parameters in the dynamic function. E.g., use:
    • folder=/dev-demo/collector-with-detail-page/.content/article/
    • type=ddarticle
    • count=5
  • Open a container page in ADE and drop the new dynamic function onto the page.

In order to develop a collector, which can be used with the <cms:collector>-tag, the collector must implement the interface I_CmsResourceCollector. The package org.opencms.file.collectors already provides a standard implementation for this interface with A_CmsResourceCollector. Extend this class, if you develop your own collector. Following methods have to be implemented:

  • List<String> getCollectorNames();
    The method has to return the names of the collectors implemented by your collector class.
  • String getCreateLink(CmsObject cms, String collectorName, String param)
            throws CmsException, CmsDataAccessException;
    The method has to return the link that should be executed when a user clicks on the direct edit "new" button on a list created by the named collector. If this method returns null, it indicates that the selected collector implementation does not support a "create link", and so the "new" button will not be shown on lists generated with this collector.
  • String getCreateParam(CmsObject cms, String collectorName, String param)
            throws CmsDataAccessException;
    This method has to return the parameter that is passed to getCreateLink(CmsObject cms, String collectorName, String param). If this method returns null, it indicates that the selected collector implementation does not support a "create link", and so no "new" button will be shown on lists generated with this collector.
  • List<CmsResource> getResults(CmsObject cms, String collectorName, String param)
                       throws CmsDataAccessException, CmsException;
    The function has to return the list of org.opencms.file.CmsResource objects that are gathered using the named collector.

Edit opencms-vfs.xml and add following line to <collectors>-node (replacing the class given here by your own collector class) and restart the Servlet Container afterwards.

<collector class="org.opencms.dev.demo.CmsSimpleResourceCollector" order="180" />