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
- Code Editor Example
- Control Configuration
- Custom Templates
- Template Helpers
- Pairing with Filter control
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-targetand 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. The string couldn't contain "-". 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.
|
|
| displayStyle | string | select |
This option lets you change the style of the filter.
Months and OnlineOrVenue filters
Facet filters
|
| 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.
|
|
| 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"}
|
|
| displayCurrentCategoryName | boolean |
This option is only available for the traversablecategories filter style. It allows you to configure the control to display the currently selected category's name under the breadcrumbs.
|
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>