@tech

What’s that mouthful title all about?  I’ve been working on a new WordPress plugin for a client which allows an easy display of small bits of info on their home page which is not contained in posts or pages and is easy to update.  Not a monumental task, until you want to allow users who are not administrators the ability to access and save settings for the plugin.

The basic premise is I don’t want to create a post or a page that only contains 20 words or less of text.  It needs to have a bold headline, an optional subhead, and optionally include a link to a page with more info about the tiny blurb of text.  Rather than try and continually instruct new editors in the fundamentals of HTML formatting, I opted for capturing these small bits of info as plugin options.  In doing so I could then utilize CSS to do the simple formatting for displaying all of the bits properly, including the optional features.

It works great by the way.  I hope to release it to the WordPress community in the not-too-distant future.  But I hit a snag.  Plugins by default are reserved for administrators to manage and edit, and my client needs to allow others who simply can’t have the power of an administrator to blow up the site, to be able to edit these texts.  No problem, it’s WordPress after all.  Right?

I spent hours searching the web trying to find the solution to this.  Not only on WordPress.org but everywhere.  After the first hour came the incredulous grunt from not easily finding the answer.  Not far beyond that was disgust from the lack of documentation on this.  With all the bells and whistles built in to WordPress, how is it this doesn’t seem to be easy to accomplish?

Throughout all of my searching I was able to find bits and pieces that solved part of the equation, but none of them brought the entire solution together in one place.  Hence this post.  Through much trial and error I’ve been able to boil this down to a fairly simple solution.

One Caveat
This post assumes you are already familiar with creating plugins and is NOT an exhaustive tutorial on that.  If you aren’t already familiar with creating plugins head on over to WordPress.org first to familiarize yourself with the idea.

And A Quick note
For any of the code listed here you’ll want to replace ‘myplugin’ with what ever unique identifier you choose for your plugin.

FUNCTIONS.PHP

First I’ll cover the way-too simple bit which needs to be in your theme functions.php file.  We will declare a global variable and give it the value ‘editor’.

/* ALLOW PLUGIN EDITING FOR EDITORS */
if ( is_admin() ) {
	$myplugin_permission = 'editor';
}

Capturing the declaration in the test is_admin() simply checks if the admin page has been called and if so only set the variable at that time.  This could probably be omitted and simply declare the variable without it.

THE PLUGIN

A WordPress plugin can be anything from simple to complex.  Ours needs to step a bit beyond simple in order to allow editing to any user who is not an administrator.

First, the settings for your plugin need to be registered.  To do that we need a function such as this:

function register_myplugin_content_settings() {
	register_setting( 'myplugin_group', 'myplugin_option' );
	register_setting( 'myplugin_group', 'myplugin_option2' );
	register_setting( 'myplugin_group', 'myplugin_option3' );
	register_setting( 'myplugin_group', 'myplugin_option4' );
}

The first value in the register_setting() function is the name of your plugin settings group which needs to be consistent throughout.  The second value is what ever your setting name is.  You’ll need to register every setting your plugin uses that you wish to make available for editing by users other than admins.  If you have 2 setting you’ll call this function twice.  10 setting and you’ll call it 10 times.  You get the picture.

Next we’ll create another function that handles all of the permissions issues, calls the first function to register your plugin settings, and then displays a menu item for your plugin settings page.  Once again, I’m assuming you already have a plugin you’re applying this to.

function myplugin_plugin_content_settings() {
	// determine permission
	global $myplugin_permission;
	$myplugin_defaultCap = 'administrator';
	if ($myplugin_permission == 'editor'){
		function extend_myplugin_capability( $capability ) {
		    return 'edit_pages';
		}
		// allows updating settings for editors
		add_filter( 'option_page_capability_myplugin_group', 'extend_myplugin_capability' );
		$myplugin_defaultCap = 'edit_pages';
	}
	//create new top-level menu
	// edit_pages allows admins & editors access but no one else
	add_menu_page('Home Page Boxes', 'Home Page Boxes', $myplugin_defaultCap, 'myplugin', 'myplugin_display_settings');
	//call register settings function
	add_action( 'admin_init', 'register_myplugin_content_settings' );
}

The first thing this function does is handle setting the plugin permission which allows anyone in the editor role to change the settings.

The function needs access to the global variable we define in the theme functions.php file.  To do this we add:
global $myplugin_permission;

Then we define a variable for the default editing permissions set to administrator with:
$myplugin_defaultCap = ‘administrator’;

Next we check the value of the permission variable and if it’s set to ‘editor’ we need to do some work:
if ($myplugin_permission == ‘editor’){

It’s important to note that we’re not simply checking to see if the value of $myplugin_permission is set, but we’re asking for a specific value.  This insures a typo won’t give edit permission to all users of the blog.  If the value isn’t set to ‘editor’ we skip this routine and permission to edit is reserved only for admins.

All of the lines within this routine except the last one, can easily be found elsewhere.  The function and add_filter call to the function are what modify the role of editor to allow access to modifying the plugin settings.  We’re changing the editor capabilities to add ‘edit_pages’.  This capability in WordPress is available only to administrators and editors.  By extending editing ability for this plugin settings to the ‘edit_pages’ capability we’re automatically giving access to editors.  If you would also like access to be given to authors as well set it to ‘edit_posts’.  To see the entire list of capabilities and who can do what take a look at “Roles and Capabilities” on WordPress.org.

The last line in this routine changes the default editing permission variable to the exact same capability we returned in the extend_myplugin_capability function, in this case ‘edit_pages’:
$myplugin_defaultCap = ‘edit_pages’;

Why not set it to ‘editor’ since we initially defined it as ‘administrator’?  The ‘administrator’ value is the default role that includes all of the admin capabilities in WordPress.  However if we set this to ‘editor’, an admin would be able to still edit the settings, but the settings page would not be available to an admin, only to an editor.  Since we want admins and editors to see the settings page we need to instead assign a capability both roles have access to.

Next up we call the add_menu_page function which creates your settings page within the admin area.  Having already created a plugin you should be familiar with this as all plugins require it or one of it’s sister functions.  The only difference here is we refer to the value held in $myplugin_defaultCap to set the capability, which is also the visibility, in determining who can access the settings page.  Here is where using this variable is important.  Accessibility to the settings page must change depending on the setting of the $myplugin_permission variable in the functions.php file.

The last step is to call the add_action function which registers the plugin settings.

The very last thing to do is to call the myplugin_plugin_content_settings function as such:

add_action('admin_menu', 'myplugin_plugin_content_settings');

WRAP UP

Here’s all of the code together that sits at the end of your plugin file:

function register_myplugin_content_settings() {
	register_setting( 'myplugin_group', 'myplugin_option' );
	register_setting( 'myplugin_group', 'myplugin_option2' );
	register_setting( 'myplugin_group', 'myplugin_option3' );
	register_setting( 'myplugin_group', 'myplugin_option4' );
}
function myplugin_plugin_content_settings() {
	// determine permission
	global $myplugin_permission;
	$myplugin_defaultCap = 'administrator';
	if ($myplugin_permission == 'editor'){
		function extend_myplugin_capability( $capability ) {
		    return 'edit_pages';
		}
		// allows updating settings for editors
		add_filter( 'option_page_capability_myplugin_group', 'extend_myplugin_capability' );
		$myplugin_defaultCap = 'edit_pages';
	}
	//create new top-level menu
	// edit_pages allows admins & editors access but no one else
	add_menu_page('Home Page Boxes', 'Home Page Boxes', $myplugin_defaultCap, 'myplugin', 'myplugin_display_settings');
	//call register settings function
	add_action( 'admin_init', 'register_myplugin_content_settings' );
}
add_action('admin_menu', 'myplugin_plugin_content_settings');

This may seem like a lot of hoops to jump through in order to achieve the desired permissions.  You could after all just hard wire the settings in your plugin and not bother with variables, both in the plugin and in the theme functions.php file.  That is true.  It would make everything a little cleaner and simple.  My intention however is to make my plugin available to multiple clients and to the WordPress community, where being able to change permissions to edit plugin settings with simply one line in the functions.php file would be a nice feature to have.

I hope this helps someone who may be struggling to find this solution as I did.