Participants Database has two basic roles for accessing and interacting with the plugin in the backend: Plugin Admin and Record Edit. By default, these roles correspond to the WordPress roles of Administrator and Editor.
This means that if your WP role is Editor, you will be able to edit records, add new records, list records, etc. An Administrator will be able to additionally edit the configurations, delete records, perform CSV exports, and things like that.
WordPress roles are worked with at the code level by testing for a particular capability, depending on the specific context. The plugin uses two standard capabilities for determining which plugin role a particular user has. For admins, it’s ‘manage_options’ and for plugin editors, it’s ‘edit_others_posts’. So, this means that any role that has the ‘edit_others_posts’ capability will be able to edit Participants Database records.
Using Custom Roles and Capabilities
When you set up custom roles, you give those roles capabilities. These capabilities, naturally, determine what a user with one of your custom roles can do. If you want your custom role to work with Participants Database, they should have one of those standard capabilities: ‘manage_options’ for admins and ‘edit_others_posts’ for editors.
What if you don’t want your roles to have either of those standard capabilities? For that, you’ll need to define custom capabilities. This is fairly easy to do. First, determine the name of your custom capabilities, then assign those capabilities to the custom roles you’ve created.
To show you how that could work, let’s say you want to define two custom roles, and those people will mostly just be able to work with Participants Database. You would give those roles some basic capabilities (such as ‘read’), plus a custom capability that is just for Participants Database.
In this example, there are two roles: PDB Admin and PDB Editor. PDB Editor will be given the custom capability ‘edit_pdb_records,’ and the PDB Admin role will be given the custom capability ‘configure_pdb.’ You’ll give the admin ‘edit_pdb_records’ too, so that your plugin admin can do all the things.
Now, to actually implement these capabilities and use them to determine what the user can do, we need to construct a filter. The filter takes the plugin’s default capabilities for each role and changes them to our custom capabilities. Once that is done, the custom roles will have access to Participants Database in the backend.
Putting in the Filter
For those of you familiar with WordPress coding practices, you’ll know there are several ways to place the filter code. I am providing it to you in the form of a plugin (because that is the easiest for novices to use) but it could easily go into your theme functions file. If you’re a more advanced coder, you’ve got a script somewhere that defines your custom roles, and that is really the best place to put our filter so all the functions relevant to the custom roles is in the same place.
Please Note: you must have these custom capabilities in your current role. If you do not, Participants Database will disappear from the admin because it’s only visible to those with the custom roles installed by the example plugin below.
This plugin must be used with some kind of WP role editor plugin so that you can assign the custom capabilities to your roles.
Many people will be using a plugin from the WP repository to define their custom roles, so installing our filter as another plugin is a logical way to add that customization. Be sure that you are adding these custom capabilities to your roles in the role editor plugin. It won’t work without that because your roles won’t have the needed capabilities.
Here is the filter in the form of a plugin. See below the code window for instructions on how to install it.
To install, first click on the gist page link at the bottom left of the code window above. Then click on the “Download Zip File” button on the gist page, download the file, then install it using the Plugins/Add New menu item. There is a button for uploading the zip file at the top of the add new plugin page.
If you need to edit the plugin (for instance, to use different names for your custom caps) you can use the plugin file editor in the WP admin.
I’ve published a couple of other tutorials on this topic, take a look at these for another look at using roles and capabilities with Participants Database.
Advanced Use of the Filter
This filter doesn’t try to change the specific things that each role can do. This is possible, however, by using the “context” value to determine which capability to return. The Backend User Access Control article above gives a list of possible contexts to filter for.