Date: Fri, 29 Mar 2024 09:23:01 -0600 (MDT) Message-ID: <2104473185.2959.1711725781358@confluence-external-wiki> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_2958_1081868150.1711725781358" ------=_Part_2958_1081868150.1711725781358 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
The filters API is broken into two broad sections.
Filters are used in Yellowfin to restrict the data returned in a r= eport to the exact data that a user is interested in (for example, restrict= ing time periods to just return data for the last quarter, or restricting t= o a list of countries that a user has responsibility for). You can learn mo= re about filters in general and how to create them in this section.
Dashboard and Report objects will both contain the object <= em>filters. This object will contain any filters th= at have been set up as user prompt filters, these are filters that a user c= an change at run time. Any hardcoded filters on a report are not able to be= accessed through the API.
The filter object can be accessed as follows:
For a report:
report.filters
And for a dashboard:
dashboard.filters
This Filters API contains all of the available user prompt filters for a p=
iece of content as well as various methods that allow developers to manipul=
ate the filter. It also can fire a number of events that allows your applic=
ations to react to changes within the filters.
A filter will typically relate to a Database column that is to be = restricted, such as a specific date field, a dimension field (countries, pr= oducts) or even a metric (sales, costs, margin). Values are set against a f= ilter and these values are passed through to the Database query in order to= restrict the data being returned.
Filter values can have two states - Staged (or no= rmal) and Applied.
Applied values are the values that are currently being used by the report or dashboards to filter the query result.= Anytime the API uses getAppliedValue it is referring to these val= ues.
A staged filter value is a value that is set in the Filter but not= yet applied to the report output. For example, in the filter =E2=80=9CDemo= graphic=E2=80=9D when a user selects the value =E2=80=9CAdventure=E2=80=9D = this sets the staged value of that filter to =E2=80=9CAdventure=E2=80=9D. A= nytime the API uses setValue or getValue, it is referring= to the staged value of the filter. This is not reflected in the report or = dashboard until the filters are applied.
Some filters will also have defaultValues, these are alwa= ys read only.
Throughout this reference document and the FilterObject reference document<= /a>, you will see references to different value objects.
E.g. valueOne, valueTwo, appliedValueOne.
Yellowfin uses these values to correctly apply the filter values w= hen running a report.
ValueOne will refer to the value of a filter that= has a single input option (Equal To, Different From, etc). It will also be= used as the lower value in a between operator (Between and Not Between) so= when using a between operator valueOne should always be lower than valueTw= o.
ValueList is the value used for a list operator (= In List, Not In List) and is an array of string or number values.
From a functionality point of view, there is very little differenc= e between a report filter and a dashboard filter object. A dashboard filter= object serves many reports as it will have linking objects that allow many= reports to be linked to a single filter.
When building a dashboard in Yellowfin, users will first add repor= ts to the dashboard and then add filters from those reports to the dashboar= d. This is described here<= /a>.
A filter added to a dashboard will be allocated its own unique fil= ter id, even though it is derived from a report filter in the first instanc= e. This Dashboard Filter will continue to maintain a reference to the repor= t filter from which it was based. Changes made to report filters will flow = through to dashboard filters.
If you have code that references a report filter by UUID it will b= e accessible in a report filters object by that UUID:
report.filters.getFilt= er('47fe96c2-5101-4b0d-9018-7d12a84d3519'); |
If that report and filter were then added to a dashboard, you woul= d no longer be able to use the exact same code to access the dashboard filt= ers. This is because it is possible for there to be multiple instances of t= he report and filter active on a dashboard together, so they are all refere= nced by their dashboard filter uuid.
dashboard.filters.getFilter(= '47fe96c2-5101-4b0d-9018-7d12a84d3519'); //Will return null |
No properties associated with the Filter object need to be accesse=
d to utilise the API functionality.
Fetches a FilterObject for the passed filterId. If there is no mat= ching filterId then null will be returne= d.
filterId - (String, Number)
The Name or the UUID of the filter you wish to access.
Get the filter named =E2=80=9CDemographic=E2=80=9D
let filte=
r =3D filters.get('Demographic'); |
Get the filter by UUID
let filte=
r =3D filters.get('47fe96c2-5101-4b0d-9018-7d12a84d3519'); |
Object - {String, FilterObject}
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 Fi= lter UUID.
This function is useful for observing which filters are available =
in the FiltersAPI. If you are looking for a specific filter it is recommend=
ed using filters.getFilter(filterId) rat=
her 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) i=
nstead.
Nothing.
Iterates over all the filter objects in a FilterAPI, calls the pas= sed fn with an individual FilterObject being passed to it on each iteration= .
fn - Function to call for each iteration of the loop.
You might want to build a list of all of the applied values:<= /span>
let appliedFilterValues =3D =
[]; |
This would create a list of applied filter values with the filter'= s name and uuid also included in the object.
Boolean
Returns true if there are any User Prompt filters on the content. = Returns false otherwise.
Call a custom filter panel generator based on if the filters API h= as filters or not.
if(filter=
s.hasFilters()) { |
Nothing.
Clears the values and immediately applies the now empty values, fr= om the FilterObject relating to the passed filterId= . If no filter is found matching that filterId, nothing will hap= pen.
filterId - (String)
UUID or Name of the filter you wish to clear.
Nothing.
Clears the values and applies the empty filter values in every Fil= terObject contained within the FiltersAPI.
Nothing.
Copies all the staged values to the applied filters object and run= s any reports that are affected by this. Triggers the applied event.=
Set Average Age at Camp and Demographic and then apply them:
let demog=
raphic =3D filters.getFilter('Demographic'); |
Or apply filters when a button on the page is clicked:
document.=
querySelector('div#applyButton').addEventListener=
('click', function(e) {=
|
Promise.
Reloads filter data from the server. Promise is resolved once the = filters have been loaded.
Nothing.
Resets all filters back to their default values.
filters.resetFiltersTo= Default(); |
Number.
Creates a listener on an event which will call the
When an event is set up, a unique ID is assigned to it which is re=
turned as the result of this function. This ID can be used by the
See the event reference section for details about the even= ts that the API will trigger itself.
It is also possible for developers to trigger their own events (se= e .trigger()) which can also be listened to using this function.
Create a listener on the changed object and remove it once the eve= nt occurs once:
let event=
ListenerId =3D filters.addEventListener('changed'=
, function(event) { |
Nothing.
Removes the callback function associated with the passed listenerI= d. This will mean that when the event associated with that callback functio= n occurs, that callback will not be fired anymore.
let event=
ListenerId =3D filters.addEventListener('changed'=
, function(event) { |
Nothing.
Triggers an event on the FiltersAPI and calls any listener functio= ns that have been created for that event. This can be used to trigger custo= m events that you may have set up for the application.
When using a custom filter input we could trigger a filter click e= vent, so that another part of the application could react to that.= p>
//Add a 'userClick' li=
stener to the filter object, which we will set up a trigger for later on.=
span> |
There are a number of events related to actions a user takes or fu= nctions that are called, that will automatically trigger within the FilterA= PI. All of these events will contain the following structure:
Triggered when any of the FilterObjects within the FiltersAPI chan= ges its staged values.
Event - Object
Contains
let filte=
rs =3D report.filters; |
Triggered when any of the filters within the FiltersAPI has differ= ent values applied to it. This happens when the user hits the apply button,= or the applyFilters function is called.
Event - Object
Contains
let filte=
rs =3D report.filters; filters.applyFilters(); = |
Triggered when any of the FilterObjects within the FiltersAPI = are reset.
Event - Object
Contains
let filte=
rs =3D report.filters; |
Triggered when any of the FilterObjects within the FiltersAPI are = cleared.
Event - Object
Contains:
let filte=
rs =3D report.filters;
|