Role Scoper plugin for WordPress

Usage Guide

by Kevin Behrens

http://agapetry.net/

http://agapetry.net/forum/

original document: 10 July 2008

revision: 3 November 2008

This document contains Topical commentary to orient an experienced WordPress blog administrator to the new permission controls offered by Role Scoper. Those uninterested in this discussion may skip to step-by-step instructions in the How-to Guide. This document is a work in progress which will be expanded and updated periodically.

For a general overview of Role Scoper’s motives and screen shots which may provide a helpful accompaniment, see the following online document: http://agapetry.net/news/introducing-role-scoper/

Contents

Section 1: Glossary and Commentary

Section 2: How-to Guide

Section 3: Customizations and Extensions

Installation

1. Upload / extract the zip to your web server such that the directory wp-content/plugins/role-scoper/ contains role-scoper.php, etc. 
   
   If your site has CPanel, just copy the zip into wp-content/plugins and extract.  Otherwise, extract the zip on your local computer and use FTP to create the new server directory and upload all files.
2. Log into WordPress (yoursite/wp-admin/) as an Administrator
3. Click on Plugins; activate Role Scoper

Once the plugin is activated, this Usage Guide should prove helpful.  Your steps from here depend on what you're trying to accomplish.  If this document and the Role Scoper interface don't point the way, you can always place a request for help in the support forum.

Section 1: Glossary and Commentary

Description

Role Scoper is a comprehensive drop-in replacement for capability enforcement and administration in WordPress. Assign reading, editing or administration roles to users or groups on a page-specific, category-specific or other content-specific basis.

Menu Access

After activating Role Scoper, you will find two new utility links on the right next to “Settings”: Roles and Groups. Most of Role Scoper’s settings are accessed through the “Roles” or “Groups” links.

“Groups” pertains to the definition of User Groups, and to role assignments for those groups (see “User Groups” below. The role assignment portion of the “Groups” tab is therefore a mirror of corresponding role assignment links on the “Roles” tab which pertain to individual users.

Those wishing only to assign or restrict access to an individual post or page may go straight to the WordPress post/page editor interface and look for the new “Readers”, “Contributors” and “Editors” tabs.

Scope: Blog, Section or Object

By default, Wordpress roles specify capabilities that a user has blog-wide. Pages and Posts can be marked private. If a user’s role includes the read_private_pages capability, all private pages are readable to them. Otherwise none are. The same is true for editing or publishing capabilities - a user can edit all posts made by other users, or none of them.

Role Scoper allows you to assign roles in any of three scopes: blog-wide (Blog scope), category-wide (Section scope) or for a specific post/page (Object scope). To reduce confusions, the generic names “section” and "object" are not generally used in the User Interface or in this documentation.  However, a section can consist of some custom taxonomy other than “category”, and may or may not use the WP term_taxonomy schema.  Likewise, Role Scoper can be configured to control permissions for "objects" other than posts and pages.  In the future, other plugins may use Role Scoper API to define sections such as forums, calendars or galleries.

When some read or edit operation is requested, Role Scoper filters the request and grants permission if the user has a qualifying role in any scope:

Blog scope or Section scope or Object scope.

Category Role Assignment

Category roles, as an instance of “Section Roles”, are assigned on the WP Admin -> Roles -> Category page.  Users and/or Groups may receive a Category Role assignment.  Each Category has a separate set of role checkboxes. Note that whether assigning or removing role assignments, you must check all the users/groups and all the roles being modified. The dropdown list next to the “Update” button determine what effect the update has.

When assigning Category Roles, you can choose whether to assign to the selected categories only, to the selected and all subcategories (present or future), or to subcategories only.

Post / Page Role Assignment

Post Roles and Page Roles are instances of “Object Roles”. They may be assigned via new tabs on the WP post / page edit interface - “Readers”, “Editors”, etc. When selecting users or groups for page role assignment, note that the normal checkboxes assign the role to current page, whereas the braced {[]} checkbox assigns the role to all subpages (present or future).

Category Restrictions (previously known as "Exclusive Section Roles")

A role assignment grants a user or group capabilities which they may not already have. When you assign several users the Post Editor role in “Category A”, you are allowing them to edit “Category A” posts on the basis of Category Role. Some may already qualify based on their general (blog-wide) WordPress role, others may not.

However, one user’s role assignment does not reduce access for any other users. To deny some users access to “Category A” even though their General Role qualifies, you must specify a Category Restriction. There is a separate setting for each Role in each Category. For Category A, if the Post Reader role is restricted, then users with a general Wordpress role of Post Reader (which includes anonymous users) cannot read Category A posts unless they have a Category Role or Post Role assignment. Users with a different general role which also contains the required capabilities will not be excluded.

Another way of describing Restrictions is that they allow you to selectively remove one or more qualifying clauses from the {General Role OR Category Role OR Post/Page Role} formula.

Some “Category Restriction” details to note:

• If a post is in “Category A” and “Category B”, a user will not be excluded unless both categories have the necessary role restrictions.
• With any role assignment, a user is considered to possess the assigned role and all roles it “contains”. The Author role contains the Contributor role if Author also has all of Contributor’s capabilities. The contained role is a subset of the containing role.
• For a user to be excluded, restrictions must be set for their General Role and all the roles it contains. For example, if a user’s Author role has been marked Restricted for “Category A”, they are not excluded from reading posts unless the roles “contained” in Author (Post Contributor and Post Reader) are also restricted. The actual role requirement in that case is Post Reader.
• Blogs which have used Role Manager to customize WP roles should be aware of the following: If Role Scoper is configured to use “RS” role types, Category and Post/Page Restrictions are applied on the basis of which “RS” roles a user’s WP role contains. This statement will only be decipherable in conjunction with the documentation on “role types”. It should be a non-issue for WP installations which have removed any caps from the default WP role definitions.

Restricted Post / Page Roles

As stated above, categories can be configured such that a user’s General Role is ignored - and a qualifying Category Role or Post/Page role assignment is required. Likewise, individual posts and pages can be configured such that General Role and Category Roles are ignored. These Post/Page Restrictions can be used to narrow read or edit access.

Limiting read access to a fixed set of users is a three-step operation in the WordPress post edit interface.

1. select those users in the “Readers” tab
2. check the “Restrict” checkbox
3. save the post

User Groups

Any General Role, Category Role or Post/Page role assignment can be applied to individual users or to a group of users. If your user base includes subsets of user who commonly get the same role assignments, consider defining those users as members of a Group.

WP Role Metagroups

In addition to custom-defined user groups, you may find it convenient to assign some Category Role or Post/Page Role to all users who have a certain WordPress-defined Role. You will find these metagroups (labeled as [WP Editor], [WP Author], etc.) alongside the custom-defined groups in role assignment interfaces.

“Private” versus “Restricted”

Wordpress defines “private” posts and pages as those which require a corresponding read_private capability, usually possessed only by Administrators, Editors, and by the content author. Most significantly, the content is hidden from anonymous users.

For the purpose of limiting read access, Role Scoper Restrictions can be used as an equivalent. If a post’s categories, or the post itself, Restrict the Post Reader role, the post is effectively private regardless of the WP private status. Likewise, Category Role or Post/Page Role assignments can enable access to a “private” post or page as long as the assigned role includes the corresponding read_private capability.

Despite the potential equivalence stated above, setting sensitive posts or pages to WP “private” is still the recommended approach. This will ensure that if Role Scoper is accidentally disabled, content is not revealed inappropriately. In the future, Role Scoper may automatically set posts/pages to private when a corresponding Role Scoper setting is made. Due to technical difficulties, you must currently achieve that extra safeguard manually.

Role Type

In Wordpress jargon, Roles contain Capabilities. Wordpress comes with a default set of Roles - Administrator, Editor, Author, Contributor and Subscriber. Those default role definitions are sensible and sufficient for most WP installations. The adventuresome can use the Role Manager plugin to add or remove capabilities from any role, perhaps to account for new capabilities defined by some other plugin. The intent is that for any user, there is one role definition which comprehensively describes every capability the user has, for any object type which exists within the blog. Every user has one general role.

By default, Role Scoper takes a different approach - the “RS” role type. Each object type has a different set of role definitions. So, for posts, there are “Post Reader, Private Post Reader, Post Author, Post Editor” role definitions. Likewise for pages and, potentially, for other plugin-defined object types which choose to support RS role definitions.

The upshot of this is that instead of defining a modified “Author” role which also includes the “edit_pages” capability, you just assign the “Page Author” role where desired. Instead of just assigning one comprehensive WP-defined role, you can select a pertinent RS-defined role separately for each object type.

If for any reason you must apply WP-defined roles as Category Roles or Post/Page Roles, simply go to WP Admin > Roles > Roles and change the Role Type dropdown to “WP”.

Limiting the Page Parent Selection

Another happy side effect of “RS” role types is the ease with which plugins can enable users to assign newly-defined capabilities. Role Scoper introduces the “create_child_pages” capability. This capability enables a user to select the corresponding page as “Page Parent”. Otherwise a page is unavailable as parent unless the user can edit it. The new RS-defined “Page Associate” contains “create_child_pages”, making it one step up from Page Reader. This useful role distinction would have been difficult to provide if each blog administrator was required to manually merge the capability into existing WP roles.

Note that Role Scoper will not allow a page to be published with a “Main Page” parent unless the user has the blog-wide edit_published_ pages capability. Although WordPress doesn't provide a means to remove “Main Page” from the dropdown, attempts by unqualified users to publish a new page with “Main Page” parent will result in “draft” status. Attempts to modify an existing page from non-Main to Main (or from Main to non-Main) Page Parent will revert the page back to the previous stored Page Parent.

Section 2: How-to Guide

(note: this section is a work in progress which does not yet fully address Editing Roles)

Defining a custom User Group (not required for direct user role assignment)

1. Go to WP Admin -> Groups
2. Click the “Add New” scroll link
3. Enter a group name and description
4. Select checkboxes for Group Members
5. Optionally, select Group Administrators (WP admin can always manage group)
6. Click the Create button

Groups created in this manner will be available for role assignment in the following procedures.

Role Scoper can be configured to hide or reveal posts regardless of any WP-defined “private” status. The procedures below are sufficient to set post visibility. However, there are three reasons you might still choose to set the WP “private” status:

• Setting the WP “private” status will enable more flexibility in controlling read access per category
• A post that has the WP “private” status will continue to be hidden if Role Scoper is accidentally uninstalled.
• Setting the WP “private” status will make the posts easier to administer, taking advantage of “Manage Posts” filtering provided by the WP core

The following procedures apply regardless of whether you check the “keep this post private” box:

Restricting Read Access to an Individual Post/Page

1. Enter the WordPress Write Post / Edit Post interface
2. Scroll down to the “Readers” tab (under “Advanced Options”) and expand it
3. Check the “Restrict” checkbox at the bottom of the tab
4. Save the post

The post will now be hidden from WP Subscribers who are not selected in this “Readers” tab.  If the post must also be hidden from WP Contributors, set the “Restrict” checkbox in the “Contributors” tab.  To hide it from WP Authors and Editors, set the “Restrict” checkbox in the “Editors” tab.  In Role Scoper lingo, the post now Restricts the checked roles.

Granting Read Access to an Individual Post/Page

1. Decide whether you want to manage permissions user-by-user, for Wordpress role “groups”, and/or for custom-defined User Groups.  If custom user groups are desired, define those first (see above).
2. Enter the WordPress Write Post / Edit Post interface
3. Scroll down to the “Readers” tab (under “Advanced Options”) and expand it
4. Select the checkbox of any User and/or Group who should have read access
5. Save the Post

If it's convenient to manage each hidden post/page with the above procedures, that's all you need to know.  If access control by category is desirable, read on.

Restricting Read Access by Post Category

1. Go to WP Admin -> Restrictions -> Category
2. Scroll down to your category of interest, perhaps using the scroll link at top
3. Select the “Private Post Reader” checkbox to restrict read access to private posts by anonymous users and WP Subscribers
4. Optionally, select the “Post Reader” checkbox to restrict read access to non-private posts by anonymous users and WP Subscribers (if the WP Subscriber role has not been modified to include read_private_posts)
5. Scroll to the top
6. Note that the adjacent dropdown indicates that the Update action will cause blog-wide assignment of the selected roles to be ignored for posts in the selected category.
7. Click the Update button

Granting Read Access by Post Category

1. Go to WP Admin -> Roles -> Category
   
2. Scroll down to your category of interest, perhaps using the scroll link at top
3. Select the roles you would like to assign
4. Scroll to the top
5. Select users and/or groups to assign selected roles
6. Note that the adjacent dropdown indicates that the Update action will cause the selected roles to be assigned for posts in the selected section. 
7. If you want the same role to also be assigned for all current and future subcategories, change the dropdown to “assign for selected and sub-categories”.
8. Click the Update button

Note that if a Post Restriction is not set for Readers, read access to it will be granted if:

• the user has a qualifying Category Role in any post category

• any of the post's categories do not ignore the user's qualifying blog-wide general role (or another qualifying role it contains)

So you cannot hide a post just by assigning it to an additional “hidden” category.  If individual posts don't restrict the Readers role, they will be readable if any of their categories are readable to the user.   If your categorization and post restriction goals demand the “readable cat + hidden cat = hidden post” formula, you'll be frustrated with this plugin.  But here are some suggestions for making the Role Scoper model work with your existing categories:

• As mentioned above, different role requirements and assignments can be made for “private” and “non-private” posts in the same category.
• Depending on how your theme displays categories, you could move some “Category A” posts into a new subcategory ( Category A / Category A*), and remove them from “Category A”.  Then set Category Restrictions and Category Role assignments for Category A*.

Restrict Posting / Editing by Category

There are two pieces: granting access and restricting access, and two basic ways to achieve the desired access and restrictions:

• Start with user(s) who have too little access and elevate them
• Start with user(s) who have too much access and restrict them

You can also use some combination of the two.  Where possible simplify your life by setting your users as WordPress subscribers, then following the first Role Scoper configuration procedure below.  This also provides the greatest security, since those users will default to zero editing ability if Role Scoper is accidentally deactivated or otherwise disabled.

Enabling a Subscriber to Post in specific Categor(ies)

1. Set UserA to WordPress role of Subscriber
2. Assign a Category Role of Post Author to UserA for the desired category (WP Admin > Roles > Category)

If some users need to retain a higher WordPress role but still be limited in posting categories, you will also need to define that extra restriction as follows:

Restricting Posting Categor(ies) for Contributor/Author/Editor

1. Go to the Category Restrictions admin page 
   (WP Admin > Restrictions > Category)
2. In the "DEFAULTS" table, check the boxes for “Post Contributor” and “Post Author”.  Also “Post Editor” if you want to restrict WP editors.
3. Confirm the dropdowns next to Update button say “Restrict selected roles" and "for selected categories"
4. Click Update

Now Contributor and Authors (and editors, if you restricted that role) will not be able to post or edit in any category unless you assign them a Category Role for it, as explained for UserA above.  Note that the "DEFAULTS" setting applies the restriction to all existing and future categories (unless one is manually unrestricted).  To restrict fewer categories, select desired restrictions for each category instead.

Enabling a User to Edit Specific Page(s), and Nothing Else:

1. Give them a WordPress role of Subscriber
2. Manage > Pages > Edit their page
3. Expand the "Editors" tab under "Advanced Options"
4. Check the non-braced checkbox to the left of your user's name (if subpages will be created, also check the braced checkbox {[]}, which assigns the role for all current or future subpages)
5. Save the Page

Note that if you also assign this user a Role Scoper General Role of Page Author, they will be able to create subpages off their member page, but not off any other pages:

1. Go to WP Admin > Roles > General
2.  Select your user name(s)
3.  Select the Page Author role
4.  Click Update

OR, if you want all subscribers to have this ability:

1. Go to WP Admin > Roles > General
2. Select [WP Subscriber]
3. Select the Page Author role
4. Click Update

Section 3: Customizations and Extensions

(note: this section will be expanded in future revisions)

Hidden Content Teaser

By default, Role Scoper hides content for which users lack a sufficient role assignment. You can also apply a teaser by activating that option in the Role Scoper options page at WP Admin > Roles > Roles.

Other Role Scoper Options

Other options on the Roles > Options page pertain primarily to customizations of the Role Scoper for future plugin-defined data sources. Most users can safely leave the default settings. The settings available there do contains descriptive captions.

Template Functions

To support customized markup of restricted and/or currently hidden posts, Role Scoper provides the following template functions for use in themes:

 is_restricted_rs( );

 is_teaser_rs( );

note: If calling these functions outside the WP loop, you should pass post ID as the first function argument. Otherwise just call as stated above.

Plugin API

Other plugins may define their own data sources, taxonomies (WP term_taxonomy or custom tables), capabilities and roles. See defaults_rs.php and role-scoper_main.php for example hook usage. Details will be provided in later versions of this document.

A current version of this document is available online at

http://agapetry.net/downloads/RoleScoper_UsageGuide.htm