Item14441: major recode, including unit tests, documented the changes…

… done here - had to reverse-engineer the changes to do so (thanks a f**king bunch) fixed Item14430: corrected acl handling to allow transitions when user doesn't have CHANGE access fixed Item13473: Item13211: broken code.

data/Sandbox/DocumentApprovalWorkflow.txt

@@ -2,7 +2,6 @@
    * Set WORKFLOWNOTICE = This topic is under document control. Last approval on %WORKFLOWLASTTIME_APPROVED%: %WORKFLOWLASTVERSION_APPROVED%
    * Set WORKFLOWBUTTON =  <table border="0" cellspacing="0" cellpadding="0"> <tr><td>You are permitted to change the status of this document:</td><td>%WORKFLOWTRANSITION%</TD></tr></table>
    * Set this to 1 to enable debugging about the workflow
-   * Set WORKFLOWDEBUG = 1
 
 Existing Controlled documents:
 %SEARCH{"Set WORKFLOW = DocumentApprovalWorkflow" excludetopic="%TOPIC%" nonoise="on" format="|$topic|"}%
@@ -33,6 +32,8 @@ Workflow history: %<nop>WORKFLOWHISTORY%
 | APPROVED       | revise   | UNDERREVISION |           | ApprovedForm  |
 | UNDERREVISION  | ready for approval | WAITINGFORQM  | | InProcessForm |
 | WAITINGFORQM   | approve  | WAITINGFORCTO |           |               |
-| WAITINGFORQM   | reject   | UNDERREVISION |           |               |
+| WAITINGFORQM   | reject   | UNDERREVISION | nobody    |               |
 | WAITINGFORCTO  | approve  | APPROVED      |           | ApprovedForm  |
 | WAITINGFORCTO  | reject   | UNDERREVISION |           |               |
+
+%META:PREFERENCE{name="WORKFLOWDEBUG" value="1"}%

data/System/VarWORKFLOW.txt

@@ -1,61 +1,116 @@
 %META:TOPICINFO{author="ProjectContributor" date="1407507830" format="1.1" version="1"}%
 #VarWEB
 ---+++ WORKFLOW* -- macros associated with WorkflowPlugin
-| *Controlling topics in the workflow* ||
-| =%<nop>WORKATTACHTOPIC%= | Expands to a link that lets you attach to the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be <strike>struck out</strike>).|
-| =%<nop>WORKFLOWEDITTOPIC%= | Expands to a link that lets you edit the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be <strike>struck out</strike>).|
-| =%<nop>WORKFLOWFORK{...}%= | Expands to a button that will create a copy of the _current_ topic (see below for more details) |
-| =%<nop>WORKFLOWTRANSITION%= | Expands to either (a) a pull-down menu if the user can perform more than one transition, (b) a button if the current user can only perform one transition, or (c) empty space if the current user is not allowed to perform any action. You can change the format of the button using a CSS class (see WORKFLOWTRANSITIONCSSCLASS below) |
-| *Querying the workflow* ||
-| =%<nop>WORKFLOWHISTORY%= | Expands to the history of state transitions the topic has undergone. The format of the history is dictated by the =WORKFLOWHISTORYFORMAT= (described below). |
-| =%<nop>WORKFLOWLASTREV{"State"}%= | Expands to the version number when the document was last in the state _State_. |
-| =%<nop>WORKFLOWLASTTIME{"State"}%= | Expands to the timestamp when the document was last in the _State_ state. For example, =%<nop>WORKFLOWLASTTIME{"APPROVED"}%= would be replaced by the timestamp when the document was last in the =APPROVED= state. |
-| =%<nop>WORKFLOWLASTUSER{"State"}%= | Expands to the last user who transitioned the document into the state _State_. |
-| =%<nop>WORKFLOWLASTVERSION{"State"}%= | Expands to a link to the version of the document when it was last in the state _State_. |
-| =%<nop>WORKFLOWSTATE%= | Expands to the current state of the document. It can also be given a =topic= parameter (default), in which case the state of that topic is returned. |
-| =%<nop>WORKFLOWSTATEMESSAGE%= | Expands to the corresponding message in the state table. |
 
-(All the macros accept an optional default parameter, which is the name of a topic, a =web= and a =rev= parameter. If these are omitted, they will default to the current topic, latest revision)
+All the following macros accept web and topic parameters:
+| *Parameter* | *Meaning* | *Default* |
+| =web= | (Optional) name of the web containing the topic | current web |
+| =topic= | (Optional) name of the topic (may use web.topic syntax) | current topic |
+
+Where it makes sense, the macros also accept a =rev= parameter.
+
+If the topic is *not* controlled, then any references to =WORKFLOW=
+macros are simply removed. You can use this behaviour to place these
+tags in the header or footer in your skin templates. They appear only
+if the currently displayed document is controlled. Otherwise, they are
+just removed and do not disturb the layout.
+
+---++++ =%<nop>WORKATTACHTOPIC%=
+Expands to a link that lets you attach to the topic (if the you are not
+able to modify the topic, either in the workflow sense or according to the
+tandard access controls, the link will be <strike>struck out</strike>).
+
+---++++ =%<nop>WORKFLOWEDITTOPIC%=
+Expands to a link that lets you edit the topic (if the user is not able to modify the topic, either in the workflow sense or according to the standard access controls, the link will be <strike>struck out</strike>).|
+
+---++++ =%<nop>WORKFLOWFORK{...}%=
+Expands to a button that will create a copy of the _current_ topic.
+
+When the button is pressed, Foswiki will create a copy of
+the current topic (which must be in a workflow).
+
+| *Parameter* | *Meaning* | *Default* |
+| ="TopicName"= | (Optional) name of the topic to fork | current topic |
+| =newnames="NameOne,NameTwo"= | Comma-separated list of name(s) of the new topic(s) to create, You can use a web specifier on the topic names. | required, no default. |
+| =label="Fork"= | Label to use in the button | ="Fork"= |
+| =lockdown="on"= | Set this if you want the forked topic to be set as uneditable after the fork | =off= |
+Used when you have a topic that has to be split to follow different
+routes through a workflow - for example, when a requirement is refined
+to create two new requirements that must follow their own lifecycles;
+or perhaps a problem report is found to affect two different
+components of a system, and the resolutions have to be separately
+tracked. Both the copied topic and the new topic will have workflow
+history entries added.
+
+For example,
+=%<nop>WORKFLOWFORK{"OriginalTopic" label="Divide and conquer" newnames="ForkPathOne,ForkPathTwo" lockdown="on"}%= will create two copies of =OriginalTopic=, named =ForkPathOne= and =ForkPathTwo= and set the =OriginalTopic= as uneditable (using ALLOWTOPICCHANGE).
+
+The histories in both the fork copies and the original topic record
+what happened.
+
+You have to be able to modify the topic (both in the workflow sense
+and according to the standard access controls) in order to fork.
 
-Furthermore, the plugin replaces any macro starting with =WORKFLOW= that is defined in the workflow description file.
+%X% due to a bug in versions of the plugin prior to Oct 2009, the
+ default "TopicName" parameter was interpreted as the name of the
+ *new* topic to fork to. This has been corrected, but the macro will
+ revert to the old meaning if you omit the =newnames= parameter.
 
-If the topic is *not* controlled, then any references to =WORKFLOW= macros are simply removed (you can use this behaviour to place these tags in the header or footer in your skin templates. They appear only if the currently displayed document is controlled. Otherwise, they are just removed and do not disturb the layout).
+---++++ =%<nop>WORKFLOWTRANSITION%=
+Expands to either (a) a pull-down menu if the user can perform more
+than one transition, (b) a button if the current user can only perform
+one transition, or (c) empty space if the current user is not allowed
+to perform any action. You can change the format of the button using a
+CSS class (see WORKFLOWTRANSITIONCSSCLASS below)
 
-In addition there are two macros you can define in your topics (or !WebPreferences)
 
-WORKFLOWHISTORYFORMAT tells the plugin how to format each new line added to the WORKFLOWHISTORY. The format is used as a template for each new entry, and should include all the formatting necessary to make the history look nice when it is viewed.
+---++++ =%<nop>WORKFLOWHISTORY{...}%=
+Expands to the history of state transitions the topic has undergone.
+
+| *Parameter* | *Meaning* | *Default* |
+| =format= | Format of each result | Value of =%<nop>WORKFLOWHISTORYFORMAT%= |
+| =header= | Header before results | |
+| =footer= | Footer after results | |
+| =separator= | Separator between results | |
+| =include= | Regular expression matching states to include | |
+| =exclude= | Regular expression matching states to exclude | |
+
+The format is used as a template for each new entry, and should
+include all the formatting necessary to make the history look nice
+when it is viewed.
 
 In this example the history is formatted as a table:
    * Set WORKFLOWHISTORYFORMAT = $n| $state | $wikiusername | $date |
-The leading $n expands to a newline character that separates each line of the history.
+The leading $n expands to a newline character that separates each line
+of the history.
+
 You could also format the history as a bullet list:
    * Set WORKFLOWHISTORYFORMAT = $n   * $state -- $wikiusername, $date
-The standard [[format tokens]] are supported, as well as the following special tokens:
+The standard [[format tokens]] are supported, as well as the following
+special tokens:
 | *Token* | *Expands to* |
-| =$wikiusername= | Who triggered the transition |
+| =$user= | Who triggered the transition to this state |
 | =$state= | The target state of the transition |
-| =$date= | Date of the transition |
+| =$day= =$dow= =$epoch= =$hours= =$isotz= =$minutes= =$mo= =$month= =$rcs= =$seconds= =$tz= =$wday= =$we= =$week= =$ye= =$year= | Components of the date of the transition |
+| =$email= =$http= | Alternative represenations of the full date |
 | =$rev= | Version at the transition |
+| =$comment | Comment accompanying the transition |
+| =$index= | 1-based number of this result |
 
-The appearance of the button to change state can be configured by providing a CSS class. For example,
-   * Set WORKFLOWTRANSITIONCSSCLASS = myCSSClass
-The default is =foswikiChangeFormButton foswikiSubmit=.
+---++++ =%<nop>WORKFLOWLAST{...}%=
+Expands to the history recorded when the topic was last in a certain state.
 
-The =WORKFLOWFORK= macro is used to generate a button that will create a copy of
-a workflow topic. It accepts the following parameters:
 | *Parameter* | *Meaning* | *Default* |
-| ="TopicName"= | (Optional) name of the topic to fork | current topic |
-| =web= | (Optional) name of the web containing the topic to fork | current web |
-| =newnames="NameOne,NameTwo"= | Comma-separated list of name(s) of the new topic(s) to create, You can use a web specifier on the topic names. | required, no default. |
-| =label="Fork"= | Label to use in the button | ="Fork"= |
-| =lockdown="on"= | Set this if you want the forked topic to be set as uneditable after the fork | =off= |
-This macro is used when you have a topic that has to be split to follow different routes through a workflow - for example, when a requirement is refined to create two new requirements that must follow their own lifecycles; or perhaps a problem report is found to affect two different components of a system, and the resolutions have to be separately tracked. Both the copied topic and the new topic will have workflow history entries added.
+| ="State"= | Name of the state | |
+| =format= | Format | |
 
-For example,
-=%<nop>WORKFLOWFORK{"OriginalTopic" label="Divide and conquer" newnames="ForkPathOne,ForkPathTwo" lockdown="on"}%= will create two copies of =OriginalTopic=, named =ForkPathOne= and =ForkPathTwo= and set the =OriginalTopic= as uneditable (using ALLOWTOPICCHANGE).
+The format is the same as that used for =WORKFLOWHISTORY=.
 
-The histories in both the fork copies and the original topic record what happened.
+---++++ =%<nop>WORKFLOWSTATE%=
+Expands to the current state of the document. It can also be given a
+=topic= parameter (default), in which case the state of that topic is
+returned.
 
-The user has to be able to modify the topic (both in the workflow sense and according to the standard access controls) in order to fork.
+---++++ =%<nop>WORKFLOWSTATEMESSAGE%=
+Expands to the corresponding message in the state table.
 
-%X% due to a bug in versions of the plugin prior to Oct 2009, the default "TopicName" parameter was interpreted as the name of the *new* topic to fork to. This has been corrected, but the macro will revert to the old meaning if you omit the =newnames= parameter.