Arlo

Filters

Some Arlo JS Controls have the ability to be paired with the filter control. This allows you to give the users a way to apply a filter to a controls result set. Each filter control can contain multiple filters of different types, each of which has a range of configuration options that allow you to specifiy how users will see and interact with the control.

There are various types of filters, some that fetch their options from the API and others that are created on the client using javascript. This article will detail the different types of filters and when/how they can be used with other Arlo JS Controls.

This document describes how to create filter controls. If you want to filter a controls results using set values that the user can't adjust, see here.

Contents

Getting Started

The following code block contains a simple example of the configuration necessary to add a filter control to your webpage.
This alone is not enough to filter the results of another control, and requires further configuration to achieve this. Based on the general getting started guide.

                        
                        <div id="filter-target"></div>  
                           
                        <script src="//connect.arlocdn.net/jscontrols/1.0/init.js" charset="utf-8" defer="defer"></script>           
                 
                        <script id="filter-template" type="text/html">
                            //Filters are configured here
                        </script>
                        <script>
                               document.addEventListener("arlojscontrolsloaded", function () {
                                    var filterControl = {
                                        moduleType: "Filters",
                                        targetElement: "#filter-target",
                                        template: "#filter-template",
                                        filterControlId: 1
                                    };
                                    new ArloWebControls().start({
                                       "platformID": "demo.arlo.co",
                                        "modules": [
                                            filterControl
                                        ]
                                 });
                                });
                        </script>
                    

Explanation of the example configuration above:

  • Define a container for a filter control.
  • Load the Arlo JS Controls application code onto the page
  • Define a configuration for a filter control (moduleType: "Filters") that other controls can pair with using its filter control ID (filterControlId: 1). This control will be displayed in the DOM element with id #filter-target and rendered using the template in the script element with id #filter-template.
  • Start the application, specifying a platform ID of "demo", and the Filter Control configuration.

Code Editor Example

For an explanation about the demo control code editors and how you can integrate these demos into your own page, click here.

Filters Example - Paired with all in one upcoming event list

See the Pen Filters by Arlo Software Ltd. (arlosoftware) on CodePen.

Filter Control Configuration

To create a filter control, you should use a moduleType value of "Filters".
Example: moduleType: "Filters"

The filter control has the following config options, as well as the shared configuration options.

Field Type Default Description
facetType string "Event" Controls that use the eventsearch or eventtemplatesearch endpoints can use filters that are generated by retrieving facet data for those endpoints.
Depending which endpoint the paired control will use, you can configure the filter control to get its facet data from that endpoint.
The two options at this point are "Event" and "EventTemplate".
Example: facetType: "EventTemplate"
filterControlId string   Assign the control an ID that can be referenced by another control in order to filter its results.
Example: filterControlId: "filter1"
defaultValue string   The default value for the filter. This value will be applied every time the control is loaded.
Example: defaultValue: "Sydney"

Filter Control - Full Configuration Example

                        var filterControl = {
                            moduleType: "Filters",
                            targetElement: "#filter-target",
                            template: "#filter-template",
                            facetType: "EventTemplate",
                            filterControlId: "myfilter",
                        };

                        <script id="filter-template" type="text/html">
                            <%= showFilter({filterCode: "locname", 
                                    displayStyle: "ul", 
                                    config: {
                                        top:10, 
                                        orderby: "count" 
                                    }, 
                                    callbacks:{
                                    onBeforeRender: "beforeFilterRender", 
                                    onRender: "afterFilterRender"}, 
                                    showCount: false, 
                                    targetElement: "#my-filter-target" 
                                }) %>
                        </script>
                    

Custom Templates

You can write a custom template for your control using HTML combined with the Underscore library templating system.. See the general template guide for more information.

Available template properties

Filter control templates do not have any of their own properties. Instead, they are built using only the showFilter() template helper function, to which you can pass filter configuration information. You can still use arbitrary HTML alongside this function.

Template Helpers

The Show Filter function

This is the function you will use in your filter control templates to create filters of various types. The table below covers the configuration options that are available for it.

Filter view helper full example: showFilter({filterCode: "locname", config: {top:10, orderby: "count" }, displayStyle: "ul", callbacks:{onBeforeRender: "beforeFilterRender", onRender: "afterFilterRender"}, showCount: false, targetElement: "#my-filter-target" }) %>)

There are two types of filters, those that are created using the facets endpoint in the Arlo Public API, and ones created by the client side application. Depending on the endpoint you are filtering (events or event templates), you will have different filter facets available to use with in your filter control. Event filter facets are documented here and event template filter facets here.

The following are filter types not based on facets.

  • months - Allows you to filter events by month. It will create a list from the current month until 12 months from now. Only allows selection of a single month at a time.
  • search - Allows you to filter events by keywords. This filter can match on keywords found in various data fields of event objects, and is displayed as a HTML input.
  • onlineorvenue - Allows you to filter events by whether they are run online (e.g. webinar style) or at a venue.
  • traversablecategories - Creates a traversable category tree filter, which allows you to filter events, event templates and other category lists by category id

Configuration Options

Field Type Default Description
filterCode string   This is where you specify the type of filter you are creating. You will specify either the name of a facet from the API, or the name of a filter that is created on the client side.
config object   This option lets you specify advanced options for creating facet based filters.
  • "top": Only return the 'top' x results for the filter, where x is the config value passed as top.
  • "orderBy": Order the filter results by a specified property. You can set this to "count" or "label" ("label" is the default.)
displayStyle string select This option lets you change the style of the filter.
Months and OnlineOrVenue filters
  • "select": Will show the filter as a drop down from which you can select a single value.
  • "ul": Will show the filter as a list, from which you can select a single value.
Facet filters
  • "select": Will show the filter as a drop down from which you can select a single value.
  • "ul": Will show the filter as a list, from which you can select multiple values at a time.
  • "radios": Will show the filter as a set of radio buttons, from which you can select a single value.
  • "checkboxes": Will show the filter as a set of checkboxes, from which you can select multiple values at a time.
callbacks object   This options lets you provide callbacks for various stages of the filter control life cycle. These callbacks operate in the same was as callbacks for the event list.
  • "onBeforeRender": You can provide a callback here to manipulate the filter data before rendering it. This callback will be passed in the data structure that will be used in rendering the filter.
  • "onRender": You can provide a callback here for manipulating the rendered list after it has completed rendering. This callback will be passed parent dom element that represents the filter, as a jQuery object.
targetElement string   By default, the filter will be displayed in the same location as it is declared in the template. This options allows you to tell the filter to render in another location, which is specified by providing a css element id selector.
placeholderText string "Search" For the search filter only. Allows specifying the placeholder text that appears in the search input before the user enters a value.
Example: placeholderText: "Click here to search..."
displayLabel string   For the select and radio display styles. Allows specifying the label that appears on the filter before an option has been selected.
showCount boolean true Facet based filters are capable of showing a count of the total number of results for each of its options. This configuration option allows you to choose whether to display it or not.
Example: showCount: false
depth number This option is only available for the traversable categories filter. It allows you to specify how many levels deep of the category tree the user of the filter can traverse.
Example: depth: 2
monthFormat MomentJS format MMM This option is only available for the months filter. It allows you to set the format of the displayed months.
Example: monthFormat: 'MMM YYYY' e.g. July 2017
onlineOrVenueText object This option is only available for the onlineorvenue filter. It allows you to configure the values of the online or venue filter options.
The configuration option can have three configurable propertys: 'online', 'venue and 'all'.
Example: onlineOrVenueText: {online: "Live online", venue: "At a venue", all: "All delivery types"}

The Show Clear Filters Button function

This function will display a 'Clear filters' button which will allow the user to clear all the filters that have been applied.

            <%= showClearFiltersButton({clearButtonMessage: "Clear filters"}) %>
        

Configuration Options

Field Type Default Description
clearButtonMessage string   Specify the message for the clear filters button.
alwaysShow boolean false Enable this option to always display the clear filters button instead of only after a filter has been applied.

Example: Upcoming event paired with filter control

To create an event list with dynamic, user configurable filters (using html selects, checkboxes etc) you can combine your events list with a filters control. Filters are page controls that allow you to filter the list based on various data properties.

When filters are applied, they will update the url to reflect the current filter state. The resulting url will load the page with filters applied (for bookmarking or sending url to others). You can have multiple filter controls on the same page which could be listened to by one or more list controls.

In order to filter to your events list, you should provide an additional filter control configuration. In this configuration, you will define a unique filterControlId property. You will then define the same property in the event list configuration to tell it which filter control to listen to.

Below are step by step instrutions for pairing an events list control with a filter control.

Step 1

You have an events list configured with a filterControlId. Important: The filterControlId must contain no spaces and only alphanumeric characters.

                         var upcomingEventsControl = {
                            moduleType: "UpcomingEvents",
                            targetElement: "#upcoming-events-control",                    
                            top: 5,
                            filterControlId: "myFilter",
                            template: "#upcoming-events-template"             
                        };  
                    

Step 2

Now you should add an additional filter control configuration, configured using the same filterControlId.

At this point you should have exactly the same result as in step 1.

                                var filterControl = {
                                        moduleType: "Filters",
                                        targetElement: "#filters",    
                                        template: "#filter-template",                        
                                        filterControlId: "myFilter"                     
                                    }; 
                    

Step 3

Now you can use the filter view helpers to configure and place your filters inside the filters template. You can, of course, use arbirary HTML here to add additional elements.

                                 <script type='text/template' id='filter-template'>
                                    <%= showFilter({filterCode: "locname"}) %>
                                    <%= showFilter({filterCode: "templatecategory",
                                    config:{top:10, orderby: "count"},
                                    displayStyle: "ul",
                                    callbacks:{onBeforeRender: "beforeFilterRender",
                                    onRender: "afterFilterRender"} }) %>
                                    <br />
                                </script>