Stephanie Leary

Writer and WordPress consultant

  • Books
    • Content Strategy for WordPress (2015)
    • WordPress for Web Developers (2013)
    • Beginning WordPress 3 (2010)
  • Blog
    • Fascism Watch (2016-17)
    • Content Modeling for WordPress series
    • WordPress Hidden Gems series
  • Work
    • Portfolio
    • Services
    • WordPress Plugins
    • WordPress Themes
    • Presentations and Interviews
    • on GitHub →
  • About
    • Press Kit
  • Contact
    • Mailing List

Creating roles

February 24, 2010 Stephanie Leary Leave a Comment

Sometimes, rather than adding capabilities to an existing role, you need to create a whole new role. The code to do so is relatively easy. Again, place these lines in your theme’s functions.php file:

// Create
add_role('privatereader', 'Private Reader', array(
            'read' => 1,
            'level_0′ => 1,
            'read_private_pages' => 1,
            'read_private_posts' => 1,
        ));
?>

The add_role function requires three arguments: the role’s name (for internal use), the display name, and an array of the role’s capabilities. (See the Codex page on Roles and Capabilities for a complete list of the capabilities in WordPress.) Here, we’ve given our role the same two capabilities a subscriber starts out with, ‘read’ and ‘level_0.’ (The level_n capabilities exist for backward compatibility with very early versions of WordPress, which used a 1-10 scale instead of named roles.) Then we’ve added the two roles relating to private content.

If you create or edit a user now, you should see the new Private Reader role as an option.

If we wanted to modify our new role, we’d use the same code we used to change capabilities before, but but we’d change the get_role function’s argument to our new role’s internal name.

// remove ability to read private pages
$PrivateRole = get_role('privatereader');
$PrivateRole -> remove_cap('read_private_pages');
?>

Need to remove the role? That’s easy:

remove_role('privatereader');
?>

That’s nice, but now what?

In this example, it makes sense to create a new role only if you wanted to keep the subscriber role as-is; otherwise; it was simpler to just modify the subscriber role.

When would it make sense to create a new role?

Let’s imagine a new scenario. You’re building a large site, and you, the programmer, are sharing responsibilities with a graphic designer. You want to give your designer complete control over the content and theme design, but you don’t want him editing other users, adding plugins, or importing content from other sites.

We could create a whole new role and enumerate every capability we want the designer to have, as we did above for the private reader, but this role will be similar to the administrator’s, and that’s a lot of capabilities! Instead, we’ll duplicate the admin role and remove the eight or nine capabilities we don’t want the designer to have.

Creating a designer role

$admin = get_role('administrator');

// get_role returns an object.
// We want the capabilities piece, which is an array.
$caps = $admin->capabilities;

// Remove the stuff we don't want in the new role.
unset($caps['activate_plugins']);
unset($caps['edit_plugins']);
unset($caps['update_plugins']);
unset($caps['delete_plugins']);
unset($caps['install_plugins']);
unset($caps['edit_users']);
unset($caps['delete_users']);
unset($caps['create_users']);
unset($caps['import']);

// Add the new role.
add_role('designer', 'Designer', $caps);
?>

And that’s that!

Note that WordPress’s admin menus and screens don’t always behave exactly as you’d expect. In this case, even though we’ve removed all capabilities involving plugins, the designer will still be able to access the Plugins → Add New screen, search for plugins, and install them — but s/he won’t be able to activate the new plugin, or see the list of installed plugins.

The user/role structure is due for an overhaul in version 3.1; hopefully these menu glitches will be addressed then.

Managing Roles with Plugins

If you’d rather click tickyboxes than write all this code, Justin Tadlock’s Members plugin provides an elegant user interface for everything I’ve shown here. It also has some extra features related to private content.

WordPress capabilities, design, permissions, Privacy, Users and Roles

Leave a Reply Cancel reply

Your email address will not be published. Required fields are marked *

Fascism Watch

The Fascism Watch is a daily(ish) news roundup. View all the previous Fascism Watch posts »

Latest WordPress Book

Content Strategy for WordPress

A short book for content strategists and managers on implementing a complete content strategy in WordPress: evaluation, analysis, content modeling, editing and workflows, and long-term planning and maintenance.

Read the sample chapter

Kindle Nook iBooks Kobo Smashwords

WordPress for Web Developers

WordPress for Web Developers (9781430258667)

This is a book for professional web designers and developers who already know HTML and CSS, and want to learn to build sites with WordPress. The book begins with a detailed tour of the administration screens and settings, then digs into server-side topics like performance and security. The second half of the book is devoted to development: learning to build WordPress themes and plugins.

This is the second, much-revised and updated edition of Beginning WordPress 3, with a more accurate title. Everything’s been updated for WordPress 3.6.

WordPress for Web Developers is out now. See what's inside...

The best WordPress features you’ve never noticed

  • WordPress Hidden Gems: Screen Options
  • WordPress Hidden Gems: Bulk Edit
  • WordPress Hidden Gems: Private Status
  • WordPress Hidden Gems: Dashboard Feed Readers
  • WordPress Hidden Gems: Options.php

Content Modeling for WordPress series

  • Content modeling for WordPress, part 1: analyze content
  • Content modeling for WordPress, part 2: functional and organizational requirements
  • Content modeling for WordPress, part 3: a sample content model

This is an excerpt from Content Strategy for WordPress.My latest books are Content Strategy for WordPress (2015) and WordPress for Web Developers (2013). Sign up to be notified when I have a new book for you.

Copyright © 2021 Stephanie Leary