Table of Contents
Struct Plugin: Filters
Filters are used to filter aggregations.
Fixed Filters
Fixed filters are added through the filter and filteror options. They expect a column name, a comparator and a value to compare with.
Example:
---- struct table ---- schema : projects A cols : %pageid%, product, budget, team filter : product = Fantastico Basic filteror : product = Fantastico Professional ----
Column names can of course reference the full column name (eg. projects.product) or use defined aliases (eg. A.product). Should your field name contain a dot, you always need to provide a full column name (eg. projects.foo.bar).
Comparators
For filtering, multiple comparators are possible:
| Comparator | Meaning |
|---|---|
= | Exact match |
!= or <> | Does not exactly match |
< | Less than |
<= | Less or equal than |
> | Greater than |
>= | Greater or equal than |
~ | Wildcard match. Use a * as wildcard. Like Apple* to match Apple Pie and Apple Computer; e.g. dessert~ *Pie. Case insensitive. |
*~ | Wildcard match. Look for matches containing search term; e.g. dessert*~ Pi match Apple Pie |
!~ | Negative Wildcard match. Select everything that does not match the expression. |
=* | Regular expression search; example: keyword =* Hydraulic|Spindle filters out pages where the keyword is “Hydraulics” or “Spindle”. To match an empty value use =* ^(?![\s\S]) |
IN | Match any element in a list. List is limited by round brackets and contains elements separated by comas. Each element can be a string (limited by single or double quotes) or a number. Example syntax: somefield IN (“a”, 'b', 123, 12.1) |
Value Placeholders
When defining fixed filters it is sometimes useful to compare against semi-dynamic values. This is where value placeholders come in handy. You simply use the placeholder instead of a value when creating the filter.
The following example prints all projects the current user is a team member of:
---- struct table ---- schema : projects A cols : %pageid%, product, budget, team filter : team = $USER$ ----
| Placeholder | Description |
|---|---|
$USER$ | Currently logged in user |
$USER.name$ | Real name of currently logged in user |
$USER.email$ | Email of currently logged in user |
$USER.grps$ | Groups of currently logged in user. Useful with structgroup plugin. |
$TODAY$ | Today's date in Y-m-d format |
$DATE(<formula>)$ | A calculated date, where <formula> is a valid Date/Time Format |
$ID$ | The page's full page ID (of the page the aggregation is defined on) |
$PAGE$ | The page's page name without a namespace |
$NS$ | The page's namespace |
$STRUCT.<schema>.<field>$ | The struct data saved for the current page in given field. |
Dynamic Filters
Aggregations can be “live” filtered by either adding the dynfilters option, using a Cloud Control or Filter Control or by passing the right URL parameters.
The following example adds filter input fields for all selected columns.
---- struct table ---- schema : projects A cols : %pageid%, product, budget, team dynfilters : 1 ----
Filters created through this method always use the *~ comparator, eg. look for the search term anywhere in the column's data.
Manually Creating Filter Links
Dynamic filters can also be added through the flt parameter. The parameter is an array type, with the schema name, column name and comparator combined in the key and the comparison value in the value part.
Example: ?flt[projects.budget>]=10000
For example you could add the above filter to an internal link like this:
[[:myprojects:overview?flt[projects.budget>]=10000|Show large Projects]]
When following that link, an aggregation on that page myprojects:overview will be dynamically filtered to all projects with a budget greater than 10000. A filtering note and a link to reset the filtering is displayed above the aggregation.
Multiple Filters
If multiple filter: instructions are used, all conditions must be true, comparable to the AND operator in SQL.
The following example removes all results with the color yellow or green from the result set.
---- struct table ---- schema: colors cols: * filter: color <> yellow filter: color <> green csv: 0 ----
To combine multiple filters where it is sufficient for any of the conditions to be true, comparable to the OR operator in SQL, you can either work with filteror: instructions or with the IN comparator, also present in SQL.
The following two examples are identical and will only show results where the color is either yellow or green.
---- struct table ----
schema: colors
cols: *
filteror: color = yellow
filteror: color = green
csv: 0
----
---- struct table ----
schema: colors
cols: *
filter: color IN ("yellow","green")
csv: 0
----
Note that the struct plugin currently has no support for the NOT operator present in SQL. For example, it's currently not possible to create a filter with a NOT IN comparator.