<?php if (!defined('PmWiki')) exit();
/*  Copyright 2004 Patrick R. Michaud (pmichaud@pobox.com)
    This file is part of PITS (PmWiki Issue Tracking System), you can
    redistribute it and/or modify it under the terms of the GNU General
    Public License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This file defines code needed for the PmWiki Issue Tracking System
    (PITS).  The code is highly specialized towards the needs of
    pmwiki.org, and may not be useful (or even usable) anywhere else,
    but enough people have asked for it that I'm making it available
    in the Cookbook and wishing people the best of luck with it.

    Eventually there will likely be a "supported" version of this
    capability, and the supported version *may* even use the code below :-).
    But until Pm clears a few other items off of his to-do list, he
    may have limited ability to provide detailed support.  (Offers of
    financial support have been known to significantly affect his
    development/support priorities, however. :)

    Issues with PITS can, of course, be registered in PITS on
    pmwiki.org (http://www.pmwiki.org/PITS).

    Okay, enough disclaimers, here's the code already.

    - ~Pm

    ----

	A little bit later, Didier Lebrun, who was looking for this sort of
	application for a project, evaluated that PITS code could be quite
	easily de-specialized by moving the hardcoded stuff specializing it
	into configuration vars. So he did.

	The configuration is done mainly through template vars, with original
	PITS config being the default. Pm's original PITS script has only been
	changed when necessary, for the only purpose of making things
	configurable. The templates are as raw as possible, so as to be able
	to configure virtually anything while introducing as little overhead
	as possible. The de-specialized version should be able to run PITS as
	well as any other application of the same kind.

    - ~DidierLebrun

    ----

    Usage:
    * Copy pits-*.php into cookbook/pits.php
    * Create a local/MyPitsGroup.php file
    * Put in it the vars you want to ajust (see Config vars below)
    * At the end of it, put:
      include_once("cookbook/pits.php");
      ?>
    * Create a MyPitsGroup.MyPitsForm file and put in it:
      (:pitsform:)
    * Create a MyPitsGroup.MyPitsList file and put in it:
      (:pitslist[ somefield=somevalue,othervalue otherfield=!excludevalue ...]:)
      where "somefield" is the name of a field and "somevalue,othervalue"
      are the values you want to list. On the opposite "otherfield=!excludevalue"
      will exclude the records where "otherfield" correspond to "excludevalue".
      But you can just put (:pitslist:) to display the full list.
    * ... That's it !

    ----

    Notes:
    * All vars in the templates MUST be escaped (ex: \$SomeVar)
    * Vars can be "local" ones or "global" ones
    * Local vars correspond to field names:
      (ex: $summary = content of the 'summary' field)
    * Global vars are those given by PmWiki, like $Author and $Now.
      Currently, $Author and $Now are the only ones supported, but you
      can add others in function PitsEvalTemplate(). You must avoid
      $...Url vars like $PageUrl and such, since the http://... link in
      them would be interpretated twice. But you can use [[...]] type of
      links anyway.
    * You can even use PHP functions in templates:
      ex: ".strftime('%Y-%m-%d %H:%M',$Now)." (see $PitsEditTemplateFmt)

    ----

    History:
    0.1 - Initial version released by Pm with the disclaimers above
    0.2 - By Didier Lebrun <dl@vaour.net>:
          * De-specialized the original code (hardcoded -> config vars)
          * Stripped $PageUrl vars in template
          * Allowed space after label ("Label : content")
          * Limited parsing to the PITS header (leave out the comments below)
          * Allowed links in any table fields (ex: [[~Author]])
          * Stripped LF and other spaces between HTML lines (avoid vspace)
          * Added HTML entities charset for some systems (mainly NTFS ?)
*/

define(PITS_VERSION, '0.20');

# ---- Config vars ---- #

## These vars can be overriden in the PITS group configuration file
## (local/YourPITSGroupName.php). Whenever you see something like:
##   SDV($SomeVar, "default setup");
## you must put in your config something like:
##   $SomeVar = "custom setup";
## SDV() is a just PmWiki function allowing to set a default value
## when none has been setup in the config.

## Number of chars for page names
SDV($PitsIDLenght,5);

## Label to field name mapping. Labels and names can be whatever you like,
## as long as they are consistent through all configuration vars.
SDV($PitsLabels, array(
	'Summary' => 'summary',
	'Created' => 'created',
	'Status' => 'status',
	'Category' => 'category',
	'From' => 'author',
	'Assigned' => 'assigned',
	'Priority' => 'priority',
	'Version' => 'version',
	'OS' => 'os',
	'Description' => 'description'
));

## Template for the input form
SDV($PitsFormTemplateFmt, "
<form method='post'>
	<input type='hidden' name='action' value='postpits' />
	<table class='pitsform'>
		<tr>
			<td class='pitsformlabel'>Author:</td>
			<td class='pitsforminput'><input type='text' name='author' value='\$Author' /></td>
		</tr>
		<tr>
			<td class='pitsformlabel'>Summary:</td>
			<td class='pitsforminput'><input type='text' name='summary' size='60'/></td>
		</tr>
		<tr>
			<td class='pitsformlabel'>Category:</td>
			<td class='pitsforminput'>
				<select name='category'>
					<option value=''></option>
					<option value='Bug'>Bug</option>
					<option value='Feature'>Feature/Change Request</option>
					<option value='Documentation'>Documentation</option>
					<option value='Cookbook'>Cookbook</option>
					<option value='PHP Compatibility'>PHP Compatibility</option>
					<option value='Other'>Other</option>
				</select>
			</td>
		</tr>
		<tr>
			<td class='pitsformlabel'>Priority:</td>
			<td class='pitsforminput'>
				Low
				<input type='radio' name='priority' value='1' />
				<input type='radio' name='priority' value='2' />
				<input type='radio' name='priority' value='3' />
				<input type='radio' name='priority' value='4' />
				<input type='radio' name='priority' value='5' />
				High
			</td>
		</tr>
		<tr>
			<td class='pitsformlabel'>PmWiki Version:</td>
			<td class='pitsforminput'><input type='text' name='version' /></td>
		</tr>
		<tr>
			<td class='pitsformlabel'>OS/Webserver/<br />PHP Version:</td>
			<td class='pitsforminput'><input type='text' name='os' /></td>
		</tr>
		<tr>
			<td class='pitsformlabel' valign='top'>Description:</td>
			<td class='pitsforminput'><textarea name='description' cols='60' rows='15'></textarea></td>
		</tr>
	</table>
	<div align='center'><input type='submit' value='Submit new issue' accesskey='s' /></div>
</form>
");

## Template for filling the edit box with input data
## "----" MUST be present at the end to separate the entries from the
## eventual comments that could be added afterwards.
SDV($PitsEditTemplateFmt, "
Summary: \$summary
Created: ".strftime('%Y-%m-%d %H:%M',$Now)."
Status: Open
Category: \$category
From: [[~\$author]]
Assigned:
Priority: \$priority

Version: \$version
OS: \$os

Description:
\$description

----
");

## Template for list table.
## The "(/)PitsListItemFmt" tags MUST be present as delimiters of the entry part.
SDV($PitsListTemplateFmt, "
<table border='1' cellspacing='0' class='pitslist'>
	<tr>
		<th><a href='?order=-name'>Issue#</a></th>
		<th><a href='?order=created'>Created</a></th>
		<th><a href='?order=category'>Category</a></th>
		<th><a href='?order=version'>Version</a></th>
		<th><a href='?order=-priority'>Priority</a></th>
		<th><a href='?order=status'>Status</a></th>
		<th><a href='?order=summary'>Summary</a></th>
	</tr>
<!--PitsListItemFmt-->
	<tr>
		<td>[[\$name]]</td>
		<td>\$created</td>
		<td>\$category</td>
		<td>\$version</td>
		<td>\$priority</td>
		<td>\$status</td>
		<td>\$summary</td>
	</tr>
<!--/PitsListItemFmt-->
</table>
");

## HTML styles
SDV($PitsStylesFmt, "
  table.pitsform {}
  td.pitsformlabel { text-align:right; font-weight:bold; }
  td.pitsforminput {}
  div.pitspage {}
  span.pitspagelabel {}
  span.pitspagedata {}
  table.pitslist {}
  table.pitslist th a { text-decoration:none; }
  table.pitslist th { background-color:#eeeeee; }
");

## Edit form top message
SDV($PitsEditMessageFmt,"<p class='vspace'>Please review and make any edits
    to your issue below, then press 'Save'.</p>");

## Fields that can be filtered by name=criteria args
SDV($PitsListFilters,array('summary','created','status','category','priority','version'));

## Criteria used for default and complementary sorting after explicit criteria
SDV($PitsListDefaultSort,array('-priority','status','category','name'));

## Charset for HTML entities conversion ('ISO-8859-1' usually, 'UTF-8' on NTFS systems)
SDV($PitsHtmlEntitiesCharset, 'ISO-8859-1');

# ---- end of Config vars ---- #

$PitsGroup = FmtPageName('$Group',$pagename);
$PitsGroupUrl = "$ScriptUrl/$PitsGroup";
$HTMLStylesFmt[] = $PitsStylesFmt;
markup('pitsform','inline','/\\(:pitsform:\\)/e',"Keep(PitsForm(\$pagename))");
markup('pitslist','directive','/\\(:pitslist\\s*(.*?):\\)/e',
  "FmtPitsList('',\$pagename,array('q'=>PSS('$1')))");
markup('pitsread','directive','/^('.implode('|',array_keys($PitsLabels)).')\s*:(.*)/',
  "<:block><div class='pitspage'><span class='pitspagelabel'>$1:</span>\
  <span class='pitspagedata'>$2</span></div>");
include_once("$FarmD/scripts/author.php");

## PitsForm() generates the form for entering a new issue.  Note that
## once an issue has been created, it's a normal wikipage and is edited
## according to the normal editing code (i.e., there's no form-based
## editing yet).
function PitsForm($pagename) {
  global $PitsFormTemplateFmt;
  $tmpl = preg_replace('/\s*\n\s*/','',$PitsFormTemplateFmt);
  $out = PitsEvalTemplate(array(),$tmpl);
  return FmtPageName($out,$pagename);
}

## Fills the edit form with formatted input
if ($action=='postpits') {
  Lock(2);
  foreach(ListPages("/^$PitsGroup\\.\\d/") as $i)
    $issue = max(@$issue,substr($i,strlen($PitsGroup)+1));
  $pagename = sprintf("$PitsGroup.%0".$PitsIDLenght."d",@$issue+1);
  $action = 'edit';
  $EditMessageFmt = $PitsEditMessageFmt;
  $_REQUEST['post'] = 1;
  $_POST['text'] = PitsEvalTemplate($_REQUEST,$PitsEditTemplateFmt);
}

## FmtPitsList() creates a table of PITS issues according to various
## criteria.
function FmtPitsList($fmt,$pagename,$opt) {
  global $PitsGroup,$PitsListTemplateFmt,$PitsLabels,$PitsHtmlEntitiesCharset,
    $PitsListFilters,$PitsListDefaultSort;
  $opt = array_merge($opt,@$_REQUEST);
  $pitslist = ListPages("/^$PitsGroup\\.\\d+$/");
  $tmpl = preg_replace('/\s*\n\s*/','',$PitsListTemplateFmt);
  $sect = preg_split('#[[<]!--(/?(?:PitsListItemFmt)\\s?.*?)--[]>]#',$tmpl);
  if(count($sect)!=3) Abort("\$PitsListTemplateFmt MUST have 3 sections !");
  $out[] = FmtPageName(array_shift($sect),$pagename);
  $terms = preg_split('/((?<!\\S)[-+]?[\'"].*?[\'"](?!\\S)|\\S+)/',
    $opt['q'],-1,PREG_SPLIT_DELIM_CAPTURE|PREG_SPLIT_NO_EMPTY);
  foreach($terms as $t) {
    if (trim($t)=='') continue;
    if (preg_match('/([^\'":=]*)[:=]([\'"]?)(.*?)\\2$/',$t,$match))
      $opt[strtolower($match[1])] = $match[3];
  }
  $n=0; $plist=array();
  foreach($pitslist as $p) {
    $page = ReadPage($p);
    list($head) = preg_split('/\n----/',$page['text'],0);
    preg_match_all('/(^|\n)([A-Za-z][^:]*):([^\n]*)/',$head,$match);
    $fields = array();
    for($i=0;$i<count($match[2]);$i++)
      $fields[$PitsLabels[trim($match[2][$i])]] =
        htmlentities(trim($match[3][$i]),ENT_QUOTES,$PitsHtmlEntitiesCharset);
    foreach($PitsListFilters as $h) {
      if (!@$opt[$h]) continue;
      foreach(preg_split('/[ ,]/',$opt[$h]) as $t) {
        if (substr($t,0,1)!='-' && substr($t,0,1)!='!') {
          if (strpos(strtolower(@$fields[$h]),strtolower($t))===false)
            continue 3;
        } else if (strpos(strtolower(@$fields[$h]),
             strtolower(substr($t,1)))!==false)
          continue 3;
      }
    }
    $plist[$n] = $fields;
    $plist[$n]['name'] = preg_replace("/^$PitsGroup\\.(\\d+)$/","$1",$p);
    $n++;
  }

  $cmp = CreateOrderFunction(implode(',',
    array_merge(array(@$opt['order']),(array)$PitsListDefaultSort)));
  usort($plist,$cmp);
  $tr = array_shift($sect);
  foreach($plist as $p) $out[] = PitsEvalTemplate($p,$tr);
  $out[] = array_shift($sect);
  return FmtPageName(implode('',$out),$pagename);
}

## This function creates specialized ordering functions needed to
## (more efficiently) perform sorts on arbitrary sets of criteria.
function CreateOrderFunction($order) {
  $code = '';
  foreach(preg_split('/[\\s,|]+/',strtolower($order),-1,PREG_SPLIT_NO_EMPTY)
      as $o) {
    if (substr($o,0,1)=='-') { $r='-'; $o=substr($o,1); }
    else $r='';
    if (preg_match('/\\W/',$o)) continue;
    $code .= "\$c=strcasecmp(@\$x['$o'],@\$y['$o']); if (\$c!=0) return $r\$c;\n";
  }
  $code .= "return 0;\n";
  return create_function('$x,$y',$code);
}

## This function is used to evaluate the templates while insulating their
## vars from potential name conflicts
function PitsEvalTemplate($hash,$tmpl) {
  global $Author,$Now;
  foreach($hash as $k=>$v) $$k = $v;
  return(@eval("return(\"$tmpl\");"));
}

?>