Loading...
 
Skip to main content

History: PluginList

Source of version: 217

Copy to clipboard
            ! Plugin List
''Introduced in ((Tiki7))''. If you are searching for the list of all plugins, see ((All Plugins)).

{maketoc title="Sections within this page" levels="2,3"}

!! Introductionary 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 ((Unified Index|search index)) so it should be emphasized that this means that ===only=== the data that has actually been indexed by the ((Unified Index)) can be accessed. A 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 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 ((PluginTrackerlist|TrackerList)) plugin but it is not limited to just the ((Tracker)) data. When combined with the ((PluginCustomSearch)) plugin, LIST can replace ((PluginTrackerlist|TrackerList)) and ((PluginTrackerfilter|TrackerFilter)) plugin usage and can considerably extend it!! Please also see ((PluginListExecute)).

!!! 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 aswell 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 practice in respect of a consistent sort order. This is not mandatory, but makes it easier to understand the prinicple, 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 extend, you can nest them aswell. 

!!! 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 aswell, maybe even better sense for some reason. 

The control block ''"~np~{FORMAT(name=...)}~/np~"'' (in upper case) wraps around the control block ''"~np~{display}~/np~"'' 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 ''~np~{filter} and in the {column}~/np~'' inside the  ''"~np~{OUTPUT(template=table)})~/np~"'' control block.
Contrarily we use ''"name"''  in the optional ''~np~{display}~/np~ and  ~np~{FORMAT()}''~/np~ control blocks.

__When we use this ...__

{CODE()}
{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}
{CODE}

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

{CODE()}
{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}
{CODE}

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

When we reference the orignal 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 __((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.

!!Additional child pages of the LIST documentation

{toc}

!! Syntax Overview 

The overall format is the same as any other plugin: 
{CODE(colors="tiki")}
{LIST()}
body content
{LIST}{CODE}

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 :

{FANCYTABLE(head="__::plugin-like control block::__|__::description::__|__::version::__|__::default or required::__|__::see below for more detail::__" sortable="n")}
__list__ or __pagination__| The LIST plugin will display 50 results by default but depending on the output you might want to decrease the visible amount of results to improve performance. |pagination from Tiki 11 |default is 50 items | see the child page ((PluginList pagination or list control block)) for full details and worked examples
__filter__ |is a ===required=== control block in the LIST body content and is  used to define the search query that will be carried out ie what objects from the complete set that have been indexed by the Unified Search will be included in the resultant list |  |:: required:: |   see the child page ((PluginList filter control block)) for full details and worked examples
__OUTPUT__ |defines what the output 'template' will be by either using one of several standard/built-in templates eg table, medialist or carousel or by referencing a user defined wiki or smarty template. For the table template for example, the body content is used to define which columns/fields are shown |  |::optional:: |     see the child pages ((PluginList output control block)) and ((PluginList advanced output control block)) for full details and worked examples
__ALTERNATE__  |used in conjunction with the OUTPUT control block it can define an alternative output when an individual item (row) from a search/listing has no value | | ::optional::  |see the child page ((PluginList output control block)) for more details and worked examples
__FORMAT__ |The FORMAT control block is used to create individually templated objects that can then be used in any of the individual OUTPUT methods.  | | ::optional:: |see the child page ((PluginList format control block))  for full details and worked examples
__DISPLAY:__ |Used to define placement and formatting of individual objects|  |  ::optional:: |  see the child page ((PluginList display control block))  for full details and worked examples
__SORT:__ |allows the resultant list of objects to be sorted in a specified order|  | ::optional:: |  see the child page ((PluginList sort control block)) for full details and worked examples
{FANCYTABLE}

!! Basic worked example

::step by step instructions to be added here for a 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 ((pr:Easy Geoblog)), which is available at the ((Profiles Wizard)) ).
 
!! Body content elements of the LIST Plugin

Each of the principle plugin-like control blocks are described in more detail in the following set of child pages:
{toc}

!! 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 ((Unified Index)) documentation.

!! More Worked Examples

!!! Example Tracker item with Comments

!!!! Item
{CODE(colors="tiki")}
{LIST()}
 {pagination max="1"}
 {filter type="trackeritem"}
 {filter field="object_id" content="{{itemId}}"}
{LIST}
{CODE}

!!!!! Comments
{CODE(colors="tiki")}
{LIST()}
 {filter type="comment"}
 {filter field="parent_object_id" content="{{itemId}}"}
 {filter field="parent_object_type" content="trackeritem"}
{LIST}
{CODE}

!!! Example Tracker item with a picture (file)

{CODE(colors="tiki")}
{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}
{CODE}

!!!! Same Example as above within a table 
(see: ((PluginList output control block|LIST - OUTPUT control block)))

{CODE(colors="tiki")}
{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}
{CODE}


!!! Example Blog Post List
''This code:''

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

''Would produce on this site:''

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

!!Tutorials
* ((Tutorial - Display Tracker Data with Plugin List))
*[https://www.youtube.com/watch?v=oMgf1GcWzOs|LIST plugin demo and nesting tracker items - Youtube]

!!Related
See also:
* ((PluginTrackerList))
* ((PluginTracker))

-=Aliases=-
* (alias(Plugin List))

        

History

Advanced
Information Version
Sammy Ndabo Fix incorrect phrase 242
Marc Laporte 241
drsassafras spelling, grammer 240
Marc Laporte 239
Jonny Bradley added params 238
Alessandro Martinelli 237
Alessandro Martinelli Added a few words about nested lists. 236
Jonny Bradley fancytable Plugin modified by editor. 235
Marc Laporte 234
Marc Laporte 233
Nelson Ko [Rollback by koth to version 230] 232
Nelson Ko 231
Nelson Ko 230
Nelson Ko 229
Nelson Ko 228
Jean-Marc Libs This section is always at the bottom on other pages and it is really useful for navigation so I always look for it first 227
Roberto Kirschbaum Remarksbox pointing to TrackerListToListConverter 226
G. change Pretty Trackers link from linking to an inner page because the inner page is not recognized for whatever reason 225
G. fix the fix 224
G. fix wrong link for Pretty Tracker 223
Marc Laporte 222
Marc Laporte AutoTOC 221
Roberto Kirschbaum fix typo 220
Marc Laporte 219
Marc Laporte 218
Jean-Marc Libs 217
luciash d' being 🧙 216
luciash d' being 🧙 215
drsassafras moving aggragate command to new page 214
Victor Emanouilov 213
luciash d' being 🧙 212
egberto 211
Bernard Sfez / Tiki Specialist Edit restored by rescue script 2017-04-24T18:09:12+00:00 210
Bernard Sfez / Tiki Specialist Edit restored by rescue script 2017-04-24T18:09:12+00:00 209
Bernard Sfez / Tiki Specialist 208
Bernard Sfez / Tiki Specialist 207
Bernard Sfez / Tiki Specialist 206
Bernard Sfez / Tiki Specialist 205
pianoliv adding youtube tuto link 204
Torsten Fabricius 203
Torsten Fabricius so many '' ... maybe I should not make so many words "italic"? 202
Torsten Fabricius 201
Torsten Fabricius typo like ..... arrgs! 200
Torsten Fabricius typos all over the place, sorry ... fixed straight away ;-) 199
Torsten Fabricius 198
Torsten Fabricius 197
Torsten Fabricius minor text revision (language) 196
Torsten Fabricius again revised my newly added content 195
Torsten Fabricius again revised my newly aded content 194
Torsten Fabricius typo 193