History: PluginTracker

            !  {icon name="sitemap" rotate="270"} Plugin Tracker
!! Overview
Use this ((wiki plugin)) to create a form for inputting an item into a tracker. You can specify what fields will be included in the form. Since ((Tiki6)), this plugin can also be used as a simple way to create custom forms which output the result as pre-formatted wiki pages instead of tracker items.

!! Parameters
{pluginmanager plugin="tracker"}
{REMARKSBOX(type="note",title="Note")}The -+overwrite+- parameter is only to overwrite tracker items (not wiki pages) - not useful when -+discarditem="y"+- {REMARKSBOX}
{REMARKSBOX(type="note",title="Note 2")}When using -+outputwiki+- as template you cannot use Smarty syntax programmatically because the resulting output is static wiki page (not computed against an existing Tracker Item like with Pretty Trackers and TrackerLists) - you can use only -+{$f_XX}+- to indicate the fields values or ((Argument variables)).{REMARKSBOX}

!! Administration
* You can limit the tracker fields that can be used in this plugin in the field admin panel of the tracker: 
+ "Field is public? for use with ((PluginTrackerlist|trackerlist plugin)) option
+ For Tiki 9.x, the User Selector field (the "userId" field in your tracker, perhaps), edit the field, Permissions, Visibility, Visible by All (even though that's counter-intuitive (you want those items private to that use)).  
* If you have a tracker that has only one item per user/IP or if you use the plugin with the param view=user, the plugin will automatically prefill the item if that already exists.
{REMARKSBOX(type=warning, title=Warning)}This plugin can not be used on a cached wiki page.{REMARKSBOX}

!! Examples
{CODE(colors="tiki")}
{TRACKER(trackerId="1" fields="1:3:4" action="Send")} Thanks for your contribution! {TRACKER}
{CODE}

!!! How to pre-fill some fields
In some situation you want to go to a TRACKER page (in our example named SubmitOrder) where fields are automatically pre-filled. In this case you can use an URL like this:
-+tiki-index.php?page=SubmitOrder&autosavefields=1&autosavevalues=tikiwiki+-

When in the page SubmitOrder, you click on Save, and the field 1 will be filled with the value -+tikiwiki+-. If the field 1 is multivalue field (ex: category), the value will be added to the potentially additional value the user has selected whatever the user does.

Tip:
The construction of such URL can use the feature 'Wiki argument variables'
(see ((Advanced Wiki Syntax usage examples|#How_to_display_URL_param_in_a_page_or_the_page_name_or_the_user_name)))
 -+~np~tiki-index.php?page=SubmitOrder&autosavefields=2:3&autosavevalues={​{itemId}​}:{​{page}​}~/np~+-

You could also use the ''url'' parameter "__prefills__" with the corresponding "__values__". See more information here:
* ((PluginTracker Advanced))
* ((PluginTrackerPrefill))
 
See also ((PluginTrackerList)) to see how to use the parameter -+url+- to transfer an -+itemId+- to an URL or ((PluginJQ)) if you want to use jQuery.

!!! How to fill an item in more than one step
If you want to fill some fields of an item in a page and to fill some other ones in another page, you need to use the param ''url'' with the ''itemId'' option.
Example (uses ((SEFUrl)) enabled links):
Page1
{CODE(colors="tiki")}
{tracker trackerId="1" fields="1:2:3" url="Page2?itemId"}
{CODE}
Page2
{CODE(colors="tiki")}
{tracker trackerId="1" fields="4:5:6" url="Page3?itemId"}
{CODE}
Page3 - the final one that will display the currently submitted itemId:
{CODE(colors="tiki")}
{trackerlist trackerId="1" fields="1:2:3:4:5:6"}
{CODE}

It is also possible to use tabs and link to each tab using "cookietab".
Note that the tracker item will be saved by sequence so you better check that no mandatory field rules are on the way.
{CODE(colors="tiki")}
{TABS(tabs="First Tab|Second Tab|Third Tab")}
{tracker trackerId="1" fields="1:2:3" action="Next" url="pageName?cookietab=2&itemId"}
/////
{tracker trackerId="1" fields="4:5:6" action="Next" url="pageName?cookietab=3&itemId"}
/////
{TRACKER(trackerId="1" fields="7:8:9" action="Save")}Saved!{TRACKER}
{TABS}
{CODE}

!!! How to put multiple tracker plugins into a single transaction?
''New in ((Tiki15))''
Plugin tracker's transaction feature enables a sequence of trackers to be chained into a single transaction, which is submitted only after the user submits the last tracker form. Otherwise the transaction is cancelled.
The easiest way to use the feature is to create a wiki page for each of the steps.
Here is an example.
# wiki page: Register+Step+1
+ {CODE(wrap="1" colors="tiki")}
{tracker trackerId="1" fields="2" action="Next" ignoreRequestItemId="y" registration="y" chosenGroup="Registered" transactionName="RegistrationTransaction" transactionStep="0" transactionFinalStep="n" url="Register+Step+2"}
{CODE}
# wiki page: Register+Step+2
+ {CODE(wrap="1" colors="tiki")}
{tracker trackerId="2" fields="4" action="Finish" ignoreRequestItemId="y" transactionName="RegistrationTransaction" transactionStep="1" transactionFinalStep="y"}
{CODE}
The registration and the tracker records of -+trackerId+- 1 and 2 will only get saved after the user presses Finish on Register+Step+2.

!!! How to write a template to display the form elements on the wiki page where the plugin is saved
As mentioned, in a template, use the -+{$f~095~__id__}+- syntax to insert the value of ''fieldId''=__id__.
It is also possible and nowadays ===recommended=== to use the -+{$f~095~__permanentname__}+- syntax to insert the value of __''permanent name"__ of the tracker field __instead of the id__.
It is also ===recommended=== to use a specific custom prefix for all fields of a tracker (one prefix per tracker) to allow to reuse and to provide existing trackers easily with a profile. Syntax:  -+{$f~095~___prefix_permanentname__}+-. The prefix can be set in the tracker preference settings.

It is also possible to insert the ''ItemId'' itself, which is useful to create new wiki pages with tracker plugins inside. To do this you'll have to add an ((Auto-Increment Field)) to your tracker, with the appropriate options to auto-fill it with the ''itemId''. This new field content (''itemId'' value) can then be inserted in the template with the syntax seen above.

Since ((Tiki15|Tiki 15.1)), wiki page templates can be (optionally) used for email notifications using the "__wiki:page name tpl__" format instead of -+template_name.tpl+- files in the -+templates/mail+- dir. Tiki will use a page "page name subject tpl" if found.
Please mind, that wiki pages are more for quick and easy use cases, for testing and for proof of concept, whilst -+.tpl+- files in the server directory are more reliable and much better to handle in larger projects or for advanced use cases.

Mind: -+.tpl+- templates for emails are stored in the folder -+templates/mail+-

!! How to go from TRACKERLIST to TRACKER on this item
{CODE(colors="tiki")}
{trackerlist trackerId="1" fields="1:2:3:4:5:6" url="Page1?itemId"}
{CODE}

!! Email
!!! How to send email to a recipient when new tracker item is created
You can use the parameter -+email+- to send an email once the tracker item has been created.
{REMARKSBOX(type="note" title="Important")}From ((Tiki15)) onwards, you need to have:
* a template:
** placed in your Tiki files root in the -+templates/mail+- directory, 
++ __or__ 
** specified as a wiki page as "wiki:page name tpl", 
* and you need to set an email address to monitor changes of the Tracker, at the Tracker properties level
+ ("Trackers > Edit tracker > Notifications > __Copy activity to email__"). (This should not be needed; is this a regression? {sign user="luci" datetime="2022-06-20T16:34:07+00:00"})
{REMARKSBOX}

The format for the email parameter is: from|to|template.
*__from__ is the sender email that will be used for the notification. Multiple addresses can be set (separate multiple addresses with a comma)
*__to__ is the recipient(s) to whom the email address will be sent.
+ Multiple addresses can be set (separate multiple addresses with a comma).
+ Since Tiki 11 (maybe earlier) you can set a tracker field (same item) being used in the tracker plugin template (required).
* __template__ is the template(s) to be used for email subject and body. (separate templates can be used)
+Using several emails and several templates it is possible to send different email (different subject & body) to different people. (see examples below)
* The following values can be used for ''__from__'' and ''__to__'':
+ __email(s)__, __username(s)__, __fieldId(s)__ or __createdBy__
+ -+createdBy+- was added in ((Tiki 17)) and ===might=== be back-ported to 16.
+ username sends to the email of the registered user account and -+createdBy+- sends to the email of the currently logged in creator of the item.

Since ((Tiki15|Tiki 15 .1)), Tracker plugin allows ((Items List and Item Link Tracker Fields|Items List fields)) to be used as the __to__ or __from__ fields in the email parameter. They will be shown in the form as read only labels. This might be useful in cases such as:
* One tracker defines business shops, with its members to be notified of changes related to that shop. And...
* A second tracker handles data of products from shops, and they have:
** one field as ''Item link'' to relate the product with their corresponding shop where they sell it.
** another field from the second tracker is an ''Items list'', to indicate the person to be notified, as user defined in the first tracker for that shop. 
* You use the email parameter in a plugin tracker call to tracker 2, using the field corresponding to the person (as field id in tracker 2) as the recipient or sender of the email.

Since ((Tiki16|Tiki 16.3)), email recipients option allows to set fieldId of a ((User selector|UserSelector)) (including multiple users selected) and ((Group selector|GroupSelector)).

!!! Basic plugin usage
__single recipient, single template__
{CODE(colors="tiki")}
{TRACKER(trackerId="1" fields="1:2:3" action="Send" email="sender@domain.com|recipient@domain.com|templatename.tpl")}{TRACKER}
{CODE}

__single recipient (creator), default site sender, basic default template (for quick proof of concept)__
{CODE(colors="tiki")}
{TRACKER(trackerId="15" action="Send"  email="|createdBy|")}
Thank you for submitting an issue.
We will come back to you as soon as possible.
What do you want to do now: ((Issue Tracker|submit another issue)) or ((HomePage|browse the website))?
{TRACKER} 
{CODE}

__single recipient (creator), custom sender, custom template for body, default basic subject__
{CODE(colors="tiki")}
{TRACKER(trackerId="15" action="Send"  email="info@example.com|createdBy|mytemplate.tpl")}
Thank you for submitting an issue.
We will come back to you as soon as possible.
What do you want to do now: ((Issue Tracker|submit another issue)) or ((HomePage|browse the website))?
{TRACKER} 
{CODE}

__single recipient (creator), custom sender, custom template for body, custom subject template__
{CODE(colors="tiki")}
{TRACKER(trackerId="15" action="Send"  email="info@example.com|createdBy|mytemplate.tpl,mytemplate_subject.tpl")}
Thank you for submitting an issue.
We will come back to you as soon as possible.
What do you want to do now: ((Issue Tracker|submit another issue)) or ((HomePage|browse the website))?
{TRACKER} 
{CODE}

!!! Advanced plugin usage 

__multiple recipients, single template__
{CODE(colors="tiki")}
{TRACKER(trackerId="1" fields="1:2:3" action="Send" email="sender@domain.com|recipient_1@domain.com,recipient_2@domain.com,recipient_3@domain.com|templatename.tpl")}{TRACKER}
{CODE}

In this case it will send the same notification to recipient_1, recipient_2 and recipient_3.

__multiple recipients, multiple templates__
{CODE(colors="tiki")}
{TRACKER(trackerId="1" fields="1:2:3" action="Send" email="sender@domain.com|recipient_1@domain.com,recipient_2@domain.com,recipient_3@domain.com|templatename_a.tpl,templatename_b.tpl,templatename_c.tpl")}{TRACKER}
{CODE}

In this case each recipient will receive a different notification. The recipient_1 will receive email using template_a, recipient_2 will receive email using template_b and recipient_3 will receive email using template_3.

__creator plus second recipient, two different body templates and two different subjects__
{CODE(colors="tiki")}
{TRACKER(trackerId="15" action="Send"  email="info@example.com|admin@mysite.com,createdBy|admin-template.tpl,creator-template.tpl,admin-template_subject.tpl,creator-template_subject.tpl")}
Thank you for submitting an issue.
We well come back to you as soon as possible.
What do you want to do now: ((Issue Tracker|submit another issue)) or ((HomePage|browse the website))?
{redirect page="Test-Tracker-Creator-Email"}
{TRACKER} 
{CODE}

__single recipient (field), custom sender, custom template to fill the tracker plugin, custom template for body, custom subject template__

Wiki page
{CODE(colors="tiki")}
{TRACKER(trackerId="15" action="Send" email="info@exemple.com|12|mytemplate.tpl" wiki="Template page")}Thank you!{TRACKER}
{CODE}

Template page
{CODE(colors="tiki")}
{TR()}Name{TR}: {$f_11}
{TR()}Email address{TR}: {$f_12}
{CODE}

When filling the form (using the template) the email address from the field 12 will be used as recipient.


!!! Templates (to create the email subject and email body)
Each template needs two files, one for the subject one for the body. All the templates must be in the templates/mail directory or (since Tiki15.1) in wiki pages and specified as "__wiki:page name tpl__" (you have to include the "__tpl__" exact word in the name without a dot, and place it, for instance, at the end).

!!!! Email body and subject naming conventions
The naming of these files needs to be slightly different depending on whether you use template files on disk or wiki pages as templates.

!!!!! Template files on disk
If you want to use smarty template files on disk:
* body: "__mytemplate.tpl__"
* subject: "__mytemplate_subject.tpl__"

Example:
{CODE(colors="tiki")}
{TRACKER(trackerId="1" fields="1:2:3" action="Send" email="sender@domain.com|recipient@domain.com|mytemplate.tpl")}{TRACKER}
{CODE}

Note that you don't specify the subject template in the tracker plugin call, but the subject needs to exist with the corresponding name ("mytemplate_subject.tpl" in this case) if you want to have the subject message customized.

!!!!! Wiki pages as Smarty templates
If you want to use wiki pages as smarty templates:
* body:  "__page name tpl__"
* subject:  and "__page name subject tpl__"
+ note that the tpl word (without a dot) needs to be prepended with the word "__subject __" (subject __and a space__)

Example:
{CODE(colors="tiki")}
{TRACKER(trackerId="1" fields="1:2:3" action="Send" email="sender@domain.com|recipient@domain.com|wiki:page name tpl")}{TRACKER}
{CODE}

Note that you don't specify the subject template in the tracker plugin call, but the subject needs to exist with the corresponding name ("page name subject tpl" in this case) if you want to have the subject message customized. 

!!!! Subject template
{CODE(colors="tiki")}
Hello, the {tr}item{/tr} "{$f_name}" {tr}was modified at{/tr} {$server_name} in {$mail_trackerName}
{CODE}

Where ~np~{$f_name}~/np~ will be the content of the field name, ~np~{$server_name}~/np~ is the domain name and ~np~{$mail_trackerName}~/np~ is the tracker name.

!!!! Body template
{CODE(colors="tiki")}
{tr}Hello,{/tr}

{tr}Title:{/tr} {$f_name}
{tr}Description:{/tr} {$f_description}

{tr}View the tracker item at:{/tr}
	{$mail_machine_raw}/tiki-view_tracker_item.php?itemId={$mail_itemId}
{CODE}

!!!! Template - variable list
Not all wiki variables work (pretty tracker syntax won’t work).
;$mail_date : The current timestamp
;$mail_user : User login
;$mail_itemId : The tracker itemId
;$mail_item_desc : The item "title"
;$mail_trackerId : Tracker id
;$mail_trackerName : Tracker name
;$mail_machine : URL of the request (example: -+https://doc.tiki.org/PluginTracker+- )
;$mail_machine_raw : URL of the site root (example: -+https://doc.tiki.org+- )
;$server_name : Server name (example: -+doc.tiki.org+- )
;$status : The item's new status (e.g. Open, Pending or Closed, translated)
;$f_123 or $f_permanentName : Values of the fields


!!Related pages
See also:
* ((PluginTrackerlist)) - which displays a given tracker items. 
* ((PluginTracker Advanced))
* ((Pretty Tracker))
* ((PluginList))