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

## Available filters

Name Description Boolean Sample Tiki Version
categories Match on the object's directly associated categories yes 1 OR 3 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 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 at : Admin -> Editing and Plugins -> Wiki argument variables no {filter favorite="{{user}}"} 8
field Basic filter by field contents
For the full list of fields see Unified+Index#Fields
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 contibutions 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
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

### 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 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:
{filter content="NOT "}
• to include all blanks OR NULL values:
{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).

## 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 anayzed 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
{LIST()}
{pagination max="10"}
{filter content="hello world"}
{filter categories="1 AND 2"}
{filter language="en or unknown"}
{filter type="wiki page"}
{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. 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+
{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+
{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"}

#### 1.1.2.1. Unix timestamps

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

Tiki 9+
{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.3. 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
{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.4. Tracker with categories

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

### 1.1.5. Tracker and logged user items

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

### 1.1.6. Tracker item status

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

### 1.1.7. Tracker items with empty field

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

### 1.1.8. Wiki pages with partial match

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

### 1.1.9. 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'
{LIST()}
{filter type="wiki page"}
{filter field="title" content="\"foo bar\""}
{LIST}

### 1.1.10. 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'
{LIST()}
{filter type="wiki page"}
{filter field="title" exact="foo bar"}
{LIST}

### 1.1.11. Wiki pages with boolean partial matches and spaces in strings

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

### 1.1.12. Users in specific group(s)

Filter users in a specific group
{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
{LIST()}
{filter relation="42" objecttype="trackeritem" qualifier="thing.related.content.invert"}
{LIST}

## All the LIST Plugin control blocks

listfilter | listfilters | list filter | list filters | listfilterrange | filterrange

### Keywords

Keywords serve as "hubs" for navigation within the Tiki documentation. They correspond to development keywords (bug reports and feature requests):

Accessibility (WAI and 508)
Accounting
Articles and Submissions
Banners
Batch
BigBlueButton audio/video/chat/screensharing
Blog
Bookmark
Browser Compatibility
Calendar
Category
Chat
Clean URLs
Communication Center
Compression (gzip)
Content Templates
Contribution
Credit
Date and Time
Debugger Console
Documentation link from Tiki to doc.tiki.org (Help System)
Docs
Draw
Dynamic Content
Dynamic Variable
External Authentication
FAQ
File Gallery
Forum
Friendship Network (Community)
Groups
Hotword
HTML Page
i18n (Multilingual, l10n, Babelfish)
Image Gallery
Import-Export
Install
Integrator
Interoperability
Inter-User Messages
InterTiki
Kaltura video management
Karma
Live Support
Logs (system & action)
Look and Feel
Lost edit protection
Mail-in
Map with Mapserver
Meta Tags
Mobile Tiki and Voice Tiki
Mods
Module
MultiTiki
MyTiki
Payment
Permissions
Platform independence (Linux-Apache, Windows/IIS, Mac, BSD)
Polls
Profiles
Profile Manager
Report
Toolbar
Quiz
Rating
Feeds
Score
Search engine optimization
Search
Search and Replace
Security
Share
Shopping cart
Shoutbox
Slideshow
Smiley
Social Networks
Spam protection (Anti-bot CATPCHA)
Spellcheck
Stats
Surveys
Tags
Tell a Friend, alert + Social Bookmarking
TikiTests
Theme CSS & Smarty
Trackers
Transitions
TRIM
User Administration including registration and banning
User Files
Watch
WebDAV
Webmail
Web Services
Wiki History, page rename, etc
Wiki Plugin extends basic syntax
Wiki Syntax
Wiki structure (book and table of content)
Workspace
WSOD
WYSIWYCA
WYSIWYG
XMLRPC