internal package Foswiki::Plugins::WorkflowPlugin::ControlledTopic

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:

Child packagesChild packages

internal package Foswiki::Plugins::WorkflowPlugin::ControlledTopic

A thin layer over the meta for a topic that carries meta-information about the workflow in an easy-to-access way, and provides operations that support the plugin.

ClassMethod new($workflow, $web, $topic)

Construct a new ControlledTopic object.

• $workflow - pointer to Workflow object
• $web - web name
• $topic - topic name

ClassMethod load($web, $topic [, $rev])

Load an existing controlled topic. Topic must exist.

• $web - web name
• $topic - topic name
• $rev - optional topic revision to load

Will die if it detects anything wrong with the load

ObjectMethod getCurrentStateName() → $statename

Get the name of the current state of the workflow in this topic

ObjectMethod getCurrentState() → \%state

Get the row of the workflow state table for the current state of this topic

ObjectMethod getForm() → $formname

Get the name of the currently attached form.

ObjectMethod getLast($state) → \%history

Get the history record stored from the last time the topic transitioned to the given state. Transition records contain at least state and date

ObjectMethod getLastBefore($date) → \%history

Get the last history record stored from before the given date.

ObjectMethod setState($statename)

Set the current state. Note does not record history, doesn't change the form.

ObjectMethod setForm($formname)

Set the current form.

ObjectMethod haveNextState($action) → $boolean

Return true if a new state is available from the current state using this action

ObjectMethod canEdit() → $boolean

Determine if workflow allows editing for the current user.

ObjectMethod canView() → $boolean

Determine if workflow allows viewing for the current user.

ObjectMethod canTransition($action) → $boolean

Determine if workflow allows the given action for the current user. Note that admin users can always transition, and can override workflow rules.

• $action - the action to test

ObjectMethod changeState($action[, $comment [,$breaklock]]) → $form

Change the state of the topic, noitifying the change to listeners and saving the topic.

• $action - the action from the current state
• $comment - comment accompanying the state change
• $breaklock - if true, stomp over any lease on the topic

Note that the current user may not have permission to edit the topic after the transition. However if a form is added, they need to be able to edit to fill in the form. To that end, they are automatically (and temporarily) granted CHANGE for the next edit only.

Note this method does not check if the transition is permitted for the current user under workflow rules.

@throw WorkflowException if there's a problem

@return the name of the new form, if the form has changed, undef otherwise

ObjectMethod notifyTransition($transition [, %options])

Send email to all interested parties that the given transition has just been executed.

• $transition - reference to a transition that must exist in the workflow object for this controlled topic.
• %options can include:
  • default_template - required to tell what temaplte to use
  • template - alternative to the default_template
  • any number of UPPERCASE tokens that will be expanded in the mail template

ObjectMethod save($lockdown)

Save the topic to the store.

• lockdown can be used to lock the topic for changes after save.

StaticMethod handleSave($meta)

beforeSaveHandler - check if the temporaryGrant flag is set, and if not remove any temporary grant from the meta.

ObjectMethod fork(\@forks [,$lockdown]) → $string

Create a series of new topics that are clones of this topic, except that the history of the copied topic is not carried over. Topics being cloned to must not exist.

• \@forks - array of hashes each containing web, topic for the topics being created
• $lockdown - if true, will lock down this topic for changes after the cloning is complete

If any of the clone topic names are AUTOINC, will modify the @$forks to reflect the actual topic name used.

Returns alist of the topics created.

Will throw WorkflowException if there's a problem (or Error if there's a deeper problem)

ObjectMethod expandMacros($text) → $expandedText

Expand all macros in the text in the context of the topic, and perform some rendering steps (remove , and ) ---+++ =OnjectMethod= stringify() → $string Generate a stringified version of the topic, for debugging