Extension talk:Workflow.php

This talk page pertains specifically to the development of this extension. For more general discussion about bugs and usage etc, please refer to the mediawiki.org talk page at MW:Extension talk:Workflow

Overview

Eventually we'd like to support many work-flow related features in the wiki, but the first and most important is to create the simplest possible means of moving articles from one point in a workflow sequence to another. To do that a parser function called #workflow has been created which allows the article to become part of a specified sequence of "phases" which can be quickly cycled through without needing to edit the containing article. Articles which are part of one or more such sequences (workflows) will exhibit extended catlinks information to show their current position within their them.

This extension code consists of four main aspects which are described in more detail below:

• the parser-function rendering which includes the javascript for switching between states when clicked, and for making the AJAX requests to update the state after a delay.
• updating one of the workflow's parser-function statements in the article
• extending the catlinks content with workflow position information
• returning just an article's catlinks information

Usage Syntax

The idea with the syntax is to enforce a solid convention for the way workflow is approached as an overall system rather than offer flexibility od syntax to suit many diverse uses. The general syntax is as follows:

{{#workflow:Job|In progress}}

The parameter represents the current state from the sequence specified in Workflow:Job, if it is not supplied, the first state in the list is assumed. This parameter is updated by the AJAX requests when the state is changed by the client-side JavaScript.

The article Workflow:Job contains a sequential bullet list of article titles each of which forms a specific phase in the workflow. The workflow extension is hard-wired to categorise the article into Category:Title (where "Title" is the currently selected state in the cycle), and to transclude Template:Title. Using the Category and Template name-spaces here is not optional, it is designed to enforce a consistent method usage of the workflow system which is extremely important when using a wiki for organisation. In the example above, the content of Workflow:Job might be as follows:

*[[Lead]]
*[[Quote]]
*[[In progress]]
*[[Complete]]
*[[Invoiced]]
*[[Paid]]

Each of the titles in the list should have a corresponding article in the Category and Template namespaces, if they're missing, they'll show up as red links in the catlinks information so they can easily be created. Also they should have an article in the Main namespace (which will show as red links in the Workflow article if not) which talks about that workflow phase as a concept.

By using the Workflow namespace, and enforcing the strict use of Category and Template with that title (in a similar way to how the MediaWiki software uses the Talk namespace in specific way) it allows us to later extend the way other namespaces are used with workflow items, for example to allow phases to contain automation scripts, unit tests or other context-specific meta-data.

Example 1

Switching between two binary states 1/0, on/off, yes/no.

• Yes
• No

Parser function call

{{#workflow: Binary|Yes}} where Workflow:Binary is a bullet list of;

*[[Yes]]
*[[No]]

Example 2

An example sequence of three states in a workflow, Category:First state, Category:Second state, Category:Third state.

Extending Category Info

The category links information below the article content can be thought of in a more general sense as the information about the current article's relationships to other articles.

Semantic MediaWiki's "facts" section below the article is in the same place, except that it is rendered as part of the article's content which we feel is wrong because it's conceptually outside the content not part of it. Another way to look at it is that information about the article which is not explicitly part of the article's content should not be returned by a request which uses the render action.

The workflow sequences that an article is a part of is also a very important aspect of its relationships, and the extension should add this information to the catlinks area using the following syntax (except that the namespaces wouldn't be displayed):

Workflow:Job: Category:Lead → Category:Quote → Category:In progress → Category:Complete → Category:Invoiced → Category:Paid

The catlinks can be extended by overriding the getCategoryLinks method of the user's skin object if one exists.

To extend the workflow area rendered within <div class="catlinks">...</div>, an optional parameter should be allowed which would use template information to render alternative workflows, e.g.

{{#workflow:Job|In progress|Template=MyWorkflow}}

The article template:MyWorkflow visually renders a workflow where the input parameters are either unnamed parameters relating to the sequence in Workflow:Job, or named parameters relating to the articles contained within Workflow:Job. Note they do not have to be complete, which allows the ability of two sepate paths in a complex workflow to be accessed and updated from two separate parser functions.

The AJAX Response

The response to the AJAX requests requires a tag in the article to have its state updated, and for the category-links part of the rendered page to be returned to the client. To get the properly rendered category links, the parser needs to be instantiated and the page rendered, so the normal AJAX dispatcher must be bypassed since it is used to return data before instantiating the main article environment. The following code is called at start-up to achieve this. As can be seen it enables the two other aspects of the code, which are handled in their own functions described below.

{{{1}}}

Returning Catlinks

Returning the catlinks is trivial and has already been tested using the following method similar to the render action.

{{{1}}}