jQuery UI in WordPress 3 Admin Pages
This article covers getting jQuery, and in particular jQuery UI up and running inside the WordPress admin. At the time of writing the latest version of WordPress is version 3.01 and that is the version we shall be using. Also, WordPress is running locally (using WAMP Server 2.0) with the default Twenty Ten theme (1.1).
Originally, I wanted to use jQuery UI on a Plugin admin options page. However my initial attempts were unsuccessful so I thought that I would document, and share, my experiences. There isn’t a huge amount of WordPress specific jQuery UI resources around (although there are numerous basic jQuery tutorials around), so hopefully the information presented here will help others overcome the initial hurdles.
The main jQuery core library is enqueued by default in the WordPress admin, so you do not need to add this manually if you are only using jQuery without the jQuery UI libraries. You will need to load the jQuery UI libraries manually though, on the pages you need them, as these are only included by default on specific WordPress pages, such as the admin dashboard, edit posts/page screens etc. They are not included everywhere so you will have to take care of this yourself.
HINT: It is worth remembering at this point that jQuery is NOT enqueued by default on non-admin pages. So you need to add this manually if you want to use jQuery on your blog pages.
To access the jQuery UI library, I manually added a call to jQuery UI core from the admin_init hook. This ensures it is enqueued in the WordPress admin only (not on blog pages) which is exactly where I needed it. Checking the page source I could see that both libraries (jQuery core, and jQuery UI core) were being loaded into the page.
Initially I thought that the jQuery UI core had not loaded but quickly found out that is loaded by default in the footer. Because of this the next thing I did was to change my jQuery code run only when the document was loaded, by wrapping it inside:
// jQuery code here
Before it was simply:
// jQuery code here
You may have also noticed that I switched from the default jQuery syntax ($) to the no-conflict mode (jQuery) too. Again, nothing doing. What was going on?
I suspected that I needed to add in more UI libraries other than the core, but without further investigation I really did not know what to add in (other than add in the whole lot, which was tempting I admit!).
HINT: If you are adding in the jQuery, and jQuery UI libraries that ship with WordPress then you need to know the correct handle names when enqueueing them. To load in the jQuery UI core you use wp_enqueue_script( ‘jquery-ui-core’ ). I naively thought that you just used the file name, without the extension, as the handle (this is ui.core.js incidentally), which didn’t work! So how do you know what handles to use? Fortunately the WordPress codex comes to the rescues here. You can find a list here:
I am not sure how up to date this list is, how accurate, or for what version of WordPress/jQuery etc. but it is certainly a good starting point. After some more research it was clear that the jQuery UI core library that ships with WordPress does not contain a lot of necessary code (depending on what you need to do of course). For my purposes I wanted to use the jQuery UI accordion widget, so obviously needed to include this manually somehow. To add in an external jQuery file you have two choices:
- Include the necessary files with your Plugin.
- Reference a version from the web.
For the time being I am using the URL method. One advantage of this is that you will be taking advantage of cached libraries, should they have been loaded previously on another page. This can make your WordPress admin pages load faster.
After adding in the accordion widget things STILL weren’t working, and the reason this time was that I also needed to add in the widget library too! Also, by default your jQuery UI widgets will appear quite plain as they need some CSS to spruce them up a little bit. The jQuery theme roller is an excellent resource for this.
In the end, I got jQuery and jQuery UI working together satisfactorily by de-registering the default jQuery library and enqueueing the jQuery libraries using the Google API’s and adding URL references. The default jQuery loaded in the admin and external libraries did not seem to work too well together. There was obviously something else missing that needed it to work properly. The beauty of using the Google API if you want to do any jQuery UI code is that it is very simple to add in ALL UI functionality, which includes all widgets and effects, you don’t have to add in anything else. All you need to do is add in references to the libraries and you are away!
If you go to: http://docs.jquery.com/UI/Accordion for the accordion widget demo then view the source code you will see that the demo is referencing two scripts (jQuery, and jQuery UI – which includes all widgets and effects), and one style sheet. Enqueueing these same files in the WordPress admin (after de-registering the default jQuery library shipped with WordPress), and adding the demo code to a Plugin page finally worked!
The screen shot above shows the jQuery accordion widget (which has bounce slide effect incorporated) in action inside our new ‘Twenty Ten Styles’ Plugin. This Plugin which is currently under development, allows users to easily edit multiple styles in the new default WordPress theme – Twenty Ten.
Whilst you can certainly use the default jQuery and jQuery UI libraries that ship with WordPress, plus any other external jQuery UI libraries such as effects, accordion, tabs etc. that you need, I didn’t look any further (for now!) into how to get the default jQuery libraries to work in harmony with external libraries (there may have been issues with version conflicts too). I was more than happy to just de-register the default jQuery admin library and use the nice and compact Google API versions.
There is no right or wrong way to use jQuery in your admin pages. As long as all libraries are loaded (enqueued) properly then it is really a matter of preference. You can mix and match the jQuery libraries (i.e. the ones that ship with WordPress, and external libraries), or de-register the default library and load your own from an external source, or from files included with your Plugin.
Note, if you want to use the above method in your own Plugins then it is very important to make it work on your Plugin page ONLY. If you don’t then EVERY WordPress admin page will use your loaded jQuery libraries. i.e. the default jQuery (shipped with WordPress will not be active). In this case the main admin dashboard may not function properly (try it and see!), and you won’t be able to drag around the dashboard widgets. Also, the expand/collapse arrows to the right of each top level menu item will not work properly.
Other admin pages including Plugins may well be relying on the default WordPress jQuery too, and could exhibit unexpected behaviour. Also, if you de-register any jQuery libraries, before registering your own, you should make sure that you do so ONLY on your Plugin page. Otherwise you will be inadvertently breaking other admin pages as mentioned above.
If you are ever in doubt as to what styles/scripts have been added to your admin pages then always check the page source and see exactly what has been added to which pages.