The Analysis Filter

This topic introduces developers to the Analysis Filter super-element. The Analysis Filter provides a mechanism that allows users to filter data at runtime and immediately updates visualizations dependent on that data.
 



About the Analysis Filter

The Analysis Filter allows users to apply filtering, at runtime, to the datalayers that support their visualizations. Changes made to the filtering immediately causes the visualizations to be updated.

As a super-element, the Analysis Filter has an interface that users can interact with at runtime. The interface can be configured and restricted depending on the use-case requirements.

     

The example above shows the Analysis Filter in use with a data table. If the user checks or unchecks one of the filters, the data table will be refreshed accordingly (the refresh can include the entire page or just selected elements). The Analysis Filter has two developer-controlled viewing modes: Simple and Design.
 

In Simple view, shown above, users can click an existing filter description to display input controls and change the filtering value.

In Design view, a "gear" icon is displayed; clicking it opens a control panel, shown above, that can be used to manage filters.

The controls provide a variety of tools for creating, editing, grouping, and removing filters, as shown above.

When using "In List" or "Not In List" comparisons in filters, multiple values can be entered, separated by commas. However, the values themselves may include commas, causing incorrect comparisons.
 

To address this, values for these types of filters are now represented in the controls by visual "pills" that enclose the complete value, as shown above. The filter uses the complete string within the pill during its comparison operation.
 

Pills with included commas are created by entering the first part of the value and pressing comma. This creates a blue pill as shown above. Then place your cursor inside the pill and type the rest of the value. Press tab to exit the pill and repeat the process for the next value, if desired.

The Analysis Filter is usually used to compare column data and a value you enter, but you can also directly compare the values in two data columns:
 

To do this, first select a Filter Column, as shown above, and a supported Comparison operator (= < > <= >= Not=). Then select the second column from the list displayed when you click the [] button, or enter the column name within square brackets.
 

Retaining User Settings

Filters users create or modify can be saved between sessions and made available to them during their next session (this is discussed in more detail below).

Back to top

Using the Analysis Filter Wizard

Logi Studio includes a wizard that can assist you in creating an Analysis Filter. The wizard assumes that you've already added an appropriate Connection element in the _Settings definition and configured it, and have added a DataLayer element that uses it.
 

As shown above, the wizard can be started by selecting and then right-clicking most datalayer elements, and using the context menus to select "Add an Analysis Filter". The wizard will open:
 

Select the columns that you want to be able to use for filtering the data. Columns that are not selected here will not appear as filtering choices in the Analysis Filter interface. Click Next, and then Finish.

The wizard will insert the necessary Analysis Filter family elements.

 The wizard may also insert other elements, if they're necessary and not already in place. For example, if you run the wizard by selecting a datalayer in a Dashboard panel and there is no Panel Parameters element already in use, the wizard will insert one and then insert the Analysis Filter elements under it.

Back to top

Analysis Filter Attributes

The Analysis Filter element has the following attributes:
 

Attribute

Description

ID

(Required) Specifies a unique identifier for this element.

Case Sensitive
 

Specifies whether comparisons will be case-sensitive. For elements using DataLayer.ActiveSQL, this attribute value may be set to DataSourceCollation, causing case-sensitivity to be defined by the database column's "collation", which may be case-sensitive or not. This option can provide better performance for case-insensitive filters.

For an Analysis Filter used with DataLayer.Active SQL and Sql Compare Filter elements, the default is DataSourceCollation. The default is True for all other elements.

Disable Design View

Specifies whether to display the filter in Design view mode. This allows the user full control of filter creation and updates. Normally, a report run without an Analysis Filter Save File specified initially appears in Design view. When redisplayed, the report's Analysis Filter appears in Simple view.

Disabling Design view causes the Analysis Filter to appear only in the Simple view.

Default Value: False.

Disable Simple View

Specifies whether to display the filter in Simple view mode. This allows the user to do easy updates of existing filters. Normally, a report run without an Analysis Filter Save File specified initially appears in Design view. When redisplayed, the report's Analysis Filter appears in Simple view.

Disabling Simple view causes the Analysis Filter to appear only in Design view.

Default Value: False.

Filter Caption Element ID

Specifies the ID a Label element that will display a one-line description of the filter(s) in use, allowing filtering criteria to be shown anywhere in the report page. To use it, add a Label element to the report and give it a unique ID, leave its Caption attribute blank, and specify its ID in this attribute. The Label's Caption will be filled at runtime with the filter's description/caption. For example: [Customer ID] = VINET

Filter List Location

Specifies whether, when using the Design view, the list of defined filters appears beneath the input controls or beside them to the right. This allows management of the space the filter uses.
Default Value: Bottom (beneath the controls)

No Filters Simple Caption

Specifies text to be displayed in Simple view when no filters have been defined.
Default value: (No filters)

Refresh Element IDs

Specifies, in a comma-separated list, the IDs of the elements to be refreshed within the page, using AJAX, when a filter is checked or unchecked or a filter definition or value is changed. If left blank, then the entire page will be refreshed when a filter value changes.

Request Forwarding

Set to True to pass all request parameters received by this page to the next page. Values set using a Default Request Values element are not forwarded. Default value: False.

 Request parameters cannot be forwarded if there is an Input element with the same name on the page, because this would result in an attempt to pass two values with the same name.

Save File

Specifies the fully-qualified file path and name of an XML file where user runtime filter changes will be saved. Must include the .xml file extension and can use an @Function token.

Example: @Function.AppPhysicalPath~\Filters\AFSaveFile.xml
Example: @Function.AppPhysicalPath~\UserFilters\@Function.UserName~.xml

Save files can also be stored in a database, see Introducing Bookmarks.

Save File Starter

Specifies the fully-qualified file path and name of an XML file to be used as the initial Save File in cases when the Save File does not exist yet. For example, when the Save File is different for each user, the Save File Starter file can include a set of default filters.

Create a Save File Starter file by setting a Save File value, then defining filters to create the desired default set, then moving and/or renaming the Save File into the Save File Starter location.
Example: @Function.AppPhysicalPath~\Filters\InitialFilters.xml

Security Right ID

If specified, access to this element is controlled via Logi security. Specify the ID of a Right defined in the application's settings/security section. Only users that Right will be able to see the element. Multiple Right IDs may be entered in a comma-separated list. In that case, the element will be visible to users with any one of the Rights specified.

Template Modifier File

Specifies the full name of a template modifier file to be used to alter the Analysis Filter element. See the section below for more information about template modifiers. The template modifier file can be in any folder accessible to the web application; if a fully-qualified file path is not provided in this attribute value, then the application expects it to be in your project's _SupportFiles folder.


The columns that can be selected in the Design view control panel when creating filters are defined by Analysis Filter Column elements, one per column, that are added as children of the Analysis Filter element.

Back to top

Analysis Filter Column Attributes

The Analysis Filter Column element has the following attributes:
 

Attribute

Description

Column Header

(Required) Specifies the text describing the column that will appear in the list of columns that can be selected when defining a filter in Design view. This text also appears in the filter description, between square brackets, in Simple view. Allows you to specify a "user-friendly" name for the column.

Data Column

(Required) Specifies the name of a column in the datalayer.

Data Type

(Required) Specifies the data type of the column specified in the previous attribute.

ID

(Required) Specifies a unique identifier for this element.

Format

Specifies a format for values or percentages displayed. More information can be found in Format Data.

Popup Values for Filter

Specifies text to be displayed in Simple view when no filters have been defined.
Default value: (No filters)

Security Right ID

If specified, access to this element is controlled via Logi security. Specify the ID of a Right defined in the application's settings/security section. Only users that Right will be able to see the element. Multiple Right IDs may be entered in a comma-separated list. In that case, the element will be visible to users with any one of the Rights specified.


Back to top

Using the Analysis Filter Elements

The Analysis Filter works by adding an automatically-generated Condition Filter element beneath existing datalayer elements (Sql Condition Filter for DataLayer.ActiveSQL). To implement it, you need to add an Analysis Filter element (and its child elements) and the Analysis Filter Insert element. Here's an example:

The report definition shown above includes a data table, with datalayer and columns. An Analysis Filter element has been added and configured with an element ID. This configuration will cause the whole page to be refreshed when the filter changes.

If, instead, we wanted to refresh only the data table and not the whole page, we could enter its element ID in the Refresh Element IDs attribute.

Next, we'll add Analysis Filter Column elements beneath the Analysis Filter element. Each of these adds a column into the list of columns that can be used when defining a filter in Design view. It's important to accurately specify the data type as this affects which user controls are displayed later.

Additional Analysis Filter Column elements have now been added and, as shown above, you can see how they produce entries in the drop-down list of filter columns in Design view. In addition, an optional Wait Panel element has been added, in case the filtering operation takes some time to complete.

Date- and DateTime-type columns can be configured, using the Popup Values for Filter attribute, to offer users different filter value selection methods, in addition to direct entry: selection from a list, from a calendar, and from a time picker. Different input controls are displayed for each method:
 

 For illustration purposes, in the example above, we've created separate filters for each of these methods - a real implementation would probably not include this. The Order Date column can only be represented by one Analysis Filter Column element so to produce the variety of selection methods in the example, we added columns to the datalayer using Calculated Column elements, configured using @Data.OrderDate~ tokens, and then added Analysis Filter Columns for these calculated columns.
 

When working with Date- and DateTime-type data, you can select a comparison against a specific date or a "Sliding Date" time window. A drop-down list of options appears, with date options, as shown above.

 If the Globalization element's First Day of Fiscal Year attribute has been set in the _Settings definition, the drop-down list will include a set of Fiscal options, highlighted above.
 

Finally, we've added an Analysis Filter Insert element, as shown above, beneath our table's datalayer. Its sole attribute is configured with the ID of the Analysis Filter element. This is the element that connects the datalayer and filter.

We now have a fully-functional filtering mechanism for our data table.
 

Passing Parameters

You may need to pass parameters when the Analysis Filter updates the page or visualization. The element's Request Forwarding attribute allows you to pass all the request parameters received by the page (but doesn't include any values from Default Request Parameters). You can also be more selective about what's passed by using a Link Parameters element as a child of the Analysis Filter.

More information about passing parameters can be found in Pass Information.

Back to top

Saving Individual User Settings

A described earlier, the Analysis Filter will automatically save a user's runtime filter changes during their session, if the Save File attribute is set. The file specified will be created if it does not exist but its containing folder is not automatically created. You must ensure that the account used by the web server to run the application has "Write" permission to the folder (usually, creating the folder under the application's root folder will handle this).

You can also save separate configurations for each user that survive their sessions. If Logi Security is being used, include the @Function.UserName~ token as part of the Save File name. If not, you can use @Function.GUID~ to generate a unique file name for the user and then save the file name as a cookie in the user's browser.

Back to top

Filtering with Query String Parameters

Special reserved query string parameters can be used to manipulate the Analysis Filter.
 

Remove all Filter Definitions

All filter definitions can be removed by calling the report with the rdAfReset parameter set to True.
 

In the example above, a Label has been added to a report as a link that clears all filters. The Target.Report element is set to Current Report and the Link Parameters element is used to pass the rdAfReset parameter.
 

Force a Page Refresh with Current Filter Values

You can force a complete page refresh by calling the report with the rdAfRefresh parameter set to True.
 

Define a New Filter

You can define and apply a new filter by sending a full set of query string parameters. The parameters are:

    rdAfCommand="FilterSet"
    rdAfFilterColumn_<AnalysisFilterID>="<ColumnName>"
    rdAfFilterOperator_<AnalysisFilterID>="<Operator>"
    rdAfFilterValue_<AnalysisFilterID>="<FilterValue>"
    rdAfMode_<AnalysisFilterID>="<ViewMode>"
    rdAnalysisFilterID="<AnalysisFilterID>"

where:

  • <AnalysisFilterID> is the ID of an existing Analysis Filter element in the report being called
  • <ColumnName> is the name of a column that has an Analysis Filter Column element configured for it
  • <Operator> is one of the operators available in Design view
  • <FilterValue> is the data value on which to filter the column
  • <ViewMode> specifies the filter display mode to be used, Simple or Design

If one or more filters already exist for the specified column then when these parameters are applied, the value of the first existing filter will change. An additional filter will not be created.

Here's an example for comparison purposes, using the XML source for these parameters defined in a Link Parameters element. They're based on the filter examples used in earlier sections of this topic:
 

<LinkParams
  rdAfCommand="FilterSet"
  rdAfFilterColumn_myAnalysisFilter="CustomerID"
  rdAfFilterOperator_myAnalysisFilter="="
  rdAfFilterValue_myAnalysisFilter="VINET"
  rdAfMode_myAnalysisFilter="Simple"
  rdAnalysisFilterID="myAnalysisFilter"
/>


To make the code dynamic, tokens can be used to provide values for the parameters: 

  rdAfFilterValue_myAnalysisFilter="@Request.FilterOnThis~"


Back to top

Using Analysis Filters in Dashboards

Analysis Filters can be used to filter data for visualizations in Dashboards, in individual panels and globally.

 Panels derived from an Analysis Grid having an Active Query Builder child element can have the Analysis Filter automatically generated. This enables the user to filter data for panels created from a metadata-driven Analysis Grid, without the need to add the Analysis Filter elements described below. This is controlled by the Dashboard element's Auto Panel Filters attribute.
 

Filtering Individual Panels

As you might expect, the data used in a dashboard panel can be filtered with an Analysis Filter.
 

As shown above, implementing Analysis Filters in a panel is simple. In the dashboard panel, add a Panel Parameters element with a child Analysis Filter element. Configure the Analysis Filter, and its child elements, just as described in the earlier sections of this topic. Don't forget to add an Analysis Filter Insert element beneath your datalayer.
 

Once the Analysis Filter has been added, clicking the panel's "gear" icon will display a menu that has an "Edit" option. This option will open the Panel Filter panel, as shown above. The controls displayed in it will depend on the view mode, Simple or Design, configured in the Analysis Filter attributes and have been discussed earlier in this topic.

Adding or removing filters will immediately filter the data in the dashboard panel accordingly.
 

Adding a Global Filter

You can also add a "global" filter, one that affects the data used in multiple dashboard panels at once. This type of filter functionality is automatically available when there are multiple dashboard panels containing Analysis Filter elements, or multiple panels created from a metadata-driven Analysis Grid, and is controlled by the Dashboard element's Auto Global Filter attribute.
 

The example dashboard shown above has two panels, each of which has an Analysis Filter configured for it. Both visualizations use data from the ShipCountry column in their datalayers.
 

We can create a global filter by clicking the gear icon for the dashboard tab, as shown above, and selecting the Add Global Filters pop-up menu item.
 

The Global Filter panel will be displayed, as shown above. The controls displayed in it will depend on the configured view mode and have been discussed earlier in this topic. Adding a global filter will immediately update the data in both dashboard panels.
 

A global filter description will appear at the top of the tab and can be used as a link to re-open the Global Filter panel.

In addition, when you hover your mouse cursor over this description, the panels affected by the global filter will be highlighted, as shown above.

If you uncheck all of the defined filters in Simple view and close the panel, no descriptions are shown but the Filter icon will remain and you can click it to re-open the panel.
 

Global Filtering using Chart Data Points

You can also create a global filter in a dashboard by selecting data points in a chart. This is behavior similar to that seen when you use Chart Canvas chart and Input Selection elements together. Let's see it in action:
 

Once again, we have an example with two dashboard panels, one with a chart and one with a table, shown above. When a bar in the chart is clicked, a global filter is created automatically and three other things happen:

  1. A Filter Description appears at the top of the dashboard tab. This can be clicked to edit the global filter.
  2. The color of the selected chart bar changes to indicate it's included in a filter.
  3. The data for the table in the second panel is filtered.

 Note how this is different from the previous global filtering example: the chart that was clicked is not filtered.

Clicking the same chart bar a second time will cancel the filter related to that data. Clicking another bar will add additional criteria to the global filter.

Clicking the Filter Description at the top of the dashboard tab will cause the automatically-generated Global Filter panel to be displayed. As before, the controls displayed in it will depend on the view mode, Simple or Design, configured in the Analysis Filter attributes.
 

For chart types that support it, you can also create a global filter by dragging the cursor to select a range of values, as shown in the Line chart above. This is similar to using Chart Canvas chart and Input Selection Range elements.

More information about dashboards can be found in Logi Info Dashboard .

Back to top

Customizing Analysis Filter Appearance

Analysis Filter appearance can be changed most easily by applying a theme to the report definition. Most of the screen shots in this document were taken with the Signal theme applied. You can also create your own custom theme, based on a standard theme, using the Theme Editor tool. For more information, see Work with Themes.
 

Changing Appearance Using Style Classes

Analysis Filter appearance can be also customized using style classes and the standard classes for it are taken from the Analysis Grid style sheet:

    <yourAppFolder>\rdTemplate\rdAnalysisGrid\rdAg10Style.css

Developers can override classes in this style sheet by copying them to their application style sheet and modifying them there.

  Do not make changes in the standard style sheet in the rdTemplate folder.
 

Changing Appearance Using Template Modifiers

The Analysis Filter element uses a "template file" to define certain element properties that are not otherwise available as attributes to the developer for modification. These include language- and culture-specific Caption attributes that you may want to change to match the locale (or you may simply want to change the captions to better suit your application).

The Analysis Filter element's Template Modifier File attribute identifies a custom XML file developers can create containing elements that will override the same elements in the template file.

For example, the Analysis Filter template file:

    <yourAppFolder>\rdTemplate\rdAnalysisFilter\rdAfTemplate.lgx

contains several Label elements. One of them has an ID of "lblFilterColumn_rdAfID"; this controls the caption text that appears beside the Filter Column drop-down list in Design view. This text can be modified by changing the Caption associated with that Label element. To change the text from its default "Filter Column" to "Column to filter by", create your own XML file, identify it in the Template Modifier File attribute, and add this code to it: 

<TemplateModifier>
    <SetAttribute ID="lblFilterColumn_rdAfID" Caption="Column to filter by" />
</TemplateModifier>

You can set the attributes for any number of elements in this file; examine the rdAfTemplate.lgx file to learn the ID and Caption attributes available. The template modifier file can be in any folder accessible to the web application; if a fully-qualified file path is not provided in the Template Modifier File attribute value, then the application expects the file to be in its _SupportFiles folder.

More detailed information about template modifier files can be found in Template Modifier Files.

Back to top