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

Versions Compared

Old Version 15

changes.mady.by.user user-3484a

Saved on

compared with

New Version Current

changes.mady.by.user user-3484a

Saved on

Key

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

...

The filters API is broken into two broad sections.

  • The Filters API - this refers to functionality concerned with the filter container object and all of the filters within it (could be one or more filters).
  • The Filters Object API - this refers to functionality concerned with an individual filter.


Filters Overview

Filters are used in Yellowfin to restrict the data returned in a report to the exact data that a user is interested in (for example, restricting time periods to just return data for the last quarter, or restricting to a list of countries that a user has responsibility for). You can learn more about filters in general and how to create them in this section.

...

Throughout this reference document and the FilterObject reference document, you will see references to different value objects.

...

If you have code that references a report filter by UUID it will be accessible in a report filters object by that UUID:

report.filters.getFilter('47fe96c2-5101-4b0d-9018-7d12a84d3519');

If that report and filter were then added to a dashboard, you would no longer be able to use the exact same code to access the dashboard filters. This is because it is possible for there to be multiple instances of the report and filter active on a dashboard together, so they are all referenced by their dashboard filter uuid.

dashboard.filters.getFilter('47fe96c2-5101-4b0d-9018-7d12a84d3519'); //Will return null 


...

Anchor
filtersapi
filtersapi

Property Reference

No properties associated with the Filter object need to be accessed to utilise the API functionality.

...

getFilter(filterId)

Returns

FilterObject

Description

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

...

Get the filter named “Demographic”

let filter = filters.get('Demographic');
console.log(filter.name, filter.uuid); //Output the name of the filter as well as its UUID


Get the filter by UUID

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. 

...

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

...

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

Example

We suggest building a You might want to build 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

...

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

...

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

...

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

...

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.

...

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

...

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

 filters.trigger('userClicked', { element: e.currentTarget } );
});


...

Anchor
eventreference
eventreference

...

  • 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.

...

  • 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.

...

  • 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.

...

  • 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.

...

  • 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();