You are here: Wiki>System Web>ChecklistPlugin (2021-08-05, AlexanderWeimer) Edit Attach Edit wiki text

Checklist Plugin

ChecklistPlugin creates simple checklists. It handles the tags %CLI% (CheckList Item), %CHECKLIST%, %CHECKLISTSTART%, %CHECKLISTEND% and depends on the Foswiki:Extensions.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

image button) and 'done' (represented by a

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.

On this page:

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:

  [[%TOPIC%ChecklistItemState]]

If you have installed the Foswiki:Extensions.SpreadSheetPlugin you can find a statistics on this item state topic. And if you have installed the Foswiki:Extensions.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%

first step
second step
last step

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%

first step
second step
last step

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%

first step
second step
third step

Example 4: Create two checklists on a topic:
(

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"}%

first step
second step

first step
next step

Example 5: Create a checklist in a table:

| *state* | *todo* |
| %CLI%   | first step |
| %CLI%   | second step |

state	todo
	first step
	second step

Example 6: Create multiple lists with tables and hard linked item states to allow add/insert/remove items:

The %EDITTABLE% and %CHECKLISTSTART% tag have to stay in the same line.

%EDITTABLE{changerows="on" format="|label,0,#%SERVERTIME{$year$month$day$hour$min$sec}%|text,50|"}%%CHECKLISTSTART{name="list1"}%
| *STATUS<br/>(click to change)* | *Item* |
| #2007Feb07093710 | testitem |

%CHECKLISTEND%

%EDITTABLE{changerows="on" format="|label,0,#%SERVERTIME{$year$month$day$hour$min$sec}%|text,50|"}%%CHECKLISTSTART{name="list2"}%
| *STATUS<br/>(click to change)* | *Item* |
| #2007Feb07093712 | second |

%CHECKLISTEND%

%EDITTABLE{changerows="off" format="|label, 0, #2025Oct24130410 |text, 50|"}%

STATUS (click to change)	Item
	testitem

%EDITTABLE{changerows="off" format="|label, 0, #2025Oct24130410 |text, 50| "}%

STATUS (click to change)	Item
	second

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%

first step
next step

(

- todo

- done )

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"}%

first step
next step

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 <whitespace>#<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%

first step
1. first new inserted item
next step
1. second new inserted item

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 (useless if `useajax` is `on`)	`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"`
descr	%CLI%	a description for a checklist item used in the `[[%TOPIC%ChecklistItemState]]` topic; you can use it as a default option (without `descr`), e.g: `%CLI{"my description"}%`	`descr=""`
descrcharlimit	%CLI% %CHECKLIST% %CHECKLISTSTART%	character limit for a description (useful if no description was given and therefore it is stripped from the text before and after a checklist item)	`descrcharlimit="100"`
hide	%CHECKLIST% %CHECKLISTSTART%	shows a button to show or hide checklist items; if you put a `@<state>` into the hide value, you can hide/show only items with the given state; restriction: this button works only for items between %CHECKLISTSTART% and %CHECKLISTEND%	`hide="Hide/Show 'done' items @done"`
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"`
log	%CHECKLIST% %CHECKLISTSTART%	enables/disables logging	`log="off"`
logformat	%CHECKLIST% %CHECKLISTSTART%	format of a log entry	`logformat=" * %SERVERTIME% - %WIKIUSERNAME% - Item %CLIID%: from %STATE% to %NEXTSTATE%"`
logtopic	%CHECKLIST% %CHECKLISTSTART%	log topic	`logtopic="%TOPIC%ChecklistLog"`
logpos	%CHECKLIST% %CHECKLISTSTART%	log entry position; allowed values: append, prepend	`logpos="append"`
name	%CLI% %CHECKLIST% %CHECKLISTSTART%	a naming context (default: `_default`) - useful and recommended if you define more than one checklist on a topic ( if you use it in `%CHECKLIST%` you must use it in all related `%CLI%` tags too)	`name="mychecklist1"`
notify	%CLI% %CHECKLIST% %CHECKLISTSTART%	enables/disables mail notification if a item state was changed	`notify="off"`
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"`; if you put a `@STATESEL` into the `reset` value you get a state selection popup with all states	`reset="Reset all @STATESEL"`
showlegend	%CHECKLIST% %CHECKLISTSTART%	if you set it to `"on"` a states legend with icons will be displayed (default: `off`), e.g: ( - todo - 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:"`
statesel	%CLI% %CHECKLIST% %CHECKLISTSTART%	enables/disables state selection popup (default: off)	`statesel="on"`
statetopic	%CLI% %CHECKLIST% %CHECKLISTSTART%	set the checklist item state topic (default: `<YourTopicName>ChecklistItemState`)	`statetopic="MyItemStateTopic"`
static	%CLI% %CHECKLIST% %CHECKLISTSTART%	allow/disallow state changes of checklist items (useful if you create summary pages of some items of different checklists)	`static="off"`
template	%CLI% %CHECKLIST% %CHECKLISTSTART%	template name (see Plugin settings / Templates )	`template="patchday"`
text	%CLI%	text will be attached to the item and will be clickable	`text="my first step"`
timestamp	%CLI% %CHECKLIST% %CHECKLISTSTART%	timestamp format used for `statictopic` or tooltip substition (%TIMESTAMP%)	`timestamp="%SERVERTIME% - %TWIKIUSERNAME%, last state: %STATE%"`
tooltip	%CLI% %CHECKLIST% %CHECKLISTSTART%	sets the tooltip of the state icons (substituted variables: %STATE% - current state; %NEXTSTATE% - next state; %STATEICON% - state icon; %NEXTSTATEICON% - next state icon; %STATES% - comma separated list of all states; %STATECOUNT% - number of states; %LEGEND% - a legend of all states and state icons; %TIMESTAMP% - the timestamp formated with `timestamp` attribute)	`tooltip="%STATE%"`
tooltipbgcolor	%CLI% %CHECKLIST% %CHECKLISTSTART%	tooltip background color (`statesel` popup background color is also effected)	`tooltipbgcolor="%WEBBGCOLOR%"`
tooltipfixleft	%CLI% %CHECKLIST% %CHECKLISTSTART%	offset to fix horizontal tooltip position	`tooltipfixleft="-163"`
tooltipfixtop	%CLI% %CHECKLIST% %CHECKLISTSTART%	offset to fix vertical tooltip position	`tooltipfixtop="0"`
useajax	%CLI% %CHECKLIST% %CHECKLISTSTART%	enables/disables JavaScript/AJAX based item state changes (default: `on`)	`useajax="1"`

Examples

Use this examples to check your installation:

Click me to change my state 'todo' to 'doing'.
first step
Click me to change my state 'todo' to 'doing'.
next step

State	TODO
Click me to change my state 'doing' to 'done'.	first step
Click me to change my state 'todo' to 'doing'.	next step

System 1
Click me to change my state 'todo' to 'doing'.
System 2
Click me to change my state 'doing' to 'done'.

ChecklistPluginChecklistItemState

Plugin Settings

This extension no longer processes settings from this topic. Settings should be applied in SitePreferences, or in the WebPreferences topics.

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

Debug plugin: (See output in working/logs/debug.log)
- Set CHECKLISTPLUGIN_DEBUG = 0

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

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

Enables/Disables state legend (default: off)
- Set CHECKLISTPLUGIN_SHOWLEGEND = off

Enables/Disables link anchors (default: on)
- Set CHECKLISTPLUGIN_ANCHORS = on

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

Enables/Disables mail notification (default: off; old bevavior: on)
- Set CHECKLISTPLUGIN_NOTIFY = off

Enables/Disables AJAX feature (JavaScript based item state changes):
- Set CHECKLISTPLUGIN_USEAJAX = on

Sets the icon state tooltip:
- Set CHECKLISTPLUGIN_TOOLTIP = Click me to change my state '%STATE%' to '%NEXTSTATE%'.

Sets offsets to fix horizontal/vertical tooltip position:
- Set CHECKLISTPLUGIN_TOOLTIPFIXLEFT = 0
- Set CHECKLISTPLUGIN_TOOLTIPFIXTOP = 0

Enables/Disables state selection popup (default: off):
- Set CHECKLISTPLUGIN_STATESEL = off

Templates

Templates allows you to setup all plugin attributes bounded to a template name. Only uppercase letters are allowed for a template name.

Syntax: Set TEMPLATE_template name_attribute name = attribute value

Template Usage: %CLI{template="template name"}% (the same for %CHECKLISTSTART%, %CHECKLIST%).

Examples:

Default
- Set TEMPLATE_DEFAULT_STATEICONS = :-I|:-)
- Set TEMPLATE_DEFAULT_STATES = todo|done

Patchday
- Set TEMPLATE_PATCHDAY_STATEICONS = :no:|:yes:|:skull:|%Y%
- Set TEMPLATE_PATCHDAY_STATES = notpatched|patched|reboot|done
- Set TEMPLATE_PATCHDAY_CLIPOS = left
- Set TEMPLATE_PATCHDAY_TOOLTIP = Click me to change my state %STATE% %STATEICON% to %NEXTSTATE% %NEXTSTATEICON%.
  There are %STATECOUNT% states (%STATES%).
  %LEGEND%

Plugin Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Plugin Info

Change History:
v1.200 (25 Jul 2015)	Foswikitask:Item1930: Use relative pub URL paths Foswikitask:Item12141: Allow use of arbitrary %ICON macros in graphics Foswikitask:Item13557: Update for Foswiki 2.0
v1.026 (21 Oct 2009)	TWiki:Main.DanielRohde: added timestamp feature requested by TWiki:Main.VickiBrown; fixed uninitialized value bugs;
v1.025 (15 Oct 2009)	TWiki:Main.DanielRohde: added documentation requested by TWiki:Main.PeterThoeny; added hide entries feature requested by Christian Holzmann; added log feature requested by TWiki:Main.VickiBrown
v1.024 (20 Apr 2007)	TWiki:Main.DanielRohde: fixed missing ')' in generated JavaScript commands
v1.023 (1 Mar 2007)	TWiki:Main.DanielRohde: fixed minor anchor link bug reported by TWiki:Main.KeithHelfrich; fixed tooltip position bug
v1.022 (12 Feb 2007)	TWiki:Main.DanielRohde: improved AJAX performance; added new feature (state selection for reset button); fixed %TOC% bug reported by TWiki:Main.HelenJohnstone; fixed some minor and major bugs (mod_perl, description stripping, `static` feature, 'text' icons); removed useforms feature
v1.021 (31 Jan 2007)	TWiki:Main.DanielRohde: fixed some major bugs (mod_perl, plugin preferences); improved performance (AJAX); fixed minor IE caching bug (AJAX related); added new attributes (tooltip, descr, template, statesel) requested by TWiki:Main.KeithHelfrich; fixed installation instructions bug reported by TWiki:Main.KeithHelfrich
v1.020 (15 Jan 2007)	TWiki:Main.DanielRohde: added AJAX feature (`useajax` attribute) requested by TWiki:Main.ShayPierce and TWiki:Main.KeithHelfrich
v1.019 (14 Dec 2006)	TWiki:Main.DanielRohde: fixed major default options bug reported by TWiki:Main.RichardHitier
v1.018 (30 Aug 2006)	TWiki:Main.DanielRohde: fixed notification bug reported by TWiki:Main.JosMaccabiani; fixed a minor whitespace bug; add static attribute
v1.017 (9 Aug 2006)	TWiki:Main.DanielRohde: fixed access right bug; disabled change/create mail notification (added attribute: notify)
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 Foswiki: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 Foswiki:Extensions/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

Related Topics: SitePreferences, Plugins

-- TWiki:Main.DanielRohde - 27 Oct 2005

PackageForm edit

Author	TWiki:Main.DanielRohde
Version	1.200
Release	25 Jul 2015
Repository	https://github.com/foswiki/ChecklistPlugin
Copyright	© 2005-2009 Daniel Rohde © 2008-2015 Foswiki Contributors
License	GPL (Gnu General Public License)
Home	http://foswiki.org/Extensions/ChecklistPlugin
Support	http://foswiki.org/Support/ChecklistPlugin

Topic attachments
I	Attachment	Action	Size	Date	Who	Comment
js	itemstatechange.js	manage	11 K	2018-06-11 - 11:12	AlexanderWeimer

Topic revision: r5 - 2021-08-05, AlexanderWeimer

System

Copyright &© by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Wiki? Send feedback