PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

---

Parent package: Foswiki::Plugins::QMPlugin
Child packages:

More ...Less ...

internal package Foswiki::Plugins::QMPlugin::State

implements a state that a network is in

a topic is in a certain state. one state can transition into another by following the topological constraints of the underlying network.

ClassProperty TRACE

boolean toggle to enable debugging of this class

ClassProperty PROPS

definition of all mandatory properties of an object of its kind; node, edge and role classes each refine this list

ClassMethod new($web, $topic, $rev, $meta) → $state

constructor for a state object

ObjectMethod init($web, $topic, $rev, $meta)

init this state by reading the associated topic; this method is called as part of the constructor, but may also be called afterwards to assign a different topic or revision to it.

ObjectMethod finish()

called when this object is destroyed

ObjectMethod setWorkflow($workflow) → $net

set the workflow definition topic of this state; this is either done as part of the init() method; returns a Net object when a workflow as set successfully, undef otherwise.

ObjectMethod unsetWorkflow($workflow) → $net

remove the workflow definition and its net from this state

ObjectMethod props() → @props

get a list of all known state properties

ObjectMethod prop($key, $val) → $val

getter/setter of a certain property of this state

ObjectMethod deleteProp($key) → $val

remove a property from this state, returns the original value

ObjectMethod expandValue($val) → $val

expand the given value in the context of the current topic

ObjectMethod save(%params) → $this

save this state into the assigned topic/ params are forwared to Foswiki::Meta::save().

ObjectMethod updateMeta() → $this

save this state into the assigned meta object, don't save it to the store actually

ObjectMethod change($action, $to, $comment, $user, $keepReviews) → $boolean

change this state by performing a certain action, providing an optional comment; returns true if the action was successfull and the state has been transitioned along the lines of the net. Otherwise an error is thrown. Note that only the properties of this state are changed; it is not stored into the current topic; you must call the save() method to do so.

The keepReviews boolean allows to keep review objects from a previous transition. Previous review objects will be filtered out not matching the current action.

ObjectMethod resetReviews() → $boolean

reset an ongoing parallel review to the start. returns true if any review was found and deleted

ObjectMethod filterReviews($action, $id) → $boolean

removes any review that does not the given state and action parameters, returns true if an review has been deleted.

ObjectMethod traverse($edge, $comment)

change the current state by traversing the given edge; note that this only changes the current location within the net; the changed data is not stored into the current state.

ObjectMethod updateCustomProperties()

recompute all custom node properties and store them into the state

ObjectMethod log($edge, $comment)

write the event of traversing the given edge to the wki logs with an optional comment

ObjectMethod queueCommand($edge, $id, $params)

queue the command of an edge being traversed

ObjectMethod processCommands($type)

commands are processed after this state has been saved, not earlier, as some commands handler might alter the store of the changed state, such as moving the related topic to the trash.

ObjectMethod sendNotification($template) → $errors

sends a notifications for the current edge transition. This is called when a transition has actually happened, but may also be called later on to re-send the email notification. this method is always called when save() is performed; the method returns a list of errors that may have happened as part of the mail delivery process. See also Foswiki::Func::sendEmail.

$template is the name of the template to be used for the email, defaults to qmpluginnotify.

ObjectMethod getNotificationTemplate($edge) → $templateName

get the name of the template for the given edge. if the edge doesn't have a mailTemplate property will the QMNet's default net be used. See Foswiki::Plugins::QMPlugin::Net::getNotificationTemplate().

ObjectMethod setACLs($node) → $boolean

sets the ACLs as imposed by the current node of the state or the specified one; this method is called by save() itself and probably of no direct use otherwise.

returns true if acls changed and false if no change was needed.

ObjectMethod getWeb() → $web

get the web of this state

ObjectMethod getTopic() → $topic

get the topic of this state

ObjectMethod getMeta() → $meta

get the meta object of this state

ObjectMethod getRevision() → $rev

get the revision of the topic of this state

ObjectMethod getLastApproved($force) → $state

get the state that was last approved starting at the current rev. if $force is set the last revision will be digged out by a search. the approvalRev property will be used otherwise.

ObjectMethod getReviews() → @reviews

get all reviews of this state

ObjectMethod numReviews() → integer

get the number of reviews in this state

ObjectMethod numComments() → integer

get the number of reviews in this state

ObjectMethod getReviewEdge() → $edge

get the edge that has been reviewed

ObjectMethod getCurrentNode() → $node

get the node that this state is currently associated with

ObjectMethod getCurrentEdge() → $edge

get the edge that has been traversed to reach this state

ObjectMethod getNet() → $net

get the net that this state is currently associated with

ObjectMethod getPossibleActions($node, $user) → @actions

get the list of possible actions starting from the current node or the node specified in the call; the empty list is returned when user is not allowed to perform any actions

ObjectMethod getTriggerableActions($node, $user) → @actions;

get a list of actions that might be triggered

ObjectMethod getPossibleEdges($node, $user) → @actions

get the list of possible edges starting from the current node or the node specified in the call; the empty list is returned when user is not allowed to perform any actions

ObjectMethod getTriggerableEdges($node, $user) → @actions;

get a list of edges that might be triggered

ObjectMethod isReviewedBy($user) → $boolean

returns true when the current state has been reviewed by user already

ObjectMethod isParallel() → $boolean

returns true when there the current review actions must be signed off by multiple users

ObjectMethod isApproved($node) → $boolean

returns true if the given or current node of the state is an approval node

ObjectMethod hasChanged() → $boolean

returns true when this state was changed as part of a transition, returns false if other changes happened to the topic

ObjectMethod getCurrentSignOff($edge) → $percent

get the current sign-off progress counting the number of people that already reviewed this state

ObjectMethod addReview($data)

create a new review of this state

ObjectMethod getReviewers($action) → @users

get the list of users that already reviewed the current state

ObjectMethod getNumReviews($edge) → $number

returns the number of people that already reviewed the current state using the given action

ObjectMethod getComments() → @comments

get the list of comments in reviews; each item in the result list has properties:

• author
• date
• text

ObjectMethod getPossibleReviewers($from, $action, $to) → @users

get the list of allowed users of outgoing edges, optionally performing a certain action; returns an empty list there are no specific restrictions, that is all users may perform a certain action

ObjectMethod getPendingApprovers($node) → @users

get the list of users that still need to approve the current state

ObjectMethod getPendingReviewers($edge) → @users

get the list of users that still need to review the current state

ObjectMethod reroute($web, $topic, $meta)

create a copy of the underlying topic and continue the state there

ObjectMethod reassign($to)

change meta object part of this state

ObjectMethod render($format) → $string

render the properties of this object given the specified format string

ObjectMethod asJson() → $json

ObjectMethod renderReviews() → $string

returns a string representation of all reviews of a state

ObjectMethod getCore() → $core

convenience method to get the plugin core

ObjectMethod translate($string) → $string

translates a string using MultiLingualPlugin

ObjectMethod stringify() → $string

returns a string representation of this object

ObjectMethod json()

returns a JSON encoder/decoder