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.

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>
${jcr:description}
</p>