How to use jQuery UI elements in the WordPress admin interface

- by

One thing I’ve been struggling with was to use jQuery UI elements in my plugins, for example jQuery UI Tabs. Even though the libraries are included with WordPress, I couldn’t get them to work.

Thanks to Pippin’s Plugins I could figure it out – thanks, Pippin!

My initial mistake was the way I created the admin page. WordPress provides so called wrapper functions that make creating an admin page very easy. For example, adding an admin page under the Dashboard works like this:

// Add a new submenu under DASHBOARD using wrapper function
function wpguru_plugin_starter_menu() {
	add_dashboard_page('Plugin Starter', 'Plugin Starter', 'manage_options', 'pluginStarter', 'pluginStarter');
}
add_action('admin_menu', 'wpguru_plugin_starter_menu');

Check the WordPress Codex for detailed explanations on how to create other pages: http://codex.wordpress.org/Administration_Menus

Even though this works fine, it’s not quite possible to enqueue scripts inside pages created like that – which is why it wasn’t working for me. Instead, as Pippin points out, you can create admin pages in a more complex fashion:

// Add a new submenu under DASHBOARD using array
function wpguru_plugin_starter_menu() {
	global $starter_plugin_admin_page;
	$starter_plugin_admin_page = add_submenu_page ('index.php', __('Plugin Starter', 'plugin-starter'), __('Plugin Starter', 'plugin-starter'), 'manage_options', 'pluginStarter', 'pluginStarter');
}
add_action('admin_menu', 'wpguru_plugin_starter_menu');

The reason for this extra complexity is that now we have a global reference to our menu page. This is important, because now we can

– use that reference to call scripts, and
– make sure we load our scripts only in our own admin page, not in every admin page there is

The latter point is rather important: just image what would happen if my scripts are loaded on every possible admin page, potentially causing problems with many other plugins and core functions.

I know this is complex stuff, so please bear with me before we start loading those builtin scripts. Because before we do, we probably have a js file of our own we want WordPress to load on our admin page. To make that possible, we’ll have to register it first, like so:

// register our own JS file
function starter_plugin_admin_init () {
	wp_register_script ('custom-starter-script', plugins_url( '/starter-script.js', __FILE__ ));
}
add_action ('admin_init', 'starter_plugin_admin_init');

Nothing is happening just yet, other than WordPress being aware that a new script has been registered and is ready for use if enqueued.

With our reference at hand, and our own script registered, let’s enqueue all the scripts we need to make our admin page look smashing. For this example, I’ll use jQuery UI Tabs, and of course my own custom-starter-script:

// now load the scripts we need
function starter_plugin_admin_scripts ($hook) {
	
	global $starter_plugin_admin_page;
	if ($hook != $starter_plugin_admin_page) {
		return;	
	}
	wp_enqueue_script ('jquery-ui-tabs');
	wp_enqueue_script ('custom-starter-script');
}
add_action('admin_enqueue_scripts', 'starter_plugin_admin_scripts');

You can find a list of libraries included in WordPress and their respective enqueue codes here: http://codex.wordpress.org/Function_Reference/wp_enqueue_script

If we’d build an interface without WordPress we’d also have to load the jQuery library (as jQuery UI needs it to work), however there’s no need for it when we’re using WordPress because it’s clever enough to load dependencies for us. Neat, huh?

Full Project Code

All that’s left now is to display the HTML for our tabs inside the main function. Rather than pasting that here, take a look at a full working project I’ve posted to GitHub called Plugin Starter. The code is well documented and contains links to further reading too.

I think I would never have understood this concept had it not been for Pippin’s excellent explanations, with many “how not to” examples. Check out his post here:
http://pippinsplugins.com/loading-scripts-correctly-in-the-wordpress-admin/

Now go forth and create many funky admin interfaces for themes and plugins!



If you enjoy my content, please consider supporting me on Ko-fi. In return you can browse this whole site without any pesky ads! More details here.

1 thought on “How to use jQuery UI elements in the WordPress admin interface”

Leave a Comment!

This site uses Akismet to reduce spam. Learn how your comment data is processed.