Skip to content

[Misc] Enqueue Params

Jump to bottom
picasso edited this page Feb 16, 2021 · 9 revisions

Scripts & Styles enqueue params

Methods for enqueue scripts and styles on front-end:

  • enqueue_style($file, $params = [], $handle_only = false)
  • enqueue_script($file, $params = [], $handle_only = false)

Methods for enqueue scripts and styles on back-end (admin page):

  • admin_enqueue_style($file, $params = [])
  • admin_enqueue_script($file, $params = [])

Filename

The first argument to $file contains the name of the script/style and possibly the full path to the file.

If $file is null then the plugin <prefix> will be used as filename.

If $file starts with 'http' or 'https' then it treated as external and is used without any modification.

If the string $file begins with an exclamation mark ('!') or $params has key absolute equal to true, then the following path and file name are considered absolute and are not modified.

Otherwise, the argument $file is considered a filename and the full path to the plugin/theme root as well as the relative path to files of this type are appended to it, taking into account the difference for front-end and back-end (see below).

Folder structure

Relative paths are created by the get_filepath method and it looks like this:

public function get_filepath($is_style, $is_frontend, $file) {
    $dir = $is_frontend ? ($is_style ? 'css' : 'js') : ($is_style ? 'admin/css' : 'admin/js');
    return sprintf($is_style ? '/%2$s/%1$s.css' : '/%2$s/%1$s.min.js', $file, $dir);
}

Thus, if you are not satisfied with the folder structure for scripts and styles that the framework uses, then you can change this by overriding the get_filepath method in your class. For example, if you want all scripts and styles to be in one dist directory without splitting into subdirectories, then this method will look like this:

public function get_filepath($is_style, $is_frontend, $file) {
    return sprintf($is_style ? '/dist/%1$s.css' : '/dist/%1$s.min.js', $file);
}

Enqueue params

Available parameters ($params) and their default values:

    [
        'deps'          => [],
        'handle'        => null,
        'bottom'        => true,
        'data'          => null,
        'register_only' => false,
        'handle_only'   => false,
        'absolute'      => false,
        'async'         => false,
        'defer'         => false,
        'refresh'       => $this->debug,
        'media'         => 'all',
    ];

Parameters common for both scripts and styles:

  • deps - an array of registered script/style handles this script/style depends on
  • handle - name of the script/style. Should be unique. If is null then it will be generated from the $file argument (will be the filename from the path or will be equal to <prefix> if $file is equal to null)
  • register_only - registers the script/style only and does NOT enqueue it
  • handle_only - calculates a script/style handle and returns it without enqueue or register
  • absolute - if is true, then the argument $file is considered absolute and is not modified
  • refresh - if is true, then instead of the plugin/theme version, a numerical sequence created from the timestamp of the last update of the script/style file will be used (which avoids file caching during development)

Parameters affecting only scripts:

  • bottom - whether to enqueue the script before </body> instead of in the <head>
  • data - an associate array, which will be passed as generic data from PHP to JavaScript. If array contains key 'jsdata_name' then it will be used as the variable name avialable in JavaScript. Otherwise the name of the variable will be '<prefix>_jsdata'
  • async - if is true, then the async attribute will be added to <script> tag. This attribute means that the browser will download the JavaScript in the background and continue parsing as normal without waiting. When the JavaScript is done being downloaded then the browser will immediately stop parsing and execute this script
  • defer - if is true, then the defer attribute will be added to <script> tag. It tells the browser not to wait for the script, download it in the background and continue parsing, but unlike the async attribute, the defer attribute will not execute the JavaScript until after the entire HTML document is parsed

Parameters affecting only styles:

  • media - the media for which this stylesheet has been defined. The same as for wp_enqueue_style WordPress function

Note

The version of the plugin/theme (that is specified in the main plugin file or in the stylesheet file for the theme) will be used as the version for the enqueued script/style. If the refresh param for script/style enqueue is set to true, then instead of the plugin/theme version, a numerical sequence created from the timestamp of the last update of the script/style file will be used. А toggle for managing this parameter is automatically added to the Debug Plugin panel in the sidebar on the Settings Page.

Returns a script/style handle if it has been enqueued/registered, false on failure.

Returns a script/style handle if param handle_only is set to true, without enqueue/register the script/style, false on failure.

❗ Only if a script/style file is found in the specified folder, it will be enqueued. If the file is not found, then an error message with details will be written to the default log.

Zukit - The Developer Framework for WordPress

Basics

Add-ons

Settings Page

Custom Blocks

Components

Miscellaneous

Related Projects

Clone this wiki locally