ClassicPress Plugin Development: Loading Back-End Stylesheets

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.

All of the plugins I have written have a settings page in the admin dashboard, either for settings to be configured or for instructions on how to use the plugin. I often have an admin stylesheet which needs to be loaded on the settings page. There is two ways in which stylesheets 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 stylesheet is to register it. This is done using the wp_register_style function which ClassicPress provides.

wp_register_style(string $handle, string|bool $src, string[] $deps = array(), string|bool|null $ver = false, string $media = 'all')
wp_register_style parameters
$handle (string) (Required) Name of the stylesheet. Should be unique.

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

$deps (string[]) (Optional) An array of registered stylesheet handles this stylesheet depends on. 
Default value: array()

$ver (string|bool|null) (Optional) String specifying stylesheet 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 ClassicPress version. If set to null, no version is added.
Default value: false

$media (string) (Optional) The media for which this stylesheet has been defined. Accepts media types like 'all', 'print' and 'screen', or media queries like '(orientation: portrait)' and '(max-width: 640px)'.
Default value: 'all'
wp_register_style return value
(bool) Whether the style has been registered. True on success, false on failure.

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

add_action('admin_init', 'azrcrv_XXXX_register_styles');

function azrcrv_XXXX_register_styles() {
    wp_register_style('azrcrv-XXXX-admin-style', plugins_url('assets/css/admin.css', __FILE__));
}

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

wp_enqueue_style(string $handle, string $src = '', string[] $deps = array(), string|bool|null $ver = false, string $media = 'all')
wp_register_style parameters
$handle (string) (Required) Name of the stylesheet. Should be unique.

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

$deps (string[]) (Optional) An array of registered stylesheet handles this stylesheet depends on. 
Default value: array()

$ver (string|bool|null) (Optional) String specifying stylesheet 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 ClassicPress version. If set to null, no version is added.
Default value: false

$media (string) (Optional) The media for which this stylesheet has been defined. Accepts media types like 'all', 'print' and 'screen', or media queries like '(orientation: portrait)' and '(max-width: 640px)'.
Default value: 'all'

The optional parameters above do not need to be incuded when the stylesheet has first been registered. This means out call for the enqueue in the admin dashboard 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_admin_style');

function azrcrv_XXXX_register_styles() {
	if (isset($_GET['page']) AND $_GET['page'] == 'azrcrv-XXXX'){
		wp_enqueue_style('azrcrv-XXXX-admin-style');
	}
}

As you can see, there is a check within the function to ensure the page loaded is the admin page for the plugin; this means we only load the admin stylesheet for this plugins admin page and no other.

The above outlines the first approach; the second approach is to not register the style and simply enqueue the stylesheet, 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.