Apostrophe 1.5: legacy documentation

Still using Apostrophe 1.5? Check out Apostrophe 2 for your future projects.

Workflow Plugin

apostropheWorkflowPlugin

Apostrophe's philosophy is to help everyone contribute to websites more easily. However, some projects do have a firm requirement that content be approved by appropriate persons before it goes live. The Apostrophe workflow plugin is a straightforward solution to that problem.

Rules for Editing Content

The workflow plugin ensures that all slot edits must be approved by someone with the admin credential before they go live.

Those with edit privileges who do not have the admin credential can edit content, but their changes are not immediately live, and they cannot make them go live on their own.

Everyone with editing privileges sees a new "workflow toolbar." The workflow toolbar indicates whether you are in draft mode or public mode. In draft mode, you can edit content, but it does not immediately become visible to the public. In public mode, you can see what is currently visible to the public.

Those with admin privileges will see an "Apply Changes" button in the workflow toolbar. When this button is pressed, all of the changed content currently visible in the browser is synced to the published version of the website. Those with mere editing privileges won't see this button, so their content cannot become publicly visible until an appropriate person approves it.

This is implemented using a separate draft_version column in the a_area table, complementing the latest_version column. latest_version is seen by all logged-out users and in "applied" mode. The greater of draft_version and latest_version (or whichever is not null) is seen in "draft" mode.

Note that these rules apply to all editing of Apostrophe slots and areas that are visible in the browser. The content of a blog post or an event still must be approved.

Styling the workflow toolbar

The workflow toolbar has a class of "a-workflow-toolbar" and wraps around an unordered list containing four list items :

* Draft button: a-workflow-toolbar-draft * Public button: a-workflow-toolbar-applied * Apply button: a-workflow-toolbar-apply * Help text: a-workflow-toolbar-alert

A class of "a-workflow-current" is applied to the list item that corresponds to the current workflow mode. For example, a-workflow-current is applied to the a-workflow-toolbar-draft <li> when in draft mode.

Additionally, the <ul> contained in "a-workflow-toolbar" is given a class of "draft" when in draft mode, and "applied" when in applied mode.

Additional Workflow Rules

In addition to the workflow toolbar for editing content, certain additional rules are enforced to ensure that no one without admin privileges is able to publish things without approval:

* If a person without admin privileges creates a blog post or event, it is initially in the draft state. * A person without admin privileges cannot change a blog post or event to the published state. * If a person without admin privileges creates a page, it is initially in the unpublished state. * A person without admin privileges cannot switch a page to the published state.

Not Covered

The workflow plugin is not intended to address workflow issues for non-Apostrophe content, such as your custom admin generator modules.

Installation and Configuration

We recommend adding this line to your svn:externals for your plugins folder:

apostropheWorkflowPlugin http://svn.apostrophenow.org/plugins/apostropheWorkflowPlugin/trunk

Once you have committed and updated your project, you'll have the plugin in your plugins folder.

To enable the plugin, edit your ProjectConfiguration.class.php file and add the plugin to the end of the list of enabled plugins. It must appear after apostrophePlugin in the list.

Then be sure to run the apostrophe:migrate task. In development, you do it like this:

./symfony apostrophe:migrate

For staging and production, if you are using our apostrophe:deploy task, apostrophe:migrate will be run automatically. If you are not using apostrophe:deploy, you can run apostrophe:migrate on the relevant servers manually, as long as you specify an environment:

./symfony apostrophe:migrate --env=prod

At this point you are ready to go. For existing projects we strongly recommend familiarizing your users with the new workflow in a staging environment before you enforce it in production.

Overriding the Labels

The labels of the buttons are fed through Symfony's internationalization mechanism, in the aWorkflow namespace, so that you can translate them if desired.

In addition, you can override the labels in app.yml, like this:

all:
  aWorkflow:
    labels:
      confirmApply: "Are you sure you want to apply these changes?"
      applyChanges: "Apply Changes"
      public: "Public"
      draft: "Draft"
      draftBanner: "You are currently in draft mode. Changes you make will not be public until applied."
      publicBanner: "You are currently in public mode. This is the website as it exists in its published state."

Any labels you do not override are left unchanged.