Lists Paragraph

The Lists Paragraph provides the ability to dynamically generate a list of Events, News, People, Basic Pages, Courses or Publications to display on a page.

List Paragraphs are powerful site-building tools. They offer a variety of display and sorting options based on the types of content in the list and can be adjusted to display a specific number of items and/or dynamically generated based on taxonomy terms.

View list examples

The Lists paragraph is made of these parts:

• List Format: This section offers a View list to choose a content type (Events, News, People, etc.) and Display format. Display options vary based on content type.
• Advanced options: This setting can customize a list based on taxonomy terms, as well as override the default number of items displayed.
• Headline: The headline displays as a heading above the list. This is a required field. 
• Description: The description text displays below the headline and above the list. This is an optional field.
• Button: The button displays a button-styled link below the list. This is an optional field.
• Style/Behaviors: Provides options for handling empty lists and for controlling heading behavior.

Note: see Comparing Teaser and Lists for potential use cases for Lists and a comparison between Lists and the Teaser Paragraph.

List Paragraph varieties

List Paragraphs come in a few different flavors to support common sitebuilding needs.

Event Lists

• Display options: Can be displayed in a card, list, or past events list format.
• Sort: Sorted by date.
• Filtering: Card and list formats will always show upcoming events first. Events that have already occurred will fall off the list. Past events list will show all events that have already occurred.

News Lists

• Display options: can be displayed in a card or list format. 
• Sort: Most recent news always appears at the top of the list.

People Lists

• Display options: displayed in a grid format. 
• Sort: People are sorted alphabetically.

Publication Lists

• Display options Publications can be displayed in either APA or Chicago citation styles. 
• Sort: Publications are sorted by publication date

Course lists

• Display options: Course lists can be displayed in a card or list format

Advanced options

By utilizing the advanced option settings for these displays, you can customize your list by taxonomy terms, or change the default number of items displayed in your list.

Creating a custom list filtered by taxonomy terms

If you would like to customize which items appear in a list, create a custom list based on your taxonomy terms. 

Enter your taxonomy term(s) in the Advanced Options field called Arguments. Convert all spaces to a hyphen (e.g. the term for “In the News” would be “in-the-news.”) In the example below, we have a People list that is filtered by the Person Type term "Humanities and Sciences."

• No items will appear on that list until you have tagged content with the term.
• You can combine terms to get lists that include members from two different categories. For example, if you had people tagged by "Faculty" and people tagged by "Staff," you could make a faculty and staff list by having the arguments be entered separated by commas or plus signs: faculty+staff. This will show everyone who is faculty OR staff.

Limitations

• There is no way to custom order list items
• There is no way to exclude one or more items from your list without removing the tag or unpublishing the content
• There is no way to produce a list that only shows the intersection between two tags (for example, only showing people who are tagged as both faculty AND staff.)

Managing the number of items on your list

To override the default number of list items displayed, simply enter your desired number of items in the Advanced Options field Number of items. This also disables the pager if one is configured for this display. 

Manage empty lists

If no items meet the list criteria and the list is empty, Site managers can choose to either hide the list paragraph or display an empty list message, such as "No events scheduled at this time. Check back later." If a new item becomes available later that does meet the criteria, the Lists Paragraph will reappear on the page or the empty message will disappear. This is especially helpful for events lists.

Hide the List Paragraph

Here's how to hide the empty list paragraph:

1. Open the Style/Behaviors, found at the bottom of the edit form.
2. Check Hide if empty.

Display an empty list message

1. Select Style/Behaviors, found at the bottom of the edit form.
2. Type your message in the Empty list message text box.

Manage the Lists Paragraph Headline display

The following are settings that control the behavior of Lists Paragraph Headline. The Headline field is required to ensure proper heading order is available for users using assistive technologies and search enginers. The Headline field for a Lists Paragraph is always a Heading 2 (h2) and individual list items are always set as Heading 3 (h3.) These settings help you control the behavior of the Headline Heading 2.

Display heading: Recommended - This displays the Headline as an H2. This is the default setting.

Visually hide heading: This keeps the Headline in the page structure as an H2, but hides it in the display. This is appropriate if you wish to provide additional context for assistive technologies and search engines.

Remove heading: This completely removes the Headline from the page and assumes you have placed an H2 on the page above this paragraph. Used incorrectly, removing the Headline can create an accessibility issue.