Checklists Plugin

Name	Checklists Macros
Vendor	Comala Technology Solutions, Inc. (Website)
Authors
Homepage	http://confluence.atlassian.com/display/CONFEXT/Checklists+Plugin
Issue Management	http://developer.atlassian.com/jira/browse/CHK
Categories	Content Macros
Version	1.4.0
Availability	Confluence v2.3.3 to v2.9-m5
State	Stable
Support
License	Freeware / Open Source (BSD)
Price	Free
Release Docs	n/a
Java API Docs	n/a
Download Source	http://www.comalatech.com/confluence/plugins/src/checklists-1.4.0-src.jar
Download JAR	checklists-1.4.0.jar

Winner of the 2007 Confluence Codegeist!

Description/Features

A set of macros to generate checklist tables for a subset of pages (children of a given parent-page and/or filtered by a label). For each page, labels can be added/removed, values can be edited, and text segments can be added.

It provides a handy way to construct to-do lists, or manage the stages of a project. You could even use it to make an ad-hoc document workflow.

You can just jump to the Examples to see how the macros can be used

Attributes

Attributes are stored as metadata, so they can be access through the Metadata plugin.

Security

The macro check permissions to ensure the user is allowed to see the content and modify it.

Change log

All the changes made through the checklist are log and the history can be access through a macro.

Wiki segments

Wiki segments can be defined so they get rendered for each of the checklist's pages, allowing to use other plugins to produce powerful reporting.

Table of contents

• Usage
  • {checklist}
  • Columns
    • {checklist-label}
    • {checklist-input}
    • {checklist-wikiinput}
    • {checklist-select}
    • {checklist-wiki}
    • {checklist-excerpt}
    • {checklist-pagelink}
    • {checklist-include}
    • {checklist-metadata}
    • {checklist-column}
  • {checklist-attribute}
  • {checklist-log}
• Examples
  • Example 1: simple checklist
  • Example 2: checklist with excerpts and mutually exclusive labels
  • Example 3: checklist with excerpt and wiki input
  • Example 4: checklist with metadata lookup and plain text input
  • Example 5: checklist with a simple selection, and accessing the values later
  • Example 6: checklist with a selection of labels using different captions
  • Example 7: checklist with a selection of users
  • Example 8: checklist with wiki segments on each listed page
  • Example 9: checklist including the entire content of each page
  • Example 10: displaying the change log of a page's attributes modified through a checklist
  • Example 11: advanced checklist for a design review
  • Example 12: advanced checklist for a simple issues list
  • Example 13: to-do list view using keywords
  • Example 14: using Keywords to set the page owning the page as parent (and using label filter) in a template
• Installation
• Version History
• Acknowledgments
• Screenshots

Usage

Keywords

Parameters value can have any of the following keywords that will be replace when rendering the page:

{checklist}

Generates a checklist for a subset of pages. The rows are children pages of a given page (parent) and can be filtered by a label. The columns can be labels that are set/un-set for the pages, the excerpt or a text.

The columns of the checklist can also be defined using the {checklist-label}, {checklist-input}, {checklist-wikiinput}, {checklist-select}, {checklist-excerpt}, {checklist-include}, {checklist-wiki}, {checklist-metadata} macros.

{checklist-label}

Defines a column as a label. Every time a cell of this column is selected, the label will be added/removed to/from the referred page. See Example 4.

{checklist-input}

Defines a column as a text input. See Example 4.

{checklist-wikiinput}

Defines a column as a wiki-text input. See Example 3.

{checklist-select}

Defines a column as a selection (drop-down menu). The selection can be from a list of options, a list of labels or a list of users. See Example 5, Example 6 and Example 7.

If store is set to checklist and there is only one option to select from, then the column is handled as a checkbox (/). See Example 11

{checklist-wiki}

Defines a column as a wiki segment to be rendered for each of the pages on the checklist. See Example 8.

{checklist-excerpt}

Defines a column as the excerpt of each of the pages. See Example 3.

{checklist-pagelink}

Defines a column as a link to each of the pages. See Example 15.

{checklist-include}

Defines a column as the entire content of each of the pages. See Example 9.

{checklist-metadata}

Defines a column as a lookup of existing metadata for each page. See Example 4.

{checklist-column}

This macro is being deprecated. Use {checklist-label}, {checklist-excerpt} or {checklist-wikiinput} instead.

{checklist-attribute}

This macro allows to Display the value of an attribute set on a page through a checklist. See Example 6.

{checklist-log}

Generates a checklist change report for a given page. See Example 10.

Examples

Lets say we have a page Animals as parent of the pages Dog, Cat, Shark, Elephant, Turtle, Salmon, Snake, Whale, Frog, Toad, Lizard, Platypus and Eagle.

Example 1

{checklist:name=The animals| parent=Animals|checklabels=mammal, oviparous, pets}

All the children of Animals are shown. The checks are for the labels mammal, oviparous and pets. Whenever any the check is selected, the appropriate label is added/removed to/from the page on the row.

Example 2

Lets add the excerpt of each page and restrict to show only the children of Animals that have the label oviparous and make the check labels bird, fish, amphibian or reptile mutually exclusive.

{checklist:name=Oviparious|parent=Animals|excerpt-heading=Classification|
    label=oviparous|checklabels=fish, amphibians, reptiles, birds|mutuallyexclusive=true}

Note that mutually exclusive labels are handled as a drop down menu.

Example 3

Lets restrict to show only the children of Animals that have the label pets, and add a comment for each page on the checklist:

{checklist:name=The pets| parent=demo:Animals| label=pets| excerpt-heading=Classification| comment-heading=Comments}

The values can be an actual wiki segment!

The same checklist can be created using {checklist-excerpt} and {checklist-wikiinput} to provide more detail over the columns (width, rows and cols).

{checklist:name=The pets| parent=Animals| label=pets}
    {checklist-excerpt:Classification|width=10%}
    {checklist-wikiinput:Comments|rows=5|cols=20|width=50%}
{checklist}

Example 4

The heading of a label check (Mammal?) can be different from the actual label name (mammal) using the {checklist-label} macro. Because the Comments (set in the previous example) are stored as metadata, they can be accessed using the {checklist-metadata} macro. Also, you can define plain text input using the {checklist-input} macro.

{checklist:name=The pets names|parent=Animals|label=pets}
   {checklist-label:Mammal?|label=mammal}
   {checklist-metadata:Comments}
   {checklist-input:Common pet names|cols=20}
{checklist}

Example 5

You can define a column as a selection. Lets say we need to define whether or not the oviparious are swimmers:

{checklist:name=Swimmers|parent=Animals|label=oviparous}
   {checklist-excerpt:Classification|width=10%}
   {checklist-select:Can swim?}
      yes
      no
   {checklist-select}
{checklist}

Then, the value can be accessed later using {checklist-attribute} or any of the Metadata Plugin macros:

Eagle can swim? {checklist-attribute:page=eagle|attribute=Can swim?}
Shark can swim? {metadata-from:shark|Can swim?}

Will render as:

Eagle can swim? no
Shark can swim? yes

Example 6

A selection could use labels instead of metadata values. Similar to example 2, here the actual labels used are bird, fish, amphibian or reptile but the caption can be different:

{checklist:name=The oviparious|parent=Animals|label=oviparous}
   {checklist-select:Type|uselabels=true}
       fish|It's a fish
       amphibians|It's an amphibian
       reptiles|It's a reptile
       birds|It's a bird
   {checklist-select}
{checklist}

Make sure the labels are in lowercase, otherwise you could have problems displaying the existing value (see CHK-14)

Example 7

Users can also be selected:

{checklist:name=Pets on the team|parent=Animals|label=pets}
   {checklist-select:Who owns one?|usersgroup=all}
{checklist}

Example 8

Arbitrary wiki segments can also be added to the checklist to be rendered for each page. Lets say we know each of the Animals' pages has a picture (photo.jpg). Using the Linking plugin we can also create a link for editing each page.

{checklist:name=Pet's photos|parent=Animals|label= pets}
   {checklist-wiki:Photo}
       !photo.jpg!
   {checklist-wiki}
   {checklist-wiki:Edit page}
      {link-to:page edit}Edit page{link-to}
   {checklist-wiki}
{checklist}

Example 9

You can actually include the entire content for each page. Use with caution it can get really messy.

{checklist:name=All the pet's pages|parent=Animals|label= pets}
   {checklist-include:Full page}
{checklist}

Example 10

You can view the log of changes made through the checklist using the {checklist-log} macro:

{checklist-log:page=dog}

Will render as:

If we want see who made the latest change on the Comments and when (useful when including as part of a {checklist-wiki} body), we can use:

{checklist-log:format=useranddate|maxentries=1|Comments}

Will render as:

Example 11

A more sophisticated checklist used for a design review. Each of the evaluation criteria is defined as child of the page qa-goals. The values are stored into the actual checklist and nothing is changed on the criteria pages.

{checklist:name=Design review checklist|parent=qa-goals}
  {checklist-excerpt:Description}
  {checklist-select:Reviewed?|store=checklist}
      reviewed_sprint_1
  {checklist-select}
  {checklist-wikiinput:Evidence?|width=20%|rows=3|cols=20|store=checklist}
  {checklist-wikiinput:Comments|width=40%|rows=5|cols=50|store=checklist}
{checklist}

Example 12

Using the Linking plugin we can create a simple issues list:

{link-page:template=Issue|parent=@self}Click to add a new issue{link-page}
{checklist}
   {checklist-excerpt:Description}
   {checklist-label:Active?|label=active}
   {checklist-select:State|uselabels=true}
        decision-made|Decision made
        no-decision|No decision made
        retired|Retired
   {checklist-select}
   {checklist-select:Raised by|usersgroup=all}
   {checklist-select:Assigned-to|usersgroup=all}
   {checklist-wikiinput:Comments|cols=20|rows=5}
   {checklist-wiki:Last commented by}
        {checklist-log:format=useranddate|maxentries=1|Comments}
   {checklist-wiki}
{checklist}

Example 13

Using Keywords to filter pages based on the current user

{checklist:Tasks for @userfullname@|parent=Tasks|label=user_@user@}
    {checklist-label:active}
{checklist}

Note that his example assumes that alphanumerical user names (i.e. johndoe would work but john.doe would not).

Example 14

Using Keywords to set the page owning the page as parent (and using label filter) in a template

{checklist:Features|parent=@self|label=active}
   {checklist-excerpt:Description}
{checklist}

Example 15

Not yet... extremely busy right now, but I will include a nice example to demonstrate how you can beautify (even more) a checklist

Installation

You need to have System Administrator permissions in order to install and configure plugins.

Installing and Configuring Plugins using the Plugin Repository Client

If the plugin you wish to install is listed in the Confluence Plugin Repository, you can use the Confluence Repository Client to install it. Just find the plugin in the list and click the 'install' link. There's more information in Installing and Configuring Plugins using the Plugin Repository Client.

Installing and Configuring Plugins Manually

If the plugin you wish to install is not listed in the Confluence Plugin Repository, you can still install it by uploading it to your Confluence site:

1. In the 'Administration' section of Confluence, click the Plugin Repository link.
2. Click the 'Upload' tab.
3. Use the 'Browse' button to find the plugin jar you wish to install.
4. Select the jar file and click 'Open'.
5. The plugin will be uploaded from your machine to Confluence, and will be automatically installed.

There's more information in Installing and Configuring Plugins manually.

RELATED TOPICS

Removing malfunctioning plugins

Version History

Issues

Acknowledgments

• This macro uses portions of the MetadataUtils of the Metadata Plugin
• The table sorting is done using a modified version of the SortTable.js script of the Table Plugin

Screenshots

Screenshots