It’s long been widely accepted that one of the biggest advantages WordPress has over its competitors is its admin user interface. It is, on the whole, very easy and intuitive to use. Furthermore it’s being constantly refined and improved, with the media upload screen now one of the many things under scrutiny. Unfortunately, there is something that the WordPress-UI team have no control over, which consistently undoes all their hard work: plugins and themes.

Your plugin’s UI (I shall use the term plugin in this article, but the same applies to your theme's UI) is one of the most important aspects of your plugin. It defines how people interact with it, how easy it is to use, and perhaps even how much they enjoy using it. This is the ultimate aim of your plugin: to make a particular task, or tasks, easier for your end user (in fact this is the seemingly forgotten aim of computers themselves). The UI should be attractive, but ultimately it should be functional. When deciding how to layout your plugin, you need to decide how to make your plugin easy to use - better yet, get feedback - this is essentially what WordPress is doing.

Introduction

In recent weeks and months there’s been a lot of discussion about how WordPress’ usability could be improved - ranging from general UI improvements to accessibility (if you don’t think accessibility is a problem for either WordPress or your plugin, I’d recommend checking out Graham Armfield’s excellent talk from WordCamp Edinburgh). More recently, Tom McFarlin prompted a lot of discussion on integrating with WordPress’ UI. The discussion moved onto the need for a UI guideline for plugin authors to help them ensure their plugin integrated seamlessly into WordPress. This guideline is starting to take shape in the form of the WordPress User Interface Guidelines.

In this series we’ll be looking at steps that you can take to help integrate your plugin into WordPress’ UI. In this article, we’ll focus on some basic guidelines, as well some the of the UI API available to you. Please note these guidelines are in no way 'official'. In the subsequent articles we’ll be looking at more ‘practical’ examples, including using metaboxes on custom admin pages, and the use of WordPress’ admin pointers.

Why Integrating With WordPress Matters

User Experience

This is the most important reason. The core purpose of both the WordPress UI and your plugin or theme is to facilitate content management and production for the end user. It is to enable the user to achieve a specific purpose. If your plugin or theme introduces a UI that is vastly different from WordPress’ then you’re forcing the user to learn a completely new interface. In doing so you’re making it harder for them and they’ll probably uninstall your plugin and find another. Consistency is key here.

Secondly, it’s just ugly when a plugin or theme sticks out like a sore thumb. The WordPress admin is (mostly) beautifully consistent - and plugins which don’t fit in are just an eye sore. This is not even to say that the plugin’s own UI is particularly ugly. It may well be that the plugin’s interface is slick - but it will still look out of context.

The best plugins fit seamlessly into WordPress to the extent where it’s nearly impossible to tell where WordPress itself stops and the plugin starts. It’s these plugins that users enjoy using, largely because they look like they're meant to be there. Plugins should extend WordPress - not make it into a CMS Dr. Frankenstein would produce.

Future Proof Your Plugin

WordPress provides a lot of ways to help you ‘fit in’ with WordPress. It also provides a lot of CSS on the admin pages which you can take advantage of. Doing both of these is an effective way of ‘future proofing’ your plugin’s UI. Any changes made to WordPress will be reflected on your plugin too. On the other hand if you ‘go it alone’ with your admin UI - each WordPress update brings with it an increased chance that your plugin UI will conflict with WordPress. By using WordPress’ styles and layouts, you make life a bit easier for yourself, as well as your users.

Unofficial Admin UI Guidelines

Reduce Your Plugin Footprint

You might think your plugin is the most important thing in the repository, and it might be the best of its kind out there. But does it really need prime spot on the admin menu? An important aspect of any user interface is a simplicity that allows users to find what they want quickly. Cluttering up the menu is the opposite of this.

Your plugin might not even need its own sub-page. All default settings pages can have sections added to them. If your plugin has only a few settings, and they wouldn’t be out of place in an existing settings page, you should consider this.

If your plugin does require a place on the top-level menu think carefully about where it should go. The admin menu is split up into three sections: the dashboard, content management, and settings. Where your top-level menu item should go depends on what the primary purpose of your plugin is. If it’s producing, editing, and managing content - it should go in the middle. If its purpose is maintenance, performance, or configuration (for example, integration with a third-party software, caching, or back-up plugins) these should probably go at the bottom.

Finally, your plugin shouldn’t over impose itself. Littering your plugin with ‘donate’ links, advertisements, or feeds from your blog will not endear your plugin to your users. Plugin ‘branding’ should be avoided, or at least subtle enough not to conflict with WordPress’ UI.

Although this might not effect the usability of the plugin, integrating into the look of WordPress makes for a seamless, and better user experience. It’s not that the plugin’s brand might be terrible (some look fantastic) - but more that they look out of place.

Decisions Not Options

Most plugin authors, understandably, want their plugin to appeal to as wide range of users as possible. An unfortunate side effect is that the user is presented with a cock-pit of options. Part of the WordPress philosophy is decisions not options:

As developers we sometimes feel that providing options for everything is a good thing, you can never have too many choices, right? Ultimately these choices end up being technical ones, choices that the average end user has no interest in. It’s our duty as developers to make smart design decisions and avoid putting the weight of technical choices on our end users.

There are two things that need to be balanced: on one hand you want users to be able tweak the way your plugin behaves. On the other, too many options can make finding any of them difficult, and can leave the user bewildered and frustrated. There’s no one-size-fits all here, and it's a judgement that should be made on your experiences of what your users ask for.

However, options are not the only way of allowing your plugin to be tweaked:

• Use plugin hooks. Sometimes, particularly when dealing with the more technical aspects of your plugin, it’s more appropriate to introduce one hook, to allow a setting to be changed, or an action triggered, than it is to introduce an array of options to achieve the same purpose.
• Providing overridable plugin templates. For example, in my plugin Event Organiser, basic templates are included, which by default, are used. The user can copy these into their theme, and edit them there to override it. This gives the user complete control, but doesn’t need an extensive settings page.
• Be smart. For example, recently I created a payment log which included a date column to be formatted using just numbers. But American users quite often expect dates to be in mm-dd-yyyy format, while Europeans would expect dates in dd-mm-yyyy format. The log formatted the dates according to the site’s timezone (although a screen option was added in case it needed to be changed).

Plugin Settings Go Under…

The settings menu item? Or your own top level menu? I’ve even found some in the ‘Plugins’ menu item before now. There’s a lot of debate about this. For the majority of plugins, which don’t need their own top level menu, the decision is made for them. But what about plugins that do? I can only give my opinion here. A convincing point is that some users expect to find the plugin settings under the plugin’s menu. In some cases though I think this exposes a misuse of the admin menu - the menu should not be the "plugin’s menu", but a menu associated with some sort of task (like creating and editing posts, viewing comments etc). Just as WordPress separates tasks from settings, so should plugins.

Secondly, changing settings is a task in its own right - one that is done rarely, often only after installing WordPress or a plugin. Because it is not regularly visited, placing it under the Settings menu item tidies up your plugin’s sub-menu for everyday use.

If you want to ensure your settings page is not missed, I encourage you to add a link to it under your plugin’s name on the 'Plugins' page. This is the page the user will land on when they activate the plugin, and so will make finding your settings much easier.

Here's an example of how to achieve this:

add_filter('plugin_action_links', 'wptuts_plugin_settings_link', 10, 2);
function wptuts_plugin_settings_link($links, $file) {

	if ( $file == 'myplugin/myplugin.php' ) {
		/* Insert the link at the end*/
		$links['settings'] = sprintf( '<a href="%s"> %s </a>', admin_url( 'options-general.php?page=my_plugin_settings' ), __( 'Settings', 'plugin_domain' ) );
	}
	return $links;

}

Page Tabs

If your plugin settings do not fit comfortably onto one page, you should consider using tabs to split them up. WordPress uses tabs on the Appearance -> Themes page, and these can be added to your settings (or custom admin pages, if needed). When using page tabs there’s very little reason not to use WordPress’ tabs. How to do this was covered in Tom McFarlin’s Settings API series here on Wptuts+.

But what if you need too many tabs? Horizontal tabs don’t scale particularly well - and overflowing tabs can look confusing and ugly. This plugin makes a good attempt at dealing with a lot of settings pages - but the lines of settings still make it overwhelming:

Let’s assume that all these tabs are necessary (which they probably aren’t), then you might decide vertical tabs are a more suitable solution. I've seen a few themes implement vertical tabs (often poorly), usually using their own styling. While WordPress doesn’t use vertical tabs (with the exception of the help tabs) - you should base your designs on what is available to you. Feel free to experiment, but try to keep it looking native to WordPress - it'll be interesting to see what people come up with.

Admin Notices

WordPress has two types of admin notices: general notices, and error messages - styling them yellow and red respectively. If your plugin needs to display a notice to the user, you should use one or the other depending on the context of the message.

Using WordPress’ notice API is a very easy way of giving the user a consistent experience. An example of how to do this is:

/*
 * Admin notice nag - displays a message
 */
/* Display a notice that can be dismissed */
add_action( 'admin_notices', 'wptuts_admin_notices' );
function wptuts_admin_notices() {

	printf( '<div class="updated"> <p> %s </p> </div>', esc_html__( 'This is a yellow notice', 'plugin_domain' ) );

	printf( '<div class="error"> <p> %s </p> </div>', esc_html__( 'This is a red error warning', 'plugin_domain' ) );

}

You should, obviously, only display messages which are relevant - which means conditionally showing your notices on only certain screens, and for certain users. To do this you can use get_current_user_id() and get_current_screen():

function wptuts_admin_notices() {

	// Display notice if user has '_wptuts_display_notice' stored and on screen with id 'portfolio'
	$screen_id = get_current_screen()->id;
	$display_notice = get_user_meta( get_current_user_id(), '_wptuts_display_notice', true );

	if ( $display_notice && 'portfolio' == $screen_id ) {
		// Display notices
	}

}

For persistent notices you should include a dismiss link to allow the user to hide the message. Like the following example:

/* Conditionally display notice */
add_action( 'admin_notices', 'wptuts_persistant_notice' );
function wptuts_persistant_notice() {

	/* Check that the user hasn't already clicked to ignore the message */
	if ( ! get_user_meta( get_current_user_id(), '_wptuts_hide_notice', true ) ) {

		printf( '<div class="updated"> <p> %1$s  | <a href="%2$s"> %3$s </a> </p> </div>', __( "This is a persistent notice. To hide it click 'dismiss'", 'plugin_domain' ), esc_url( add_query_arg( 'wptus_nag', wp_create_nonce( 'wptus_nag' ) ) ), __( 'Dismiss', 'plugin_domain' ) );
	}
}

/* Hide notice */
add_action( 'admin_init', 'wptuts_hide_notice' );
function wptuts_hide_notice() {
	if ( ! isset( $_GET['wptus_nag'] ) ) {
		return;
	}

	// Check nonce
	check_admin_referer( 'wptus_nag', 'wptus_nag' );

	// updated user meta to indicate dismissed notice
	update_user_meta( get_current_user_id(), '_wptuts_hide_notice', 1 );
}

You can also use ajax to dismiss admin notices, but you should also provide a non-JavaScript fallback.

Buttons

WordPress provides styling for two ‘types’ of buttons: ‘primary’ and ‘secondary’. The former appears as a blue button and there should only ever be one of these buttons on any given page. The secondary button is a white button. WordPress provides a couple of helper functions for creating buttons: get_submit_button() / submit_button() functions.

submit_button(
	__( 'Submit text', 'plugin_domain' ),
	'primary',
	'submit'
);

Links

Actions that are ‘destructive’, for example a link that deletes something, should be red. There are often classes you can use (like trash) that will do this for you. For other links, WordPress automatically sets the colours and this shouldn’t be overridden.

Links on tables (such as the posts table) should filter the table, and not redirect the user. The exception is ‘action links’, which appear when you hover over a row (for example the ‘edit’, and ‘trash’ links).

Screen and Menu Icons

You can (and should) use page icons on your admin pages. Ideally these should be custom (avoid re-using the same icons for different purposes). To change the icon for a custom post type you can (conditionally) print CSS in the admin head to override the default icon image.

You must ensure that you are only doing this for your post-type’s pages, so as not to override icons on other pages. Here's an example of how:

<?php
// Add screen icon
add_action( 'admin_head', 'wptuts_event_screen_icon' );
function wptuts_event_screen_icon() {
	$post_type = get_current_screen()->post_type;

	if ( 'event' == $post_type ) {
		?>
		<style type="text/css">
			#icon-edit {
				background: url(<?php echo plugin_dir_url(__FILE__ ); ?>css/images/icon-32.png);
			}
		</style>
		<?php
	}
}
?>

For custom admin pages you can also use screen_icon(). This prints the HTML for the screen icons. It takes one (optional) argument: either a string (used in the ID attribute of the icon container) or a screen object which is used to create an appropriate ID attribute. For example: screen_icon('myplugin'); will print something like:

<div id="icon-myplugin" class="icon32">
	<br />
</div>

Using the admin_head hook as above, you can target #icon-myplugin and provide a background image.

For custom post types, the menu can be specified when you register the post type:

register_post_type( 'event', array(
	...
	'menu_icon' => plugin_dir_url( __FILE__ ) . 'css/images/icon-32.png';
	...
));

For tabs added to the menu using add_menu_page you can specify the icon as one of the arguments:

add_menu_page(
	__( 'Page title', 'plugin_domain' ), // Used for the title tags of the page
	__( 'Page title', 'plugin_domain' ), // Page as it appears on the menu
	'manage_options', // Capabilities to access this page
	'wptuts_custom_page_callback', // Callback which prints the content of the page
	plugin_dir_url( __FILE__ ) . 'css/images/icon-32.png'
);

Screen and menu icons should be grey-scale. A colourful menu icon more obviously sticks out, and looks ‘odd’ to say the least. Regardless of how good the icon is, it ruins the aesthetic of the admin sidebar. Worse still, a colourful menu icon says to me that you’re not bothered about ‘playing nice’ with WordPress’ UI, so I’m going to suspect that the plugin's code doesn’t ‘play nice’ with WordPress either.

Remember that the screen icon needs to work well on three different backgrounds:

Help Tabs

It’s always a good idea to give your users some extra guidance in case they need it. However, including it on the page can introduce clutter, (and help text is never an alternative to intuitive UI design). WordPress allows you add content to the ‘help’ tab that appears on the top right of the screen. (Screen options and help tabs can often be overlooked by users, however there are early discussions on how to improve them. Please note these are discussions only and nothing has been decided).

The ability to add ‘contextual help’ has been around since 2.7, but since 3.3 the help tab got a bit of a revamp, introducing a tabbed help bar.

You can add your own tab with the following code. It’s important you only add the contextual help on the appropriate screens. You should also check that the method WP_Screen::add_help_tab exists, as otherwise pre-3.3 versions of WordPress will throw a fatal error.

add_filter( 'contextual_help', 'wptuts_contextual_help', 10, 3 );
function wptuts_contextual_help( $contextual_help, $screen_id, $screen ) {

	// Only add to certain screen(s). The add_help_tab function for screen was introduced in WordPress 3.3.
	if ( $screen_id != 'screen_id' || ! method_exists( $screen, 'add_help_tab' ) )
		return $contextual_help;

	$screen->add_help_tab( array(
		'id'      => 'wptuts-overview-tab',
		'title'   => __( 'Overview', 'plugin_domain' ),
		'content' => '<p>' . __( 'Some help text here', 'plugin_domain' ) . '</p>',
	));
	return $contextual_help;
}

Tables

When using tables on the admin side of your plugin it is almost always better to use the same styling that WordPress uses for its tables. The layout and appearance is ideal for presenting data such as product sales, activity logs, etc, providing your users with a consistent interface. Importantly, the users will instinctively expect that hovering over a row will reveal ‘action links’, and that links in the columns will filter the table. Don’t be afraid to adapt your table to your specific needs (changing the width of columns, custom styling for images in the column, etc.) - but it’s important to present your data in a way that will be broadly familiar and intuitive to your users.

By far the easiest way of replicating WordPress’ admin table is by extending the WP_List_Table class. There are numerous articles explaining how to do this - but the best ‘tutorial’ is the Custom List Table plugin, which provides you with a worked example and is incredibly well commented. However, be warned, that although the Codex says the WP_List_Table class is suitable to be extended by developers, the actual source code marks this class as ‘Private’. Potentially, WordPress could change the class - and if such changes do happen you would need to check that they do not break your table.

jQuery UI Styling

All of jQuery UI is provided in WordPress (and if your plugin uses any, it should be using the WordPress provided scripts). Unfortunately, there is not necessarily the corresponding CSS styles. This is currently left for plugins to provide. However, there is potential for this to change with this Trac ticket. Helen Hou Sandi, core WordPress developer, has worked on two jQuery UI themes which complement WordPress (one for each admin colour scheme). There’s no guarantee this will make it into WordPress* - but in any case, you should download both themes and use them with your plugins.

A demo plugin can be downloaded here. From that you can also extract the two themes:

• jquery-ui-fresh.css (the default grey colour scheme)
• jquery-ui-classic.css (the blue colour scheme)

Place these in your plugin folder. When you register scripts, use the theme selected by the user:

add_action( 'wp_enqueue_scripts', 'wptuts_register_scripts' );
function wptuts_register_scripts() {

	if ( 'classic' == get_user_option( 'admin_color' ) ) {
		wp_register_style ( 'wptuts-plugin-jquery-ui-css', plugin_dir_url( __FILE__ ) . 'jquery-ui-classic.css' );
	} else {
		wp_register_style ( 'wptuts-plugin-jquery-ui-css', plugin_dir_url( __FILE__ ) . 'jquery-ui-fresh.css' );
	}

}

Then you can call wp_enqueue_style( 'wptuts-plugin-jquery-ui-css' ) where you need to (obviously, you should give the styles a different handle, unique to your plugin). This alone can go a long way in helping give your plugin a look consistent with WordPress.

*If it does make it into WordPress, then you can remove the above from your plugin and use the WordPress provided styling instead.

Thinking Outside of the Box

Not all content in WordPress is a post, comment, or attachment and sometimes the existing UI doesn’t provide what you need. In these cases it’s just not appropriate to impose upon it the ‘post’ structures that exist natively. For example, Gravity Forms is a plugin which allows you to add and manage forms to your site. If they restricted themselves to the native WordPress UI, presenting forms as almost like posts, for example, the result would be a worse user experience and fewer sales for Gravity Forms.

Giving your users the best UX is not simply putting everything inside lists and metaboxes. If your plugin needs to present information in a way that is alien to the native WordPress UI - feel free to get creative and experiment. But how do you draw the line between being creative and integrating with the WordPress UI? This was something brought up in the comments of Tom’s post mentioned earlier. The truth is that it comes down to personal judgement and experimenting to see what works. Gravity forms, on the whole, do this well:

Importantly, although the WordPress UI might not provide precisely what you need - there is a lot to draw inspiration from. For example, if you want your users to be able to drag-and-drop items - you can look to the Menus page for guidance. You shouldn’t discard the admin UI entirely. Some ‘principles’ of the admin UI (some listed above) are translatable regardless of what you are trying to achieve, such as: the use of colour, links, buttons and icons. And the details matter - getting the gradients, radius and font right are important to maintain consistency, particularly when you are doing something ‘different’. For the drag-and-drop example, you might want to reuse the grey place-holder with a dashed border.

This attention to detail might seem difficult - but getting it right is actually the lazy (and in this case, appropriately so) thing to do. WordPress adds a lot of styling to the admin page - and for the most part this will be inherited automatically by your plugin. In other cases it’s just a matter of adding the right classes to your elements.

Conclusion

The following articles in this series will be a lot more ‘practical’, but hopefully this article has illustrated some immediate and easy steps to providing your users with a more consistent admin. The guidelines listed here are in no way official, and nor are they exhaustive - and I would welcome discussion and suggestions!