Like what you see? Have a play with our trial version.

Error rendering macro 'rw-search'

null

Versions Compared

Old Version 12

changes.mady.by.user user-3484a

Saved on

compared with

New Version 13

changes.mady.by.user user-3484a

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Function Reference

getFilter(filterId)

Returns

FilterObject

Description

Fetches a FilterObject for the passed filterId. If there is no matching filterId then null will be returned.

...

let filter = filters.get('47fe96c2-5101-4b0d-9018-7d12a84d3519');
console.log(filter.name, filter.uuid); //Output the name of the filter as well as its UUID



getAllFilters()

Returns

Object - {String, FilterObject}

Description

Returns an Object that contains all of the user prompt filters for the content that the FiltersAPI is attached to. This object is keyed by Filter UUID. 

Notes/Limitations

This function is useful for observing which filters are available in the FiltersAPI. If you are looking for a specific filter it is recommended using filters.getFilter(filterId) rather than getAllFilters()[uuid] as getFilters can accept a UUID or a name. If you wish to iterate over all filters, we recommend using filters.forEach(fn) instead.


forEach(fn)

Returns

Nothing.

Description

Iterates over all the filter objects in a FilterAPI, calls the passed fn with an individual FilterObject being passed to it on each iteration.

Parameters

fn - Function to call for each iteration of the loop.

Example

We suggest building a list of all of the applied values:

let appliedFilterValues = [];
filters.forEach(filter => {
appliedFilterValues.push(Object.assign({
name: filter.name,
uuid: filter.uuid,
      }, filter.appliedValues));

This would create a list of applied filter values with the filter's name and uuid also included in the object.


hasFilters()

Returns

Boolean

Description

Returns true if there are any User Prompt filters on the content. Returns false otherwise.

Example

Call a custom filter panel generator based on if the filters API has filters or not.

if(filters.hasFilters()) {
     generateMyCustomFilterPanel(filters);
}


clearFilter(filterId)

Returns

Nothing.

Description

Clears the values and immediately applies the now empty values, from the FilterObject relating to the passed filterId. If no filter is found matching that filterId, nothing will happen.

Parameters

filterId - (String) 

UUID or Name of the filter you wish to clear.


clear() 

Returns

Nothing.

Description

Clears the values and applies the empty filter values in every FilterObject contained within the FiltersAPI.


applyFilters()

Returns

Nothing.

Description

Copies all the staged values to the applied filters object and runs any reports that are affected by this. Triggers the applied event.

Examples

Set Average Age at Camp and Demographic and then apply them:

let demographic = filters.getFilter('Demographic');
let ageAtCamp = filters.getFilter('Average Age at Camp');

demographic.setValue(['Adventure']);
ageAtCamp.setValue([15, 35]);

filters.applyFilters();


Or apply filters when a button on the page is clicked:

document.querySelector('div#applyButton').addEventListener('click', function(e) {
     filters.applyFilters();
});



loadFilters()

Returns

Promise.

Description

Reloads filter data from the server. Promise is resolved once the filters have been loaded. 


resetFiltersToDefault()

Returns

Nothing.

Description

Resets all filters back to their default values. 

Examples

filters.resetFiltersToDefault();


addEventListener(eventName, callbackFunction)

Returns

Number.

Description

Creates a listener on an event which will call the callbackFunction whenever that particular event occurs. 

When an event is set up, a unique ID is assigned to it which is returned as the result of this function. This ID can be used by the removeEventListener function to remove the callback when you are done with it. If you are writing an application that requires loading and unloading reports, it is recommended that you keep track of these listenerIds so that you can remove them when no longer needed.

See the event reference section for details about the events that the API will trigger itself.

It is also possible for developers to trigger their own events (see .trigger()) which can also be listened to using this function. 

Example

Create a listener on the changed object and remove it once the event occurs once:

let eventListenerId = filters.addEventListener('changed', function(event) {
     console.log('One of my filters changed');
     filters.removeEventListener(eventListenerId);
});


removeEventListener(listenerId)

Returns

Nothing.

Description

Removes the callback function associated with the passed listenerId. This will mean that when the event associated with that callback function occurs, that callback will not be fired anymore. 

Example

let eventListenerId = filters.addEventListener('changed', function(event) {
     console.log('One of my filters changed');
     filters.removeEventListener(eventListenerId);
});



trigger(eventName, eventData)

Returns

Nothing.

Description

Triggers an event on the FiltersAPI and calls any listener functions that have been created for that event. This can be used to trigger custom events that you may have set up for the application. 

Example

When using a custom filter input we could trigger a filter click event, so that another part of the application could react to that.

//Add a 'userClick' listener to the filter object, which we will set up a trigger for later on.
filters.addEventListener('userClick', function(event) {
    console.log('A user clicked on the element ' + event.element + ' which is tied to this filter');
});
//Get the custom filter list from the DOM and create a click listener on that which will trigger userClicked events on the filter
let myCustomFilterList = document.querySelector(‘div#customFilterList’)
myCustomFilterList .addEventListener('click', function(e) {
    filters.trigger('userClicked', { element: e.currentTarget } );
});

Anchor
eventreference
eventreference

Event Reference

There are a number of events related to actions a user takes or functions that are called, that will automatically trigger within the FilterAPI. All of these events will contain the following structure:

  • eventName - String - The name of the event that has been triggered. 
  • filterEvents - Array{Object} - An array of events that comprised this filter list change event. The object will contain at least the following.
    • uuid - UUID of the filter that changed.
    • filter - FilterObject that caused this event to trigger.
    • Certain other filter events can contain more information. You can see the documentation in FilterObject for more in depth details on the Event object for each event.


changed

Description

Triggered when any of the FilterObjects within the FiltersAPI changes its staged values.

Parameters

Event - Object

Contains

  • eventName - “changed”
  • filterEvents - Array{Object} - Array of change event objects that have contributed to the filtersAPI triggering the changed event.
Example

let filters = report.filters;

filters.addEventListener('changed', function(event) {
        console.log(event.eventName); //'changed'
        console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject, changed: Object, previous Object }, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);


applied

Description

Triggered when any of the filters within the FiltersAPI has different values applied to it. This happens when the user hits the apply button, or the applyFilters function is called.

Parameters

Event - Object

Contains

  • eventName - “applied”
  • filterEvents - Array{Object} - Array of change event objects that have contributed to the filtersAPI triggering the applied event
Example

let filters = report.filters;

filters.addEventListener('applied', function(event) {
        console.log(event.eventName); //'applied'
        console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject, changed: Object, previous Object }, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);

filters.applyFilters();


reset

Description

Triggered when any of the FilterObjects within the FiltersAPI are reset.

Parameters

Event - Object

Contains

  • eventName - “reset”
  • filterEvents - Array{Object} - Array of reset event objects that have contributed to the FiltersAPI triggering the reset event.
Example

let filters = report.filters;

filters.addEventListener('reset', function(event) {
        console.log(event.eventName); //'changed'
        console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject}, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);
filters.resetFiltersToDefault();

filters.getFilter('Demographic').reset(); //Trigger reset on an individual filter


cleared

Description

Triggered when any of the FilterObjects within the FiltersAPI are cleared.

Parameters

Event - Object

Contains:

  • eventName - “cleared”
  • filterEvents - Array{Object} - Array of cleared event objects that have contributed to the filtersAPI triggering the cleared event.
Example

let filters = report.filters;

filters.addEventListener('reset', function(event) {
        console.log(event.eventName); //'changed'
        console.log(event.filterEvents); //[{ uuid: 'a-filter-uuid', filter: FilterObject}, {....}]
});

filters.setFilterValue('Demographic', ['Adventure']);

filters.applyFilters();