Fullscreen
[Show/Hide Right Column]

Search for, list, and filter all types of items and display custom formatted results
Print
English
Documentation TOC  »  Features  »  Wiki  »  Wiki Plugin  »  PluginList

Plugin List

Introduced in Tiki7

List is a wiki plugin that uses the improved search index to provide search functionality. It provides a full-text search across most major tiki features, enhanced by programmable filter, OUTPUT, DISPLAY, and SORT commands, which combined can render almost any information in the database in any format desired, similar to pretty trackers.

Syntax Overview

The body of the plugin contains commands with their own plugin-like syntax, but only these four exist within LIST:

filter: chooses the objects (rows) to include. (required)
OUTPUT: which columns/fields to include about those objects (optional)
DISPLAY: placement and formatting of those fields. (optional)
SORT: which order. (optional)

noteTo Do

This part needs help - need to explain the scope of these commands (what each is for)


Steps to Create a List

Note that it is important to set a max otherwise performance might be slow:
{list max="10"}

Note that this setting will take precedence over any maxRecords setting which is set in the query string, and that maxRecords in the query string will only apply if offset is set anyway, while the above setting will work always.

Filter
Basic usage
{LIST()}
    {list 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="1317427200" to="1320105600"}
{LIST}

  • the range is for dates, uses unix time - convert it here
Tiki 9
In Tiki 9, the following date filters are possible:
    {filter range="modification_date" from="1317427200" to="now"}
    {filter range="modification_date" to="now" gap="31536000"}
    {filter range="modification_date" from="now" gap="31536000"}

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}

Output
Wiki Output Sample
||Type|Object
{LIST()}
    {OUTPUT()}{display name=object_type}|{display name=object_id}
{OUTPUT}
{LIST}
||


Table Formatting
Sample using the default table formatting
{LIST()}
   {filter type=trackeritem}
   {filter content="water"}
   {OUTPUT(template="table")}
       {column sort="title" label="Title" field="title_link" mode=raw}
       {column label="Description" field="description"}
       {column sort="tracker_field_18" field="event_date" label="Event Date"}
   {OUTPUT}

   {FORMAT(name="title_link")}{display name=title format=objectlink}{FORMAT}
   {FORMAT(name="event_date")}{display name=tracker_field_18 format=date}{FORMAT}
{LIST}


Note that the column plugins are converted to a data array sent to the template. The table formatting uses smarty formatting and provides the same capabilities.

N.B. As of Tiki 9+ you will need to define mode=raw on columns containing html output such as objectlink and trackerrender formatted values due to corrections in the parser for Tiki 9.

Wiki Formatting (Within Plugin)
For each result, the plugin allows to apply a template.

Display
General Formatting Options
  • The DISPLAY 'plugin' can have an additional default parameter to specify the value to use if the object type does not contain the named value
    • use default="" to show a blank value instead of "No value for ..." when there is no value
  • The DISPLAY 'plugin' can can have an additional format parameter to specify custom display methods
    • plain: as-is, default format
      • Optional 'separator' attribute
    • date: using the short date format
    • datetime: using the short datetime format (Tiki8)
    • objectlink: uses the value as the label to a link to the object
    • snippet: to display the initial portion of the a large text
      • Optional 'length' attribute
      • Optional 'suffix' attribute
    • reference: to display a link based on the value
      • Mandatory 'type' attribute
      • Optional 'separator' attribute
    • trackerrender: to render a tracker field (when using trackerrender the Smarty variable "$context.search_render" will be "y" and can be used to have different formatting in the trackeroutput Smarty tpl)
  • (Tiki 9+) list_mode="y" can be added to use the list display settings for that field. e.g. {display name="tracker_field_42" format="trackerrender" list_mode="y"}
  • (Tiki 9+) pagetitle="y" will set the browser title to the contents of the field for the first item found in the results with pagetitle set (useful for single item result pages)
  • The FORMAT 'plugin' allows to apply a wiki template and store it inside a named value. The value can then be used inside an other wiki template, or more usefully inside a smarty template.

Examples
Display category links
{display name=categories format=reference type=category}

Display freetag links
{display name=freetags format=reference type=freetag}

Display item link
{display name=tracker_field_42 format=trackerrender}
{display name=tracker_field_42 format=reference type=trackeritem}

Start of wiki page
{display name=wiki_content format=snippet length=500 suffix="..."}

(Tiki 8) Categories
(display name=categories format=categorylist singleList=y}
(display name=categories format=categorylist requiredParents="15,20" excludeParents="5,6"}
(display name=categories format=categorylist singleList=y separator=", "}


Sort
Setting Sort Mode
Please be warned that sorting is normally based on string. if you are trying to sort by numbers, make sure all your numbers are of the same number of digits. Otherwise 2 will be larger than 12 if doing a string sort.
{sort mode="tracker_field_18_asc"}
{sort mode="tracker_field_18_desc"}

If you want to do a numeric sort (such that 12 is larger then 2, use the following instead (from Tiki 8):
{sort mode="tracker_field_18_nasc"}
{sort mode="tracker_field_18_ndesc"}

From Tiki 8, there is also a way to simulate random results when showing a short list. This is of course not compatible with pagination. You have to specify a list of sort modes on irrelevant fields to choose randomly from, for example:
{sort mode="randommode" modes="tracker_field_18_nasc,tracker_field_18_ndesc,tracker_field_19_asc,trackerfield_19_desc"}


Advanced
Wiki Formatting (In Separate Wiki Page)
(Available from Tiki 8) This is the same as Wiki Formatting Within Plugin but with the difference that the formatting of each item can be on a separate wiki page. First:

Separate Wiki Page Output Sample
{LIST()}
    {output wiki=ResultsTemplatePageName"}
    {FORMAT(name=label)}{display name=title format=objectlink}
{display name=description}{FORMAT}
    {FORMAT(name=description)}{display name=description}{FORMAT}
{LIST}


After that, create the wiki page template "ResultsTemplatePageName" in which you will put the following

Separate Wiki Page Formatting Sample
{literal}
This is the label: {display name=label}
This is the description: {display name=description}
{/literal}


Note that the "literal" Smarty tags are required to prevent {display name=label} and {display name=description} from being parsed as usual smarty variables.

If you want to use HTML in your template, the following is the correct way:

Separate Wiki Page Formatting Sample
{literal}
{HTML(wiki=1)}
<div>This is the label: {display name=label}</div>
<div>This is the description: {display name=description}</div>
{HTML}
{/literal}

Advanced Smarty Formatting
For more advanced formatting, the plugin can rely on Smarty templates stored on disk. The template is sent the resultset as input.

The content of the output plugin is ignored when the template parameter is set.

Using a template file
{LIST()}
    {output template=/path/to/file.tpl}

    {FORMAT(name="label")}{display name=title format=objectlink}
{display name=description}{FORMAT}
{LIST}


WARNING when using smarty IF:
Please note that if you are using smarty if or otherwise testing for the values of variables returned using the plain formatter, that the value of such variables is not just the string but has the noparse tags as well. These no parse tags are needed in order to prevent extra line breaks and other wiki parsing artifacts to appear. It is recommended to simply test values of raw unformatted variables instead.

For example: ~np~This is the string~/np~





Notes on the Syntax


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

Available Fields


The field list can be found in the Search Index documentation.

Available filters

NameDescriptionBooleanSampleTiki Version
categoriesMatch on the object's directly associated categoriesyes1 OR 37
contentFull 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.		yeshello world7
deepcategoriesMatch on the object's categories or their parents, providing deep searchingyes1 OR 38
languageSearch on the object's language (2-letter code) when available. unknown is used when unspecified.yes*en or fr OR unknown7
typeFilter on object typenowiki page (from Tiki 8 you can search for multiple types by providing a comma separated list)7/8
rangeA date (unix timestamp) range
Must have from and to arguments specified		no<searchfieldname>8
rangeIn 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 otherno<searchfieldname>9
textrangeA text range
Must have from and to arguments specified		no<searchfieldname>8
relationMust have certain relation
Additional field arguments objecttype and qualifier (the relationship) must be specified		no<object_id>8
favoriteShow only the favorited objects of a certain userno{{user}}8
contributorsuser login to search for as the contrbutors for the contentyesadmin OR testuser8


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

Boolean Syntax

To be documented here, see UnifiedSearch for the moment.

Accessible variables:
  • $results, containing the result set. Each results contain all values provided by the search query along with those requested manually.
  • $count, the total result count
  • $maxRecords, the amount of results per page
  • $offset, the result offset
In Tiki 8, the following have been added:
  • $offsetplusone, basically $offset + 1, so that you can say "Showing results 1 to ...."
  • $offsetplusmaxRecords, basically $maxRecords + $offset, so you can say "Showing results 1 to 25"
  • $results->getEstimate(), which is the estimate of the total number of results possible, which could exceed $count which is limited by the max Lucene search results to return set in Admin...Search

Including Pagination
To include pagination below the template, pagination=1 can be used, just like when using the wiki formatter. However, if you want to locate the pagination elsewhere, you can do it using Smarty. Skip the pagination=1 part.

Tiki8
{pagination_links resultset=$results}{/pagination_links}

Examples

Example TPL File

Example showing an add to cart plugin
<table>
  {foreach from=$results item=row}
    <tr>
      <td>
        <h3>{$row.title}</h3>
        <p><em>Category: {$row.category}</em> <strong>Price:</strong> {$row.price}</p>
        {wikiplugin _name="addtocart" code=$row.tracker_field_20 description=$row.tracker_field_21|escape price=$row.tracker_field_24}{/wikiplugin}
      </td>
    </tr>
  {/foreach}
</table>
{pagination_links resultset=$results}{/pagination_links}


Note: In Tiki 9.0 (at least) $row values are wrapped in reversed no-parse tags, so if you want to test for a value within the TPL (e.g. where price == 0 for instance) you would need to use:
{if $row.stock neq '~ /np~0~np~'}
(but without the space between the ~ first and the /)

Example Blog Post List

This code:
{LIST()}
   {list max="10"}
   {filter type="blog post"}
{LIST}


Would produce on this site:

No results for query.


aliases
Plugin List

Contributors to this page: Nelson810 points  , Jonny Bradley1251 points  , Marc Laporte9146 points  , lindon137 points  , mlpvolt4388 points  , Louis-Philippe Huberdeau1046 points  and xavi67984 points  .
Page last modified on Thursday 03 May, 2012 15:11:43 UTC by Nelson810 points .
The content on this page is licensed under the terms of the Creative Commons Attribution-ShareAlike License.

SourceHistorySlideshow

Site Language

Reference Guide

Keywords

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



Tiki Newsletter

Delivered fresh to your email inbox!
Newsletter subscribe icon
Don't miss major announcements and other news!
Contribute to Tiki