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

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

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.

{filter field="tracker_field_ABC" editable="y"}

See also: 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:

{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".

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.

{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.

{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

{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.

1.1.2. File gallery

{LIST()}
    {pagination max="11"}
    {filter field="gallery_id" content="5"}
{LIST}

1.1.2.1. File gallery to display an image in a smarty template

{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(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.

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

{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:

{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.

{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:

{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:

{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:

{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

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:

{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

{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

{LIST()}
{list max="1"}
{filter content="2" field="tracker_id"}
{filter field="tracker_field_username" content="{{user}}"}
{LIST}

• Any other Wiki Argument Variables can be used.

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".

{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:

{LIST()}
{list max="1"}
{filter content="2" field="tracker_id"}
{filter field="tracker_field_username" multivalue="{{user}}"}
{LIST}

1.1.8. Tracker item status

{LIST()}
  {filter content="2" field="tracker_id"}
  {filter field="tracker_status" content="o OR p"}
{LIST}

1.1.9. Tracker items with empty field

{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.

{LIST()}
  {filter content="2" field="tracker_id"}
   {filter field="title_initial" content="B"}
{LIST}

1.1.11. Wiki pages with partial match

{LIST()}
  {filter type="wiki page"}
  {filter field="title" content="foo"}
{LIST}

1.1.12. Wiki pages with partial match and spaces in string

{LIST()}
  {filter type="wiki page"}
  {filter field="title" content="\"foo bar\""}
{LIST}

1.1.13. Wiki pages with exact match and spaces in string

{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

{LIST()}
    {filter content="\"hello world\" OR \"goodbye world\""}
{LIST}

1.1.15. Users in specific group(s)

{LIST()}
  {filter field="object_type" content="user"}
  {filter field="groups" multivalue="Customers OR Staff"}
{LIST}

1.1.16. Related items

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"

{LIST()}
  {filter relation="42" objecttype="trackeritem" qualifier="thing.related.content.invert"}
{LIST}

{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

{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

Related

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