History: PluginTrackerFilter

Source of version: 77 (current)

Use this ((wiki plugin)) to give an interface to filter a tracker's items by field values.

{REMARKSBOX(type=info)}Since ((Tiki7)), there is a more modern (and slightly more complicated) way of displaying tracker listings (and more). Please see ((PluginLIST)) and ((PluginCustomSearch|CustomSearch))
based on ((Search and List from Unified Index|UNIFIED SEARCH)) and provides a much more feature rich set of capabilities.{REMARKSBOX}

! Plugin TrackerFilter

!! Syntax
{CODE(caption=>example,wrap=>1)}
{TRACKERFILTER(trackerId=1, filters=1/d:2/r:3, fields=1:4:5)}This is the result{TRACKERFILTER}
{CODE}

!! Parameters
The plugin has a core set of parameters, but because it also shares all the parameters available from the ((PluginTrackerList|TRACKERLIST)) plugin, these additional parameters can be added to customise the look of the result (except the filterfield, exactvalue and filtervalue - using these parameters will overwrite the core filter selection) 

The__ core set of parameters __are as follows:
* __trackerId__: Id of the tracker
* __filters__ is the list of fields that can be filtered with the format of their display.
+The fields are identified by their numeric Ids. All the fields must belong to the same tracker. After tiki>=8, the status can be a filter and must be entered as status or Status (Filter example: 3/d:Status/d)
+The Id can be followed by the character / and one of this format:
** d: drop down list of all the values occurring for the field: only one value can be selected
** r: radio buttons of all the values occurring for the field: only one value can be selected
** m: multiple choice in the drop down list of all the values occurring for the field( a multiple choice acts as an OR between the values of the choice)
** c: checkbox (multiple choice) in the drop down list of all the values occurring for the field
** t: text entry (tiki >= 2.0): a text input where the user must enter a part of the text
++If the text contains % like a%. it will search all the values beginning with % (can also do %a or a%b%c) or a* or *a
** T: text entry (tiki >= 2.0): a text input where the user must enter an exact value of the field
** i: text entry + initial (tiki >=2.0): a list of initial that will directly filter on an initial. Note: if you use initial, not other field can be filtered
** sqlsearch: advanced mysql search (tiki >= 5.0): a list of fields where a mysql advanced search will be done - Note: the search is done field content per field content: It means if you query A B and A is in a field and B in another one you will not find the item. The syntax will be (1:2)/sqlsearch means 'do a advanced mysqlsearch on fields 1 and 2.
** > or < or >= or <=: comparison (tw >=6.0): the field will be compared using the format as operator. Ex: filters="1/>=" will find all the items with the field 1 bigger (for a numeric)  or after (for a date) the value the user will give
** range: range of values ( -+from+- and -+to+- search boxes shown). Timezone-aware fields like JsCalendar field are converted properly before being searched, so search is done in the correct timezone. Range filter can be used with any field - not only dates but it is most useful for dates and numeric fields. ((Tiki16|tiki >=16.2))
* __fields__ will show the fields displayed for the selected items
* __action__ : name of the submit button - default is "filter" (tiki >= 1.9.8)
* __noflipflop__:  will not show the flipflop to hide and display the list of filters. (tiki >=6.0)
* __export_action__:  (tiki >= 6.0) if set to appropriate text e.g."Confirm CSV Download" this over-rides the normal trackerfilter approach and displays a button with the designated text that directly exports the set of fields specified as a CSV file. A filter to define a specific 'filter set' must be defined by using the filterfield, filtervalue/exactvalue parameters, formatted in the standard ways. Additional parameter options are (default|alternate):
**__export_itemid__=y|n - includes the ItemId in the export
**__export_status__=n|y - includes the status field in the export
**__export_modif__=n|y - includes the modified date in the export
**__export_created__=n|y - includes the creation date in the export
**__export_charset__=UTF-8|ISO-8859-1 - defines the character set to be used for the export
*__mapButtons__=y|n - Display Mapview and Listview buttons (from Tiki6, requires Google Maps feature)
*__url__ replace tracker item url with the url you input in the field. You can include the Item Id. This is very usefull combined with TrackerList and/or Pretty tracker to link the results of the tracker filter to another page (wiki or template) where the item will be displayed as single entity (using TrackerList plugin).
+''Use Case'' : Search and display tracker item in wiki pages without any relation to the trackers usual design (buttons, pagination, etc)
+Set the plugin TrackerFilter in a wiki page to display and filter tracker item. Be sure it is working with the usual parameters and display items. Set the parameter Show Links to yes (showlinks="y") and in the parameter URL set the page that will be used to display the item once the item link is clicked with the following url="singleitem_tpl?itemId". 
+Create a second wiki page named "singleitem_tpl". In this page set the plugin TrackerList with the Tracker Id parameter and set for Wiki Page (wiki="item_tpl").
+Create a third page named item_tpl that you are now free to design the way you want that will display the item fields.
+ That way you can design all the way the page using wiki syntax and CSS and the user will never have the feeling he is looking at a tracker or at trackers items.

The __full set of available parameters__,  the core TRACKERFILTER set and the additional ones from TRACKERLIST,  are set out in the various TABS below:

{TABS(tabs="Main|Basic Filtering|Show/Hide|Calendar|Export" toggle="y" inside_pretty="n")}
{pluginmanager plugin="trackerfilter" paramtype="none"}
/////
{REMARKSBOX(type=tip title=Note)}''These parameters allow the results to be pre-filtered before the user sees them. To allow the user to filter, sort or paginate results, see the parameters under the tablesorter tab.''{REMARKSBOX}
{pluginmanager plugin="trackerfilter" paramtype="filter"}
/////
{pluginmanager plugin="trackerfilter" paramtype="show"}
/////
{pluginmanager plugin="trackerfilter" paramtype="calendar"}
/////
{pluginmanager plugin="trackerfilter" paramtype="export"}
{TABS}
!!!Additional note on parameters
* __Info on 'filters' parameter field formats:__
** d: drop down list of all the values occurring for the field: only one value can be selected
** r: radio buttons of all the values occurring for the field: only one value can be selected
** m: multiple choice in the drop down list of all the values occurring for the field( a multiple choice acts as an OR between the values of the choice)
** c: checkbox (multiple choice) in the drop down list of all the values occurring for the field
** t: text entry: a text input where the user must enter a part of the text
++If the text contains % like a%. it will search all the values beginning with % (can also do %a or a%b%c) or a* or *a
** T: text entry: a text input where the user must enter an exact value of the field
** i: text entry + initial: a list of initial that will directly filter on an initial. Note: if you use initial, not other field can be filtered
** sqlsearch: advanced mysql search (Tiki5): a list of fields where a mysql advanced search will be done - Note: the search is done field content per field content: It means if you query A B and A is in a field and B in another one you will not find the item. The syntax will be (1:2)/sqlsearch means 'do a advanced mysqlsearch on fields 1 and 2.
** > or < or >= or <=: comparison (Tiki6): the field will be compared using the format as operator. Ex: filters="1/>=" will find all the items with the field 1 bigger (for a numeric)  or after (for a date) the value the user will give
*__Notes on the use of the export option:__
**if the export_action parameter is not empty then the basic functionality of the plugin is changed to allow designated fields and other parameters to be exported as a CSV file for ALL the tracker items with the substitution of the normal  'Filter' button  by a custom button using the export_action text
**the fields that are exported are those specified in the 'fields' parameter
**other item values can be exported by setting the following parameters:
***export_status is set to 'y' to show the status of the individual item in the CSV file (the default is 'n')
***export_created is set to 'y' to show the item's creation date in the CSV file (the default is 'n')
***export_modif is set to 'y' to show the item's modification date  in the CSV file (the default is 'n')
***export_charset can be set to the character set to be used in the export ie typically UTF-8 which is the default
**__Please note:__ if the export_action parameter is not empty then there is currently a problem with using the plugin editor, since for the export option there is no need to set the filters parameter - but for normal use this is a required parameter. This exception is allowed for in the main plugin code but at present the plugin editor does not recognise the exception and will not complete the 'Insert' until this parameter is entered. It is therefore recommended that edits to the trackerfilter plugin are carried direct in the main editor(s) when using the export option.
*__url__ replace tracker item url with the url you input in the field. You can include the Item Id. This is very useful combined with TrackerList and/or Pretty tracker to link the results of the tracker filter to another page (wiki or template) where the item will be displayed as single entity (using TrackerList plugin).
+''Use Case'' : Search and display tracker item in wiki pages without any relation to the trackers usual design (buttons, pagination, etc)
+Set the plugin TrackerFilter in a wiki page to display and filter tracker item. Be sure it is working with the usual parameters and display items. Set the parameter Show Links to yes ( -+showlinks="y"+- ) and in the parameter URL set the page that will be used to display the item once the item link is clicked with the following -+ur<x>l="singleitem_tpl?itemId"+- . 
+Create a second wiki page named "singleitem_tpl". In this page set the plugin TrackerList with the Tracker Id parameter and set for Wiki Page ( -+wiki="item_tpl"+- ).
+Create a third page named -+item_tpl+- that you are now free to design the way you want that will display the item fields.
+ That way you can design all the way the page using wiki syntax and CSS and the user will never have the feeling he is looking at a tracker or at trackers items.
!!! Field types allowed
|| Field type | since tiki version
category - e | 6, and probably earlier
drop-down list - d | 6, and probably earlier
email - m | 6, and probably earlier
text field - t | 6, and probably earlier
textarea - a | 6, and probably earlier
numeric field - n | 6, and probably earlier
country - y | 6, and probably earlier
user | 6, and probably earlier
group | 6, and probably earlier
item list | 9, only as text
item link | 9, only as text
auto-increment | 9
freetags | 9
||

Note:
For a drop-down list, the values of the drop down list will be displayed, For the other field types, the values found in the database will be displayed.
!!Examples

!!! Trackerfilter with table sorter setting to perform calculations
As the data are filtered you can also perform calculation on the fly.

Here we add all the value of the last col.
{CODE()}
{trackerfilter filters="273/d:431/d" displayList="y" noflipflop="y" trackerId="21" fields="273:268:269:435:431" showlinks="y" shownbitems="y" showcreated="n" showlastmodif="n" showlastmodifby="n" status="o" max="-1" editable="114" server="n" sortable="y" tsortcolumns="type:none|type:none|type:none|type:none|type:none" tsfilters="type:text|type:nofilter|type:nofilter|type:nofilter|type:nofilter"  tstotals=" | | | |type:col;formula:sum;label:total " tstotaloptions="ignore|ignore|ignore|ignore|#,###"}
{CODE}

!!! Checkbox
It can be interesting to use the checkbox capacity of trackerlist to do some action on some filtered items:
{CODE(colors="tiki")}
{trackerfilter filters="82/d:84" fields="82:83" checkbox="85/to/Email to checked/send/soho-send_message.php/soho-send_message.tpl"}
{CODE}

You can also get directly connected to the message box
{CODE(colors="tiki")}
{trackerfilter filters="82/m:84" fields="82:83" checkbox="85/to/Email to checked/xxx/messu-compose.php"}
{CODE}

Imagine a tracker 
{BOX(bg=grey)}{img fileId=213 }{BOX}
A search page like this
{CODE(colors="tiki")}
{trackerfilter trackerId="1" filters="5:6:9:8/d:(2:1:3)/sqlsearch" showlinks="y" fields="5:2:1" wiki="tracker ideas"}
{CODE}
The page will look like
{BOX(bg=grey)}{img fileId=212 }{BOX}

and when you  click on filter you will have something like this
{BOX(bg=grey)}{img fileId=214 }{BOX}