Custom Section Editing Roles

For some users the built-in "Section Editor" role may not be enough.

The section editing plugin was designed to support customized "Section Group-ready" roles. There are two ways custom roles can be defined:

1. Programmatically
2. By using a custom role management plugin (such as "Members")

In both cases, a solid understanding of the built-in WordPress Roles and Capabilities system is in order. The plugin hooks in to the map_meta_cap function in particular to handle overriding edit / delete / and publish capabilities for specific posts.

Consequently, in order for custom post type permissions to be controlled via section groups they must be registered with map_meta_cap set to true.

Creating Custom Section Editing Roles Programmatically

In order for a role to be limited by section editing caps, the following capabilities must not be added for your role:

• edit_published_posts
• delete_others_posts
• delete_published_posts
• publish_posts

The built-in “Section Editor” role adds the following caps to allow editing of non-published content:

• read
• read_private_posts
• edit_posts
• edit_others_posts
• edit_private_posts
• delete_posts

Note that the exact names of these primitive capabilties varies by post type — “Pages”, for instance, get “edit_published_pages”, “publish_pages”, etc. Custom post types can be registered with custom capability names by using the capability_type and capabilities arguments. See the Codex page for register_post_type() and Justin Tadlock’s excellent article on post type capabilities for more information.

Section Editing Capabilities

The key to "section editing-ness" lies in the following capabilities:

• edit_in_section
• edit_*_in_section
• delete_*_in_section
• publish_*_in_section

Without the “edit_in_section” cap, a role will not grant membership to section groups. The other three capabilities override the usual edit / delete / publish checks for published posts. Replace the asterisk with the post type name you want to limit with section editing restrictions.

Example — Custom Role with Full Post Editing Capabilities

<?php
/**
 * Define a custom role that is limited by section editing privileges for "Pages", but
 * has full edit / delete / publish privs for "Posts"
 */
function create_page_section_editor() {

        // Maybe create custom "Page Section Editor" role
	$role = get_role( 'page_section_editor' );
	if ( empty( $role ) ) {
		add_role( 'page_section_editor', 'Page Section Editor' );
	}
	$role =& get_role( 'page_section_editor' );

        // Populate with desired capabilities
	$role->add_cap( 'read' );
	$role->add_cap( 'upload_files' );

        // Full edit/delete/publish privileges for "Posts"
	$role->add_cap( 'read_private_posts' );
	$role->add_cap( 'edit_posts' );
	$role->add_cap( 'edit_others_posts' );
	$role->add_cap( 'edit_private_posts' );
	$role->add_cap( 'delete_posts' );

	$role->add_cap( 'edit_published_posts' );
	$role->add_cap( 'delete_others_posts' );
	$role->add_cap( 'delete_published_posts' );
	$role->add_cap( 'publish_posts' );

        // Section editing limited privileges for "Pages"
	$role->add_cap( 'read_private_pages' );
	$role->add_cap( 'edit_pages' );
	$role->add_cap( 'edit_others_pages' );
	$role->add_cap( 'edit_private_pages' );
	$role->add_cap( 'delete_pages' );

        // Section editing specific capabilities
	$role->add_cap( 'edit_in_section' );
	$role->add_cap( 'edit_page_in_section' );
	$role->add_cap( 'delete_page_in_section' );
	$role->add_cap( 'publish_page_in_section' );

}

add_action( 'buse_populate_roles', 'create_page_section_editor' );

The buse_populate_roles hook is triggered by the section editing plugin during upgrade and any time an action may introduce new post type-specific capabilities (theme switch, plugin activated, etc.). Developers can utilize this hook to define their own section editing roles when the plugin is active.

Note that roles and capabilites are committed to the database by default. As such there is no need to create roles and modifiy capabilities on every page request.

Preventing the "Section Editor" role from being Created

Developers wishing to prevent the creation of the default "Section Editor" role can do so using the "buse_create_section_editor_role" filter:

<?php
function prevent_section_editor_role_creation( $should_create ) {
	return false;
}
add_filter( 'buse_create_section_editor_role', 'prevent_section_editor_role_creation' );

Since roles and capabilities are stored in the database, the section editor role will not disappear when the plugin is deactivated. Section editors will lose the ability to edit any content, however.