Dynamic Sortable / Filterable List

Overview

In addition to the content to be sorted /filtered, a dynamic sortable / filterable list requires two primary components:  a content export (JSON) file for managing the content to be included in the list and a web page with a dynamic sort-filter module for displaying the list.  Follow the process below for setting up a dynamic sortable / filterable list.

1. Determine Requirements
2. Set Up Custom Taxonomies (Optional)
3. Prepare Content Pages / Files
4. Set up the Content Export (JSON) File
5. Create the Dynamic Sort-Filter Page
6. Publish the JSON File and Sort-Filter Page

Notes on multi-site filtering/sorting: You can now set up a dynamic sort-filter module to pull pages from multiple sites. See the section “Building a Multi-Site Filter-Sort Module” at the end of this document.

1. Determining Requirements

Before working in the WCMS to set up a dynamic sort-filter list, web developers should work with the content owners to answer some key questions about the list:

• Which types of content should be included?  For example, should the list include only web pages, or should it include a combination of web pages and PDF files (or perhaps some other type of file)?
• Should the user be able to filter the list?  If yes, what filter categories are needed?  You can use standard taxonomy categories (e.g., Topics, Document Type) and / or custom taxonomy terms set up for the site.
• How should users be able to sort the list?  Typically, for sorting the content title and some time of content date are used (e.g., Article Date entered by a web developer or the last link-publish date).
• Which text should be used for the content title and description?  For example, you could use page short titles instead of the regular titles.  For the description, you could use content from the page body or the link descriptor text.
• Should images be included?  Iconic images can make a dynamic sort-filter list more engaging.
• Do you need to include any special fields besides the standard title, description, image, etc.?  For example, if you are listing YouTube videos, you may want to include the low-resolution URLs.
• How should content be pulled into in the dynamic sort-filter list?  The content export file allows you three options:  Pull the content automatically from the parent folder of the content export file or from selected folders; select the content items manually; or specify a managed feed.  With the automatic option, you can filter the content export by standard taxonomy categories and / or custom taxonomy terms.

The list above provides just a high-level view of the options you must consider when building a dynamic sort-filter list. Before you proceed with the next step, we recommend that you review all the steps below to better understand your options for configuring a dynamic sort-filter page and the ways in which the process steps are connected.

2. Setting up Custom Taxonomies (Optional)

In addition to a keyword filter, the dynamic sort-filter list supports optional filtering by category. You can use the standard taxonomies in the Metatags and Taxonomies panel for each page / file (e.g., Topics, Audiences, Document Type) and/or any custom taxonomies created for your site.

You can also use standard and/or custom taxonomies to control the pages / files included in the dynamic sort-filter list.  This is explained in the section on setting up the content-export JSON file.

Once you determine your needs for filtering (working with the content owners), a site manager can set up any custom taxonomies you need.  A manager can then add the terms to each custom taxonomy by selecting “Manage Taxonomies” in the WCMS’s left menu and then selecting the custom taxonomy. (Publishers and editors can also add terms when editing content.  Each custom taxonomy has its own panel in the right rail of the page / file.  These panels support the creation of taxonomy terms.) Note that parent-child associations can be created between categories.

For more information on custom taxonomies, see the intranet-based WCMS Developer’s Guide. On the intranet search for “WCMS Guide.”)

3. Preparing Content Pages / Files

Ensure that all the pages (or files) to be included in the dynamic sort-filter have the required field entries to support titles, images, descriptions, URLs, dates, and any filter categories. For example, if you are using the standard taxonomy “Document Type” for filtering by category, make certain the correct Document Type values are chosen for each page / file. (Note that standard taxonomies, such as Topics and Document Types are in the “Metatags and Taxonomies” panel of the page / file, while the categories for custom taxonomies appear on the right of the content form, with each taxonomy having its own panel.)

A content inventory report may help you with page checking. For more information on field use, see Selecting Fields for JSON File below.

As new pages are created after the dynamic sort-filter list is set up, make certain your web team continues setting the page properties as necessary.

Note:  If you are using a managed feed to control the pages to be included in the dynamic sort-filter list, you can add a page to the feed via the “Feeds” panel in the page’s right fail.  Or you can open the managed feed and add pages to the feed list there.  For more information on managed feeds, see the intranet-based WCMS Developer’s Guide. On the intranet, search for “WCMS Guide.”)

4. Setting Up the Content Export

Creating a Content Export File

1. From WCMS content browser, click “New Content” and, when prompted, select “Content Export.”
2. Select the content types for the sort / filter module you will be creating (typically page or file).  For each content type to be included, click “Add Additional Content Type.”
3. Select JSON as the export format.
4. Check “Include Alt Text for Image Fields.”
5. Check “Use Friendly Field Names.”
6. Check “Use Root-Relative URLs.”
7. If you are including one or more taxonomies for filtering and want to include the complete hierarchy for each filter tag, check “Output Full Hierarchy (taxonomy fields only).”
8. If you check “Output Full Hierarchy,” you can then check whether or not to “Include Parent Terms in Filter List.”
9. If including full taxonomy hierarchy, enter a delimiter character (suggestion: try the default “>” character).
10. Select the template version.  Save the file (with JSON extension) but do not close.

Selecting Fields for JSON File

While in the content export form, use the list builder (“Fields” panel), to add the page / file fields you will need for display, filtering, and sorting.  Consider the following types of fields:

• For content titles:  Select Title or Short Title.  Typically you should check “Sort on this Field” and enter sort labels such as “A to Z” and “Z to A.”
• For content descriptions:  Typically, this can be Link Descriptor Text or Post Content.  If you select Post Content, you should probably enter a value for “Truncate text after this many words.”
• For content dates:  A date is very helpful for sorting. Select Article Date or whichever date field you would like to use for sorting.  Don’t forget to check “Sort on this field” and use labels such as “Oldest to Newest” and “Newest to Oldest” for the descending and ascending sort labels.
• For images: Add “Iconic Image” to the list of fields.
• For linking:  Add “Public URL” to the list of fields. (This is essentially a required field.)
• For filtering:  To make the list filterable by one or more categories, add each required taxonomy (standard or custom). Don’t forget to check “Filter on this Field.”
• For alternative formats/languages:  To include the links to alternative file formats and/or alternative languages, select these fields for pages. (Tip:  When you set up the dynamic sort-filter Visual Composer element, there is a field on the Display tab for hiding field labels.  Consider hiding this field label.)
• For special fields:  Don’t forget any additional fields to display in the sort-filter list beyond the standard title, description, etc.

Finally, for convenience, jot down the fields you are using.  (Note that you can override the field labels to something friendlier and easier to remember.)  You will need the exact field titles as used in the content export field list when you insert the dynamic sort-filter module a page.

Save the file to preserve your selections, but do not close it.  (Use the JSON extension.)

Selecting Content for Export

While in the content export form, select how the content should be pulled into the file:  automatic, manual, or feed.

• If you select automatic, the WCMS includes in the JSON file all pages / files (depending on content types selected and any filters as explained below) in the same folder as the JSON file, including subfolders.  To prevent this default behavior, select one or more folders.  The “automatic’ selection also allows you to limit the content export by one or more taxonomies.  For example, you could tag your pages by the standard taxonomy “Document Type,” and in the content export, specify that only pages with the document type “News & Announcements” or “Fact Sheets” are to be included.  If you specify more than one taxonomy value, the JSON export file includes only pages / files that meet all taxonomy values you specify.
• If you select manual, you can then use a list builder to manually select the pages / files.
• If you select feed, you must then select a managed feed. (For information on managed feeds, see the intranet-based WCMS Developer’s Guide.  On the intranet, search for “WCMS Guide.”)

Then select the publishing status for the preview, dev, and link environments.

Filtering Content for Export

If you have selected the “Automatic” option for pulling content, you can use the filter options at the bottom of the content export form to limit the  scope of the export by custom and/or standard global taxonomies.

If you do not select any categories/terms for a taxonomy, there will be no filtering on that taxonomy.

Don’t forget to save the JSON file.

5. Creating the Dynamic Sort-Filter Page

1. Create or open the page that will contain the dynamic sort-filter module. Tip: If your JSON file is automatically pulling pages with no folder or taxonomy constraints, do not place this page in the same folder as the content pages to be pulled. Otherwise, this page will display in the sort-filter list.
2. Working in Visual Composer, add an element called Dynamic Sort Filter. (Make certain you allow plenty of space for this module. Typically, it should span the page.)
3. In the Data tab of the Settings pop-up, select the JSON file. (If you are setting up a multi-site sort-filter using multiple content export files, select the JSON files for the other sites in the Advanced tab.)
4. Then, while still in the Data tab, enter the field labels (based on your selections in the content export form). For example, if you are using Link Descriptor Text for the content description, enter “Link Descriptor Text” (without quotation marks) in the field “Description Field Name.” List in the “Additional Field Names” field any fields to display beyond the standard title, description, etc. (Note that in the content export setup, you can override field labels, so you could set the “Link Descriptor Text” field to be the “Description” field. In this case, you would enter “Description” in this field.)
5. To show all hierarchical values for filtering (such as the multiple levels in “Topics”), check the field “Filter Values Are Hierarchical.”
6. In the Settings pop-up, complete the Display, Behavior, and Pagination tabs. Tip regarding image placement: If displaying multiple columns, select top position for images.

Important note about previewing your list: To support optimal performance in preview, the WCMS displays a limited number of items, so depending on the number of items in the JSON, you may see only a subset of the total pages/files in the JSON. This constraint exists only in preview mode.

6. Publishing

Remember to publish the JSON file(s) when you publish the page containing the dynamic sort-filter module.

Also, when new pages / files are created that are to be included in the JSON file, you will need to republish the JSON file when you publish those pages.

Tip: Consider setting up recurring publishing for the JSON file(s).

Setting Page Display Properties (Optional)

If you are using the Article Date field, you can have it display on each listed page by default.  If you are using a custom taxonomy, you can show the page’s custom category as a link to the sort-filter page. (See example page.  In the example “November 1, 2018” is the Article Date and “Posted In: Bicycles” is the custom category.)

Set these options in the defaults section of Folder Properties:

• Display Article Date on Page
• Show Categories/Taxonomy Terms on Page (Important notes: If you select a taxonomy here, do not override the field label for the taxonomy in the content export JSON file; also use the automatic option to pull the pages)
• Sort/Filter Page (the page where you inserted the sort-filter module)

At this time you cannot select a standard global taxonomy for displaying on the content page (e.g., content source, topics).

If your list pages have been published, don’t forget to republish them if you change these display options.

Building a Multi-Site Sort-Filter Module

There are two approaches to pulling content from multiple sites.

Using Multiple Content Export Files

One approach requires creating a content export file for each site and ensuring that all the files are set up consistently. (You can copy a file from one site to another using the Bulk Actions option in the WCMS content browser.) This approach works well if you are using the automatic option for exporting content.

When setting up the dynamic sort-filter module, select one content export file on the Data tab and then, on the Advanced tab, select the content export files for the additional sites.

If you are using custom taxonomies for filtering, a site manager must create the same filter taxonomies for each site.  For example, if you have a filter taxonomy called “series” that you are using to tag only two sites out of three to be included in the filter-sort list, the taxonomy must be created for all three sites and included in the content export files for all three.  You are not required to tag content with “series” terms in the third site, but the taxonomy must be in the site’s content export file.

Using a Single Content Export File

With the second approach, you can create one content export file and, within the file, use the manual option to select pages / files for export.  To select pages / files from other sites, use the “Search” tab on the Select Content Item screen, with “All CDC Sites” or “All My Sites” selected for the Site field.