Loading JavaScript libraries

WordPress comes pre-packaged with a number of JavaScript libraries commonly used in user interface and Ajax development. The most common libraries — jQuery, Prototype, and Scriptaculous — are all bundled with WordPress, with jQuery being the preferred library for WordPress core development.

Ajax is an abbreviation for Asynchronous JavaScript and XML. Ajax is a loose-fitting word that describes highly interactive and transactional programming. It is notable because a Web site using Ajax can load data and perform actions transparently without the need for a refresh of the browser page. WordPress uses Ajax for a number of things, including Quick Edit functionality, category and tag creation from the Write screen, and more.

There are specific mechanisms in place to ensure that scripts are loaded with required dependencies and, of course, you as a plugin or theme developer, have the tools needed to allow your own JavaScript files and libraries to be loaded. WordPress does this using two functions: wp_enqueue_script() and wp_register_script().

Preparing JavaScript with wp_enqueue_script()

The first function used to add a script to the WordPress page load is wp_enqueue_script(). It takes all the JavaScript that it has to load and orders the scripts according to dependency. Typically, this function takes one or two arguments, unless it requires another library. Add-ons or plugins for existing JavaScript frameworks fall into the latter category. The first argument is a friendly name, or a handle, for the script. This handle might already exist if it comes preloaded with WordPress or if it has been registered (using wp_register_script()) somewhere else via the plugin. Otherwise, you can call a new piece of JavaScript anything as long as it is unique.

Using a non-unique name will not break WordPress, but it will replace a previously named script. Likewise, if another wp_enqueue_script() is used in another plugin or later in your own plugin and it uses the same handle, then whichever script is declared last takes precedence.

The second argument is the URL or path to the JavaScript file. It is optional, but if provided, it will also register the script with WordPress (similar to wp_register_script()). The third argument is a PHP array that lists each required library. Note that this list of libraries is by handle, not by URL. Optionally, you could add a fourth argument designating a version number of the library (such as 1.2 for jQuery 1.2), and a fifth argument that you would set to true if you want the JavaScript loaded in the footer or false if not. By default, the version is always the most recent and scripts are not loaded in the footer — they are loaded in the head. An example of loading the jQuery Cycle plugin is shown below:

Creating new Dashboard widgets

One of the longest-standing requests in the WordPress community was to provide a way for users to customize the WordPress Admin Dashboard. This request was not only addressed on a global level; it was also addressed on an individual user level. The Dashboard incorporates the “drag and drop” capability, enabling you to pull widgets around and place them in the Dashboard according to preference. You can also hide widgets. Even more importantly, plugin developers can now make new Dashboard widgets available. Creating new widgets for the Dashboard requires three things: a function that generates the HTML in a widget, a function that registers the widget for the Dashboard, and a line that hooks the second function into the proper hook. An example of this widget creation is shown below:

A great (but useless) Dashboard Widget

Hello World!

<?php
}
function example_db_widget_init()
{
wp_add_dashboard_widget(‘example-dashboard-widget’,’Example Widget’,
‘example_db_widget_html’);
}
add_action(‘wp_dashboard_setup’,’example_db_widget_init’);[/html]

In this code, the first function, example_db_widget_html(), provides HTML for the widget. Its formatting matches existing WordPress Dashboard widgets for consistency.

While the function in this example is fairly useless, it demonstrates exactly what this type of function should look like. You can use it for anything. Many plugin developers use data from third-party APIs such as Google Data APIs, Google Maps, or anything that fits their purposes.

The second function, example_dv_widget_init(), provides controller code that makes the widget available to WordPress. It only needs the wp_add_dashboard_widget() function. This function requires three arguments.

The first argument is a unique handler for the widget. This name will also become part of the CSS class that wraps around the HTML, so you can apply a custom look and feel for the widget.

The second argument is the display name for the widget. Finally, the third argument is the callback, or function name, that will provide the HTML. In this case, the callback is the name for the first function, example_db_widget_html.

Callbacks are used in programming to refer to an external function, class, or method that handles the actual execution of a code.

The third portion of this code hooks the example_db_widget_init() function into the wp_dashboard_setup hook. However, it is essential for the code to get “hooked” into the WordPress runtime.