Question

How can I manage a list of to do items?

Answer

To Do

The XToDo plugin provides the ability to enter, view, and edit to do items. This is a complete rewrite of, and is no longer compatible with, an earlier version. Both the format of the datastore for the to do items and their placements in the filesystem have changed. For a live example and a sandbox where you can experiment with the plugin, visit:

http://www.madhckr.com/project/PmWiki/Scratch/XToDo

XToDo is free software licensed under the GNU General Public License (GPL).

How It Looks

Features

• Owners. Each to do item can be associated with one of a few owners that can be different for each page group.
• Notes attachments. Each to do item can have a full Wiki page as an attachment. This makes it easy to add notes or discussions to items as they are being worked on.
• Entry and editing of to do items using a form. You no longer need to textually edit to do item fields to update them. Instead, a form with the appropriate option lists is supplied for this purpose.
• To do items are associated with the group of the page where they are created. Each group now has its own list of to do items.
• Selection of to do item listing using various criteria, including categories, status names, and dates. This will be expanded soon to allow the use of priority and urgency index, and other selection criteria.
• Automated marking and dating of completed to do items. When an item changes its status to and from 'Completed', its record is updated automatically to include the completion date.
• Customizable color scheme for highlighting to do items. When enabled, overdue and completed to do items are highlighted with a color scheme that can be customized with CSS stylesheets or configuration directives.
• Customizable to do item categories. To do item categories can be set in the local or group configuration files and can be overridden in the page where the to do entry form is displayed.

Files

• The complete package: XToDo.tgzΔ or XToDo.zipΔ (last update: 2005-11-11)
• The script: XToDo.phpΔ (last update: 2005-11-11)

Prerequisites

• You must be running PmWiki 2.0.10 or better.

Installation

• Extract the contents of XToDo.tgz or XToDo.zip, which are the script XToDo.php and a directory of icon images called XToDo.
• Place XToDo.php in the cookbook directory and add the following line to the local configuration script local/config.php:

        include_once('cookbook/XToDo.php');

• Place XToDo directory in the pub subdirectory of your Wiki site.
• To do item categories can be customized by setting the variable $todo_category_names in the local or group configuration script like this:

        $todo_category_names = array('Personal', 'Business', 'Other');

• To do item owners can be defined by setting the variable todo_owner_names in the local or group configuration script like this:

        $todo_owner_names = array('Anonymous', 'Mickey Mouse', 'Bauhaus');

• To override the default colors and styles settings, you can add this to your local configuration script and customize the values between the braces:

 $HTMLStylesFmt['todo'] = <<< EOT
 .todo-form { border: none; }
 .todo-form tr td { border: none; font-weight: plain; 
     text-align: left; padding: 4px; }
 .todo-form tr td.heading { text-align: right; 
     width: 140px; padding-right: 6px; }
 table.todo-list { border: 2px solid #ccc; }
 table.todo-list tr.row1 { background-color: #eee; color: #555; }
 table.todo-list tr.row1 td { border-bottom: 2px solid #ccc; }
 table.todo-list tr:last-child.row1 td { border-bottom: none; }
 table.todo-list th { background-color: #ddd; padding: 3px; 
     font-weight: normal; border: 1px solid #ccc; color: #444; }
 table.todo-list tr td { color: #666; }
 table.todo-simple-list tr td { border: none; padding: 4px; }
 .todo-category-text { color: #666; border-bottom: 1px solid #ccc; }
 .todo-description-text { color: #444; }
 .todo-overdue-text { color: #f66; border-bottom: 1px solid #ccc; }
 .todo-completed-text { color: #446600; border-bottom: 1px solid #ccc; }
 .todo-legend { text-align: center; color: #555; font-size: smaller; }
 EOT;

Markups

The script adds the following markups:

    (:todoform category='<name>,..':)

    (:todosimplelist colorize category='<name>,..' status='<name>,..' sort='<criteria>'
        due='<criteria>' completed='<criteria>' created='<criteria>'
        show='<options>':)

    (:todolist colorize category='<name>,..' status='<name>,..' sort='<criteria>'
        due='<criteria>' completed='<criteria>' created='<criteria>':)

All markup arguments are optional. See the sections below on how to specify sort criteria and date selection criteria.

• To display a to do item entry form in a page:

    (:todoform:)

• To display a simple list of existing to do items in a page:

    (:todosimplelist:)

• To display a detailed list of existing to do items in a page:

    (:todolist:)

Sort Criteria

To specify a sort criteria in the markup argument, precede a lowercased field name with either a plus sign ('+') for ascending order or a minus sign ('-') for descending order. Field names are:

    id, priority, urgency, p*u, status, created, due, 
    completed, category, description, owner

So, for example, if you would like to display a colorized, simple list of to do items in the 'Business' category sorted by the product of each item's priority and urgency in descending order, use the following markup:

    (:todosimplelist colorize category='Business' sort='-p*u':)

Date Criteria

Absolute Specification

Relative Specification

Examples

created='d=10'

• All to do items created on the 10th of this month and this year.

completed='m=2-'

• All to do items completed between February and December this year.

due='y=2003-2005'

• All to do items due between January 1st 2003 and December 31st 2005.

due='today'

• All to do items due today.

completed='-today'

• All to do items completed by yesterday.

Author

• Julian I. Kamil

Other Contributions

• Skins.Simple - A very simple but good-looking skin for PmWiki
• Multilink - A plugin that adds the ability to support multilinks
• Wiki Farm Step By Step - Instructions on how to set up PmWiki as a farm
• Site Information - A plugin that enables the viewing of site information on a Wiki page

Changes

• 2005-11-11: Added a license file to the image subdirectory.
• 2005-11-08:
  • Added owner-based selection and sort criteria.
  • Implemented multiple category specification in the form markup.
  • Fixed the bug with items marked overdue when they are due today.
  • Added due- and completed-date flyovers.
• 2005-11-04:
  • Added an owner field.
  • Added the to do item ID to the edit form page.
• 2005-11-03:
  • Added '[-|+]today' date selection criteria (suggested by: David).
  • Replaced character status codes with icons.
• 2005-11-02:
  • Fixed the issue with empty list (reported by: nbk).
  • Fixed the issue with create date title (reported by: juytter).
  • Fixed the issue with empty group name when a list is loaded on the default page invoked with a clean URL (reported by: David).
• 2005-10-12:
  • Added status code field that can be optionally displayed in a simple list.
  • Added the ability to attach a full wiki page as a notes page to any items.
• 2005-10-11: Added date-based selection criteria.
• 2005-10-10: Fixed the problem with incorrect sorting by any date field (reported by: Beatrice Hasler).
• 2005-10-05:
  • Added maximum summary length setting for simple lists.
  • Added sort by markup argument for both lists.
• 2005-10-03:
  • Fixed the problem that caused incompatibility with LinkWikiWords setting (reported by: Jean-Claude).
  • Fixed the issue with the inability to customize styles in config.php (reported by: Beatrice Hasler).
• 2005-10-02: Added simple list view.
• 2005-10-01: Initial release of version 0.4.0 to replace version 0.3.x.

Frequently Asked Questions

• I really need to delete an existing to do item. How can I do that?
  • Each to do item is stored as a page with the name XToDo<Group>.<XXXXXX>, where <Group> equals the group name of the to do list, and <XXXXXX> equals the six digit identification of the to do item. If you really need to remove the item, simply delete the file from the wiki.d directory. In my view, however, a better practice would be to add a category called 'Obsolete' or 'Trash' and simply mark the unwanted item with that category so you can preserve the traceability of the to do item.
• Can I have different to do categories for different groups of pages?
  • Yes. First, enable the group customization feature by setting EnablePGCust to TRUE in your local configuration script. Once enabled, you could add a <Group>.php file in the local configuration subdirectory containing the definition of the categories that you would like to use for that group of pages.
• How come I don't see the checkbox in simple list getting checked when an item is completed?
  • You are probably running PmWiki 2.0.beta55. Please upgrade to at least version 2.0.10 to get the checkboxes to function properly.
• How do I filter the list to show everything except completed items?
  • Use one of the markups below.

    (:todolist status='Open,In progress,On hold,Overdue':)
    (:todosimplelist status='Open,In progress,On hold,Overdue':)

Comments and Feedback

3 nov. 2007 PKHG speaking:

The version, which can be downloaded here, does not work with PmWiki 2.2.0 beta63 ...
But it looks like I succeeded to 'adjust' things to the just mentioned version.
Here a working example ;-) http://pepe.cwsurf.de/NewHome/pmwiki.php?n=Test.XToDo
If ... it will be password protected .. XToDo.php.gzΔ

  "\n||cellpadding=0 cellspacing=0 class=todo-list \n||! ID ||
! Priority ||! Urgency ||! P*U ||! Status ||
! Created ||! Due ||! Completed ||\n";

 table.todo-list { margin: auto; }

 .todo-legend { display : none; } /* use to hide the legend */

 .todo-list .ind1 {background-color: #eeeeee; }

Announcement

I now have mailing lists established to discuss issues and suggestions regarding the development of this cookbook recipe. Please consider posting your comments, feedback and questions there so that I could see them more quickly. Thanks.

2005-12-02, Julian I. Kamil

Please place your comments and feedback as comment bubbles in the separate page called ToDo-Talk with the appropriate title.

Go to ToDo-Talk