Joomla! Documentation - User contributions [en]

Publishing Workflow Implementation

2017-10-04T07:10:42Z

Janek:

{{Top portal heading|color=white-bkgd|text-color=#333|title=
GSoC 2017 <br />
Publishing Workflow}}
[[Image:Gsoc2016.png|75px|center|link=GSOC 2017]]
<noinclude>{{Joomla version|version=4.x}}</noinclude>
{{-}}

== 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.
* [https://community.joomla.org/gsoc-2017/3119-publishing-workflow-for-joomla.html First Article]
* [https://community.joomla.org/gsoc-2017/publishing-workflow.html Second Article]

(*) These articles show the workflow project in the context of <tt>com_content</tt>

== Prerequirements ==

You have enabled the component <tt>com_workflow</tt> in the extension manager.

[[File:Enabled component.png|Extension Manager|800px|center]]

== 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 <tt>com_content</tt>.

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

Where <tt>com_xxx</tt> 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 {{rarr}} 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.

[[File:Workflows.png|Workflows|800px|center]]

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

[[File:Add new workflow.png|Add new Workflow|800px|center]]

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.

[[File:States.png|States|800px|center]]
[[File:New state.png|New State|800px|center]]

=== 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.

[[File:Transitions.png|Transitions|800px|center]]

For each transition you can specify access role, which group of users can execute it. In <tt>com_content</tt> 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.

[[File:New transition.png|Add new Transition|800px|center]]

== Managing workflows ==
Table: <tt>#__workflows</tt>
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 <tt>#__workflow_states</tt> there we are saving states.<br />
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 <tt>canDeleteState($stateID)</tt> which accepts state of id which would be deleted. Method should returns boolean values.

==== Example code: ====
<source lang="php">
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);
}
</source>

== Managing Transitions ==
Table: <tt>#__workflow_transitions</tt>
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 <tt>runTransitions($pks, $transitions, $extension, $componentTable)</tt> from WorkflowHelper and also if you want to custom handle running transition then you need to implement method <tt>updateAfterTransaction($stateID)</tt> in your Helper class which accepts to_state id and should returns boolean value.

==== Example of use ====
<source lang="php">
$runTransaction = WorkflowHelper::runTransitions($pks, $transitions, "com_content", "#__content");
</source>

==== 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 <tt>state</tt>.

== Github Project ==
[https://github.com/joomla-projects/GSoC17_publishing_workflow/tree/0.0.1-basic joomla-projects/GSoC17_publishing_workflow]

<noinclude>
[[Category:Google Summer of Code 2017]]
[[Category:Development]]
[[Category:Joomla! 4.x]]
</noinclude>

Publishing Workflow Implementation

2017-08-29T13:49:02Z

Janek: Created page with "{{Top portal heading|color=white-bkgd|text-color=#333|title= GSoC 2017 <br /> Publishing Workflow}} link=GSOC 2017 <noinclude>{{Joomla versi..."

{{Top portal heading|color=white-bkgd|text-color=#333|title=
GSoC 2017 <br />
Publishing Workflow}}
[[Image:Gsoc2016.png|75px|center|link=GSOC 2017]]
<noinclude>{{Joomla version|version=4.x}}</noinclude>
{{-}}

== Introduction ==

The general point of 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 component, which supports the new workflow concept.

You can find conception information about that project at the articles that we have published.
* [https://community.joomla.org/gsoc-2017/3119-publishing-workflow-for-joomla.html First Article]
* [https://community.joomla.org/gsoc-2017/3119-publishing-workflow-for-joomla.html Second Article]

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

== Prerequirements ==

You have enabled the component com_workflow in the extension manager.

[[File:Enabled component.png|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 - Its describe 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 you submenu:
<code>index.php?option=com_workflow&view=workflows&extension=com_xxx</code>

While 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 know from 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.

[[File:Workflows.png|Workflows]]

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

[[File:Add new workflow.png|Add new Workflow]]

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.

[[File:States.png|States]]
[[File:New state.png|New State]]

=== 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.

[[File:Transitions.png|Transitions]]

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.

[[File:New transition.png|Add new Transition]]

== Managing workflows ==

Table: <code>#__workflows</code>
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 <code>#__workflow_states</code> 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 <code>canDeleteState($stateID)</code> which accepts state of id which would be deleted. Method should returns boolean values.

==== Example code: ====
<source lang=”php”>
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);
}
</source>

== Managing Transitions ==

Table: <code>#__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 <code>runTransitions($pks, $transitions, $extension, $componentTable)</code> from WorkflowHelper and also if you want to custom handle running transition then you need to implement method <code>updateAfterTransaction($stateID)</code> in your Helper class which accepts to_state id and should returns boolean value.

==== Example of use ====
<source lang=”php”>
$runTransaction = WorkflowHelper::runTransitions($pks, $transitions, "com_content", "#__content");
</source>

==== 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 <code>state</code>.

== Github Project ==

[https://github.com/joomla-projects/GSoC17_publishing_workflow/tree/0.0.1-basic joomla-projects/GSoC17_publishing_workflow]

File:New transition.png

2017-08-29T13:43:46Z

Janek:

Add new Transtiion

File:Transitions.png

2017-08-29T13:43:12Z

Janek:

List of Transitions

File:New state.png

2017-08-29T13:42:27Z

Janek:

New State

File:States.png

2017-08-29T13:40:52Z

Janek:

States

File:Add new workflow.png

2017-08-29T13:39:52Z

Janek:

Add new Workflow

File:Workflows.png

2017-08-29T13:38:38Z

Janek:

Shows list of workflows.

File:Enabled component.png

2017-08-29T13:36:08Z

Janek:

Check if you have enabled com_workflow in extension manager