PluginList filter control block


A filter is used to define the search query that will be run to gather a set of results for the list. A large number of possible individual parameters can be 'filtered' as set out in the table below and multiple filter control blocks can be applied in an additive manner ie the equivalent of an AND operation. See also PluginList with editable filters

Available filters

Name Description Boolean Sample Tiki Version
categories Match on the object's directly associated categories yes 1 OR 3 (orphan will work) 7
content Full text search on all of the object's content
Additional field argument can be provided to search for other fields instead of the default ones.
yes hello world 7
contributors user login to search for as the contributors for the content yes admin OR testuser 8
deepcategories Match on the object's categories or their parents, providing deep searching yes 1 OR 3 8
distance filtering on object location by distance (Seems to work with Elasticsearch only - Tiki19.1) no {filter distance="10km" lat="51.5287336" lon="-0.3824611"} 16.1
exact Exact text search
Use with the field argument to search for an exact title or field value. Can be used to look for empty tracker field {filter field="tracker_field_foobar_text" exact=""}
yes hello world 13
favorite Show only the favorited objects of a certain user. The feature Wiki Argument Variables must be set no {filter favorite="{{user}}"} 8
field Basic filter by field contents
For the full list of fields see Unified Index
yes {filter field="title" content="foo"},
{filter field="tracker_id" content="42"},
{filter field="tracker_field_foobar" content="John Doe"},
{filter field="tracker_status" content="o OR p"} ,
{filter field="blog_excerpt" content="Some text"}
7 (and onwards with more fields arriving most releases)
language Search on the object's language (2-letter code) when available. unknown is used when unspecified. yes* en or fr OR unknown 7
multivalue needed when filtering on array type fields like users' groups no Customers OR Staff ?
personalize to filter down to own contributions without relying on argument variables ? ? 12
range A date (unix timestamp) range
Must have from and to arguments specified
no < searchfieldname > 8
range In Tiki 9, from and to can now take now instead of a unix timestamp, and you can also set either from or to together with "gap" to specify the one relatively to the other no < searchfieldname > 9
relation Must have certain relation
Additional field arguments objecttype and qualifier (the relationship) must be specified
no < object_id > 8
similar Find objects similar to this or a specified other object no Similar to current:
{filter similar="this"}
or {filter similar=""}
Similar to tracker item:
{filter similar="trackeritem:42"}
21.2
textrange A text range
Must have from and to arguments specified
no < searchfieldname > 8
type Filter on object type no wiki page (from Tiki 8 you can search for multiple types by providing a comma separated list)
trackeritem to search trackers
7/8
11 or earlier


* AND matching won't make much sense, single-value field

 Unified Index Field can be used to filter
While not being "real" filters, you can use some Unified Index fields to filter results. For example, title_initial or title_firstword will work:
{filter field="title_initial" content="A"}

Editable filters (option)

Since Tiki20 you can set directly a parameter to change several filter types from "hidden" to "editable" and doing so, select on the fly an existing value of a field and output results. This is very handy to set quickly a modifiable filters instead of using the plugin customSearch that require much more work.

Copy to clipboard
{filter field="tracker_field_ABC" editable="y"}


https://doc.tiki.org/PluginList-with-editable-filters

Boolean Syntax

When applying an individual filter more complex logic can also be applied using a Boolean syntax - that applies to all aspects of Unified Search - e.g. when filtering on content you could exclude all items not containing the word "water" by using:

Copy to clipboard
{filter content="NOT water"}

Empty or Non-empty

To filter for a empty or non-empty fields, the syntax might depend on the Search and List from Unified Index engine.

  • When using "MySQL Full Text Search" or "Elasticsearch" as the Unified Search Engine, you can use these syntaxes:
    • to include all non-blanks non-NULL values:
      Copy to clipboard
      {filter content="NOT "}
    • to include all blanks OR NULL values:
      Copy to clipboard
      {filter exact=""}
    • Note: it's not possible at the moment to perform an OR or AND filter operation where one of the elements is blank and the other is not, e.g.: " OR 1".

 Special case: 'Non-empty' for date fields using Elasticsearch
In the specific case of filtering for 'Non-empty' date fields when using Elasticsearch, you need to convert your syntax to filter for a (wide enough) range of valid dates: this way you will match all items having some date and leave out the ones without dates set. Otherwise, Elasticsearch will fail and trigger some error (tested with Elasticsearch 1.x and 2.x).

Category (categories)

categories vs deepcategories

The categories filter parameter will work like an EXACT filter and in the sample below ONLY object within the category 27 will be outputted. You can filter more categories by adding "AND" or "OR" operator.

Will output category 27 objects
Copy to clipboard
{filter categories="27"}


The deepcategories filter parameter will work like a more flexible filter and in the sample below object within the category 27 or object in a child category of 27 will be outputted. Same, you can filter more categories by adding "AND" or "OR" operator.

Will output category 27 and children objects
Copy to clipboard
{filter deepcategories="27"}

Not categorised for category

Tiki has a specific filter for object that are not categorised: "orphan"

You will find an example for this usage down below.

List of sub-category

To list the sub-categories under a category you need to set searchable_only=0 to allow the plugin to list indexed fields that are not available for Search. See: https://doc.tiki.org/Search-and-List-from-Unified-Index#Searchable_and_not_searchable

You will find an example for this usage down below.

Peculiarities for Elasticsearch

When using Elasticsearch as the Unified Search Index, you need to be aware of a few peculiarities:

  1. To filter by exact value use the tracker field perm name with the tracker_field_ prefix
  2. To filter by exact EMPTY value (i.e. missing value), use the _text version of the permanent name for that field where available.
    • MySQL index works with non _text version too but elastic does not. The reason is that Radio button, dropdown and a number of other fields use the normal permName field as identifier and add a _text version which is a plain text.
    • In Elasticsearch, this means that identifiers are exact-matches - they are not analyzed by search index and wildcard searches (like the empty one) does not work on them. Plain text, on the other hand, support wildcard searches, are analyzed and thus, work for exact="" search.
  3. When you use a field (let's say radio button, or dropdown, for instance) with a value "No", you will get some problems when search for that value in Elasticsearch since "No" is a stopword in Elasticsearch.
    • This is defined in the "Control Panel > Search" where you can exclude it to not be a stopword.
    • Being a stopword means that for analyzed string fields like tracker_field_myPermanentName_text, searching for stopword will result in nothing and searching for an empty value will show those fields containing a stopword. So, instead of seeing all empty ones, you will see all empty ones and all the ones that have a stopword in them - like all the "No" ones. This is undesired, so if you have such a field and need to filter on a stopword, please update the list of stopwords to exclude that specific value.

Examples

1.1.1. Basic

Basic usage
Copy to clipboard
{LIST()} {pagination max="10"} {filter content="hello world"} {filter categories="1 AND 2"} {filter language="en or unknown"} {filter type="wiki page,trackeritem"} {filter range="modification_date" from="2014-01-01" to="last week"} {LIST}


The date filters use strtotime to convert various common formats to Unix epoch. Unlike what the documentation previously said, this has always been the case.

File gallery
Copy to clipboard
{LIST()} {pagination max="11"} {filter field="gallery_id" content="5"} {LIST}

Display image
Copy to clipboard
{LIST()} {filter type="file"} {pagination max="1"} {filter field="gallery_id" content="5"} {OUTPUT()}<img src="display{display name="object_id"}" alt="">{OUTPUT} {LIST}

1.1.3. Categories

1.1.3.1. Not categorised objects

You can list uncategorized objects.

{CODE(caption="List the object not categorized"}
{filter categories="orphan"}
{CODE}

1.1.3.2. Output the list of (sub)categories within a category

List all the categories under category 15
Copy to clipboard
{LIST(searchable_only="0")} {filter deepcategories="15"} {filter type=category} {LIST}

1.1.4. Date ranges

Parameters to, from and gap:

  • The idea is that you specify the value in to as the last day you want that filter to work on.
    • For instance: 1 week ago or "-1 week" - both should work with php's strtotime() parsing.
  • Then, the gap should cover the whole previous date range that you need. If you want, for instance, items older than 1 week, you can use a number there as big as you can, for instance 40 years
    (of course not going beyond 1970 as this is the start of the UNIX era and strtotime will return odd results).
  • And the idea of parameter from is that you specify the first day you want that filter to work on.

Note that the upper boundary of the range is not included in the search


In Tiki 15, the date filters are based on seconds and the following are possible:

Tiki 15+
Copy to clipboard
{filter range="tracker_field_myDate" gap="86400" to="now"} {* Within the last day *}


From Tiki 16+, the date filter has been "humanised" and the following date filters are possible:

Tiki 15+
Copy to clipboard
{filter range="tracker_field_myDate" gap="1 day" to="now"} {* Within the last day *} {filter range="tracker_field_myDate" gap="10 years" to="-1 week"} {* Older than one week *} {filter range="tracker_field_myDate" gap="1 week" to_field="tracker_field_myDeadline"} {* 1 week before the deadline *} {filter range="modification_date" from="-10 years" gap="1 year"} {* Between 9 and 10 years ago *} {filter range="modification_date" gap="1 year" to="10 years"} {* In between 9 and 10 years from now *} {filter range="modification_date" from="-40 years" to="now"} {* Within the last 40 years; a.k.a, "in the past" *} {filter range="modification_date" from="2014-01-01" to="last week"}


You can also filter using human value like this month, next month, etc.

Copy to clipboard
{filter range="creation_date" from="first day of this month" to="first day of next month midnight"} => This month {filter range="creation_date" from="first day of previous month" to="first day of this month"} => Previous month


From Tiki 24.1+, it is possible to include missing values like this:

Tiki 24.1+
Copy to clipboard
{filter range="tracker_field_myDate" from="" to="now"} {* All dates in the past or entries without a date set *}


In Tiki 26+ (not sure since when it is available), it is possible to set a simple filter on a date field for the code to understand the filter is a about a range of dates (from - to) and display a field with a date picker:

Tiki 26
Copy to clipboard
{filter field="tracker_field_attendancereportsDate" editable="y"}

1.1.4.1. Unix timestamps

Unix timestamps may also be used. In Tiki 9+, the following date filters are possible:

Tiki 9+
Copy to clipboard
{filter range="modification_date" from="1317427200" to="now"} {filter range="modification_date" gap="31536000" to="now"} {filter range="modification_date" from="now" gap="31536000"}

1.1.5. Numeric ranges

Note that the upper boundary of the range is not included in the search

When you use Elasticsearch as the unified search index, you can reuse the same parameters to, from and gap that are shown above for Date ranges:

Tiki 15
Copy to clipboard
{filter range="tracker_field_myPermanentName" from="40" gap="100"}


This will display items which have the field with permanent name "myPermanentName" with values starting at 40 and up to 100 numbers higher (from 40 to 140).

1.1.6. Tracker with categories

Filter in a specific tracker
Copy to clipboard
{LIST()} {list max="10"} {filter content="hello world"} {filter categories="1 AND 2"} {filter content=5 field=tracker_id} {LIST}

1.1.7. Tracker and logged user items

Filter in a specific tracker and the logged user item(s) - single user selection
Copy to clipboard
{LIST()} {list max="1"} {filter content="2" field="tracker_id"} {filter field="tracker_field_username" content="{{user}}"} {LIST}


If you have __usernames made of several words and containing space(s)_ between them "content" filter won't work. You'll need to use "exact".

Filter in a specific tracker and the logged user item(s) - single user selection, username contain space(s)
Copy to clipboard
{LIST()} {list max="1"} {filter content="2" field="tracker_id"} {filter field="tracker_field_username" exact="{{user}}"} {LIST}


If you have your tracker set up to allow selecting several users in the tracker field users, you have to use instead:

Filter in a specific tracker and the logged user item(s) - multiple user selection
Copy to clipboard
{LIST()} {list max="1"} {filter content="2" field="tracker_id"} {filter field="tracker_field_username" multivalue="{{user}}"} {LIST}


1.1.8. Tracker item status

Filter by tracker item status
Copy to clipboard
{LIST()} {filter content="2" field="tracker_id"} {filter field="tracker_status" content="o OR p"} {LIST}

1.1.9. Tracker items with empty field

Filter tracker items having an empty field (exact match)
Copy to clipboard
{LIST()} {filter content="2" field="tracker_id"} {filter field="tracker_field_fieldPermanentName" exact=""} {LIST}

1.1.10. Tracker items title that start with the letter B

Note: This is the object title, for the tracker items it is set in the fields (list) parameters.

Display the items with a title that start with the letter B
Copy to clipboard
{LIST()} {filter content="2" field="tracker_id"} {filter field="title_initial" content="B"} {LIST}

1.1.11. Wiki pages with partial match

Filter wiki pages with a partial match with some text string such as 'foo'
Copy to clipboard
{LIST()} {filter type="wiki page"} {filter field="title" content="foo"} {LIST}

1.1.12. Wiki pages with partial match and spaces in string

Filter wiki pages with a partial match with some text string containing spaces such as 'foo bar'
Copy to clipboard
{LIST()} {filter type="wiki page"} {filter field="title" content="\"foo bar\""} {LIST}

1.1.13. Wiki pages with exact match and spaces in string

Filter wiki pages with an exact match with some text string containing spaces such as 'foo bar'
Copy to clipboard
{LIST()} {filter type="wiki page"} {filter field="title" exact="foo bar"} {LIST}

1.1.14. Wiki pages with boolean partial matches and spaces in strings

Filter on literal text with spaces in
Copy to clipboard
{LIST()} {filter content="\"hello world\" OR \"goodbye world\""} {LIST}

1.1.15. Users in specific group(s)

Filter users in a specific group
Copy to clipboard
{LIST()} {filter field="object_type" content="user"} {filter field="groups" multivalue="Customers OR Staff"} {LIST}

In this example we want to find all objects related to trackeritem itemId 42 related using the qualifier thing.related.content. Note we need to add .invert to the end of it becasue they are all related via a Relations field on this tracker, so the relation from their point of view is "inverted"

Related objects
Copy to clipboard
{LIST()} {filter relation="42" objecttype="trackeritem" qualifier="thing.related.content.invert"} {LIST}

Objects related to a wiki page
Copy to clipboard
{LIST()} {filter relation="page name" objecttype="wiki page" qualifier="thing.related.content"} {LIST}

Grouping filters together for the purpose of OR searching instead of AND

This permits an OR query on two fields

Copy to clipboard
{filter field="tracker_field_TaskAssignedTo" content="devsecops" group="together"} {filter field="tracker_field_TaskSummary" content="devsecops" group="together"}

This allows searching for a task assigned to the user devsecops or with devsecops in the summary.

This is available since Tiki26: https://gitlab.com/tikiwiki/tiki/-/commit/23570b601811176840897824f6e66427ab00563e

For a list of available types: Search and List from Unified Index

All the LIST Plugin control blocks



Alias names of this page:
listfilter | listfilters | list filter | list filters | listfilterrange | filterrange