ClassicPress Plugin Development: Loading Back-End Scripts

This post is part of the ClassicPress Plugin Development series in which I am going to look at both best practice for developing plugins and how I approach some requirements as well as some of the functions I commonly use.

jQuery itself is automatically loaded by ClassicPress so we don’t need to do anything to load this ourselves in a plugin; it is just our own jQuery script which we need to register and enqueue. There is two ways in which scripts can be loaded in a plugin; I will cover them both, but will note first of all that I typically use the second approach; there is an argument that the first approach is the “correct” one.

The first thing to do when you are loading a script is to register it. This is done using the wp_register_script function which ClassicPress provides.

wp_register_script(string $handle, string|bool $src, string[] $deps = array(), string|bool|null $ver = false, bool $in_footer = false)
wp_register_script parameters
$handle (string) (Required) Name of the script. Should be unique.

$src (string|bool) (Required) Full URL of the script, or path of the script relative to the WordPress root directory. If source is set to false, script is an alias of other scripts it depends on.

$deps (string[]) (Optional) An array of registered script handles this script depends on. To load jQuery this should be set to array('jquery').
Default value: array()

$ver (string|bool|null) (Optional) String specifying script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If version is set to false, a version number is automatically added equal to current installed WordPress version. If set to null, no version is added.
Default value: false

$in_footer (bool) (Optional) Whether to enqueue the script before  instead of in the .
Default value: false

Registering a script when initialising the plugin in the admin dashboard, using the admin_init action, allows us to then enqueue the script when it is needed. This is an example action hook and function (including vendor and plugin prefix) registering a script:

add_action('admin_init', 'azrcrv_XXXX_register_scripts');

function azrcrv_XXXX_register_scripts() {
    wp_register_script('azrcrv-XXXX-jquery', plugins_url('assets/jquery/admin.js', __FILE__));
}

With the script registered, we can then enqueue the script which will cause it to be loaded. Stylesheets can be loaded using the wp_enqueue_script ClassicPress function:

wp_enqueue_script( string $handle, string $src = '', string[] $deps = array(), string|bool|null $ver = false, bool $in_footer = false )
wp_register_script parameters
$handle (string) (Required) Name of the script. Should be unique.

$src (string|bool) (Required) Full URL of the script, or path of the script relative to the WordPress root directory. If source is set to false, script is an alias of other scripts it depends on.

$deps (string[]) (Optional) An array of registered script handles this script depends on. To load jQuery this should be set to array('jquery').
Default value: array()

$ver (string|bool|null) (Optional) String specifying script version number, if it has one, which is added to the URL as a query string for cache busting purposes. If version is set to false, a version number is automatically added equal to current installed WordPress version. If set to null, no version is added.
Default value: false

$in_footer (bool) (Optional) Whether to enqueue the script before  instead of in the . Default 'false'.
Default value: false

The optional parameters above do not need to be included when the script has first been registered. This means out call for the enqueue can be as simple as the below example using the admin_enqueue_scripts action hook and function (including vendor and plugin prefix):

add_action( 'admin_enqueue_scripts', 'azrcrv_XXXX_enqueue_scripts' );

function azrcrv_XXXX_enqueue_scripts() {
	if (isset($_GET['page']) AND $_GET['page'] == 'azrcrv-XXXX'){
		wp_enqueue_script('azrcrv-XXXX-jquery');
	}
}

The above outlines the first approach; the second approach is to not register the style and simply enqueue the script, which is the approach I have generally been taking. I have added this to my list of things to change to using the first method of registering and then enqueuing rather than just enqueuing. While this isn’t technically necessary to do, as enqueuing directly will work, it adds some flexibility with how the plugin can be interacted.

A script which has been registered before enqueuing can be deregistered without needing to make any changes to the code of the plugin. When it has been deregistered, enqueuing will not then load the script.