Content list widget

The Content list widget is an out-of-the-box .NET Core widget whose purpose is to render Sitefinity CMS content on the frontend. This is a single widget that can work with both static and dynamic content at the same time.

The Content list widget does not support Pages, Content blocks, and Media items.

You can place a Content list widget only inside a Section widget.
To do this, perform the following:

1. Inside a column from the Section widget, click Add widget here…
   
2. Click the Content tab.
   
3. Under the Content lists section, select the template that you want to use to display the list of content items.
   If you have created any custom temples, they also appear in this list. 
   Select between:
   • CARD LIST
   • LIST WITH IMAGE
   • LIST WITH SUMMARY
4. Click Select content.

In this section, you choose the content to be displayed by the widget. 

1. In the Content type dropdown box, select the module where you want to display content from.
   The list includes all built-in and dynamic modules, except for media modules content blocks, and pages.
   
2. If the selected content type has more than one content providers, in Source, you can choose which provider you want to display items from.
   
3. In the Selection range radio button, you can select which content to display, based on their publication date.
   There are the following filtering options:
   • All published items
     
   • From currently open parent
     This option is available only for hierarchical static and dynamic modules, such as Blog posts or Events.
     
   • Selected items
     Click  (Select <type>) icon and select an item that you want to include in the list of items. 
     Repeated this step for as many single items as you want to include in the list.
     
4. Under Filter by <parent type>, you can select patent items whose children you want to display.
   This option is available for hierarchical items only.
   1. Click  (Select <type>) icon.
      
   2. Select the items whose children you want to add to the list. 
      
   3. Repeated this step for as many single items as you want to include in the list.
      
5. Under Filter by category, you can filter the selected items by the category where they are classified.
   Click  (Select categories) and select the categories that you want to filter by.
   
6. Under Filter by tag, you can filter the selected items by the tags they are tagged with.
   Click  (Select tags) and select the tags that you want to filter by.

   NOTE: The values for a single filter are interpreted as a logical OR. This means that, if you have selected two tags – tag1 and tag2, then the items tagged with either tag1 or tag2 are displayed on the frontend.

7. In Date published dropdown box, select one of the following:
   • Any time
     
   • Last…
     Enter a number and select between day(s), week(s), month(s), years(s).
     
   • From – to
     Enter the exact date range of publication dates.
     Items that are published during this range, will be displayed in the widget.
     
8. In List template, you can change the originally selected template.
   Choose between:
   
   • Cards list
   • List with image
   • List with summary
9. In Field mappings, map the fields in the widget to the fields of the selected content type.
   For example, as Publication date for news, you can choose to display the creation date or the date that the news was last modified.
   

NOTE: If you apply multiple filters – for example, by tags and by parent, the filters are applied by using a logical AND. This means that all the conditions must be true – for example, News items tagged with tag Sports and Weather AND having been published in the last week.

You can change the logical operator to OR from the advanced settings of the widget.
For more information, see Advanced widget settings section below.

In this section, choose how to display the selected items on the page.

1. In Number of list items, you can select between:
   • Use paging
     Enter the number of items per page that you want to display.
     
   • Show limited numbers
     Enter the total number of items that you want to display.
     
2. In Sort items, select how to sort the items in the list.
   Choose between:
   
   • Last published
   • Last Modified
   • Alphabetically – ascending or descending
   • As set in Advanced mode.
     You can sort items, using custom expressions.
     For more information, see Advanced widget settings section below.

Single item settings define how individual items are displayed. Choose one of the following options:

1. Open single item in...
   Select one of the following:
   
   • Auto-generated page
     When you click an item, it is displayed in an automatically generated page with the same layout as the list page.
     
   • Selected existing page…
     From the list of existing pages, select the specific page in which the item will be displayed.

     NOTE: To display an item in a page, the page must have a Content list widget, configured with the same content type, added in advance.

2. In Single items template dropdown, select the template that you want to use to display the item, when it is clicked in the list of items.
   

To open the Advanced settings for Content list widget, in the upper-right corner, click  (Advanced settings). 
You can modify the following settings:

Label

You can change the name of the widget that is used to display the widget in the page editor.

Content view display mode

Based on your selection the items will be displayed as follows:

• Automatic
  Handles Details item URLs like: ~/page/2021/01/01/news.
  
• Master
  Shows a list that does not handle Details item URLs. For example, ~/page/2021/01/01/news will throw 404.
  
• Detail
  Shows the selected item in Details mode only.
  

Selection group logical operator

If you apply multiple filters – for example, by tags and by parent, the filters are applied by using a logical AND. This means that all the conditions must be true – for example, News items tagged with tag Sports and Weather AND having been published in the last week.

Use this radio button to change the logical operator to OR.

Filter expression

In this field, you can create a custom filter by manually entering a filter expression in JSON format. This filter expression is a serialized hierarchical JSON structure. The structure is the same serialized structure as when working with filters and the REST SDK. 

Following are some examples:

Basic filter by custom short text field

Basic filter by taxa

This filter accepts the following operators:

• "eq" - equals
• "ne" – does not equal
• "gt" - greater than (for numbers)
• "lt" - less than (for numbers)
• "ge" - greater than or equal (for numbers)
• "le" - less than or equal (for numbers)
• "any+or" - contains any of the collection
• "any+and" - contains all of the collection
• "not+(any+or)" - does not contain any of the collection
• "startswith" – starts with (for strings)
• "endswith" – ends with (for strings)
• "contains" – contains (for strings)

The above filters have the following properties:

• FieldName maps to the name of the custom field for the selected content type. 
  
• Operator maps to the logical operator.
  
• FieldValue maps to the value with which to execute the logical operation.
  

Complex filter

The complex filter is recursive and can contain child complex filters. The complex filter has an additional property, called Operator, which can be “and” or “or”, which correspond to operator between the child filters.

Sort expression

By default, items are sorted in the list by publication date in descending order. You can also enter a custom sort expression.

Use the following format: {fieldName} (ASC / DESC). For example, PublicationDate DESC

Disable canonical URL meta tag

To stop generation canonical URLs on widget level, select Yes.
For more information, see Canonical URLs.

Paging mode

You can configure paging per widget. You can specify the number of items per page in the list settings of the widget. In the advanced settings, you can control the paging mode - whether the paging works with URL segments or a query parameter. 

• URL segments
  When you select this mode, the paging is configured to work with URL segments, and you must specify the template for these segments in Template for paging URL segments field.
  The default template is -page-{{pageNumber}}- 

  The {{pageNumber}} part is mandatory, and it represents the number of the current page.
  For example, -mypage-1, -maypage-2

  The template for the URL segments also supports multiple segments.
  For example, page/{{pageNumbe}}

  NOTE: If you have more than one widget on a page that is configured to work with URL segments and they use the same template, then all the widgets will change their pages when navigating through the pages of any of the widgets. If you want every widget’s paging to work separately from the others, you must specify different segment templates for each Content list widget.

• Query parameter
  When you select this mode, the paging is configured to work with query parameters. The pages of the list are changed with the specified key parameter.

  If you select this mode, you must specify the template in the Template for paging query parameter field. The default one is page – for example, ~/pageURL?page=3. 

  NOTE: If you have more than one widget on a page that is configured to work with query parameter and they use the same template, then all the widgets will change their pages when navigating through the pages of any of the widgets. If you want every widget’s paging to work separately from the others, you must specify different query parameter templates for each Content list widget.

Custom CSS classes

You can modify the look and feel of your content widget, by applying additional CSS classes. You can add CSS classes to the List view and the Details view HTML wrapper elements. You can also add custom classes to each of the field mappings that the currently selected view supports.  

In this section, you can specify custom CSS classes that can apply to:

• The content List view
  
• The content Details view
  
• All of the mapped fields
  

Displaying hierarchical content

These settings are used to modify widgets default behavior when you have a hierarchy of content types and both parent and child widgets are placed on the same page.
This section applies only to hierarchical content types – static or dynamic.

You can choose how to display the parent items and the child items, by selecting one of the following:

• Show parent list view on child details view
  Use this setting, if on the same page, you have two widgets – one displaying the list of parent items, the other displaying a child item in Details view. 

  This radio button shows or hides the parent list, if there is another widget on the same page displaying details view of a child item.
  Use this setting on the parent widget.

  EXAMPLE: If you have a parent content type Countries that has child content type – Cities. On a page are dropped both Countries and Cities widgets. By default, when a City is opened in detailed view, the list of Countries is still visible on the page. If you want to hide the Countries widget, when a City is opened in detailed view, you must select No.

• Show parent details view on child details view
  Use this setting, if on the same page, you have two widgets – one displaying the parent item in Details view, the other displaying a child item in Details view. 

  This radio button shows or hides the parent’s Details view, if there is another widget on the same page displaying details view of a child item.
  Set this setting on the parent’s widget.

  EXAMPLE: If you have a parent content type Countries that has child content type – Cities. On a page are dropped both Countries and Cities widgets. By default, when a City is opened in detailed view, the list of Countries is still visible on the page. You may want to display additional information about the country of the selected city. To enable the Countries widget to resolve details about the country you must select Yes.

• Show child list view if no parent selected
  Use this setting, if, on the same page, you have two widgets – one displaying a list of parent items, the other displaying a list of child items. 

  This radio button shows or hides the list of child items when no parent is selected.
  Set this setting on the child’s widget.

  EXAMPLE: If you have a parent content type Countries that has child content type – Cities. On a page are dropped both Countries and Cities widgets. The Cities widget is configured to show cities only from the currently selected country. By default, if there is no Country opened in detailed view, the Cities widget does not show any items. If you want all cities to be displayed when there is no Country selected, you must select Yes.

Metadata fields

1. To use metadata fields, under SEO enabled, select Yes.
   
2. Configure the metadata fields for the module that you have selected to display in the widget.
   For more information, see Configure Meta title and Meta description.
   
3. Fill out the Meta title and Meta description fields.
   For more information, see Meta title and meta description of widgets.
   
4. To use Open Graph properties, under OpenGraph enabled, select Yes.
   
5. Configure the Open Graph fields for the module that you have selected to display in the widget.
   For more information, see Configure Open Graph properties.
   
6. Fill out OpenGraph title, OpenGraph description, OpenGraph image, OpenGraph video, and OpenGraph type fields.
   For more information, see Open Graph properties of widgets.

NOTE: For the automatically generated SEO and Open graph fields to be added to your page, you must add the call to @Html.RenderSeoMeta(this.Model) in the <head> tag of your root layout file. 

Content locations

The Content list widget supports Content locations . This is done automatically.

Support for more than one Content List widget on a page has the following limitations:

• You can configure only one widget with the setting ContentViewDisplayMode – Automatic. The other widgets must be in Details or Master mode. This way, the other widgets do not interfere with the resolving of the segments from the URL of the currently opened Details item.
  
• Multiple content widgets, config ured in Master mode, on the same page can support pagination separately from each other, if they have a different custom template, defined for their pagination parameters. This allows them to monitor various parts of the URL or different parts of the query string, so that when pagination is applied to one of the widgets, the others do not apply paging to their items.
  
• If one of the widgets on the page is configured with ContentViewDisplayMode - Automatic, then the paging of the other content list widget should be configured with paging mode query parameters.

You can cutomize both the List and the Details view of the Content list widget. 
For more information, see Create custom views for the Content list widget.