Creating a Custom Display List

Creating a Custom Display List is only recommended for authors with experience working with HTML, CSS and the List Component.

JSON, Tags & Categories, HTML, CSS

What is a Custom Display List?

A Custom Display List allows you to format and choose which page properties and page content to show in a list. Using Custom Display Lists, you can display not only page properties—tags, titles, last modified date, etc.—but specific sections of content within a page as well.

Custom Display Lists are built using a list template text file. This text file contains HTML and variables which represent either page properties or page content. (These variables work in the same manner as those used in a Dynamic Text component.) After a list template is created, it's used by a List component to generate the Custom Display List.

} Check the variables list for a complete list of available variables.

When should it be used?

Create a Custom Display List if you need to show page properties and/or content that pre-existing list display options don't show (e.g., if you want to display the date and time the page was last modified).

Reviewing the List Component

The Custom Display List is a List component using the Custom option in the Display as field. In order to fully understand the Custom Display List, we need to review the List component.

Every time a List component is created, two properties must be set:

  1. Build list using: determines which pages to list. Options for this field include Child pages, Fixed list and Advanced Search.
  2. Display as: determines the style and content of the listed pages.

Each Display as option is styled differently and shows different content. For example, the News option shows the date, title and teaser text for each listed page. However the SFU News List displays the same elements as the News option, as well as a thumbnail. Also the News option's date and title is bold, unlike the SFU News List. To view examples of these display options, go to Blog and News Display Options.

Note: the Build list using and Display as fields are independent of each other. Any combination of options from the Build list using and Display as fields can be used.

Documentation Terminology

Custom Display List - A List component using the Custom option in the Display as field.

How to create a Custom Display List

When using the List component, AEM searches for pages to list (as determined by the Build list using field) and generates a set of bullet points (<li> elements) for each page in the list. Each <li> element is generated via a list template that specifies which variables are being called (for example, the title of the page), and how that information should be displayed (e.g., inside a link). 

To create a Custom Display List, you will need to create a list template. It determines how and what is displayed inside each <li> element of the list. You can specify both structural elements inside this template file, such as <div> tags, as well as variables, which will retrieve content dynamically based on what's on the page. The template file is written as HTML.

The following tutorial explains how to create a simple Custom Display List that will display the page's title and last modified date. It will look like the example below:

Steps for creating the above Custom Display List

Creating a Custom Display List involves two parts: creating the list template and setting up the List component to use that list template.

Creating the list template

  1. Create a new text file. This will become the list template that determines what page properties/content will be displayed in each list item.
  2. Copy and paste the HTML code below into the list template. If you were creating a different Custom Display List, you would need to copy the HTML code and variables of an already existing list template, or create the list template from scratch.
    <a href="${href}">${jcr:title}</a>
    <p>Page last modified at ${cq:lastModified}</p>

    The first line of code creates a title and turns it into a link. It does this using two variables: ${href} which returns the page's URL, and ${jcr:title} which returns the page's title as entered in the Title field in the Page Properties.

    The second line creates a paragraph stating when the page was last modified. It uses the ${cq:lastModified} variable to return the time and date the page was last modified, which is then appended to the string of text, "Page last modified at ".

  3. Save the list template as a text file and upload it to the DAM. Make sure the file the .txt extension. For your reference, this list template is available for download below:

Setting up the List component to use the list template

  1. Insert a List Component onto the page you want the Custom Display List to appear on.
  2. Open the List Component's properties. Choose which method you want to use for searching for pages — see the List component documentation for options.
  3. From the List Display drop-down menu, select Custom.
  4. A new field will appear below. Click the magnifying glass and select the list template you uploaded to the DAM.

All Custom Display Lists are created using the same steps, except for creating the list template part. The HTML code and variables in the list template must be written according to the content/page properties you wish to display. For a full listing of page properties/content variables, see the variables list.

Tips for creating a Custom Display List

Creating the list template

When creating a Custom Display List, decide what page properties/content should appear in each list item. Next, in the list template, create the HTML content structure and enter the desired variables in the appropriate location. Make sure to include the HTML code below as it creates the linked title.

<a href="${href}">${jcr:title}</a>

Styling a Custom Display List

By default, a Custom Display List doesn't have any applied styles. If you wish to style a Custom Display List, create the new CSS class in your site's stylesheet, and enter the class name into the CSS Class field of the List component.

Additional Custom Display List examples

Example 1: Replicating the SFU News List display option with a Custom Display List

  • News Article 1 October 03, 2012
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse dignissim eros vitae lectus ornare ac feugiat erat volutpat. Cras urna augue, tincidunt nec commodo sed, placerat non odio.

  • News Article 2 September 15, 2012
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse dignissim eros vitae lectus ornare ac feugiat erat volutpat. Cras urna augue, tincidunt nec commodo sed, placerat non odio.

The Custom Display List above replicates the style and content of an existing list display option, the SFU News List. The difference between this example and the existing SFU News List is the teaser text. The SFU News List creates the teaser from the first 100 letters of the first pagaraph on the page, whereas this Custom Display List creates the teaser from the text in the Description field of the page properties.

This example was created with the list template below. To style the Custom Display List to look like the SFU News List display option, the newsList style was entered in the List component's CSS Class field.

List template

<img src="${thumbnail}">
<p><a href="${href}">${jcr:title}</a><span> ${datestamp}</span><br>