JITS-Talk-Tutorial

Summary: JITS Tutorial
Version: 20070404
Prerequisites:
Status:
Maintainer: Jiri
Categories:

Questions answered by this recipe

This section is optional; use it to indicate the types of questions (if any) this recipe is intended to answer.

What is JITS

Jiri's Issue Tracking System .
The main features

  • you can have multiple issue tracking systems in the site (e.g. CoreModules,Addons, Bundles, ...)
  • all tracking systems are using a few shared standard PmWiki pages placed in the JITS wikigroup.
  • If AuthUser and ZAP enabled no /cookbook files, no /local/config.php customization.
  • The issues lists can be filtered and sorted on several issue properties.
  • The optional customisation is provided by optional configuration pages per <Group>.
  • The posts (issues and comments) can be re-edited by the original author or the user with Edit authorization.
  • The user with the @admins rights can process batch deleting selected issues including their comments.
  • Easy to install
Author: Ing.Jiří Hladůvka, mail at revida dot sk

What is new in this version

How to organize JITS in the site

When describing the system in this documentation a specific JITS means a bunch of related PmWiki pages.
You can have JITS for someone's tasks (e.g. JITS for Adams' tasks, JITS for Bob's tasks) or JITS for investments or JITS for Projects - all in one site using shared pages in JITS group that are part of the distribution.

Depends on site administrator how the JITS are organized.
You can have the structure:

  • Adams (wikigroup Adams)
    • Adams/Projects (JITS Adams→Projects)
    • Adams/Tasks (JITS Adams→Tasks)

and a similar wikigroup for Bob

and

  • Projects (wikigroup Projects)
  • Projects/ProjectA (JITS Projects→ProjectA)
  • Projects/ProjectB (JITS Projects→ProjectB)

When working with some JITS (e.g. JITS Adams→Projects) you can list issues of other site's JITS.
Just set the filter "in Group" to the value "all", list all JITS issues and then switch to any listed by displaying the issue.

In the wikigroup containing some JITS you can have other types of pages; the JITS pages are differed from the others by the page variable identifying them as JITS-type-page. Thus the snippet which is necessary to be placed into the GroupFooter is applied only to JITS-type-pages.

How to install JITS

There is no need to change pages created with previous JITS versions

1. download and unzip the JITSversion.zip file from Cookbook.JITS page into wiki.d/ folder
there should be pages:

  • JITS.JITSsnip - the main source
  • JITS.JITSPgLstS - the standard source controlling the filters form and pagelists
  • JITS.JITSPgLst - the customisable source controlling the pagelists
  • JITS.JITScfgS - the source controlling the basic values of the forms selectboxes
  • JITS.JITScfg - the customisable source controlling the values of the forms selectboxes
  • JITS.JITSTutorial - this tutorial (continue reading this tutorial from your site)
  • JITS/JITSadmin - the administrator's page

2. Create some training JITS e.g. MyJITS in the Test wikigroup

  • create and edit Test.GroupFooter and copy and paste this source to the page beginning :
    (:if equal {*$:PInd} "JITS":)(:include JITS.JITSsnip #grpftr#grpftrend:)(:ifend:)
    

    Save the changes.
  • create and edit Test.MyJITS page and copy and paste this source to the page beginning:
    (:include JITS.JITSsnip #mainpage#mainpageend:)
    (:JITSlevel: main:)
    

    You can prepend the snippet by short (:title...:) or any description.
    Save the changes.
  • Set the ZAP password for the group (e.g. in Test.GroupAttributes?action=attr) to enable submitting the forms.(Must be set even if to "@nopass").
  • The MyJITS main page is displayed.
    Probably no pagelist is diplayed. Just click the button "New issue".

Process this step (2) to create further JITS (e.g. John.ProjectA, John.ProjectB, John.PersonalTasks ...)

3. Maintain the security of the JITS group against editting by unauthorized users - especially the JITS/JITSadminpage which enables mass deleting the issues and comments.


Customisation (optional)

  • Customisation of the filters and selectboxes option values for site-wide JITS
    (it's easy but advanced knowledge is a plus).
    • Display the JITS.JITScfg page source ( JITS.JITScfg?action=source ).
      Edit the (:input select ...:) lines
  • Customisation of the filters and selectboxes option values just for a specific <Group> wikigroup
    • create and edit <Group>.JITScfg page and paste&copy the source of JITS.JITScfg
    • modify <Group>.JITScfg according to your needs (how to is displayed on that page)
  • Issue pagelist customisation for site-wide JITS.
    • Edit the JITS.JITSPgLst (the fmt parts)
  • Issue pagelist customisation just for a specific <Group> wikigroup.
    • Create <Group>.JITSPgLst page and copy&paste the source of JITS.JITScfg.
    • Modify according to your needs.
Remember: When displaying the JITS the <Group>.JITScfg and <Group>.JITSPgLst is prefered to JITS.JITScfg and JITS.JITSPgLst

Combining property filter values

You can customize the <Group>.JITScfg page by this example:

(:input select name="Status" value="inprocess,open"  label="Xactive":)
(:input select name="Status" value="suspended,closed,dismissed"  label="Xinactive":)

Just avoid to select such a value when creating or editing the issue.(That is why I prepend "X" to the label). If you mark some issue with that then the "Status=all" filter ONLY can find it in the pagelist. As well no icon is available.

Display Issue-list

Display the issue-list alone; custom-filtering defined in markup without the filter-display
Example of Closed Issues:

 (:title All JITS Closed Issues:)
(:include JITS/JITSPgLstS #issuelist#issuelistend:)
(:sort: -$:ChngDate :)
(:filterG: *:)
(:JName: *:)
(:Type: *:)
(:Project: *:)
(:Status: closed:)
(:Priority: *:)

Adding icons

My customisation is this:
For each item of the select items create <picture>.gif (e.g. bug.gif, proposal.gif ...) and upload them preferably to /uploads/JITS.
The picture filename has to correspond to the "select value". So if you have a "Type" option

(:input select name="Type" value="eRRor"  label="Fatal error":)

you should have an eRRor.gif picture.

Customise the <Group>.JITSPgLst (or JITS.JITSPgLst) by the following example.
(If you are missing some picture for a specific item then create a blank transparent gif for that item.)

locate (near the end of the page) and replace

[[{=$Group}/{=$Name}|{=$Name}]]
(:cell:){=$:Summary} 
(:cell align=right:){=$:CDateWritten}
(:cell:){=$:Type}
(:cell:){=$:Project}
(:cell:){=$:Status}
(:cell:){=$:Priority}
(:cell align=right:){=$:CChngDate}
(:cell:)[[~{=$:ChngAuth}]]

with

[[{=$Group}/{=$Name}|{=$Name}]]
(:cell:){=$:Summary} 
(:cell align=right:){=$:CDateWritten}
(:cell style="white-space: nowrap;":)Attach:JITS/{=$:Type}.gif {=$:Type}
(:cell:){=$:Project}
(:cell style="white-space: nowrap;":)Attach:JITS/{=$:Status}.gif {=$:Status}
(:cell style="white-space: nowrap;":)Attach:JITS/{=$:Priority}.gif {=$:Priority}
(:cell align=right:){=$:CChngDate}
(:cell:)[[~{=$:ChngAuth}]]
Note: If you upload the icons to /uploads/<Group> you can have different icons for the same select item. Just change the foldername in the Attach commands in <Group>.JITSPgLst.

Here is my JITSicons.zipΔ
If you are missing an icon there is a blank.gif. Just rename a copy and use until you create a new one.

Jiri January 29, 2007, at 02:51 AM

List of all JITS

  • in the site - retrieve the list with

(:pagelist group=*,-JITS name=-*Recent* $:JITSlevel=main:)

  • in the current wikigroup
    (:pagelist group={$Group} name=-*Recent* $:JITSlevel=main:)

Those JITS main pages are listed the user is authorized to read (attr settings)

Localisation (XLPageLocal)

You can customize the English phrases by inserting and editing the following text into your PmWiki??.XLPageLocal (replace ?? with the language abbreviation).
(read more at http://www.pmwiki.org/wiki/PmWiki/Internationalizations)

 ## JITS
 'Filtered and ordered Issues PageList' =>'',
 'select' =>'',
 'Order by' =>'',
 'Accomplish' =>'',
 'Changed' =>'',
 'by' =>'',
 'up' =>'up',
 'New Issue' =>'',
 'Summary' =>'',
 'Type' =>'',
 'in project' =>'',
 'Priority' =>'',
 'Status' =>'',
 'Content' =>'',
 'Submit' =>'',
 'date' =>'',
 'Save changes' =>'',
 'Add comment' =>'',
 'New comment' =>''

Known problems:

  • release 20070118
    • filtering and sorting rules are stored and retrieved in the main JITS page;

it can cause an inconvenience when other visitor changes the settings in the same moment.

Future release plans

  • JITSadmin page
    • form to create JITS (input Group, Name and click Submit)
    • checkbox in pagelist to delete issues including its comments, Done in version 20070331

Release Notes

20070503

  • fixed displaying the snippet source instead of the form for filtering the issues

20070418 This version will not work with lower versions of PmWiki or ZAP

  • Adapted to PmWiki v.pmwiki-2.2.0-beta44
  • Adapted to ZAP and ZAPtoolbox modules version Apr 17, 2007
  • "Cancel" links replaced with [Cancel] buttons
  • Comments pagelist
    • another [Add comment] button at the bottom of the list
    • fixed link to the top of the page
  • "Filtered and ordered Issues PageList" changed to "...Issues Pagelist"

20070404

  • Fixed - showing the [Admin's tasks] button to unauthorized users
  • Thanks to the Other Michael
    • Author's name displays as the link [[~<authorname>]]
    • Fixed - date formats to %d.%m.%Y %R
    • Added the "Cancel editing" link when re-editing the issue
    • The "Edit" link centered and moved below the Content when the issue displayed
    • The [Accomplish] button label changed to [Filter&Sort]
    • Select boxes for Type and Project enabled when the issue is re-edited
    • "Pre-defined pagelists" tip in the Tutorial - Tips section

20070331

  • administrator's page JITS/JITSadmin added. Enables the batch issues deleting including their comments.
    The page is accessible to @admins group only.

20070327

  • comments editing enabled (suggested by Dean Staub)
  • saved issues and comments are editable by the original author and the user having “edit” authorization only.

20070326

  • adjusted for using the ZAP modules ver 2007-03!
  • to submit/change the issue or to add the comment the user must be loggedin with AuthUser

20070209

  • fixed pagetextvariables references to be relative regardless of $EnableRelativePageLinks and $EnableRelativePageVars settings (thanks to hfwang).

20070125

  • Shared pages are moved from Forms wikigroup to JITS wikigroup.
  • Configuration page is split to JITS.JITScfg and JITS.JITScfgS to make the customisation easier.
    To customise a wikigroup copy JITS.JITScfg into <Group>.JITScfg and add or remove the InputSelect options.
  • To customise the issues pagelist the JITS.JITSPgLst is to be copied into <Group>.JITSPgLst and the customisation is provided in <Group>.JITSPgLst.
  • JITS engine uses <Group>.JITScfg and <Group>.JITSPgLst preferably if the pages exist.

20070118 - tested initial version


See Also

JITS

Contributors

Comments

See discussion at JITS-Talk-Tutorial-Talk?

User notes : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.