List sorting and filtering
Often, the ability to search and filter lists of bio pages or other categorized content dynamically by the user is desired. The vt-list-sorter utility class was created to allow nested tags to be used as filters for lists where the parent tag sets the filter name and the child tags are what are applied to the content. The following instructions and example will demonstrate the features and functionailty of the utility.
1. In order for the vt-list-sorter class to work properly you will need a parent-child relationship with the tags you want to use to filter your list. The tags need to be direct children of their parent, but the parent does not have to be the root tag per the example image. The tags can be deeper in the heirarchy but they must be children of a parent tag or a single tag will be displayed as a filter.
In the example "People" and "Research Areas" are the parent filter category tags that then have associated tags that are on pages to be filtered within a list. This utility will work for existing tag structures, as long as the desired filter tags have a parent.
2. You will need to make sure the pages you want to filter are tagged with the appropriate child tags for each desired filter. The example page properties show the "People" role of "Administrative Support" as the filter tag for that bio page. Again, existing pages and tags can be used.
3. On the page where you want to display the list, you will need a List component with the following Display Options and List Properties settings.
Display options should be, Display type should be Column(s) with Title and Tags turned on. Other options can be activated, but those three must be used for this to work.
List properties need the CSS Class field with the vt-list-sorter class and the filter-[parentTagName] classes for each filter. The parentTagName should be the lowercase, hyphen separated name of the tag. This is what you set the name (not the title) filed to when you created the tag. This will also show up in the tag URL if you roll over the displayed tag, e.g., research-areas/cancer, filter-research-areas would be the class added. You can designate up to four (4) filters, no more.
You will want to build the list by Child pages or Descendant pages. The idea is you want ALL the results to show and then have the filters pare down the content. So, the limit needs to be set to a number larger than the expected results, or -1.
You do not want to build the list based on Tags and then filter via the same or child tags. That is already limiting the returned results and not letting the user control the filtering.
The ability to search for results within the list is limited at the moment. It does search the Title, Description, and Tag fields for matches. It is a literal search string, meaning it doesn't split keywords but looks for "research assistant" not "research" AND/OR "assistant". We will address this shortcoming with a future update.
Once everything is set up you will want to view the page as published so the filter and search utility class activates and you can make sure everything is working correctly before publishing the page. If you encounter a problem, please review these documents before creating a ticket using the "Request CMS Support" link on this site.