WordPress is an open-source (CMS) that powers millions of websites. Out of the box, it allows you to create and manage posts and pages. However, as your website grows, you might need to manage different types of content beyond these basic options. It is where custom post types (CPTs) come in.
A custom post type is essentially a way to group content. For instance, if you’re running a book review site, you might create a Books post type, and for a movie review website, a Movie post type. The flexibility of custom post types helps you manage content more efficiently.
But, creating custom post types is only part of the equation. WordPress role and capability system allows you to define what users can do with these post types. For example, you might want to allow certain users to edit books but not publish them. To accomplish this, you’ll need to implement custom capabilities.
In this guide, we’ll explain how to integrate custom capabilities into custom post types. We’ll go through the technical steps, provide code examples, and explain each step in simple language so you can easily understand.
By the end of this guide, you’ll have a solid understanding of custom post types, custom capabilities, and how to manage user permissions on your WordPress website.
1. Registering a Custom Post Type (CPT) with Custom Capabilities
The first step in adding custom capabilities is creating a custom post type. It is done using the register_post_type() function in WordPress. By default, this function creates a standard post type with basic capabilities. But to add custom capabilities, we need to make some adjustments.
Code Example 1: Registering a Custom Post Type for Books
Here’s how to create a custom post type called Books, with custom capabilities for editing, publishing, and deleting books:
function create_book_post_type() {
register_post_type('book', array(
'labels' => array(
'name' => 'Books',
'singular_name' => 'Book',
'add_new' => 'Add New Book',
'edit_item' => 'Edit Book',
'new_item' => 'New Book',
'view_item' => 'View Book',
'search_items' => 'Search Books',
'not_found' => 'No books found',
'not_found_in_trash' => 'No books found in Trash',
'all_items' => 'All Books',
),
'public' => true,
'has_archive' => true,
'show_in_rest' => true, // Enable Gutenberg support
'capability_type' => 'book', // Custom capabilities
'map_meta_cap' => true, // Map meta capabilities
));
}
add_action('init', 'create_book_post_type');
Explanation:
- capability_type: This tells WordPress to create custom capabilities for the Book post type. By setting this to ‘book’, WordPress will automatically generate capabilities like edit_book, publish_books, and delete_book.
- map_meta_cap: Setting this to true ensures that WordPress maps the custom capabilities to the default capabilities, such as edit_posts. This process allows WordPress to map high-level actions to low-level capabilities, such as edit_posts, delete_posts, etc.
Custom capabilities are helpful because they allow you to control who can perform certain activities on the custom content you create.
2. Understanding WordPress Role and Capability System
WordPress has a built-in system for managing editing, publishing, and deleting user roles and their capabilities. The default roles are Administrator, Editor, Author, Contributor, and Subscriber. Each role comes with a set of predefined capabilities, such as the ability to edit, publish, and delete posts.
However, WordPress allows you to customize these roles and capabilities to suit your needs. For instance, if you have a custom post type for books, you may want certain users (like editors) to be able to edit books, but only administrators to publish books.
This is where custom capabilities come into play. By integrating custom capabilities into your roles, you can control who can perform which actions on your custom post types.
3. Assigning Custom Capabilities to WordPress Roles
Now that we’ve registered a custom post type with custom capabilities, we need to assign those capabilities to user roles. The add_cap() function can help us do this.
For example, let’s say you want to allow Editors to edit and publish books, but only Administrators can delete books.
Code Example 2: Assigning Custom Capabilities to User Roles
function assign_book_caps_to_editor() {
// Get the Editor role
$editor_role = get_role('editor');
// Assign capabilities to the Editor role
$editor_role->add_cap('edit_book');
$editor_role->add_cap('publish_books');
// Get the Administrator role
$admin_role = get_role('administrator');
// Assign delete capability to Admin role
$admin_role->add_cap('delete_book');
}
add_action('admin_init', 'assign_book_caps_to_editor');
Explanation:
- get_role(): This function retrieves a role object (e.g., editor, administrator) that you want to assign capabilities to.
- add_cap(): This function adds a specific capability (e.g., edit_book, publish_books) to the role. Here, we add the capability to edit and publish books to the Editor role and the capability to delete books to the Administrator role.
4. Checking User Capabilities on the Frontend
Now that you’ve assigned custom capabilities to roles, you might want to check if a user has a specific capability before displaying content on the front end.
For example, if a user can edit books, you can show them an Edit Book button.
Code Example 3: Displaying Content Based on User Capabilities
if (current_user_can('edit_book')) {
echo '<button>Edit Book</button>';
} else {
echo '<p>You don't have permission to edit this book.</p>';
}
Explanation:
- current_user_can(): This function checks if the current user has the specified capability. In this case, we check if the user can edit books and display a button accordingly.
5. Removing Capabilities from User Roles
Sometimes, you may need to remove certain capabilities from a user role. For instance, you may want to revoke the ability to delete books from an Administrator role.
Code Example 4: Removing a Capability from a Role
function remove_delete_book_capability() {
$admin_role = get_role('administrator');
$admin_role->remove_cap('delete_book');
}
add_action('admin_init', 'remove_delete_book_capability');
Explanation:
- remove_cap(): This function removes a specific capability from a role. In this case, we’re removing the delete_book capability from the Administrator role.
6. Advanced Tips for Managing Custom Capabilities
- Using Custom Capabilities in Plugins: If you’re building a plugin that interacts with custom post types, you can easily integrate custom capabilities by defining them when registering your post types.
- Role-based Content Restriction: You can restrict access to certain content based on user roles and capabilities. This allows you to create member-only sections of your site or restrict editing permissions for certain users.
7. Troubleshooting Common Issues
As you implement custom capabilities, you might encounter some common issues:
- Permissions Not Updating: If you don’t see the custom capabilities reflected in the user interface, try signing out and logging back in or clearing your browser cache.
- Capabilities Not Working: When registering your custom post type, ensure that map_meta_cap is set to true. It will ensure that WordPress properly maps the capabilities.
Questions & Answers
Conclusion
With custom capabilities and WordPress built-in role system, you have a powerful way to control access to your custom post types. By following this guide, you’ve learned how to register a custom post type, define custom capabilities, assign those capabilities to user roles, and check capabilities on the front end.
This functionality is essential for sites that need precise control over who can do what with their content. Whether you manage a simple blog or a complex multi-user site, custom capabilities will help you fine-tune the permissions for each user role.
About the writer
Hassan Tahir wrote this article, drawing on his experience to clarify WordPress concepts and enhance developer understanding. Through his work, he aims to help both beginners and professionals refine their skills and tackle WordPress projects with greater confidence.