Location: PHPKode > scripts > Role Scoper > role-scoper/RoleScoper_UsageGuide.htm
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Role Scoper Usage Guide</title>

<style type="text/css">
ul li {
list-style-type: disc;
margin-bottom: 0.7em;
ol li {
margin-bottom: 0.7em;
ul {
margin-right: 1em;
ol {
margin-right: 1em;
.step_list {
border: 1px solid black;
margin-left: 2em;
width: 32em;
padding-right: 0.5em;
color: white;
background-color: #008c00;
font-family: Verdana,Helvetica,sans-serif;
margin-top: 0.1em;
font-weight: bold;
font-size: small;
padding-top: 0.2em;
padding-bottom: 0.2em;
h1 {
font-family: Arial,Helvetica,sans-serif;
margin-top: 2em;
h2 {
font-family: Arial,Helvetica,sans-serif;
h3 {
font-family: Arial,Helvetica,sans-serif;
margin-bottom: 0.05em;
margin-top: 1.75em;
.steplist li {
color: white;
p {
margin-top: 0.3em;
h4 {
font-family: Verdana,Helvetica,sans-serif;
margin-bottom: 0.2em;
h5 {
font-family: "Times New Roman",Times,serif;
font-weight: bold;
margin-bottom: 0.2em;
font-size: medium;
<div id="wrap">
<h1 align="center">Role Scoper
plugin for WordPress</h1>
<h1 align="center"><span style="font-size: 20pt; font-family: Arial;">Usage Guide</span></h1>
<h3 style="margin-bottom: 0.2in; text-align: center; font-family: Arial;" align="center"><font size="-1">by Kevin Behrens</font></h3>
<p style="text-align: center;" align="center"><a href="http://agapetry.net/"><span style="font-family: &quot;Courier New&quot;;">http://agapetry.net/</span></a></p>
<p style="text-align: center;" align="center"><a href="http://agapetry.net/forum/"><span style="font-family: &quot;Courier New&quot;;">http://agapetry.net/forum/</span></a></p>
<p style="margin-bottom: 0.2in; text-align: center; font-family: Arial;" align="center"><font size="-1">original
document: 10
July 2008</font></p>
<p style="margin-bottom: 0.2in; text-align: center; font-family: Arial;" align="center"><font size="-1">revision: 3 November 2008</font></p>

contains Topical commentary to orient an experienced WordPress blog
administrator to the new permission controls offered by Role Scoper.
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.</p>
a general
overview of Role Scoper&#8217;s motives and screen shots which may provide a
accompaniment, see the following online document: <a href="http://agapetry.net/news/introducing-role-scoper/">http://agapetry.net/news/introducing-role-scoper/</a></p>
1: <a href="#Section1%7Cregion">Glossary
and Commentary</a></p>
2: <a href="#Section2%7Cregion">How-to
3: <a href="#Section3%7Cregion">Customizations
and Extensions</a></p>
<p><a href="#Section3%7Cregion"><span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-weight: bold;"></span></span></a></p>
<ol class="step_list">
<li>Upload / extract the zip to your web server such that the
directory <b>wp-content/plugins/role-scoper/ </b>contains
role-scoper.php, etc.&nbsp; <br>
<span style="font-weight: normal;">If your site has
CPanel, just copy the
into wp-content/plugins and extract.&nbsp; Otherwise, extract the
zip on
your local computer and use FTP to create the new server directory and
upload all files.</span></li>
<li>Log into WordPress (yoursite/wp-admin/) as an Administrator</li>
<li>Click on Plugins; activate Role Scoper</li>
Once the plugin is activated, this Usage Guide should prove
helpful.&nbsp; Your steps from here depend on what you're trying to
accomplish. &nbsp;If this document and the Role Scoper interface
point the way, you can always place a request for help in the <a href="http://agapetry.net/forum/">support forum</a>.<br>
<a name="Section1|region"></a>
<h1 align="center">Section
Glossary and Commentary</h1>
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
activating Role Scoper, you will find two new utility links on the
right next
to &#8220;Settings&#8221;: Roles and Groups. Most of Role Scoper&#8217;s settings are
through the &#8220;Roles&#8221; or &#8220;Groups&#8221; links.</p>
pertains to the definition of User Groups, and to role assignments for
groups (see &#8220;User Groups&#8221; below. The role assignment portion of the
tab is therefore a mirror of corresponding role assignment links on the
tab which pertain to individual users.
only to assign or restrict access to an individual post or page may go
to the WordPress post/page editor interface and look for the new
&#8220;Contributors&#8221; and &#8220;Editors&#8221; tabs.</p>
<a name="general_roles"></a>
Blog, Section or Object</h3>
Wordpress roles specify capabilities that a user has blog-wide. Pages
and Posts
can be marked private. If a user&#8217;s role includes the read_private_pages
capability, <b>all</b> private pages are readable to them.
Otherwise <b>none</b>
are. The same is true for editing or publishing capabilities - a user
can edit <b>all</b>
posts made by other users, or <b>none </b>of them.</p>
allows you to assign roles in any of three scopes: blog-wide (Blog
category-wide (Section scope) or for a specific post/page (Object
scope). To reduce confusions, the
generic names &#8220;section&#8221; and "object" are not generally used in the User
Interface or in this documentation. &nbsp;However, a
section can consist of some custom taxonomy other than &#8220;category&#8221;, and
may or may not use the WP term_taxonomy schema. &nbsp;Likewise, Role
Scoper can be configured to control permissions for "objects" other
than posts and pages. &nbsp;In the future, other
plugins may use Role Scoper API to define sections
such as
forums, calendars or galleries.</p>
some read
or edit operation is requested, Role Scoper filters the request and
permission if the user has a qualifying role in any scope:</p>
<p style="text-align: center;" align="center"><span style="color: blue;">Blog
scope</span> <b>or</b>
<span style="color: blue;">Section
scope</span> <b>or</b> <span style="color: blue;">Object
<a name="roles~category"></a>
<h3>Category&nbsp;Role Assignment</h3>
roles, as an instance of &#8220;Section Roles&#8221;, are assigned on the WP Admin
Roles -&gt; Category page. &nbsp;Users and/or Groups may
receive a Category Role assignment.&nbsp;
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
modified. The
dropdown list next to the &#8220;Update&#8221; button determine what effect the
update has.</p>
assigning Category Roles, you can choose whether to assign to the selected
only, to the selected and all subcategories (present or future), or to
subcategories only.</p>
<a name="roles~page"></a>
<a name="post"></a>
<a name="page"></a>
<h3>Post / Page Role Assignment</h3>
Roles and
Page Roles are instances of &#8220;Object Roles&#8221;. They may be assigned via
new tabs
on the WP post / page edit interface - &#8220;Readers&#8221;, &#8220;Editors&#8221;, etc. When
selecting users or groups for page role assignment, note that the
checkboxes assign the role to current page, whereas the braced {[]}
assigns the role to all subpages (present or future).</p>
<a name="restrictions~category"></a>
<h3>Category Restrictions <small><small>(previously
known as "Exclusive Section
assignment <b>grants </b>a user or group capabilities
which they may not
already have. When you assign several users the Post Editor role in
A&#8221;, you are allowing them to edit &#8220;Category A&#8221; posts on the basis
of&nbsp;Category Role. Some may already qualify based on their general
(blog-wide) WordPress role,
others may not.</p>
user&#8217;s role assignment</b> <b>does not reduce access</b>
for any other users.
To deny some users access to &#8220;Category A&#8221; even though their General Role
qualifies, you must specify a<b>&nbsp;Category Restriction</b>.
There is a
separate setting for each Role in each Category. For Category A, if the
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.</p>
way of
describing&nbsp;Restrictions is that they allow you to selectively
one or more qualifying clauses from the {General Role <b>OR</b> Category
Role <b>OR</b> Post/Page
Role} formula.</p>
&#8220;Category Restriction&#8221; details to note:</b></h5>
<li>If a
post is in &#8220;Category A&#8221; and &#8220;Category B&#8221;, a
user will not be excluded unless both categories have the necessary role restrictions.</li>
any role assignment, a user is considered
to possess the assigned role <b>and</b> all roles it
&#8220;contains&#8221;. The Author
role contains the Contributor role if Author also has all of
capabilities. The contained role is a subset of the containing role.</li>
<li>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&#8217;s&nbsp;Author role has been marked Restricted for &#8220;Category
A&#8221;, they
are not excluded from reading posts unless the roles &#8220;contained&#8221; in
Author (Post
Contributor and Post Reader) are also restricted. The actual role requirement in that case is Post Reader.</li>
which have used Role Manager to customize
WP roles should be aware of the following: If Role Scoper is configured
to use
&#8220;RS&#8221; role types, Category and Post/Page Restrictions are
applied on
the basis of which &#8220;RS&#8221; roles a user&#8217;s WP role contains. This statement will only
decipherable in conjunction with the documentation on &#8220;role types&#8221;. It
be a non-issue for WP installations which have removed any caps from
default WP role definitions.</li>
<h3>Restricted Post / Page Roles</h3>
above, categories can be configured such that a user&#8217;s General Role is
ignored -
and a qualifying Category Role or Post/Page role assignment is required.
individual posts and pages can be configured such that General Role <b>and</b> Category Roles are ignored. These Post/Page Restrictions can be
used to
narrow read or edit access.</p>
access to a fixed set of users is a three-step operation in the
WordPress post
edit interface.</p>
<li>select those users
in the &#8220;Readers&#8221; tab</li>
<li>check the
&#8220;Restrict&#8221; checkbox</li>
<li>save the post</li>
<a name="groups"></a>
<p>Any General Role, Category Role or Post/Page role assignment can be applied to
users <b>or</b> 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.</p>
Role Metagroups</h3>
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
custom-defined groups in role assignment interfaces. </p>
<h3>&#8220;Private&#8221; versus
defines &#8220;private&#8221; posts and pages as those which require a
read_private capability, usually possessed only by Administrators,
Editors, and
by the content author. Most significantly, the content is hidden from
purpose of limiting read access, Role Scoper&nbsp;Restrictions can
be used
as an equivalent. If a post&#8217;s categories, or the post itself, Restrict
the&nbsp;Post Reader role, the post is effectively private regardless
of the
private status. Likewise, Category Role or Post/Page Role assignments
access to a &#8220;private&#8221; post or page as long as the assigned role
includes the
corresponding read_private capability.</p>
potential equivalence stated above, setting sensitive posts or pages to
&#8220;private&#8221; is still the recommended approach. This will ensure that if
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.</p>
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
from any role, perhaps to account for new capabilities defined by some
plugin. The intent is that for any user, there is one role definition
comprehensively describes every capability the user has, for any object
which exists within the blog. Every user has one general role.</p>
Role Scoper takes a different approach - the &#8220;RS&#8221; role type. Each
object type
has a different set of role definitions. So, for posts, there are &#8220;Post
Private Post Reader, Post Author, Post Editor&#8221; role definitions.
Likewise for
pages and, potentially, for other plugin-defined object types which
choose to
support RS role definitions. </p>
upshot of
this is that instead of defining a modified &#8220;Author&#8221; role which also
the &#8220;edit_pages&#8221; capability, you just assign the &#8220;Page Author&#8221; role
desired. Instead of just assigning one comprehensive WP-defined role,
you can
select a pertinent RS-defined role separately for each object type.</p>
for any
reason you must apply WP-defined roles as Category Roles or Post/Page
Roles, simply
go to WP Admin &gt; Roles &gt; Roles and change the Role Type
dropdown to &#8220;WP&#8221;.
the Page Parent Selection</h3>
side effect of &#8220;RS&#8221; role types is the ease with which plugins can
enable users
to assign newly-defined capabilities. Role Scoper introduces the
&#8220;create_child_pages&#8221; capability. This capability enables a user to
select the
corresponding page as &#8220;Page Parent&#8221;. Otherwise a page is unavailable as
unless the user can edit it. The new RS-defined &#8220;Page Associate&#8221;
&#8220;create_child_pages&#8221;, 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.</p>
that Role
Scoper will not allow a page to be published with a &#8220;Main Page&#8221; parent
the user has the blog-wide edit_published_ pages capability. Although
doesn't provide a means to remove &#8220;Main Page&#8221; from the dropdown,
attempts by
unqualified users to publish a new page with &#8220;Main Page&#8221; parent will
result in
&#8220;draft&#8221; status. Attempts to modify an existing page from non-Main to
(or from Main to non-Main) Page
Parent will revert the
page back to the previous stored Page Parent.<span style="font-family: Arial,Helvetica,sans-serif;"><span style="font-weight: bold;"></span></span></p>
<a name="Section2|region"></a>
<h1 align="center">Section
How-to Guide</h1>
<p align="center">(note:
this section is a
work in progress which does not yet fully address&nbsp;Editing
<h4>Defining a custom User Group <font size="-1">(not
required for direct user role assignment)</font></h4>
<ol class="step_list">
to WP Admin
-&gt; Groups</li>
the &#8220;Add New&#8221;
scroll link</li>
a group name
and description</li>
for Group Members</li>
Group Administrators
(WP admin can always manage group)</li>
the Create
created in this manner will be available for role assignment in the
Scoper can be configured to hide or reveal posts regardless of any
&#8220;private&#8221; status. The procedures below are sufficient to set post
However, there are three reasons you might still choose to set the WP
the WP &#8220;private&#8221; status will enable more flexibility in controlling
read access
per category</li>
post that has the WP &#8220;private&#8221; status will continue to be hidden if
Role Scoper
is accidentally uninstalled.</li>
the WP &#8220;private&#8221; status will make the posts easier to administer,
advantage of &#8220;Manage Posts&#8221; filtering provided by the WP core</li>
following procedures apply regardless of whether you check the &#8220;keep
this post
private&#8221; box:</p>
Read Access to an Individual Post/Page</b></h4>
<ol class="step_list">
the WordPress
Write Post / Edit
Post interface</li>
down to the
&#8220;Readers&#8221; tab (under
&#8220;Advanced Options&#8221;) and expand it</li>
&#8220;Restrict&#8221; checkbox at the
bottom of the tab</li>
the post</li>
post will now be hidden from WP Subscribers who are not selected in
&#8220;Readers&#8221; tab.&nbsp; If the post must also be hidden from WP
Contributors, set
the &#8220;Restrict&#8221; checkbox in the &#8220;Contributors&#8221; tab.&nbsp; To hide
it from WP
Authors and Editors, set the &#8220;Restrict&#8221; checkbox in the &#8220;Editors&#8221;
In Role Scoper lingo, the post&nbsp;now&nbsp;Restricts the
<h4>Granting Read Access to an Individual Post/Page</h4>
<ol class="step_list">
<li><span style="font-weight: normal;">Decide
whether you
want to manage
permissions user-by-user, for Wordpress role &#8220;groups&#8221;, and/or for
custom-defined User Groups.&nbsp;</span> If custom user
groups are
desired, define
those first (see above).</li>
the WordPress
Write Post / Edit
Post interface</li>
down to the
&#8220;Readers&#8221; tab (under
&#8220;Advanced Options&#8221;) and expand it</li>
the checkbox
of any User and/or
Group who should have read access</li>
the Post</li>
it's convenient to manage each hidden post/page with the above
that's all you need to know.&nbsp; If access control by category is
read on.</p>
Read Access by Post Category</b></h4>
<ol class="step_list">
to WP Admin
-&gt; Restrictions -&gt; Category</li>
down to your
category of interest,
perhaps using the scroll link at top</li>
the &#8220;Private
Post Reader&#8221; checkbox
to restrict read access to private posts by anonymous users and WP
the &#8220;Post Reader&#8221;
checkbox to restrict read access to non-private posts by anonymous
users and WP
Subscribers <span style="font-weight: normal;">(if the WP
Subscriber role has not been modified to include
to the top</li>
<li style="font-weight: normal;">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.</li>
the Update
Read Access by Post Category</b></h4>
<ol class="step_list">
to WP Admin
-&gt; Roles -&gt; Category
down to your
category of interest,
perhaps using the scroll link at top</li>
the roles you
would like to assign</li>
to the top</li>
<li>Select users and/or
groups to assign&nbsp;selected roles</li>
<li style="font-weight: normal;">Note
that the
adjacent dropdown indicates
that the Update action will cause the selected roles to be assigned
posts in the selected section.&nbsp;</li>
you want the same
role to also be
assigned for all current and future subcategories, change the dropdown
&#8220;assign for selected and sub-categories&#8221;.</li>
the Update
that <b>if</b> a Post Restriction is <b>not</b> set for Readers, read
access to it will be granted if:</p>
user has a qualifying Category Role in any post category</li>
<div style="margin-left: 80px;"><span style="font-weight: bold;">-
OR -</span></div>
the post's categories
do not ignore the user's qualifying blog-wide general role (or another qualifying
role it
you <b>cannot </b>hide a post just by assigning it to an
additional &#8220;hidden&#8221;
category.&nbsp; If individual posts don't restrict the Readers role,
they will be readable if <b>any</b> of their categories
are readable to the
user.&nbsp;&nbsp; If your categorization and post restriction
goals demand the
&#8220;readable cat + hidden cat = hidden post&#8221; formula, you'll be frustrated
this plugin.&nbsp; But here are some suggestions for making the
Role Scoper
model work with your existing categories:</p>
mentioned above, different role requirements and assignments can be
made for
&#8220;private&#8221; and &#8220;non-private&#8221; posts in the same category.</li>
on how your theme displays categories, you could move some &#8220;Category A&#8221;
into a new subcategory ( Category A / Category A*), and remove them
&#8220;Category A&#8221;.&nbsp; Then set Category Restrictions and Category Role assignments for Category A*.</li>
/ Editing by Category</b></h4>
are two pieces:
granting access and restricting access, and two basic ways to achieve
desired access and restrictions:</p>
<ul type="disc">
with user(s) who have too little access and elevate them</li>
with user(s) who have too much access and restrict them</li>
<p>You can also use some
of the two.&nbsp; Where
possible simplify your life by setting your users as WordPress
then following the first Role Scoper configuration procedure
below.&nbsp; This also provides the
greatest security,
since those users will default to zero editing ability if Role Scoper
accidentally deactivated or otherwise disabled.</p>
Subscriber to Post in specific Categor(ies)</b></h4>
<ol class="step_list">
UserA to WordPress role of Subscriber</li>
a Category Role of Post Author to UserA for the desired category (WP
Admin &gt;
Roles &gt; Category)</li>
<p>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:</p>
Posting Categor(ies) for Contributor/Author/Editor</b></h4>
<ol class="step_list">
to the Category Restrictions admin
(WP Admin &gt; Restrictions &gt; Category)</li>

<li>In the "DEFAULTS" table, check
the boxes for &#8220;Post
Contributor&#8221; and &#8220;Post Author&#8221;.&nbsp; Also &#8220;Post Editor&#8221; if you
want to
restrict WP editors.</li><li>Confirm
the dropdowns next to
Update button say &#8220;Restrict selected roles" and "for selected categories"</li>

<p>Now Contributor and
Authors (and
editors, if you restricted
that role) will not be able to post or edit in any&nbsp;category
unless you assign them a Category Role for it, as explained for UserA
above. &nbsp;Note that the "DEFAULTS" setting applies the restriction
to all existing and future categories (unless one is manually
unrestricted). &nbsp;To restrict fewer categories, select desired
restrictions for each category instead.</p>
<h4><b><b>Enabling a User to Edit Specific Page(s),
and Nothing Else:</b></b></h4>
<ol class="step_list">
<li> Give them a WordPress role of Subscriber</li>
<li>Manage &gt; Pages &gt; Edit their page</li>
<li>Expand the "Editors" tab under "Advanced Options"</li>
<li>Check the non-braced checkbox to the left of your user's
name&nbsp;<span style="font-weight: normal;">(if subpages will be created, also check the braced checkbox {[]}, which
assigns the role for all current or future subpages)</span></li>
<li>Save the Page</li>
<p>Note that if you also assign this user a Role Scoper General Role
Page Author, they will be able to create subpages off their member
page, but not off any other pages:</p>
<ol class="step_list">
<li> Go to WP Admin &gt; Roles &gt; General</li>
<li>&nbsp;Select your user name(s)</li>
<li>&nbsp;Select the Page Author role</li>
<li>&nbsp;Click Update</li>
<p> <strong>OR</strong>, if you want all subscribers
to have this ability:</p>
<ol class="step_list">
<li> Go to WP Admin &gt; Roles &gt; General</li>
<li>Select [WP Subscriber]</li>
<li>Select the Page Author role</li>
<li>Click Update</li>
<a name="Section3|region"></a>
<h1 align="center">Section
Customizations and Extensions</h1>
<p align="center">(note:
this section will
be expanded in future revisions)</p>
Content Teaser</h3>
Role Scoper hides content for which users lack a sufficient role
You can also apply a teaser by activating that option in the Role
options page at WP Admin &gt; Roles &gt; Roles.</p>
Role Scoper Options</h3>
on the Roles &gt; Options page pertain
primarily to customizations
of the Role Scoper for future plugin-defined data sources. Most users
safely leave the default settings. The settings available there do
descriptive captions.</p>
customized markup of restricted and/or currently hidden posts, Role
provides the following template functions for use in themes:</p>
<p><span style="font-family: &quot;Courier New&quot;; color: blue;">&nbsp;is_restricted_rs(
<p><span style="font-family: &quot;Courier New&quot;; color: blue;">&nbsp;is_teaser_rs(
calling these functions outside the WP loop, you should pass post ID as
first function argument. Otherwise just call as stated above.</p>
may define their own data sources, taxonomies (WP term_taxonomy or
tables), capabilities and roles. See defaults_rs.php and
for example hook usage. Details will be provided in later versions of
version of this document is available online at </p>
<p><a href="http://agapetry.net/downloads/RoleScoper_UsageGuide.htm">http://agapetry.net/downloads/RoleScoper_UsageGuide.htm</a></p>
Return current item: Role Scoper