You are here

Home » API reference » Workbench Moderation 7

README.txt in Workbench Moderation 7

Same filename and directory in other branches
  1. 7.3 README.txt

README file for Workbench Moderation.

File

README.txt
View source 
  1. /**

  2.  * @file

  3.  * README file for Workbench Moderation.

  4.  */

  5. 

  6. Workbench Moderation

  7. Arbitrary moderation states and unpublished drafts for nodes

  8. 

  9. CONTENTS

  10. --------

  11. 

  12. 1.  Introduction

  13. 1.1  Concepts

  14. 1.1.1  Arbitrary publishing states

  15. 1.1.2  Node revision behavior

  16. 1.1.3  Moderation states and revisions

  17. 2.  Installation

  18. 2.1  Requirements

  19. 3.  Configuration

  20. 3.1  Configuring states

  21. 3.2  Configuring transitions

  22. 3.3  Checking permissions

  23. 3.3.1  Recommended permissions

  24. 4.  Using the module

  25. 5.  Troubleshooting

  26. 6.  Developer notes

  27. 6.1  Database schema

  28. 6.2  Views integration

  29. 7.  Feature roadmap

  30. 

  31. ----

  32. 1.  Introduction

  33. 

  34. Workbench Moderation 

  35. 

  36. ----

  37. 1.1  Concepts

  38. 

  39. Workbench Moderation adds arbitrary moderation states to Drupal core's

  40. "unpublished" and "published" node states, and affects the behavior of node

  41. revisions when nodes are published. Moderation states are tracked per-revision;

  42. rather than moderating nodes, Workbench Moderation moderates revisions.

  43. 

  44. ----

  45. 1.1.1  Arbitrary publishing states

  46. 

  47. In Drupal, nodes may be either unpublished or published. In typical

  48. configurations, unpublished nodes are accessible only to the user who created

  49. the node and to users with administrative privileges; published nodes are

  50. visible to any visitor. For simple workflows, this allows authors and editors to

  51. maintain drafts of content. However, when content needs to be seen by multiple

  52. people before it is published--for example, when a site has an editorial or

  53. moderation workflow--there are limited ways to keep track of nodes' status.

  54. Workbench Moderation provides moderation states, so that unpublished content may

  55. be reviewed and approved before it gets published.

  56. 

  57. ----

  58. 1.1.2  Node revision behavior

  59. 

  60. Workbench Moderation affects the behavior of Drupal’s node revisions. When

  61. revisions are enabled for a particular node type, editing a node creates a new

  62. revision. This lets users see how a node has changed over time and revert

  63. unwanted or accidental edits. Workbench Moderation maintains this revision

  64. behavior: any time a node is edited, a new version is created.

  65. 

  66. When there are multiple versions of a node--it has been edited multiple times,

  67. and each round of editing has been saved in a revision--there is one "current"

  68. revision. The current revision will always be the revision displayed in the node

  69. editing form when a user goes to edit a piece of content.

  70. 

  71. In Drupal core, publishing a node makes the current revision visible to site

  72. visitors (in a typical configuration). Once a node is published, its current

  73. revision is always the published version. Workbench Moderation changes this; it

  74. allows you to use an older revision of a node as the published version, while

  75. continuing to edit a newer draft.

  76. 

  77. @see workbench_moderation-core_revisions.png

  78. @see workbench_moderation-wm_revisions.png

  79. 

  80. Internally, Workbench Moderation does this by managing the version of the node

  81. stored in the {node} table. Drupal core looks in this table for the "current

  82. revision" of a node. Drupal core equates the "current revision" of a node with

  83. both the editable revision and, if the node is published, the published

  84. revision. Workbench Moderation separates these two concepts; it stores the

  85. published revision of a node in the {node} table, but uses the latest revision

  86. in the {node_revision} table when the node is edited. Workbench Moderation's

  87. treatment of revisions is identical to that of Drupal core until a node is

  88. published.

  89. 

  90. ----

  91. 1.1.3  Moderation states and revisions

  92. 

  93. Workbench Moderation maintains moderation states for revisions, rather than for

  94. nodes. Since each revision may reflect a unique version of a node, the state may

  95. need to be revisited when a new revision is created. This also allows users to

  96. track the moderation history of a particular revision, right up through the

  97. point where it is published.

  98. 

  99. Revisions are a linear; revision history may not fork. This means that only the

  100. latest revision may be edited or moderated.

  101. 

  102. ----

  103. 2.  Installation

  104. 

  105. Install the module and enable it according to Drupal standards.

  106. 

  107. After installation, enable moderation on a content type by visiting its

  108. configuration page:

  109. 

  110.     Admin > Structure > Content Types > [edit Article]

  111. 

  112. In the tab block at the bottom of the form, select the "Publishing options" tab.

  113. In this tab under "Default Options", Workbench Moderation has added a checkbox,

  114. "Enable moderation of revisions". To enable moderation on this node type, check

  115. the boxes labeled "create new revision" (required) and "enable moderation of

  116. revisions", and then save the node type.

  117. 

  118. ----

  119. 2.1  Requirements

  120. 

  121. Workbench Moderation may be used independently of other modules in the Workbench

  122. suite, including the "Workbench" module. Unlike the "Workbench" module,

  123. Workbench Moderation does not depend on Views. However, Workbench Moderation

  124. does have Views integration, and it provides two useful views ("My Drafts" and

  125. "Needs Review") that appear in the Workbench. If you wish to use Workbench

  126. Moderation without Workbench, you may override or clone these views and place

  127. them where your users can find them.

  128. 

  129. Using the "Workbench" module with Workbench Moderation enables the display of

  130. moderation status information and a mini moderation form on node viewing pages.

  131. 

  132. ----

  133. 3.  Configuration

  134. 

  135. Workbench Moderation's configuration section is located at:

  136. 

  137.     Admin > Configuration > Workbench > Workbench Moderation

  138. 

  139. This administration section provides tabs to configure states, transitions, and

  140. to check whether your permissions are configured to enable full use of

  141. moderation features.

  142. 

  143. ----

  144. 3.1  Configuring states

  145. 

  146. Workbench Moderation provides three default moderation states: "Draft", "Needs

  147. Review", and "Published". The Draft and Published states are required. You can

  148. edit, add, and remove states at:

  149. 

  150.     Admin > Configuration > Workbench > Workbench Moderation > States

  151. 

  152. ----

  153. 3.2  Configuring transitions

  154. 

  155. Workbench Moderation also provides transitions between these three states. You

  156. can add and remove transitions at:

  157. 

  158.     Admin > Configuration > Workbench > Workbench Moderation > Transitions

  159. 

  160. ----

  161. 3.3  Checking permissions

  162. 

  163. In order to use moderation effectively, users need a complex set of permissions.

  164. If non-administrative users encounter access denied (403) errors or fail to see

  165. notifications about moderation states, the "Check permissions" tab can help you

  166. determine what permissions are missing. Visit:

  167. 

  168.     Admin > Configuration > Workbench > Workbench Moderation > Check Permissions

  169. 

  170. Select a Drupal role, an intended moderation task, and the relevant node types,

  171. and Workbench Moderation will give you a report of possible missing permissions.

  172. Permissions configuration depends heavily on your configuration, so the report

  173. may flag permissions as missing even when a particular role has enough access to

  174. perform a particular moderation task.

  175. 

  176. ----

  177. 3.3.1  Recommended permissions

  178. 

  179. For reference, these are the permission sets recommended by the "Check 

  180. Permissions" tab:

  181. 

  182.     Author:

  183.       Node:

  184.         access content

  185.         view own unpublished content

  186.         view revisions

  187.         create [content type] content

  188.         edit own [content type] content

  189.       Workbench Moderation:

  190.         view moderation messages

  191.         use workbench_moderation my drafts tab

  192.     

  193.     Editor:

  194.       Node:

  195.         access content

  196.         view revisions

  197.         revert revisions

  198.         edit any [content type] content

  199.       Workbench:

  200.         view all unpublished content

  201.       Workbench Moderation:

  202.         view moderation messages

  203.         view moderation history

  204.         use workbench_moderation my drafts tab

  205.         use workbench_moderation needs review tab

  206.     

  207.     Moderator:

  208.       Node:

  209.         access content

  210.         view revisions

  211.         edit any [content type] content

  212.       Workbench:

  213.         view all unpublished content

  214.       Workbench Moderation:

  215.         view moderation messages

  216.         view moderation history

  217.         use workbench_moderation needs review tab

  218.     Publisher

  219.       Node:

  220.         access content

  221.         view revisions

  222.         revert revisions

  223.         edit any [content type] content

  224.       Workbench:

  225.         view all unpublished content

  226.       Workbench Moderation:

  227.         view moderation messages

  228.         view moderation history

  229.         use workbench_moderation needs review tab

  230.         unpublish live revision

  231. 

  232. ----

  233. 4.  Using the module

  234. 

  235. Once the module is installed and moderation is enabled for one or more node

  236. types, users with permission may:

  237. 

  238. * Use the "Moderate" node tab to view moderation history and navigate versions.

  239. 

  240. When the Workbench module is enabled, users with permission may also:

  241. 

  242. * See messages about moderation state when visiting a moderated node.

  243. * Moderate content from the "View Draft" page.

  244. 

  245. ----

  246. 5.  Troubleshooting

  247. 

  248. * If users get access denied (403) errors when creating, editing, moderating, or

  249.   reverting moderated content, the "Check Permissions" tab in Workbench

  250.   Moderation's administration section can help diagnose what access is missing.

  251.   See heading 3.3 in this README.

  252. 

  253. * If you're building Views of moderation records, keep in mind that for a single

  254.   node, there will be multiple revisions, and for each revision, there may be

  255.   multiple moderation records. This means it will be very easy to end up with a

  256.   View that shows particular nodes or revisions more than once. Try adding the

  257.   "Workbench Moderation: Current" filter, or using Views' "Use grouping" option

  258.   (under the "Advanced settings" heading on the view editing page).

  259. 

  260. ----

  261. 6.  Developer notes

  262. 

  263. Workbench Moderation does not have a mature API.

  264. 

  265. ----

  266. 6.1  Database schema

  267. 

  268. Workbench Moderation uses three tables to track content moderation states.

  269. 

  270. * workbench_moderation_states

  271.   Stores administrator-configured moderation states.

  272. 

  273. * workbench_moderation_transitions

  274.   Stores administrator-configured transitions between moderation states. These

  275.   are simply pairs of moderation states: a "from" state and a "to" state.

  276. 

  277. * workbench_moderation_node_history

  278.   Stores individual moderation records related to each node revision. Each

  279.   record stores the nid and vid of a node, the original moderation state and the

  280.   new moderation state, the uid of the user who did the moderation, and a

  281.   timestamp.

  282. 

  283. ----

  284. 6.2  Views integration

  285. 

  286. Workbench Moderation provides Views integration so that site builders may

  287. include moderation information in node and node revision views.

  288. 

  289. * Filters, fields, sorts, and arguments are provided for moderation record data.

  290. 

  291. * A relationship is provided from moderation records to the user who made the

  292.   moderation change.

  293. 

  294. * A "content type is moderated" filter is provided on for nodes to help in

  295.   creating lists of only moderated content.

  296. 

  297. ----

  298. 7.  Feature roadmap

  299. 

  300. * Allow configuration of 'Draft' and 'Published' states.