Filters

Filters are one of the most advanced features of the widget-editor. They let users select the specific piece of data they need to build a compelling visualization.

The widget-editor provides three types of filters: generic filters, a geographic filter and end-user filters. Below, you'll find an explanation for each of the types, as well as some technical details about them.

Table of content

• Generic filters
• Geographic filter
• End-user filters

Generic filters

When creating a widget, the user may use the filters to remove certain data points that are not relevant to the visualization. The filters work with any columns of the dataset, even if they are not used for the axes or color tagging of the visualization.

The user can use several filters at once, and each of them may use different criteria based on the type of data of the associated columns. Currently, the widget-editor supports three types of columns: string, number and date.

These filters are serialized as the filters key of the paramsConfig object. The type of a serialized filter is SerializedFilter.

Usually, when the user selects a column, they are required to then select an operation i.e. a criteria to exclude (or include) rows. But alternatively (or in addition), they can choose to exclude rows based on whether the value for the column is null. This means that a serialized a filter may not always have an operation value, but in that case, the notNull attribute must be set to true.

If you want to know more about the types of operations available for each column type, as well as how their values are serialized, have look at the list of operations.

Geographic filter

When the user uses the geographic filter, they indicate that they want to filter out some data points based on a geometry.

This filter is not always present in the editor: it can be disabled by the host app (using the disable prop) or it may not be available because the dataset doesn't support geographic data (geoInfo attribute of the dataset payload set to false).

When it is present, the filter is a list of areas the user can select from. Only one area can be used at a time. The list combines two types of areas: predefined and user areas. These come from the adapter's getPredefinedAreas and getUserAreas methods.

To get the user areas, the adapter may need some form of authentication. If authentication is not possible, and the widget-editor is restoring a widget that was built with a geographic filter based on a user area, then the editor may display the area as “Custom area” in the interface. This is the case for the Resource Watch's adapter.

When serialized, this filter is saved as the key areaIntersection and it is assigned the ID of the area (string), if any.

End-user filters

End-user filters are a special kind of filters: not only can they be configured in the widget-editor, but they are also displayed in the Renderer and are part of the Vega specification of the widgets.

The idea is that, in the editor, the user can select columns that will be used as filters, but they do not select the values of these filters. Instead, the filters will appear in the Renderer, and the end-user will be able to dynamically filter the visualization.

The caveat of this feature is that the options for the filters are determined when the widget is created or updated in the widget-editor. This means that if the data of the dataset is updated since the widget has been last modified, the values of the filters may not be all relevant or exhaustive.

This feature can also be disabled by the host application, setting the disable prop of the widget-editor.

The end-user filters are serialized as the endUserFilters key in the paramsConfig object, and are saved as signals in the Vega specification (see above).