Christian Ziemski's
wikidPad Page

The todo-extension

Some notes at the beginning - especially for users of older versions of the extension

In April 2009 the configuration of the extension changed significantly. See description below.

In February 2008 I changed the installation technique for the todo-extension.
The old version - created within WikidPadHooks.py - is still available here for reference.

I will always upload the newest running version of the extension here. Changes will be documented here as well.
Comments, suggestions and bug reports are welcome and can be placed in wikidPad Yahoo! Group

History of changes

August 2011
- A beta version with enhanced filter possibilities. Doku will follow soon.
June 2011
- Fixed Björn's hack and enhanced handling of 'done's.
  New config option 'ignoreDones' to ignore 'done's on normal ToDo page when 'onlyRealTodos' is set to 'False' (@Björn).
  Now on special page 'ToDoDone' all 'done's are summarized (suggested by J.Lee).
  (Especially useful after setting 'ignoreDones' to 'True' to have them listed only once.)
Mai 2011
- Merged Bjorn's hack to automatically date-tag todos on wiki pages like 'yyyy-mm-dd')
  Experimental! Not tested very intensive yet. Will change a bit soon.
December 2010
- Fix: tags like '*-W*-d' sometimes sorted wrong (reported by Jens Sp.)
- New date format '*-E+-ddd' for Easter (provided by Jens Sp.)
April 2010
- Please note: The newest WikidPad 2.1 (alpha) includes several changes regarding todos.
  The todo-extension up to version 2010-03-31 doesn't work with WP 2.1.
  I did a quick hack to have a version of the extension for 2.1, but it isn't tested very well yet.
March 2010
- New: Configuration options showInfoOnPage (suggested by Andy M.), (and accompanying pgInfoFrame, pgInfoPrefix)
- New: Asterisks in headlines will be disabled now
- Bug fixes
January 2010
- New: More date formats (see in description below, marked with (**) )
- Change: ToDo tags using 'weeks' or 'month' are no longer "active" only on the first day but during the complete week/month.
- Bug fixes
May 2009
- Some new configuration values
- Bug fixes
April 2009
- New configuration syntax. Some new configuration values
- New optional local (per wiki) configuration
- Several internal changes and optimizations
- Bug fixes
February 2009
- Added support for WikidPad 2.0alpha (for alpha01_03 (2009-02-01) or later)
- Fixed a bug when config option realDatesSeparate=True and outDateFormat not "%Y-%m-%d"
January 2009
- Added some date formats (suggested by Jouni Miettunen):
  "*-Wnn" for 'Monday of every week nn'
  "*-W*-d" for 'every d weekday (Monday=1, Tuesday=2...)'
- Fixed problem with todo filter (reported by Kurt Woodham) and changed config option(!) for that
- Added config option for deleting attributes from todo entry (suggested by Kurt Woodham)
February 2008
- Easier installation (thanks to some hints from user Marko M.)
  - No more changing/copying of WikidPadHooks.py needed
  - Please read installation instructions below
- Cut out the configuration section into an (optional) separate file.
  - Makes code updates much easier. No more local config overwriting.
  - See description below.
- More flexible output format for dates (suggested by Chris Lee)
  - Have a look at "outDateFormat" in the config section (not tested on Windows yet)
  - Automatic usage of locale doesn't work on Windows yet. Fallback is used there; or use manual configuration.

Planned changes/features

Internal rewrite to make the extension better readable and maintainable [already working on it]
Automatc refresh of ToDo page (suggested by Christopher Bielenko and others)
Even more error checking
Sort of help page
Integration of statistics about todos as suggested/provided by Chris D.

Features to think about

Something like tags in blogs (suggested by Christopher Bielenko)
Jaysen Naidoo has already created such an extension: TagView
Something with "done" items
Drop support for WikidPad 1.6 when 1.8 is final (?)

Preface

While trying wikidPad as ToDo-List-Helper I found the following extensions on the wikidPad Project Home Page:

GettingThingsDone (The starting point)
- 'NextActions' by Eric Neumann
- Enhanced by icosahedral to organize by context instead of by project name.
SortedTodos
- JaysenNaidoo version to sort the page according to tags (todo.<tag>:)
- Mike Crowe added dynamic tags

Because these extensions still didn't exactly fit my needs I wrote my own, loosely based on the above.

I mainly added date calculations, date sorting, a separate calendar page and a configuration section.
(The formulas for 'date calculation from week number' I found somewhere in the WWW (link to be added later here).)

Description

If a wikiWord beginning with "ToDo" is created or selected (viewed) it automatically
collects all 'todo' entries from all other pages and inserts them here (after a placemark).
Of course you can write your own text before that placemark. It wouldn't be touched by the extension.

If the wikiWord has additional characters after the "ToDo" like "ToDoPrivate" those characters
"Private" are used as filter (case insensitive).
If there are spaces or underlines between "ToDo" and the following characters (e.g "ToDo_Private")
these are ignored and so still the filter is "Private". (This may be better readable.)
Only Todos containing that filter string (in its name or in the full entry) are collected.
(Behavior depends on configuration option "filterTodos" below.)

Note: If the optional Calendar feature is enabled below, it is "ToDoCalendar" and "ToDoCalendarPrivate" in the example above.

The todos are sorted by 'tag' the following way:

    1.) Completely untagged                                e.g. 'todo: shopping'

    2.) Tagged with special tags.                          e.g. 'todo.High: pay taxes'
      Sort order and display see config section below

    3.) Tagged with a date                                 e.g. 'todo.2006-10-31: Halloween 2006'
      Sorted by date (earliest first in list)
      Marked as 'GONE', 'TODAY', 'n hours left', 'n days left' dependent on dayrange below
      Displayed in different formats, dependent the same way.

      The following date formats are recognized:       (**) = new as of 2010-01-10   (***) = new as of 2010-12-07

          "yyyy-mm-dd"   # standard date                               e.g. todo.2006-10-31: Halloween 2006
          "mm/dd/yyyy"   # GB/US date
          "dd.mm.yyyy"   # European date
          "yyyy-mm-*"    # complete month mm (every day) of year yyyy  e.g. todo.2010-07-*:  One month for summer vacations   (**)
          "*-mm-*"       # complete month mm (every day); every year   e.g. todo.*-12-*:     Buy Christmas gifts   (**)
          "yyyy-Wnn-d"   # DayOfWeek in given week+year (Mon=1,Sun=7)  e.g. todo.2007-W03-2: Tuesday of 3rd week in 2007
          "*-W*-d"       # DayOfWeek in every week+year (Mon=1,Sun=7)  e.g. todo.*-W*-1:     go to work on Monday
          "yyyy-Wnn"     # complete week in a given year               e.g. todo.2008-W12:   complete week 12 in 2008
          "*-Wnn"        # complete week, every year                   e.g. todo.*-W52:      prepare end of year
          "CWnn"         #   same as above: Calendar Week
          "KWnn"         #   same as above: Calendar Week (German: Kalender Woche)
          "*-mm-dd"      # a date every year                           e.g. todo.*-10-31:    Halloween, in every year
          "*-*-dd"       # a day every month, every year               e.g. todo.*-*-01:     Every month, the 1st day
          "*-*-*"        # every day
          "*-mm-dd+d"    # every DayOfWeek before(-)/after(+) dd'th day of month mm   (**)
          "*-*-dd+d"     # every DayOfWeek before(-)/after(+) dd'th day every month   e.g.  todo.*-*-31-1: Monthly report (last Monday of the month)   (**)
          "*-E+ddd"      # Easter +- ddd days  (***)

      The dates with "*" are "optimistic" ones: if such a date is in the past
      it is assumed as "for next year" and not as "GONE this year".

          If there are subtags like the string "Peter" in "todo.Peter.2008-09-16: Birthday" the subtag is listed in parentheses on the todo page.

    4.) otherwise tagged                                       e.g. 'todo.family: holidays'

Note: Within the wikidPad help wiki this hook does nothing, even if you create a page ToDo there.

The following WikiDocumentAttributes will be added to that generated page
(If there isn't already a custom [icon: ...] set, see configuration below):

[icon: spanner]
[color: magenta]
[bookmarked=true]

Example

Since a few pictures are able to describe better than many words here an easy example.
(The hardcopies are taken from WikidPad 1.9 running under Linux/KDE.)

Imagine a Wiki with two wiki pages "CarAndMore" and "FamilyBusiness" with some data and todo tags on it:

Opening the wiki page "ToDo" now shows an info popup:

and then in edit mode:

The same in preview mode:

(In the standard lefthand tree view 'todo' the todo items are sorted alphabetically, on the ToDo page to the right they are sorted by date and/or tag.)

Configuration (optional)

The extension is configurable in three levels.

Within the code there is a configuration section with default values.
Don't change them there since they will be overwritten by the next update of this program.

The following configuration value 'predefinedTags' is the only one only changeable in the code itself, if you really want.

predefinedTags contains (Tag, TagHeader).
TagHeaders are the descriptive headings that will be shown for each category.
Tag 'UNTAGGED' is a special one (mandantory!) to collect the untagged todo's.

'predefinedTags', [
                ('UNTAGGED',     '++++ Not yet tagged'),
                ('High',         '+++  HIGH!'),
                ('Next',         '++++ Next Actions'),
                ('ThisWeek',     '++++ This Week'),
                ('SomeDay',      '++++ SomeDay / Maybe'),
                ('TimeToTime',   '++++ From time to time'),
                ('Low',          '++++ Tagged as LOW'),
                ('VeryLow',      '++++ Tagged as Very LOW') ],

As of 2008-02-24 there is an (optional) configuration file ToDoExtension.cfg in the same directory user_extensions as the extension itself.
(In April 2009 the syntax changed a bit.) Simply set config values in that file using the normal Python syntax: 'name = value'
Please note: Multiline entries aren't supported yet. So for example 'predefinedTags' can't be changed that way.
If you are maintaining your local configuration changes in that file they aren't overwritten any more.
This makes code updates much easier.
Please have a look at the example file ToDoExtension.cfg.example.
It contains all changeable configuration values.
(If you want to use that file for your installation you have to rename it to ToDoExtension.cfg of course.)
As of 2009-04-05 there is an additional (optional) local configuration per wiki.
It can be filled with values on the wiki page 'ToDoConfiguration'.
The syntax is the same as in the config file above.
If the wiki page 'ToDoConfiguration' has no active configuration entries on opening
the extension offers to fill it with the current values as template (all commented out).
Please note: The config values 'predefinedTags', 'isConfigPageActive' and 'configPage' can't be changed on this wiki page.

On every opening of the page ToDoConfiguration a reminder will pop up...

... just before the page itself:

Installation

Create a directory user_extensions under your wikidPad directory parallel to ('icons', 'extensions', 'export' etc.) (if it doesn't already exist)
Place the ToDoExtension.py into that directory user_extensions
Optional: Create or change ToDoExtension.cfg there. (Read about it above.)
Restart wikidPad to activate the changes

Files to download

The current one (same as the 20110606 version below): ToDoExtension.py

Additionally there is a beta version:
ToDoExtension.py-beta: Beta test: Improved filters. E.g.: Now a page "ToDo_Done_Sometext" would show all "done" todos with "Sometext" in tag.

Version history:
[2011-06-06] ToDoExtension.py-20110606: Fixed Bjorn's hack and enhanced handling for 'done's (ToDoDone). New config option 'ignoreDones'
[2011-05-15] ToDoExtension.py-20110515: (Experimental!) Merged Bjorn's hack to automatically date-tag todos on wiki pages like 'yyyy-mm-dd')
[2010-12-07] ToDoExtension.py-20101207: Fix: tags like '*-W*-d' sometimes sorted wrong (reported by Jens Sp.); new date format '*-E+-ddd' for Easter (provided by Jens Sp.)
[2010-04-10] ToDoExtension.py-20100410: Hack to make it work with newest WikidPad 2.1alpha
[2010-03-31] ToDoExtension.py-20100331: Bugfix: Grouping of [Very]Low tags / dates as "*-*-dd+d". New configuration value showInfoOnPage etc.
[2010-01-25] ToDoExtension.py-20100125: Date calculation fixed.
[2010-01-10] ToDoExtension.py-20100110: Calculation of week number finally fixed. New date formats added.
[2010-01-05] ToDoExtension.py-20100105: Bugfix: Fixed wrong calculation of week number for year 2010
[2009-07-26] ToDoExtension.py-20090726: Bugfix: Better checking for and handling of invalid date entries
[2009-05-11] ToDoExtension.py-20090511: Important bugfix: Closing a ToDo page and opening another one could lead to errors
[2009-05-05] ToDoExtension.py-20090505 BETA: Important bugfix: More problems with multiple tags and a regression from version 2009-04-26 fixed
[2009-04-26] ToDoExtension.py-20090426 BETA: Important bugfix: Problems with multiple tags and with tagstring in todo-text fixed / new sortTagsCaseInsensitive
[2009-04-22] ToDoExtension.py-20090422 BETA: New configuration values added (todoTimestamp...)
[2009-04-06] ToDoExtension.py-20090406 BETA: New configuration scheme. Bug fixes and optimizations.
[2009-02-05] ToDoExtension.py-20090205 Fix for WP2.0alpha / modified version check / new config option: showVersion
[2009-02-03] ToDoExtension.py-20090203 Better error handling for invalid dates
[2009-02-02] ToDoExtension.py-20090202 Works with WikidPad 2.0alpha now. Fixed bug with realDatesSeparate
[2009-01-24] ToDoExtension.py-20090124 Added date formats / Fixed todo filter (changed config option!) / Added opt. deletion of attributes
[2008-02-24] ToDoExtension.py-20080224b Optional configuration file for local changes.
[2008-02-24] ToDoExtension.py-20080224 Fallback and note for usage of outDateFormat on Windows.
[2008-02-23] ToDoExtension.py-20080223 First version with new internals and new installation.

Known issues

The automatic determination of the (locale) date format for list output doesn't work on Windows. Fallback is YYYY-MM-DD.