key Log In or Register to edit

Checklist Plugin

ChecklistPlugin creates simple checklists. It handles the tags %CLI% (CheckList Item), %CHECKLIST%, %CHECKLISTSTART%, %CHECKLISTEND% and depends on the TWiki:Plugins.SmiliesPlugin (see Plugin Info).

A %CLI% tag creates a image button and a simple click on it changes the state of the image button. The default states are 'todo' (represented by a indifferent image button) and 'done' (represented by a thumbs up image button).

If you put a bullet list or a ordered list between %CHECKLISTSTART% and %CHECKLISTEND% every bullet/ordered list item gets a checklist item.

Every state change will be saved to a topic with name <YourTopicName>ChecklistItemState. It is possible to define states (default: todo and done) and matching icons. You can also put more than one checklist into a topic.

Syntax Rules

Just type a %CLI% (CheckList Item) into a topic to create a single checklist item. A simple mouse click on it will change the state of this item. If the last state is reached the item state falls back to the first state.

If you put a bullet or ordered list between %CHECKLISTSTART% and %CHECKLISTEND% every bullet/ordered list item gets a checklist item.

To modify the states or state icons you can set it with %CHECKLISTSTART% or %CHECKLIST% tag. This tags can also be used to create "reset" buttons and state legends.

All tags can be used with attributes documented in the Attributes section.

To create a link to the checklist item state topic you can put the following forced link on your checklist topic: 

[<nop>[%<nop>TOPIC%ChecklistItemState]]
. If you have installed the TWiki:Plugins.SpreadSheetPlugin you can find a statistics on this item state topic. And if you have installed the TWiki:Plugins.EditTablePlugin you can edit the states directly on this topic.

Usage Examples

To change the state of a checklist item just click on it.

You type: You get: (simulated)
Example 1: Create a simple checklist:
  • second step icon was clicked one time
  • last step icon was clicked two times 
%CHECKLISTSTART%
   1 first step
   1 second step 
   1 last step 
%CHECKLISTEND%
  1. first step indifferent
  2. second step thumbs up
  3. last step indifferent
Example 2: Create a simple freehand checklist:
  • second step icon was clicked one time
  • last step icon was clicked two times 
   1 first step %CLI% 
   1 second step %CLI% 
   1 last step %CLI%
  1. first step indifferent
  2. second step thumbs up
  3. last step indifferent
Example 3: Create a checklist with three states and own icons:
  • second step icon was clicked one time
  • and third step icon was clicked two times 
%CHECKLISTSTART{states="todo|doing|done" stateicons=":no:|:-I|8-)"}%

   1 first step 
   1 second step
   1 third step 
%CHECKLISTEND%
  1. first step no
  2. second step indifferent
  3. third step cool!
Example 4: Create two checklists on a topic:
(ALERT! every %CHECKLIST% and every %CLI% tag needs a name attribute)
%CHECKLISTSTART{name="first checklist"}%
   1 first step 
   1 second step
%CHECKLISTEND%

%CHECKLIST{name="second checklist"}%

   1 first step %CLI{name="second checklist"}% 
   1 next step %CLI{name="second checklist"}%

  1. first step indifferent
  2. second step indifferent

  1. first step indifferent
  2. next step indifferent
Example 5: Create a checklist in a table: 
| *state* | *todo* |
| %CLI%   | first step |
| %CLI%   | second step |
state todo
indifferent first step
indifferent second step
Example 6: Create a checklist without annoying line breaks if HTML forms are used: 
%CHECKLIST{useforms="yes"}%
   1 %CLI{text="my first step"}%
   1 %CLI{text="my second step"}%
  1. my first step indifferent
  2. my second step indifferent
Example 7: Create a legend and a reset button:
  • Hint: You can use multiple %CHECKLIST% tags to create more than one reset button or legend at any position of your checklist topic. 
%CHECKLISTSTART{showlegend="on" reset=":-I Reset"}%
   1 first step 
   1 next step
%CHECKLISTEND%
  1. first step indifferent
  2. next step indifferent

( indifferent - todo thumbs up - done ) indifferent Reset

Example 8: Create a button to set all states in a checklist to =done=
  • the reset button was clicked
  • Hint: You can use multiple %CHECKLIST% tags to create more than one reset button. 
   1 first step %CLI% 
   1 next step %CLI% 

%CHECKLIST{reset=":ok: set all done @done"}%
  1. first step thumbs up
  2. next step thumbs up

thumbs up set all done

Example 9: Insert new items in an existing checklist without state lost.
  • first step and second step was clicked before new items (first new inserted item and second new inserted item) were added
  • Hint: You can put a #<ID> instead of %CLI{id="<ID>"}% into a bullet or ordered list item to add/insert a checklist item with own id. This works only between %CHECKLISTSTART%...%CHECKLISTEND%. 
%CHECKLISTSTART%
   1 first step
      1 first new inserted item #MyFirstInsertedItem
   1 second step  
      1 second new inserted item %CLI{id="MySecondInsertedItem"}%
%CHECKLISTEND%
  1. first step thumbs up
    1. first new inserted item indifferent
  2. next step thumbs up
    1. second new inserted item indifferent

Attributes

Usage:
%CLI{attribute1="value1" attribute2="value2" ...}%
or %CHECKLIST{attribute1="value1" attribute2="value2" ...}%
or %CHECKLISTSTART{attribute1="value1" attribute2="value2" ...}%

Examples: 

%CHECKLIST{showlegend="on" reset=":-I Reset checklist"}%
%CLI{id="i1"}%

Attribute Usable in Tag(s) Comment Example
anchors %CLI%
%CHECKLIST%
%CHECKLISTSTART% 		enables/disables link anchors (default: yes); if enabled a state change will scroll your topic to the clicked checklist item; useful for long checklists anchors="yes"
clipos %CLI%
%CHECKLISTSTART% 		determines the position of the checklist item icon (default: right); if you use another value than "left" the checklist item icon will be appended to a ordered or bullet list item clipos="left"
id %CLI% unique id of a checklist item (default: autogenerated); useful and recommended if you insert new checklist items in an existing checklist with states id="myfirstownid"
name %CLI%
%CHECKLIST%
%CHECKLISTSTART% 		a naming context (default: _default) - useful and recommended if you define more than one checklist on a topic (ALERT! if you use it in %CHECKLIST% you must use it in all related %CLI% tags too) name="mychecklist1"
pos %CHECKLISTSTART% defines the reset button and legend position (default: bottom); if you use another value than "top" the button position falls back to default pos="bottom"
reset %CHECKLIST%
%CHECKLISTSTART% 		it enables a reset image button with a given text or icon (default: undefined); if you put a @<state> into the reset value, you can reset a checklist to the given <state>, e.g: reset="@done :ok: set all done" reset="Reset all"
showlegend %CHECKLIST%
%CHECKLISTSTART% 		if you set it to "on" a states legend with icons will be displayed (default: off),
e.g: ( indifferent - todo thumbs up - done) 		showlegend="off"
states %CLI%
%CHECKLIST%
%CHECKLISTSTART% 		all known states (default: todo¦done; a list separated by a '¦') states="todo¦done"
stateicons %CLI%
%CHECKLIST%
%CHECKLISTSTART% 		icons for all states separated by a '¦' (default: :-I¦:ok:); if you use common variables like %Y% in stateicons you have to use the <nop> tag after the first %, e.g: %<nop>Y% stateicons=":-I¦:ok:"
statetopic %CLI%
%CHECKLIST%
%CHECKLISTSTART% 		set the checklist item state topic (default: <YourTopicName>ChecklistItemState) statetopic="MyItemStateTopic"
text %CLI% allows to place text behind the button (default: ""); useful to avoid the annoying line break between checklist button and text if HTML forms are used (related: useforms attribute) text="my first step"
useforms %CLI%
%CHECKLIST%
%CHECKLISTSTART% 		if enabled HTML forms are used instead of hyperlinks (default: off) useforms="off"

Examples

Use this examples to check your installation:

  1. %CLI{text="first step"}%
  2. %CLI{text="next step"}%

State TODO
%CLI% first step
%CLI% next step

ChecklistPluginChecklistItemState?

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %INTERWIKIPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the Text Formatting Rules topic:
    • Set SHORTDESCRIPTION = Create simple checklists.

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

  • Setup states and icons (defaults: todo¦done and :-I¦:ok:; remove # for setup):
    • # Set STATES = todo|doing|done
    • # Set STATEICONS = :-(|:-I|:ok:

  • Enables 'reset' button (default: disabled with undefined value; value is a text or icon):
    • # Set RESET = [Reset all]

  • Enables/Disables state legend (default: off)
    • # Set SHOWLEGEND = on

  • Enables/Disables link anchors (default: on)
    • # Set ANCHORS = off

  • Set unknown parameter message (default: %RED% Sorry, some parameters are unknown: %UNKNOWNPARAMSLIST% %ENDCOLOR% <br/> Allowed parameters are (see TWiki.ChecklistPlugin topic for more details): %KNOWNPARAMSLIST% )
    • # Set UNKNOWNPARAMSMSG = Following parameter(s) is/are unknown: %UNKNOWNPARAMSLIST%

  • Enables/Disables HTML form usage (default: off; old behavior: on)
    • # Set USEFORMS = on

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.

  • Download the ZIP file from the Plugin web (see below)
  • Unzip ChecklistPlugin.zip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/ChecklistPlugin.txt Plugin topic
    lib/TWiki/Plugins/ChecklistPlugin.pm Plugin Perl module
  • Linux/UNIX: Don't forget to change owner of data/TWiki/ChecklistPlugin.txt to your WWW server uid/gid (e.g: chown wwwrun:wwwrun ...).
  • Test if the installation was successful: see Examples section

Plugin Info

Plugin Author: TWiki:Main.DanielRohde
Plugin Version: 18 Apr 2006 (v1.016)
Change History:  
v1.016 (18 Apr 2006) TWiki:Main.DanielRohde: fixed access right bug reported by TWiki:Main.SaschaVogt
v1.015 (9 Feb 2006) TWiki:Main.DanielRohde: fixed mod_perl preload bug (removed use warnings;) reported by TWiki:Main.KennethLavrsen
v1.014 (6 Feb 2006) TWiki:Main.DanielRohde: fixed mod_perl bug; fixed deprecated handler problem
v1.013 (3 Feb 2006) TWiki:Main.DanielRohde: fixed anchor bug; fixed multiple save bug (performance improvement); fixed reset bugs in named checklists
v1.012 (2 Feb 2006) TWiki:Main.DanielRohde: fixed a minor statetopic bug; improved autogenerated checklists (item insertion without state lost); improved docs
v1.011 (23 Jan 2006) TWiki:Main.DanielRohde: fixed documentation; fixed reset bug (that comes with URL parameter bug fix); added statetopic attribute
v1.010 (28 Nov 2005) TWiki:Main.DanielRohde: fixed URL parameter bugs (preserve URL parameters; URL encoding); used CGI module to generate HTML; fixed table sorting bug in a ChecklistItemState topic
v1.009 (25 Nov 2005) TWiki:Main.DanielRohde: fixed stateicons handling; fixed TWiki:Plugins/TablePlugin sorting problem
v1.008 (9 Nov 2005) TWiki:Main.DanielRohde: fixed docs; changed default text positioning (text attribute); allowed common variable usage in stateicons attribute; fixed multiple checklists bugs
v1.007 (7 Nov 2005) TWiki:Main.DanielRohde: added new feature (CHECKLISTSTART/END tags, attributes: clipos, pos); fixed bugs
v1.006 (4 Nov 2005) TWiki:Main.DanielRohde: added new attribute (useforms); fixed legend bug; fixed HTML encoding bug
v1.005 (2 Nov 2005) TWiki:Main.DanielRohde: fixed major bug (edit lock); fixed html encoding; improved doc
v1.004 (1 Nov 2005) TWiki:Main.DanielRohde: added unknown parameter handling (new attribute: unknownparamsmsg); added 'set to a given state' feature; changed reset behavior; fixed typos
v1.003 (1 Nov 2005) TWiki:Main.DanielRohde: added attributes (showlegend, anchors); fixed states bug (illegal characters in states option); improved documentation (thanx TWiki:Main.PeterThoeny); fixed typos; fixed some minor bugs
v1.002 (31 Oct 2005) TWiki:Main.DanielRohde: fixed cache problems; fixed HTML/URL encoding bugs; fixed reload bug; fixed reset image button bug; added anchors
v1.001 (27 Oct 2005) TWiki:Main.DanielRohde: added new features ('reset','text' attributes); fixed major 'name' attribute bug; fixed documentation bugs
v1.000 (27 Oct 2005): TWiki:Main.DanielRohde: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.024
CPAN Dependencies: none
Other Dependencies: TWiki:Plugins.SmiliesPlugin
Perl Version: 5.005
License: GPL (GNU General Public License)
TWiki:Plugins/Benchmark: Good Style 100%, Formatted Search 100%, Checklist Plugin 98%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/ChecklistPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/ChecklistPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/ChecklistPluginAppraisal

Related Topics: T Wiki Preferences, T Wiki Plugins

-- TWiki:Main.DanielRohde - 27 Oct 2005

Printable copy

 
Ad Sponsor
Back to Redbourn
Copyright © We make no guarantee of the correctness of the content of this site. All material on this collaboration platform is the property of Martin Cleaver and the contributing authors.