The Members plugin is meant to be a complete user, role, and content management plugin for WordPress. Its purpose is to give you fine-grained control over who has access to what.
Right now, it's in the early stages of development. It's my hope that this provides that true CMS experience that many users long for in WordPress. There's a long road ahead, and I hope you join me for the ride.
Use the links below to navigate to a specific section in the documentation:
This is the most important thing to understand with this plugin. It's so important that I took the time out of my day to write a complete tutorial on understanding this: Users, roles, and capabilities in WordPress. If you don't understand this concept, you won't understand what this plugin does. This is not a concept created by the plugin. This is how it's done in WordPress.
I highly recommend reading that blog post, but here's the short version:
edit_posts, Role B can't activate_plugins, etc.).members.zip folder.members folder to your /wp-content/plugins directory.This plugin is set up to have a components-based system. The reason for this is that I don't want to stick everyone with a bunch of features they don't need. There's no point in using the Edit Roles component if all you need is just a login widget and some shortcodes. So, it's a use-only-what-you-want system.
To add components, look for the Members Components link under your Settings menu while in your WordPress admin. When on the new page, you'll be able to select the components you want to use.
I recommend at least activating Edit Roles component. It is at the heart of this plugin, and many other components will likely require its use in some form.
This component can be both a blessing and a curse, so I'm going to ask that you use it wisely. Use extreme caution when assigning new capabilities to roles. You wouldn't want to give Average Joe the edit_plugins capability, for example.
Edit Roles is the big daddy of all the components. It allows you to edit and assign new capabilities to existing roles.
You can find the settings page for this component under the Users menu. It will be labeled Roles. When clicking on the menu item, you'll get a list of all the available roles. From there, you can select a role to edit.
To delete a role, you must have the delete_roles capability. If you don't have that, you won't see a delete option on the Roles page.
It is important that you assign the capability of edit_roles to a role (the administrator role would be a good one). That way, only users with that particular capability can edit roles.
The New Roles component allows you to create new roles. The menu item for this is located under the Users menu and is labeled New Roles.
You can only use this component (create new roles) if you have the create_roles capability. So, if you don't have that, you need to use the Manage Roles component to add that capability to the role you currently have.
Adding new roles is pretty straightforward. You need to input a Role (only use letters, numbers, and underscores), Role Name, and select which capabilities the new role should have. You can later manage this role using the Edit Roles component.
You can assign new roles to users from the Authors & Users screen in WordPress. This is nothing particular to the plugin and is a default part of WordPress. I believe you need the edit_users capability to do this (I'll have to check).
The Content Permissions component will be the heart and soul of this plugin in the future. Right now, it only adds an additional meta box on the post/page edit screen. This meta box allows you to select which roles can view the content of the post/page. If no roles are selected, anyone can view the content.
You need the restrict_content capability to use this component. So, you'll need to add this capability to your role using the Edit Roles component.
Note that you'll see a Role custom field key and values when testing this component. This is for my personal testing only right now.
There are several shortcodes that you can use in your post/page editor. These need some major testing right now, so please offer any feedback you can.
The [access] shortcode is for hiding content from particular roles and capabilities. You need to wrap your content when using this shortcode:
[access role="editor"]Hide this content from everyone but editors.[/access]Parameters:
capability: A capability that has been assigned to a role.role: A user role from WordPress or one that you've created.feed: Set to true if you'd like to show the content in feeds.Note that capability and role parameters aren't used in conjunction. The code first checks for the capability (if input) then checks for the role (if input).
This shortcode is for showing a user's avatar through Gravatar. It should be used like so within your post/page editor:
[get_avatar id="30"]Parameters:
id: The ID of the user's avatar you'd like to show.email: The email of the user's avatar you'd like to show (you can use either id or emailsize: The width and height in pixels of the avatar.alt: The alt="Text" that should appear for the image.default: A default image for users without a gravatar.The [is_user_logged_in] shortcode should be used to check if a user is currently logged into the site. If not, the content will be hidden.
[is_user_logged_in]This content is only shown to logged-in users.[/is_user_logged_in]This shortcode has no parameters.
If you have content you only want to show to subscribers of your feed, wrap it in this shortcode:
[feed]This content will only be shown in feeds.[/feed]This shortcode has no parameters.
The [login-form]shortcode produces a form for users to log into your site. More than likely, you'll want to use the Login Form widget for something like this. The shortcode should be used like so:
[login-form]This shortcode has no parameters.
The Template Tags component gives you additional functions (i.e., template tags) to use within your WordPress theme.
This template tag checks if the currently logged-in user has a specific role.
<?php if ( function_exists( 'current_user_has_role' ) && current_user_has_role( 'editor' ) ) { ?>
Only users with the editor role can see this content.
<?php } ?>This function will check if a specific user (by ID) has the given role.
<?php if ( function_exists( 'has_role' ) && has_role( 'editor', 30 ) ) { ?>
If the user with the ID or 30 has the editor role, this will be shown.
<?php } ?>The members_list_users() template tag works much like wp_list_authors(). This is also a widget called Users if you're using the Widgets component.
<?php if ( function_exists( 'members_list_users' ) ) { ?>
<ul>
<?php members_list_users( array( 'order' => 'ASC', 'orderby' => 'display_name' ) ); ?>
</ul>
<?php } ?>This function currently only takes in a few parameters, but I hope to work more in sometime in the future.
order: Takes in ASC (ascending) or DESC (descending). The default is ASC.orderby: What to order your users by. The possible values are display_name, ID, and user_login. The default is display_name.include: Comma-separated list of user IDs to include in the list.exclude: Comma-separated list of user IDs to exclude from the list.limit: The number of users to show. Note that large lists can really hit the database.show_fullname This is set to true by default. If set to false, the users' display names will be shown.echo: Set to false to return the list of users rather than displaying them on screen.A template tag to be used within The Loop for showing the current author's avatar, name (linked to author archive), and bio. A good place to use this is in your single.php template after the post.
<?php if ( function_exists( 'members_author_profile' ) ) members_author_profile(); ?>The widgets component provides easy-to-use widgets for your site. They can be used in any WordPress widget area (provided by your theme). Currently, there's the Login Form and Users widgets.
The Login Form gives you a login form. It's a mixture of a text widget and login form. It can also show your avatar.
It's pretty straightforward, but I'll provide more documentation later.
The Users widget allows you to list users in any widget area. It's based off the members_list_users() function, so all of the parameters are the same.
The Private Blog component makes sure that only logged-in users can see anything on your site. If a user visits your site and is not logged in, they are immediately redirected to your wp-login.php (WordPress login) page.
Note that feeds are not currently blocked with this component, but it's likely they will be later with an introduction of a feeds component.
In plugins and your theme template files, you might sometimes need to check if the currently logged in user has permission to do something. We do this by using the WordPress function current_user_can(). The basic format looks like this:
<?php if ( current_user_can( 'capability_name' ) ) echo 'This user can do something'; ?>For a more practical situation, let's say you created a new capability called read_pages. Well, you might want to hide the content within your page.php template by adding this:
<?php if ( current_user_can( 'read_pages ' ) ) { ?>
<?php the_content(); ?>
<?php } ?>Only users with a role that has the read_pages capability will be able to see the content.
The components API is for developing new components to use within the Members plugin. This API is meant to be used so that users can select which components they want to run. While it is possible to build something on top of the Members plugin without using the components API, this provides a way to jump start development and keep code clean and organized.
To create a custom component, you need to use the register_members_component() function in your plugin. You should wrap it within its own function.
function register_my_components() {
register_members_component( array(
'name' => 'component_name',
'label' => __('Component Label', 'members'),
'callback' => 'component_callback_function',
'hook' => false,
'description' => __('Add a description of your component.', 'members')
) );
}name: A unique name for your component (do not localize this, use spaces, or hyphens).label: The name of the component that users will see (should be localized).description: The description of your plugin (should be localized).callback: The function to call for your component.hook: The action hook used to fire your callback function.Once you've done the above, you need to add your function to the members_register_components hook.
add_action( 'members_register_components', 'register_my_components' );If you want to check if a component is active (nice way to only load code if needed), you can use the is_active_members_component() function.
if ( is_active_members_component( $component_name ) ) {
/* Load files or do something else. */
}If you need to grab a component object, you can do so with the get_members_component() function.
$component = get_members_component( $component_name );
echo $component->name;
echo $component->label;
echo $component->description;
echo $component->callback;
echo $component->hook;Your plugin/theme can add new capabilities to the Edit Roles component if needed. This will allow users to easily select the additional capabilities for whichever roles they choose.
add_filter( 'members_get_capabilities', 'my_plugin_new_caps' );
function my_plugin_new_caps( $capabilities ) {
$capabilities[] = 'cap_name_1';
$capabilities[] = 'cap_name_2';
$capabilities[] = 'cap_name_3';
return $capabilities;
}Note that you need to respect the existing capabilities and return the original array.
In WordPress, you can use the current_user_can() function to check if the current user has a particular capability. Since you don't know whether a user has this plugin installed, you might want to check first.
The members_check_for_cap() function (only use in admin) checks if any role has a particular capability. This can be useful in setting up something like admin menus. For example, you can set up a theme settings menu for users that have the edit_themes capability. But, if this plugin is installed and a user has the edit_my_theme capability, that'll be used instead.
if ( function_exists( 'members_check_for_cap' ) && members_check_for_cap( 'some_cap' ) ) {
/* Do something if any role has the 'some_cap' capability. */
else {
/* Do something for people without the plugin. */
}Some plugins and themes might rely on the old user level system in WordPress. WordPress still has legacy support for these, but I'm hoping to continue phasing out the use of them.
By default, the levels aren't shown. They still exist, but are tucked away behind the scenes. If you need to control who has what level (levels are just capabilities), add this to your plugin or your theme's functions.php:
remove_filter( 'members_get_capabilities', 'members_remove_old_levels' );I run a WordPress community called Theme Hybrid, which is where I fully support all of my WordPress projects, including plugins. You can sign up for an account to get plugin support for a small yearly fee ($25 USD at the time of writing).
I know. I know. You might not want to pay for support, but just consider it a donation to the project. To continue making cool, GPL-licensed plugins and having the time to support them, I must pay the bills.
Members is licensed under the GNU General Public License, version 2 (GPL).
This plugin is copyrighted to Justin Tadlock.
2009 © Justin Tadlock