Adding jQuery UI elements to WordPress page

Question

Using jquery-ui widgets requires a couple of steps.

You will need to add the appropriate markup for your widget. I’ll use the slider as an example. I just created a new page and added the markup below to it in the text editor in the WordPress admin:

    <div id="sample-theme-slider"></div>

You’re going to have to have your initialization logic for the widget to get rendered. Each widget has different config options and syntax, so refer to the jquery-ui docs for the proper code for the widget type you’re adding. Take note of any of the dependencies required for the widget.

EDIT: It appears WordPress core already has jquery-ui-core listed as a dependency for widgets when they are registered, so listing it as a script dep for JS isn’t required.

This is the initialization code for the slider widget:

    $( "#sample-theme-slider" ).slider();

So you should create a JS file. I’ll just stick mine in my sample-theme’s js folder and call it sample-theme-slider.js. In WordPress jquery is loaded in noConflict mode – so you can’t just use $ and have to type out jQuery, or add a wrapper to the code above. Taking this into account, this is what the contents of my sample-theme/sample-theme-slider.js looks like:

( function( $ ) {
    $( "#sample-theme-slider" ).slider();
} )( jQuery );

Now we need to enqueue our scripts and styles for our jquery-ui widget to work. This example will just keep it simple, and use procedural PHP, but you’re welcome to implement it however you want. Let’s create the skeleton of what we need to do first. I like to create methods for scripts, styles, and enqueue separately to keep things a little cleaner when I come back to them:

function sample_theme_scripts() {
    // ...
}

function sample_theme_styles() {
    // ...
}

function sample_theme_enqueue() {
    sample_theme_scripts();
    sample_theme_styles();
}

add_action( 'wp_enqueue_scripts', 'sample_theme_enqueue' );

Starting with the scripts we will need to add the js/sample-theme-slider.js file we created earlier.

You’ll want to register your script handle with wp_register_script(), we will call it sample-theme-slider. It’s generally a good practice to name your handle to follow suit with your theme’s naming conventions, and name the file to match the handle as well. You can see the parameters listed in the developer documentation, which the order in the code you placed in the question is incorrect for wp_enqueue_script():

    function sample_theme_scripts() {
        // Your script's handle.
        $handle="sample-theme-slider";
        // Path to the script to enqueue.
        $src = get_theme_file_uri( "js/{$handle}.js" );
        // Required dependencies.
        $deps = array( 'jquery', 'jquery-ui-slider' );
        // Your script's version.
        $ver="1.0.0";
        // Add the script to the footer.
        $in_footer = true;
        // Register the script handle.
        wp_register_script( $handle, $src, $deps, $ver, $in_footer );
        // Enqueue your script by handle.
        wp_enqueue_script( $handle );
    }

You’ll notice that in the $deps array – I listed the dependencies required for our script to work, which is the jquery-ui-slider script. To get any additional jquery-ui widgets to work in your script, you would simply add them to the array by script handle.

Now if you visit your page, you’ll see the markup is modified by jquery-ui-slider and everything is perfectly in place, except you don’t actually see anything. That’s because the jquery-ui theme hasn’t been loaded.
WordPress doesn’t include the theme by default, but you can load your own, or just pull it from a CDN.

We will take the same approach as we did in sample_theme_scripts(), and first register our stylesheet’s handle with wp_register_style() then use wp_enqueue_style() on our registered handle. I usually use the CDN route since it’s a benefit to have the file cached for commonly used libs, but there’s good arguments for including it local as well.

When we register our style with wp_register_style(), we tell it what the path is to the file we wish to add to the page. It’s basically the equivalent of linking a stylesheet in your HTML. To use a CDN like Google’s we need to look up the library we want to include (jquery-ui cdn). You’ll notice the links for the various version of CSS are formatted in this way:

https://ajax.googleapis.com/ajax/libs/jqueryui/X.X.X/themes/smoothness/jquery-ui.css

Where X.X.X is, is the version number. Since we are loading jquery-ui’s JS from WordPress core, you will want to get the matching version number. This can easily be done by inspecting the $wp_scripts global variable in PHP. When you register a script, we can optionally specify $ver as a parameter, which WordPress core does specify for jquery-ui.

If you were to do var_dump( $wp_scripts ); in PHP you would see jquery-ui-core listed, and you will see can access the version number for the registered script of the $wp_scripts object with:

$wp_scripts->registered['jquery-ui-core']->ver

If we use this for our enqueue style method when using a CDN – we can ensure that when WordPress Core updates their dependencies, we don’t have to worry about updating our version number or adding conditionals for older/newer WordPress versions (unless of course the script is removed from core). So to construct a path that works for the CDN – we just need to get that version number, so the URL for linking the stylesheet is correct:

 http://ajax.googleapis.com/ajax/libs/jqueryui/{$wp_scripts->registered['jquery-ui-core']->ver}/themes/smoothness/jquery-ui.css

Putting that into practice we would make our sample_theme_styles() method like this:

    function sample_theme_styles() {
        // Access the wp_scripts global to get the jquery-ui-core version used.
        global $wp_scripts;
        // Create a handle for the jquery-ui-core css.
        $handle="jquery-ui";
        // Path to stylesheet, based on the jquery-ui-core version used in core.
        $src = "http://ajax.googleapis.com/ajax/libs/jqueryui/{$wp_scripts->registered['jquery-ui-core']->ver}/themes/smoothness/{$handle}.css";
        // Required dependencies
        $deps = array();
        // Add stylesheet version.
        $ver = $wp_scripts->registered['jquery-ui-core']->ver};
        // Register the stylesheet handle.
        wp_register_style( $handle, $src, $deps, $ver );
        // Enqueue the style.
        wp_enqueue_style( 'jquery-ui' );
    }

As a last step – you probably want to add your own styles to the slider to match your theme’s look and feel. I usually add the stylesheet handle 'jquery-ui' we made to my main stylesheet’s array of dependencies when it’s enqueued. This way I know those styles are loaded first, and my specificity for overriding isn’t struggling more than necessary. I don’t know how you enqueue your main style.css – but you would just want to locate that in your theme and add the dependency!

So everything together looks like this:

sample-theme/js/sample-theme-slider.js:

( function( $ ) {
    $( "#sample-theme-slider" ).slider();
} )( jQuery );

sample-theme/functions.php:

// Register and enqueue scripts.
function sample_theme_scripts() {
    // Your script's handle.
    $handle="sample-theme-slider";
    // Path to the script to enqueue.
    $src = get_theme_file_uri( "js/{$handle}.js" );
    // Required dependencies.
    $deps = array( 'jquery', 'jquery-ui-core', 'jquery-ui-slider' );
    // Your script's version.
    $ver="1.0.0";
    // Add the script to the footer.
    $in_footer = true;
    // Register the script handle.
    wp_register_script( $handle, $src, $deps, $ver, $in_footer );
    // Enqueue your script by handle.
    wp_enqueue_script( $handle );
}

// Register and enqueue styles.
function sample_theme_styles() {
    // Access the wp_scripts global to get the jquery-ui-core version used.
    global $wp_scripts;
    // Create a handle for the jquery-ui-core css.
    $handle="jquery-ui";
    // Path to stylesheet, based on the jquery-ui-core version used in core.
    $src = "http://ajax.googleapis.com/ajax/libs/jqueryui/{$wp_scripts->registered['jquery-ui-core']->ver}/themes/smoothness/{$handle}.css";
    // Required dependencies
    $deps = array();
    // Add stylesheet version.
    $ver = $wp_scripts->registered['jquery-ui-core']->ver;
    // Register the stylesheet handle.
    wp_register_style( $handle, $src, $deps, $ver );
    // Enqueue the style.
    wp_enqueue_style( 'jquery-ui' );
    wp_enqueue_style( 'sample-theme-style', get_stylesheet_uri(), array( 'jquery-ui' ), '1.0.0' );
}

// Enqueue required scripts and styles.
function sample_theme_enqueue() {
    sample_theme_scripts();
    sample_theme_styles();
}

add_action( 'wp_enqueue_scripts', 'sample_theme_enqueue' );

Related Posts: