Joomla! Documentation™

GSoC 2017
Publishing Workflow

Joomla! 

4.x

Introduction

The general point of the project is to replace states (trashed, unpublished, published, archived) with a more generic approach, so you can create easily a customized workflow to manage your articles or all other items within a component, which supports the new workflow concept.

You can find conception information about that project in the articles we have published.

• First Article
• Second Article

(*) These articles show the workflow project in the context of com_content

Prerequirements

You have enabled the component com_workflow in the extension manager.

Terms & Definitions

• Workflow - Container of transitions and states.
• States - Like now published, unpublished etc. but you would create it by yourself
• Transition - Defines, which state can be changed to another one
• Condition - It describes when an item with a specific state is published (public accessed), unpublished (only accessed from dashboard) and trashed.

Implement com_workflow into your extension

The implementation process will be described on the basic of com_content.

Basics

First of all you have to add the link to the workflow component into your submenu: index.php?option=com_workflow&view=workflows&extension=com_xxx

Where com_xxx is the name of your component.

Workflow

The entry point would be the "Workflows" list view, that can be found in the backend menu under: Content  →  Workflows.

The "Joomla! Default" workflow you see there [reference indicator], mimics the old behaviour that we have in previous Joomla! versions, where articles can be un- / published, trashed and archived.

Besides the obligatory permission settings, a workflow consists of a meaningful title and a description. The "Default" flag indicates that this workflow will be chosen when a new category was created. This means that if not changed, all articles within this category will adhere to that default workflow automatically.

As you can see there is one default workflow which comes with a fresh Joomla! installation.

Let's click "Manage" on the Joomla! Default workflow and take a look at the States.

States

Any given state needs to be matched to one of the three available "conditions" that an article can be in. Those are:

• Published
• Unpublished
• Trashed

The five entries you see in the list should look familiar. You can think of it as looking under the hood if you want. To pick just one example, it seems obvious that an "Archived" article is matched to the "Published" condition.

Like in the Workflow before, we also need to mark a State as Default and then that state will be first one assigned to the item.

Transitions

Our workflow would not be complete without "States”, but we also need some form of ruleset that defines what state comes after the other. It’s where the Transitions come into place.

For each transition you can specify access role, which group of users can execute it. In com_content you assign workflows to categories (1:1), so if you create an article within a category, it will get the default state of the workflow, which is assigned to the category. After that user with the correct ACL rights can execute transitions on this article/item to change the state.

Managing workflows

Table: #__workflows Columns:

• published (status of workflow)
• title
• description
• default - when you choose the default workflow then that one will be selected.
• created
• created_by
• modified
• modified_by

Managing states

All you have to do at that part is to select data from table #__workflow_states there we are saving states.
Each state has:

• workflow_id
• published (status of each state)
• title
• description
• condition (describe condition of assigned item to that state)
  • -2 (Trashed)
  • 0 (Unpublished)
  • 1 (Published)

Deleting states

Name of your Helper: <Component Name>Helper.php Class Name: <Component Name>Helper

Also you can specify when one of state could be deleted. You can do that be adding static method to your Helper class with name canDeleteState($stateID) which accepts state of id which would be deleted. Method should returns boolean values.

Example code:

public static function canDeleteState($stateID)
{
  $db    = \JFactory::getDbo();
  $query = $db->getQuery(true);

  $query->select('id')
     ->from($db->qn('#__content'))
     ->where('state = ' . (int) $stateID);
  $db->setQuery($query);
  $states = $db->loadResult();

  return empty($states);
}

Managing Transitions

Table: #__workflow_transitions Columns:

• published (status of each transition)
• title
• description
• from_state_id
• to_state_id
• workflow_id

When you want to run transition on your item, invoke method runTransitions($pks, $transitions, $extension, $componentTable) from WorkflowHelper and also if you want to custom handle running transition then you need to implement method updateAfterTransaction($stateID) in your Helper class which accepts to_state id and should returns boolean value.

Example of use

$runTransaction = WorkflowHelper::runTransitions($pks, $transitions, "com_content", "#__content");

WorkflowHelper::runTransitions($pks, $transitions, $extension, $componentTable)

Returns: True when succeeded or False when failure and errors will be thrown Arguments:

$pks

ids of articles

$transitions

ids of transitions

$extension

name of extension

$componentTable

name of table from where are ids

WARNING: If you would like to use default implementation of running transition then your item should have column state.

Github Project

joomla-projects/GSoC17_publishing_workflow

Related Information

See also:

• Publishing Workflow
• View scenarios of how to use Workflows on your site with a step by step on implementation.