Pretty Trackers

Table of contents

• Pretty Trackers
  • 1. Basic idea
  • 2. Basic Example
  • 3. Advanced example (with page selector field)
    • 3.1. tracker field: Page selector.
    • 3.2. wiki plugin: tracker
    • 3.3. wiki plugin: trackerlist (for output)
    • 3.4. a wiki page as a template:
    • Step-by-step tutorial
      • How to Create A Page Selector (Similar to A Pretty Tracker)
      • Step – 1: Create a Trackers Containing a “Page Selector” Field
      • Step – 2 (Optional): Create a Wiki Page to Display All the Items in Your New Trackers
      • Step – 3: Create a Wiki Page Containing the {TRACKER} Plugin
      • Step – 4: Create a Wiki Page Containing the {TRACKERLIST} plugin
      • Step – 5: Create A Wiki Page to Act as a Template
      • Step – 6: Verify that your Page Selector Trackers Works

The concept of a pretty tracker is similar to the functionality of Drupal's CCK (Content Construction Kit) or Mediawiki infoboxes. It allows a site manager to design on a wiki page a form, use a tracker to manage that information, and have the results of each item output on a wiki page. Both the input and the output screens can be formatted with any html one chooses, and that format (template) will apply to all instances.

They were introduced in Tikiwiki 2.0, while some extra features appeared later, like using them in conjunction with page selectors (since Tiki3 ), etc.

You need to define a form that users can input (say a listing of garage sales).
and you can have each instance of that form be represented as a wiki page, using a template you made plus with the form data inserted (!). Or even listing them all in a single wiki page if used combined with the PluginTrackerList

1. Basic idea

Note the difference in TrackerList plugin display when used without and with wiki parameter to use a wiki page as a template to format the fields of a tracker.



The wiki page which is being used as a template ("User Files Template" in this screenshot), needs to be assigned the perm tiki_p_use_as_template to the group of users that you plan that they will work with the pretty tracker, in order to work properly.

2. Basic Example

(Taken from here:
http://doc.tikiwiki.org/PluginTrackerList#pretty_trackers_param_tpl_or_wiki_ )

This basic example of 'pretty tracker' use either param tpl or wiki in the TRACKERLIST plugin call, which means that it is possible to customize how an item is displayed in a page with a smarty template or a wiki page containing smarty code. This is available since Tikiwiki 2.0

For instance, in a page named 'list of items in tracker 5', as example, you may have

{TRACKERLIST(trackerId=5, fields=30:31, showcreated=y, wiki=tpl for each item in tracker 5) /}

where fieldId=30 and fieldId=31 are 2 fields of the trackerId 5

In another page named 'tpl for each item in tracker 5', you may have

{$f_30} : {$f_31}{tr} was created in {/tr}__{$f_created|tiki_short_date}__

Take into account that the page 'tpl for each item in tracker 5' needs the perm tiki_p_use_as_template, in order to be used as a template for another wiki page.

When displayed, the page 'list of items in tracker 5' will look like similar to this

324: foobar was created on __Thu 23/10/08__
 311: toto was created in __Wed 23/10/07__

There is no table shown (if you did not recreate them in 'tpl for each item in tracker 5' for course). This implies that you can define the layout of the wiki page 'list of items in tracker 5', using wysiwyg editor or by using plain wiki markup.

Of course the name of the 'template' page is whatever you want - you need only to give the good reference in the param 'wiki'

Note: $f_created and $f_lastmodif have been introduced in tw>= 3.0. $f_itemId has been introduced in tw>=4.0

You can use also a template file in the file system

{TRACKERLIST(trackerId=5, fields=30:31, showcreated=y, tpl=B) /}

and create a templates/B.tpl. In this case no permissions are required

3. Advanced example (with page selector field)

A few pieces are required.

3.1. tracker field: Page selector.

see: page tracker
Must have: a tracker with field "page selector" with parameter like "0,0,display pagetracker"
Function: links a tracker item sometitle to a wiki page sometitle.
Parameters: auto-assign, size,create
Description:
auto-assign will auto-assign the creator of the item if set to 1
size is the visible length of the field in characters;
create is the name of the existing template to fill as content on the new page.

3.2. wiki plugin: tracker

Must have: a page named something like "add a new item" in the wiki with the TRACKER plugin and parameter "view=page"
function: a wiki plugin to display a form to input info.
see: pluginTracker and plugin tracker advanced

3.3. wiki plugin: trackerlist (for output)

Must have: in the page "display pagetracker" (as above) the plugin TRACKERLIST with parameters "view=page, max=-1, wiki=pagetracker tpl"
function: is used to display individual item/fields in the context of a wiki page.
see: PluginTrackerItem?

3.4. a wiki page as a template:

must have: a wikipage named "pagetracker tpl" (as above) with content including one or more field references like this:
{$f_13} where 13 is fieldID for the info you want to display there.
function: a page which tells the plugintrackerlist how to display the results for that item.

Step-by-step tutorial

The step-by-step tutorial that follows is attached to this wiki page as a downloadable PDF and MS Word files.

How to Create A Page Selector (Similar to A Pretty Tracker)

This tutorial describes how to create a “page tracker”
using the “tracker” feature’s “page selector” field type.
The steps on the following pages are very similar to what
it takes to create a pretty tracker.

This tutorial was done using TikiWiki Release 3.0, using the “Tikipedia” theme.
The current Tikipedia theme has not yet been updated for use with TikiWiki 3.0,
so your results may differ from those described here.

A page selector field looks like a normal text box. The text you type into a page
selctor field becomes the name of a newly created wiki page.

If the text you type in the page selector field matches the name of an existing
wiki page that was created using the page selector field, then you can add or modify
the page using the tracker (#1 below) or wiki-page with {TRACKER} plugin (#3 below) interfaces.

If, however, the text you type in the page selector field matches the name of a wiki
page that was NOT created using the page selector tracker, then some strange results occur.
In this case, the tracker item is created in the page selector tracker, and it indicates that
the item is associated with the named wiki page. The wiki page in question, however,
will NOT contain any of the data that occurs within that tracker item.
This behavior is probably a bug that needs to be addressed, or else is connected
to the use of the “Tikipedia” theme.




Figure 1-A: Four Things Needed to Create an Advanced Pretty Tracker (#2 is optional)

Step – 1: Create a Trackers Containing a “Page Selector” Field

(See #1 in Figure 1-A)

1-A: In your web browser, navigate to…

“http://your server name/tiki/tiki-admin_trackers.php”


1-B: Choose the “Create Tracker” tab (or option) and you should see a form that appears similar to Figure 1-B
(remember, I am using the “Tikipedia” theme and your Tiki’s tracker-creating form may look somewhat different).

Figure 1-B: Creating a Trackers




1-C: Give the tracker a name and description, such as the one depicted in Figure 1-B.


Figure 1-C: Select the appropriate configuration choices for your tracker





1-D: Save the tracker

Figure 1-D: Click the “Save” button to create the tracker



1-E: Verify that the tracker has been created and the fields can now be edited

Figure 1-E: After saving the tracker



1-F: Add a “page selector” field to your tracker

http://<your server name>/tiki/tiki-dmin_tracker_fields.php?trackerId=24
and add a page selector field with the parameter list defined as “1, 0, display example tracker”.
The “display example tracker” indicates the name of the wiki page (see Step 4) that will contain
the {TRACKERLIST} wiki-plugin to display your “Example” tracker.

Figure 1-F: Adding a Page Selector Field to your Trackers



1-G: Add two more fields to the “Example” tracker


Figure 1-G: Adding a Textfield to Your Trackers

Create a text field named “Text Box” and set the parameters to “0,30,,,80”.



Upon saving the new field you should see the following entries
at the bottom of the “Admin Tracker” page…


1-H: Add a text area field to your tracker

Figure 1-H: Adding a Text Area Field

Create a text area field with the parameters defined as, “1,50,10,500,15,80”.
The meaning of each parameter in this list is described in the table below the screenshot.



Table 1-H: Parameters for a text area field (missing from tracker form in Tiki 3.0)

Parameters	type	description	default	version
quicktags	1 or 0	to see the quicktags zone(1 = to see them)	0
width	numeric	number of characters(0 = browser default)	50
height	numeric	number of lines(0 = browser default)	4
max	numeric	maximum number of characters that can be saved
listmax	numeric	maximum number of characters that are displayed in list mode
wordmax	numeric	if not 0 display the word count, if > 0, javascript alert if word count exceeds the value	0	tw>=1.10

Your tracker fields should now be defined as shown below…

Figure 1-H1: Trackers Field Definitions




1-I: Verify that your newly created tracker displays these fields to your liking.

Navigate to:

http://your server name/tiki/tiki-view_tracker.php?trackerId=<your trackerId number>

And see if the three fields you created in the Example tracker appear as they should.


Figure 1-I: The completed Example tracker has three fields

Step – 2 (Optional): Create a Wiki Page to Display All the Items in Your New Trackers

(See #2 in Figure 1A)

This step is optional, but helps in verifying that the items you enter through your wiki-based tracker interface are actually saved to the tracker. The other option is to include some optional text along
with the {TRACKER} plugin (See Step 3), which only displays this text as a message after you have clicked
the “Save” button on your tracker form.

Use the “quick edit a wiki page” module to create a wiki page named “All Example Items”.
This page will be used to display the results of what you enter through the wiki-based input form
that you are about to create in Step 3.

2-A,B: Create a Wiki Page and Include a Simple {TRACKERLIST} Plugin


Figure 2-A: Create a Wiki Page





Figure 2-B: Enter the “{TRACKERLIST}” plugin text in the new Wiki Page.

Step – 3: Create a Wiki Page Containing the {TRACKER} Plugin

(See #3 Figure 1-A)


3-A: Using the “quick edit a wiki page” module, enter the text “Add New Example Item” in the text box and click the “Create/Edit” button…


Figure 3-A: Create a New Wiki Page




3-B: In the text field provided, enter the text that defines the {TRACKER} plugin…


Figure 3-B: The “Add New Example Item” Wiki Page with {TRACKER} Plugin





3-C: Upon saving the Wiki page that contains the {TRACKER} plugin, you should see the tracker fields appear in the wiki page, along with a “Save” button.


Figure 3-C: The Completed TRACKER form as displayed in the Wiki Page

Step – 4: Create a Wiki Page Containing the {TRACKERLIST} plugin

Create a Wiki Page Containing the {TRACKERLIST} plugin to display each item you enter using the “Add New Example Item” Page. (See #4 Figure 1-A)

4-A: Create a Wiki Page titled “display example tracker”

Figure 4-A: Creating a Wiki Page Using the “quick edit a wiki page” Module





4-B: Include this {TRACKERLIST} text…


Figure 4-B: {TRACKERLIST} Plugin in Wiki Page





Once you click the “Save” button, the “display example tracker” page that displays will not look very impressive (Figure 4-C). You will need to create the “exampletracker tpl” template page AND set the appropriate permissions on it (Step 5), before your page selector tracker begins to look like something special.


Figure 4-C: The “display example tracker” wiki page displayed after saving it

Step – 5: Create A Wiki Page to Act as a Template

5-A: Create the “exampletracker tpl” page to act as a template

Figure 5-A: Creating a Wiki Page Using the “quick edit a wiki page” Module




In the wiki page editor, add references for you tracker field ID numbers. The references will be in the form “{$f_<filed ID number>}” (e.g. {$f_230}). You may place these field references anywhere you want in the wiki page, and include other markup around them. If you are using the WYSIWYG editor, you can easily create fancy formats.

5-B: Edit the “exampletracker tpl” file to include your tracker field references

Figure 5-B: Template with Trackers Field References and Markup



5-C: Save your template page


Figure 5-C: The Saved Template Looks Like a Normal Wiki Page - WYSIWYG




5-D: Edit the Permissions on your “exampletracker tpl” file

Navigate to “http://your server name/tiki/tiki-listpages.php” and locate your
“exampletracker tpl” page in the list. Click on the icon shaped like a key
to navigate to the permissions page.


Figure 5-D: Finding Your Wiki Page Using “tiki-listpages.php”




5-E: Select the “Edit Permissions” tab or option

Figure 5-E: View Permissions and Edit Permissions Tabs




5-F: Locate the “Permissions” and “Groups” columns on the “Edit Permissions” page.

Figure 5-F: The “Permissions” and “Groups” Columns You Need to Modify



5-G: Under “Permissions”, check “tiki_p_use_as_template”. Under “Groups”, choose “Anonymous” and then click the “Assign” button at the bottom of the page.


Figure 5-G: Appropriate Permission and Group Selection for the Template Page





5-H: Verify that the permissions have been applied


Figure 5-H: The Edited Permissions Page

Step – 6: Verify that your Page Selector Trackers Works

Navigate back to your “Add New Example Item” page that you created in Step 3,
by entering the following in your browser’s address field:

http://your server name/tiki/tiki-index.php?page=Add+New+Example+Item

6-A: Enter Some Text in the Form Fields


Figure 6-A: Filling in Your Page Selector Tracker’s Wiki-Form





6-B: You should see your “All Example Items” page appear, listing your newly created “Test Example Page”…

Figure 6-B: All Example Items Displaying the Newly Created “Test Example Page”



6-C: Click the “Test Example Page” hyperlink to view your wiki page


Figure 6-C: The “All Example Items” Page Created in Step 2





Figure 6-D: The Wiki Page Created Using Your Page Selector Trackers






6-E: If you place the “Test Example Page” in edit mode, here’s what you will see.


Figure 6-E: What’s Behind Your Newly-Created Wiki Page…




See:

• tracker
• page tracker
• PluginTrackerList

Aliases: PrettyTracker | PrettyTrackers | Pretty Trackers

---