Underpin-WP / script-loader

Script loader for Underpin

Underpin Script Loader

Loader That assists with adding scripts to a WordPress website.

Installation

Using Composer

composer require underpin/script-loader

Manually

This plugin uses a built-in autoloader, so as long as it is required before Underpin, it should work as-expected.

require_once(__DIR__ . '/underpin-scripts/scripts.php');

Setup

1. Install Underpin. See Underpin Docs
2. Register new scripts as-needed.

Example

A very basic example could look something like this.

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description'
] );

Alternatively, you can extend Script and reference the extended class directly, like so:

underpin()->scripts()->add('key','Namespace\To\Class');

Enqueuing Scripts

To enqueue a script, run the loader and reference the script ID, like so:

underpin()->scripts()->enqueue('test'); // Enqueue the test script

A common practice is to extend do_actions in the script class to add the actions necessary to enqueue the script. If you don't need to use any logic to enqueue your script, the simplest way to enqueue the script is with the enqueue script middleware.

Localizing Scripts

Underpin expands on how script localization works. A common problem with using wp_localize_script is that the data needed to localize the script has to all be placed in one single call. Underpin gets around that by using the set_param method.

For example, say you wanted to localize ajaxUrl as your site's admin AJAX URL. You could do that at any time, like so:

underpin()->scripts()->get( 'test' )->set_param( 'ajaxUrl', admin_url( 'admin-ajax.php' ) );

As long as this is done before enqueue is fired, ajaxUrl will be localized. All items are localized inside of an object named after the localized_var. If no localized_var is specified, the var will be the handle.

So, if you enqueued ajaxUrl on a script with a handle called example, you would get something like:

// console.log(example)
{
	ajaxUrl: 'https://www.underpin.com/admin-ajax.php'
}

Script Middleware

Sometimes, it is necessary to localize the same set of paramaters, or even run the same actions across many scripts. This is where script middleware comes in handy.

For example, let's say you want to build a script that utilizes the REST API, and as a result needs a nonce and the root URL localized in the script. Doing this without a script is pretty straightforward, but verbose:

// Register script
underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description'
] );

$script = underpin()->scripts()->get('test');

// Localize script
$script->set_param('nonce', wp_create_nonce('wp_rest'));
$script->set_param('rest_url', get_rest_url());

// Enqueue script
$script->enqueue();

This is a very common scenario for WordPress scripts. Because of this, a middleware package exists to handle this automatically. The example below would accomplish the exact same thing:

// Register script
underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Rest_Middleware\Factories\Rest_Middleware'
        ]
] );

// Enqueue script
$script = underpin()->scripts()->get('test')->enqueue();

The key part of the example above is the middlewares argument. Middlewares is an array of Script_Middleware items that run in the provided order, and are intended to automate the steps needed to set up a script.

Enqueuing With Middleware

In circumstances where you always need to enqueue the script, you can use the provided enqueue middleware.

To enqueue on admin screens:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Admin_Script'
        ]
] );

To enqueue on the front-end:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script'
        ]
] );

To enqueue on the login screen:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Login_Script'
        ]
] );

To enqueue on both front-end and back-end:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'Underpin_Scripts\Factories\Enqueue_Script',
          'Underpin_Scripts\Factories\Enqueue_Admin_Script'
        ]
] );

Enqueuing Conditionally

A common scenario when enqueuing a script is to enqueue it under certain conditions. This can be handled using conditional middleware, using the array-based syntax for Underpin::make_class

For example, say you only want to enqueue a script on a specific admin page:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          [
            'class' => 'Underpin_Scripts\Factories\Enqueue_Admin_Script_Conditional',
            'args'  => [
              'should_enqueue_callback' => function(Script $script){
                return get_current_screen()->id === 'custom_screen_id';
              }
            ] 
          ]
        ]
] );

Another example, say you only want enqueue on the home page:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          [
            'class' => 'Underpin_Scripts\Factories\Enqueue_Script_Conditional',
            'args'  => [
              'should_enqueue_callback' => 'is_home'
            ] 
          ]
        ]
] );

Enqueuing Blocks

An increasingly common scenario with scripts is to enqueue a block script. This can be done like so:

underpin()->scripts()->add( 'test', [
        'handle'      => 'test',
        'src'         => 'path/to/script/src',
        'name'        => 'test',
        'description' => 'The description',
        'middlewares' => [
          'class' => 'Underpin_Scripts\Factories\Enqueue_Block_Script',
        ]
] );

Create Your Own Middleware

The middlewares array uses Underpin::make_class to create the class instances. This means that you can pass either:

1. a string that references an instance of Script_Middleware (see example above).
2. An array of arguments to construct an instance of Script_Middleware on-the-fly.

underpin()->scripts()->add( 'test', [
	'handle'      => 'test',
	'src'         => 'path/to/script/src',
	'name'        => 'test',
	'description' => 'The description',
	'middlewares' => [
		'Underpin_Rest_Middleware\Factories\Rest_Middleware', // Will localize script params.
		'Underpin_Scripts\Factories\Enqueue_Script',          // Will enqueue the script on the front end all the time.
		[                                                     // Will instantiate an instance of Script_Middleware_Instance using the provided arguments
			'name'                => 'Custom setup params',
			'description'         => 'Sets up custom parameters specific to this script',
			'priority'            => 10, // Optional. Default 10.
			'do_actions_callback' => function ( \Underpin_Scripts\Abstracts\Script $loader_item ) {
				// Do actions
			},
		],
	],
] );