See also Front-ends to Tracker data

Plugin List

If you are searching for the list of all plugins, see All Plugins. A graphical user interface (ListGUI) was added in Tiki18 and massively improved in Tiki19. Starting in Tiki21, it has been enhanced to use with Federated Search. And new in Tiki26: PluginList Sublist.

Introductory Remarks

LIST is a very powerful and flexible wiki plugin that can return and output data (a listing) of information using various sorts, filters, etc. It uses the search data provided by the improved search index so it should be emphasized that this means that only the data that has actually been indexed by the Search and List from Unified Index can be accessed. Good knowledge of how Unified Index works is therefore recommended.

By utilizing a full-text search across most major Tiki features, which is then enhanced by a programmable filter, OUTPUT, DISPLAY, and SORT control blocks, this combination can render almost any information in the database in any format desired. This means that LIST is similar in some respects to Pretty Trackers output of TrackerList plugin but it is not limited to just the Tracker data. When combined with the PluginCustomSearch plugin, LIST can replace TrackerList and TrackerFilter plugin usage and can considerably extend it!! Please also see PluginListExecute.

Please note you can use nested LIST.

Control blocks vs. Wiki Plugins

"Control blocks" are quite similar to "wiki plugins", as they use the very same syntax of parameters and values.
The positions of the parameters can be switched around in wiki plugins as well as in List control blocks. Both allow to leave out the quotation marks around the values of the parameters when the values contain no empty spaces.

However, for both, control blocks and wiki plugins, it makes sense to stick to some best practices in respect of consistent sort order. This is not mandatory but makes it easier to understand the principle, to read the own code, and to work together in teams. This is especially valid for the LIST control blocks, as there are usually a lot of control blocks used in one LIST plugin.

The difference between "control blocks" and "wiki plugins" is, that you cannot use a "control block" stand-alone outside one of the plugins, which use the "PluginList" syntax, as there are "PluginList", "PluginCustomSearch" and "PluginListExecute" (?). If you place a single List "control block" stand alone on a wiki page, either nothing happens or you'll get an error message.

"Wiki plugins", instead, can be used stand-alone anyplace where you can use wiki syntax and, to some extent, you can nest them as well.

Clarifying a potential confusion

Potentially confusing is the difference between a control block and a parameter both called "format":

The parameter "format" (in lower case) inside the control block "{display}" is responsible for how the displayed result is rendered. Maybe it also could have been named "render" instead of "format", but "format" was the naming decision of our coders and that makes sense as well, maybe even better sense for some reason.

The control block "{FORMAT(name=...)}" (in upper case) wraps around the control block "{display}" and is for example responsible for the reference to the control block column (when we consider the example of a tracker table display).

The other potentially confusing fact is, is the difference and same time similarity of the parameters "field" and "name", where we use always "field" in the {filter} and in the {column} inside the "{OUTPUT(template=table)})" control block.
Contrarily we use "name" in the optional ''{display} and {FORMAT()}'' control blocks.

When we use this ...

{filter field="tracker_id" content="10"}
  {OUTPUT(template="table")}
     {column field="tracker_field_permanent_name_1" label="columntitle" mode="raw"}
     {column field="tracker_field_permanent_name_2" label="columntitle" mode="raw"}
  {OUTPUT}

... then the "field"' parameter contains a "Unified Index field"'' - in this case a tracker field which we want to display.

But when we use this ...

{filter field="tracker_id" content="10"}
  {OUTPUT(template="table")}
     {column field="reference_1" label="columntitle" mode="raw"}
     {column field="reference_2" label="columntitle" mode="raw"}
  {OUTPUT}
     {FORMAT(name="reference_1")}{display name="tracker_field_permanent_name_1" format=trackerrender editable=inline default="n.a."}{FORMAT}
     {FORMAT(name="reference_2")}{display name="tracker_field_permanent_name_2" format=trackerrender editable=inline default="n.a."}{FORMAT}

... we referenced (passed) the actual value of the "field" parameter of control block "{column ...}" to the subcontrol block "{display ...}" inside the control block '"{FORMAT(...)", where we for some reason cannot use a parameter '"field"''.

When we reference the original content of "field" from one to another control block, both control blocks need to "know" about each other, which you see as obvious, when you have more than only one column.
So the content of the column's field parameter will be replaced with a reference string and this reference string has to be repeated in the FORMAT's name parameter. Now the column control block and the FORMAT control block are interlinked with each other. Finally, the original content of the columns field parameter (which is a "Unified Index field") has to be placed into the display's name parameter.

In other words:

"Unified Index field string" goes from "column field" to "display name"
And a "reference string" is added to "column field" and "FORMAT name"

Important to know is the content of the page Search and List from Unified Index, where you find a list of all available "Unified Index fields" for which you can filter and in respect of tracker based tables you can use to create columns.

Syntax Overview

The overall format is the same as any other plugin:

{LIST()}
body content
{LIST}

Any of the following control blocks with their own plugin-like syntax are placed in the body of the LIST plugin to define the search query that will be carried out and how the resulting list will be presented :

Parameters

While Plugin List is generally configured with plugins (some say control blocks) contained in the body as described above, there are a few standard parameters like other plugins, they are:

Additional parameter

Select fields

The syntax of the parameter is as follows: {select fields="tracker_field_permName1 tracker_field_permName2 ..."}.
This allows us to limit the number of fields actually fetched from the search index. It currently works for all 3 index types - Mysql, Manticore and Elasticsearch. It is especially useful when you want to do subtotal and calcs on a large number of results in an index that has thousands of fields. Note that object_type and object_id are always returned no matter what.

By design, title, object_type,object_id,score and row_index fields value will always be outputted. However, to benefit from the performance improvement of this additional parameter you must use it with at least one value. If you need only the title of the returned object, even if the title is always returned, you must use a value and {select fields="title"} is acceptable.

Work for the plugin List and on the plugin Customsearch

Introduced by this commit: https://gitlab.com/tikiwiki/tiki/-/commit/afc34f5c7fdea02f7c8f43b894d422b018a5eb7f

Using

{LIST()}
 {pagination max="1"}
 {filter type="trackeritem"}
 {filter field="object_id" content=""}
 {select fields="tracker_field_permName1 tracker_field_permName2 ..."}
{LIST}

Basic worked example

In the meantime, you can see a basic working example here: GeoLocation (or play in your tiki with a similar basic example after applying the profile Easy Geoblog, which is available at the Profiles Wizard ).

Body content elements of the LIST Plugin

Each of the principle plugin-like control blocks is described in more detail in the following set of child pages:

Additional General Notes on the Syntax

• The field argument in the content filter can contain multiple fields separated by commas.

Available Fields

All the fields that are indexed can be referenced by the various plugin-like control blocks e.g. filter , FORMAT, etc and a complete list of fields for each object type can be found in the Search and List from Unified Index documentation.

More Worked Examples

Example Tracker item with Comments

Item

{LIST()}
 {pagination max="1"}
 {filter type="trackeritem"}
 {filter field="object_id" content=""}
{LIST}

Comments

{LIST()}
 {filter type="comment"}
 {filter field="parent_object_id" content=""}
 {filter field="parent_object_type" content="trackeritem"}
{LIST}

Example Tracker item with a picture (file)

{LIST()}
  {filter field="tracker_id" content="1"}
{OUTPUT()}
  {display name="fathername"}%%%
  {display name="fatherpict"}%%%
  {display name="id"}
   {OUTPUT}
{FORMAT(name="fathername")}{display name="tracker_field_fatherName"}{FORMAT}
{FORMAT(name="fatherpict")}{display name="tracker_field_fatherPicture" format="trackerrender"}{FORMAT}
{FORMAT(name="id")}{display name="tracker_field_parentId"}{FORMAT}
{LIST}

Same Example as above within a table

(see: LIST - OUTPUT control block)

{LIST()}
{filter content="1" field="tracker_id"}
{filter type="trackeritem"}
{OUTPUT(template="table")}
  {column label="Father Name" field="fathername"}
  {column label="Picture" field="fatherpict" mode="raw"}
  {column label="ID" field="id"}
{OUTPUT}
{FORMAT(name="fathername")}{display name="tracker_field_fatherName"}{FORMAT}
{FORMAT(name="fatherpict")}{display name="tracker_field_fatherPicture" format="trackerrender"}{FORMAT}
{FORMAT(name="id")}{display name="tracker_field_parentId"}{FORMAT}
{LIST}

Example Blog Post List

This code:

{LIST()}
	{list max="10"}
	{filter type="blog post"}
	{filter content="1" field="blog_id"}
{LIST}

Would produce on this site:

• Blogs enabled, and blog created allowing post comments
• changes to perms and disabling forum
• site upgraded to the released tiki 2.0 stable
• DocContributors granted the perms to edit doc.tw.o homepage
• Wiki Structures re-enabled
• Copyright turned off
• Packages
• Disabled "Users can choose to stay in SSL mode after an HTTPS login" to have SSL login always on.
• Preference feature jquery validation disabled (Preference name: feature_jquery_validation)
• Comments enabled for registered users

  
  

Common Pitfalls and Mandatory Requirements when filtering Tracker fields with Plugin LIST

Tracker field configuration is critical

When using {LIST} with tracker fields, only fields indexed by the Unified Search can be filtered.
For any tracker field used inside a {filter} control block, the following options must be enabled in the tracker field configuration:

If Searchable is not enabled, {LIST} will always return No results for query for anonymous, even if:

• tracker items exist
• the filter value is correct
• permissions are correctly configured

Rebuild the search index after changes

After enabling Searchable on a tracker field:
Go to Admin → Search then Click Rebuild index

Without rebuilding the index, the field will not be available to the Unified Search, and {LIST} filters on that field will silently fail.

Using dynamic values (Smarty) in LIST filters

The content= parameter of {filter} accepts plain text or numeric values only.
Wiki plugins (such as {"now"}) are not evaluated inside content=.
To use dynamic values, a Smarty template context is required.

Practical example: filtering by day of the year

Option A — Server-side Smarty template

1. Create a Smarty template file (server-side)
File location (recommended, non-core): templates/modules/custom_daily_content.tpl

{assign var=daynum value=$smarty.now|date_format:"%j"}

{wikiplugin _name='list'}{literal}
{filter field="tracker_id" content="1"}
{filter field="tracker_field_dayNumber" content="{/literal}{$daynum}{literal}"}

{OUTPUT()}
{display name="tracker_field_dailyTitle"}
{display name="tracker_field_dailyMessage"}
{OUTPUT}
{/literal}{/wikiplugin}

2. Include it from the Custom Module
Module Name : Custom Daily Content
Module content (Wiki Markup):

{INCLUDE file="templates/modules/custom_daily_content.tpl"}

3. Call the module in a wiki page
Use the Module plugin to display the custom module on a page.
Wiki page content:

{module module="Custom Bible Plan" nobox="y"}

Option B — Wiki page used as a Smarty template (UI-managed, recommended)

1. Create a Wiki page used as a Smarty template

• Page name: Custom Daily Content Tpl
• Permissions required: tiki_p_use_as_template (Make it editable only by trusted users)
• Page content:

{assign var=daynum value=$smarty.now|date_format:"%j"}

{wikiplugin _name='list'}{literal}
{filter field="tracker_id" content="1"}
{filter field="tracker_field_dayNumber" content="{/literal}{$daynum}{literal}"}

{OUTPUT()}
{display name="tracker_field_dailyTitle"}
{display name="tracker_field_dailyMessage"}
{OUTPUT}
{/literal}{/wikiplugin}

2. Include the Wiki template in a Wiki page

{includetpl filename="tplwiki:Custom Daily Content Tpl" values=""}

For more details: PluginIncludeTpl

Tutorials

• Tutorial - Display Tracker Data with Plugin List
• LIST plugin demo and nesting tracker items - Youtube

Additional child pages of the LIST documentation

Related

See also:

• PluginList Sublist
• PluginTrackerList
• PluginTrackerList To PluginList Converter
• PluginTracker
• PLuginModule
• PluginIncludeTpl

• Plugin List