History: PluginList filter control block

            ! 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===''
{FANCYTABLE(head="__Name__|__Description__|__Boolean__|__Sample__|__Tiki Version__" sortable="n")}
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 | -+~np~{filter distance="10km" lat="51.5287336" lon="-0.3824611"}~/np~+- | 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 -+~np~{filter field="tracker_field_foobar_text" exact=""}~/np~+-|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="~np~{{~/np~user~np~}}~/np~"} |8
field | Basic filter by field contents %%% For the full list of fields see ((Unified Index|#Fields)) |yes| -+~np~{filter field="title" content="foo"}~/np~+-, %%%  -+~np~{filter field="tracker_id" content="42"}~/np~+-, %%%  -+~np~{filter field="tracker_field_foobar" content="John Doe"}~/np~+-, %%%  -+~np~{filter field="tracker_status" content="o OR p"} ~/np~+-, %%%  -+~np~{filter field="blog_excerpt" content="Some text"} ~/np~+-  | 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
{FANCYTABLE}

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

{REMARKSBOX(type="note" title="Unified Index Field can be used to filter")}While not being "real" filters, you can use some ((Unified Index|Unified Index fields)) to filter results. For example, title_initial or title_firstword will work:%%%
-+{filter field="title_initial" exact="A"}+- (__note:__ this is case sensitive, -+{filter field="title_initial" exact="a"}+- finds nothing){REMARKSBOX}

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

{CODE(colors="tiki")}
{filter field="tracker_field_ABC" editable="y"}
{CODE}

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 ((dev:Unified Search)) - e.g. when filtering on content you could exclude all items not containing the word "water" by using:
{CODE(colors="tiki")}
    {filter content="NOT water"}
{CODE}

!!! 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:
++ {CODE(colors="tiki")}
    {filter content="NOT "}
{CODE}
** to include all __blanks__ OR __NULL__ values:
++ {CODE(colors="tiki")}
    {filter exact=""}
{CODE}
** 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".

{REMARKSBOX(type="note" title="Special case: 'Non-empty' for date fields using Elasticsearch" width="100%")}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).{REMARKSBOX}

!!! 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.
{CODE(caption="Will output category 27 objects")}{filter categories="27"}{CODE}

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.
{CODE(caption="Will output category 27 and children objects")}{filter deepcategories="27"}{CODE}

!!!! 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 ((Search and List from Unified Index|Unified Search Index)), you need to be aware of a few peculiarities:
# To filter by __exact value__ use the tracker field perm name __with the tracker_field_ prefix__
# 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.
# 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
!!!# Basic
{CODE(caption="Basic usage" colors="tiki")}
{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}
{CODE}

The date filters use [https://php.net/strtotime|strtotime] to convert various common formats to Unix epoch.  Unlike what the documentation previously said, this has always been the case.

!!!# File gallery
{CODE(caption="File gallery" colors="tiki")}
{LIST()}
    {pagination max="11"}
    {filter field="gallery_id" content="5"}
{LIST}
{CODE}

!!!!# File gallery to display an image in a smarty template
{CODE(caption="Display image" colors="tiki")}
{LIST()}
    {filter type="file"}
    {pagination max="1"}
    {filter field="gallery_id" content="5"}
    {OUTPUT()}<img src="display{display name="object_id"}" alt="">{OUTPUT}
{LIST}
{CODE}

!!!# Categories
!!!!# Not categorised objects
You can list uncategorized objects.

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

!!!!# Output the list of (sub)categories within a category
{CODE(caption="List all the categories under category 15")}
{LIST(searchable_only="0")}
  {filter deepcategories="15"}
  {filter type=category}
{LIST}
{CODE}

!!!# 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 ((Tiki15|Tiki 15)), the date filters are based on seconds and the following are possible:
{CODE(caption="Tiki 15+" colors="tiki")}
    {filter range="tracker_field_myDate" gap="86400" to="now"} {* Within the last day *}
{CODE}

From ((Tiki16|Tiki 16))+, the date filter has been "humanised" and the following date filters are possible:
{CODE(caption="Tiki 15+" colors="tiki")}
    {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"}
{CODE}

You can also filter using human value like this month, next month, etc.
{CODE(caption="" colors="tiki")}{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
{CODE}

From ((Tiki24|Tiki 24.1+)), it is possible to include missing values like this:
{CODE(caption="Tiki 24.1+" colors="tiki")}
    {filter range="tracker_field_myDate" from="" to="now"} {* All dates in the past or entries without a date set *}
{CODE}

In ((Tiki26|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:
{CODE(caption="Tiki 26" colors="tiki")}
      {filter field="tracker_field_attendancereportsDate" editable="y"}
{CODE}

!!!!# Unix timestamps
Unix timestamps may also be used. In ((Tiki19|Tiki 9))+, the following date filters are possible:
{CODE(caption="Tiki 9+" colors="tiki")}
    {filter range="modification_date" from="1317427200" to="now"}
    {filter range="modification_date" gap="31536000" to="now"}
    {filter range="modification_date" from="now" gap="31536000"}
{CODE}

!!!# Numeric ranges
^Note that the upper boundary of the range is not included in the search^
When you use __((Elasticsearch))__ as the ((Search and List from Unified Index|unified search index)), you can reuse the same parameters to, from and gap that are shown above for __Date ranges__:
{CODE(caption="Tiki 15" colors="tiki")}
    {filter range="tracker_field_myPermanentName" from="40" gap="100"}
{CODE}

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

!!!# Tracker with categories
{CODE(caption="Filter in a specific tracker" colors="tiki")}
{LIST()}
    {list max="10"}
    {filter content="hello world"}
    {filter categories="1 AND 2"}
    {filter content=5 field=tracker_id}
{LIST}
{CODE}

!!!# Tracker and logged user items
{CODE(caption="Filter in a specific tracker and the logged user item(s) - single user selection" colors="tiki")}
{LIST()}
{list max="1"}
{filter content="2" field="tracker_id"}
{filter field="tracker_field_username" content="~np~{~/np~{user}}"}
{LIST}
{CODE}
* 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".
{CODE(caption="Filter in a specific tracker and the logged user item(s) - single user selection, username contain space(s)" colors="tiki")}
{LIST()}
{list max="1"}
{filter content="2" field="tracker_id"}
{filter field="tracker_field_username" exact="~np~{~/np~{user}}"}
{LIST}
{CODE}

If you have your tracker set up to allow selecting several users in the tracker field users, you have to use instead:
  {CODE(caption="Filter in a specific tracker and the logged user item(s) - multiple user selection" colors="tiki")}
{LIST()}
{list max="1"}
{filter content="2" field="tracker_id"}
{filter field="tracker_field_username" multivalue="{{~/np~user~np~}}"}
{LIST}
{CODE}


!!!# Tracker item status
{CODE(caption="Filter by tracker item status" colors="tiki")}
{LIST()}
  {filter content="2" field="tracker_id"}
  {filter field="tracker_status" content="o OR p"}
{LIST}
{CODE}

!!!# Tracker items with empty field
{CODE(caption="Filter tracker items having an empty field (exact match)" colors="tiki")}
{LIST()}
  {filter content="2" field="tracker_id"}
  {filter field="tracker_field_fieldPermanentName" exact=""}
{LIST}
{CODE}

!!!# 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.

{CODE(caption="Display the items with a title that start with the letter B" colors="tiki")}
{LIST()}
  {filter content="2" field="tracker_id"}
   {filter field="title_initial" content="B"}
{LIST}
{CODE}

!!!# Wiki pages with partial match
{CODE(caption="Filter wiki pages with a partial match with some text string such as 'foo'" colors="tiki")}
{LIST()}
  {filter type="wiki page"}
  {filter field="title" content="foo"}
{LIST}
{CODE}

!!!# Wiki pages with partial match and spaces in string
{CODE(caption="Filter wiki pages with a partial match with some text string containing spaces such as 'foo bar'" colors="tiki")}
{LIST()}
  {filter type="wiki page"}
  {filter field="title" content="\"foo bar\""}
{LIST}
{CODE}

!!!# Wiki pages with exact match and spaces in string
{CODE(caption="Filter wiki pages with an exact match with some text string containing spaces such as 'foo bar'" colors="tiki")}
{LIST()}
  {filter type="wiki page"}
  {filter field="title" exact="foo bar"}
{LIST}
{CODE}

!!!# Wiki pages with boolean partial matches and spaces in strings
{CODE(caption="Filter on literal text with spaces in" colors="tiki")}
{LIST()}
    {filter content="\"hello world\" OR \"goodbye world\""}
{LIST}
{CODE}

!!!# Users in specific group(s)
{CODE(caption="Filter users in a specific group" colors="tiki")}
{LIST()}
  {filter field="object_type" content="user"}
  {filter field="groups" multivalue="Customers OR Staff"}
{LIST}
{CODE}

!!!# 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"
{CODE(caption="Related objects" colors="tiki")}
{LIST()}
  {filter relation="42" objecttype="trackeritem" qualifier="thing.related.content.invert"}
{LIST}
{CODE}

{CODE(caption="Objects related to a wiki page" colors="tiki")}
{LIST()}
  {filter relation="page name" objecttype="wiki page" qualifier="thing.related.content"}
{LIST}
{CODE}

!! Grouping filters together for the purpose of OR searching instead of AND
This permits an OR query on two fields 
{CODE()}
  {filter field="tracker_field_TaskAssignedTo" content="devsecops" group="together"}
 {filter field="tracker_field_TaskSummary" content="devsecops" group="together"}
{CODE}
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
{toc pagename="PluginList"}


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