RoleArchitect Overview

Complete WordPress role and capability management system

System Requirements:
wordpress 5.0 or higher | Tested up to WordPress 6.9 | PHP 7.0 or higher

👥 Role Management

Create, edit, clone (PRO), and delete (PRO) custom roles with granular capability control.

📝 Content Permissions

Manage roles' permissions to view, edit, and delete others' posts and pages from a dedicated page.

🎛️ Menu Control

Hide admin menu items per role with automatic capability detection for ALL plugins.

🔒 Content Restriction

Restrict content by roles, capabilities, or login status using shortcodes or per-post settings.

Key Features

  • Visual Role Editor - Manage capabilities with categorized checkboxes and search
  • User Role Assignment - Assign multiple roles (PRO) to users with visual interface
  • Admin Menu Restriction - Toggle visibility of menu items per role with automatic capability detection
  • Dynamic Capability Detection - Automatically detects and grants required capabilities for ALL plugins
  • Content Permissions Page - Manage roles' content editing permissions from a dedicated page
  • Content Shortcodes - [ROAR_restrict] shortcode with role/capability (PRO) based access
  • Per-Post Restriction - Set viewing permissions directly in post editor
  • Page Access Control - Users cannot access unauthorized pages even with direct URLs
  • Debug Tools - Built-in diagnostic tools to identify menu and capability issues
  • Export/Import - Backup and restore role configurations
New in v1.2.0: Dynamic capability detection system now provides automatic authorization for ALL plugins. Content permissions management and advanced debug tools added.
Pro Tip: Start by creating a test role and assigning it to a test user to understand how capabilities work before applying to live users.

Installation & Setup

Get started with RoleArchitect in minutes

1

Install the Plugin

Upload the plugin folder to /wp-content/plugins/ or install via WordPress admin.

2

Activate the Plugin

Go to Plugins → Installed Plugins and activate 'RoleArchitect'.

3

Access the Plugin

A new 'Role Editor' menu will appear in your WordPress admin sidebar.

4

Verify Permissions

Only users with 'manage_options' capability (Administrators) can access the role editor features.

Important: Always backup your WordPress database before making significant role changes. The plugin includes an export/import feature for this purpose.

Role Management

Create, customize, and manage WordPress user roles

Understanding Roles & Capabilities

In WordPress, a Role is a collection of Capabilities (permissions). Each capability grants access to specific functionality. RoleArchitect provides a visual interface to manage these relationships.

Default Role Typical Use Case
Administrator Full site access, can manage everything including other users
Editor Can publish and manage all posts including others'
Author Can publish and manage their own posts only
Contributor Can write posts but cannot publish them
Subscriber Can only manage their profile and view content

Creating a New Role

1

Navigate to Role Management

Click 'Role Editor' → 'Role Management' in the admin menu.

2

Click 'Add New Role'

Click the blue 'Add New Role' button in the top right of the roles table.

3

Enter Role Name

Enter a descriptive name like 'Shop Manager' or 'Content Moderator'.

4

Select Capabilities

Use the categorized capability list. Search for specific capabilities or use 'Select All' / 'Clear All' buttons.

5

Save the Role

Click 'Save' to create the new role with selected capabilities.

Cloning an Existing Role (PRO)

Role cloning is useful when you want to create a role similar to an existing one with minor modifications.

  1. Find the role you want to clone in the roles table
  2. Click the clone icon (two pages) next to the edit button
  3. Enter a new name for the cloned role
  4. The new role will have all the same capabilities as the original
  5. Edit the new role to add or remove specific capabilities
Warning - System Roles: Default WordPress roles (Administrator, Editor, Author, Contributor, Subscriber) cannot be deleted to prevent site lockouts. However, you can modify their capabilities.

User Role Assignment

Assign and manage roles for individual users

Assigning Roles to Users (PRO: Multiple Roles)

Unlike the default WordPress behavior (one role per user), RoleArchitect allows you to assign multiple roles to a single user.

1

Navigate to User Assignment

Click 'Role Editor' → 'User Assignment' in the admin menu.

2

Find the User

Use the search box to find a specific user, or click 'List All' to see all users.

3

Select the User

Click on a user in the left panel to select them. The selected user will be highlighted.

4

Assign Roles

Check the checkboxes for all roles you want to assign to this user. You can assign multiple roles.

5

Save Assignments

Click 'Assign Roles' to save the changes. The user will immediately have all selected capabilities.

Note: When a user has multiple roles, they have the combined capabilities of all assigned roles. For example, if a user has both 'Author' and 'Moderator' roles, they can do everything either role allows.

Important Safety Feature

The plugin prevents you from removing your own Administrator role to avoid locking yourself out of the site. If you need to change your own role, have another Administrator do it for you.

Admin Menu Restriction

Control which admin menu items are visible for each role

How Menu Restriction Works

Menu restrictions allow you to hide specific admin menu items from users based on their role. This doesn't remove their capability to access those pages directly via URL, but removes the menu items from their admin sidebar.

1

Open Menu Restriction

Click 'Role Editor' → 'Menu Restriction' in the admin menu.

2

Select a Role

Use the 'Select Role' dropdown to choose which role you want to configure menu visibility for.

3

Toggle Menu Visibility

For each menu item, toggle the switch: ON (Blue) = Menu is visible, OFF (Gray) = Menu is hidden.

4

Configure Submenu Items

Expand main menu items to see their submenu items. Each submenu can be toggled independently.

5

Save Changes

Click 'Save Menu Permissions' to apply the changes to the selected role.

Bulk Actions

Use the bulk action buttons to quickly configure menu visibility:

  • Enable All - Makes all menu items visible for the selected role
  • Disable All - Hides all menu items from the selected role
  • Reset to Defaults - Restores WordPress default menu visibility based on role capabilities
Important: Plugin menus (marked with green badge) are detected automatically. Hiding a parent menu will also hide its submenu items from the sidebar.

Content Restriction

Control access to posts, pages (PRO), and custom content (PRO)

Content Restriction Methods

📝 Individual Restriction

Edit restrictions for individual posts/pages with detailed controls via the Content Restriction page.

🏗️ Bulk Restriction (PRO)

Apply restrictions to multiple posts at once via the Content Restriction admin page.

Content Restriction Modes

The Content Restriction page provides three viewing modes for controlling access to your content:

Mode Description
Public Everyone can view the content (default)
Restricted Only selected roles can view the content
Logged In (PRO) Any logged-in user can view the content

Using Individual Restriction:

  1. Go to 'Role Editor' → 'Content Restriction'
  2. Select content type and click 'List' to load items
  3. Click the edit button next to any post/page
  4. Select the desired viewing mode in the modal
  5. For 'Restricted' mode, check which roles should have access
  6. Optionally customize the 'Access Denied' message
  7. Click 'Save' to apply the restriction

Bulk Content Restriction (PRO)

The Content Restriction page allows you to manage restrictions for multiple posts at once:

  1. Go to 'Role Editor' → 'Content Restriction'
  2. Select content type (Posts or Pages)
  3. Click 'List' to load items
  4. Select items using checkboxes
  5. Choose bulk action mode and apply
Note on Access Denied Messages: The default message is 'You do not have permission to view this content.' You can customize this per-post or set a global default.

Content Restriction Shortcodes

Use shortcodes to restrict content within posts and pages

The [ROAR_restrict] Shortcode

The [ROAR_restrict] shortcode allows you to show or hide content based on user roles, capabilities, or login status.

Usage Examples

Role-Based Restriction

Show content only to administrators:

[ROAR_restrict role="administrator"] This content is only for administrators. [/ROAR_restrict]

Multiple Roles

Show content to administrators and editors:

[ROAR_restrict roles="administrator,editor"] This content is for admins and editors. [/ROAR_restrict]

Capability-Based (PRO)

Show content to users who can publish posts:

[ROAR_restrict cap="publish_posts"] Only authors and above can see this. [/ROAR_restrict]

Custom Message

Show custom 'access denied' message:

[ROAR_restrict role="subscriber" message="Premium content. Please upgrade."] This is premium content. [/ROAR_restrict]

Shortcode Parameters

Parameter Description Example
role Single role that can view content role="editor"
roles Comma-separated list of roles roles="admin,editor"
cap (PRO) Required capability to view cap="manage_options"
message Custom access denied message message="Login required"
Important: The role and roles parameters are checked against the user's roles. The cap parameter checks if the user has a specific capability. You can combine them for more precise control.

Content Permissions

Manage roles' permissions to view, edit, and delete others' posts and pages

What are Content Permissions?

Content permissions control what users can do with posts and pages created by other users. This is essential for multi-author sites where you need to control editorial workflows.

Key Capabilities

Post Permissions

  • edit_others_posts - Edit others' posts
  • delete_others_posts - Delete others' posts
  • edit_published_posts - Edit published posts
  • delete_published_posts - Delete published posts

Page Permissions

  • edit_others_pages - Edit others' pages
  • delete_others_pages - Delete others' pages
  • edit_published_pages - Edit published pages
  • delete_published_pages - Delete published pages

Managing Content Permissions

1

Open Content Permissions

Click 'Role Editor' → 'Content Permissions' in the admin menu.

2

Select a Role

Choose the role you want to configure content permissions for.

3

Configure Permissions

Use the grid layout to toggle permissions for posts and pages. Each capability can be enabled or disabled independently.

4

Save Changes

Click 'Save Content Permissions' to apply the configuration.

Common Use Cases

Scenario Configuration
Content Reviewer Enable edit_others_posts but disable delete_others_posts
Page Manager Enable all page permissions, disable post permissions
Blog Editor Enable all post permissions, disable page permissions
Limited Editor Enable edit_published_posts only (can edit but not delete)
Important: Content permissions work in conjunction with basic capabilities like 'edit_posts' and 'edit_pages'. Users must have the basic capability before they can use the 'others' or 'published' variants.
New in v1.2.0: The Content Permissions page provides a visual grid interface to manage these capabilities easily, replacing the need to manually toggle individual capabilities in the role editor.

Settings & Tools

Configure global settings and manage role backups

General Settings

Default Role

Set which role new users will receive when they register on your site. This is the same as the WordPress default role setting, accessible directly from the Role Editor interface.

Export & Import

Exporting Role Configuration

  1. Go to 'Role Editor' → 'Settings'
  2. Find the 'Export' section
  3. Click 'Download Configuration'
  4. A JSON file with all roles and capabilities will be downloaded

Importing Role Configuration

  1. Go to 'Role Editor' → 'Settings'
  2. Find the 'Import' section
  3. Paste the exported JSON data into the text area
  4. Click 'Import Configuration'
  5. All roles from the export will be restored
Warning: Importing will overwrite existing custom roles with the same name. Always backup your current configuration before importing.

Reset to Defaults (Danger Zone)

The 'Reset to Defaults' button will delete all custom roles and restore WordPress default roles to their original state. This action cannot be undone.

Danger: Before using 'Reset to Defaults', ensure you have an export of your current configuration. Users with custom roles will lose those roles and may need to be reassigned.

Frequently Asked Questions

Common questions and troubleshooting tips

Can I assign multiple roles to a single user? (PRO)

Yes! Unlike default WordPress behavior, DRU Role Editor allows you to assign multiple roles to a single user. The user will have the combined capabilities of all assigned roles.

What happens if I delete a custom role? (PRO)

Users who had that role will lose it. They may lose access to the admin area if they don't have any other roles. Always ensure users have at least one role with appropriate capabilities.

Can I modify default WordPress roles?

Yes, you can add or remove capabilities from default roles (Administrator, Editor, Author, Contributor, Subscriber). However, you cannot delete these system roles.

Does hiding a menu item remove the capability?

No. Menu restriction only hides the menu item from the sidebar. Users with the appropriate capability can still access the page directly via URL. To truly restrict access, modify the role's capabilities.

Will content restriction affect SEO?

Restricted content is still visible in the HTML source (for logged-in users). For complete protection, use the per-post restriction with the 'Restricted' mode, which filters content at the template level. Search engines typically see the restriction message, not the protected content.

Can I export roles and import to another site?

Yes, use the Export/Import feature in Settings. The exported JSON file can be imported to any site with DRU Role Editor installed. This is useful for maintaining consistent role setups across multiple sites.

I locked myself out! How do I fix it?

If you accidentally removed your administrator capabilities, you can restore access by:

  1. Accessing your database via phpMyAdmin or similar tool
  2. Finding the wp_capabilities option in the wp_options table (for your user)
  3. Restoring the administrator role, or using the 'Reset to Defaults' button if you have another admin account

This is why the plugin prevents you from removing your own admin role through the interface.

📚 Documentation Version 1.2.0 | RoleArchitect