Version

Asset

Introduction
Load assets
Localize

Introduction

The Asset class is responsible to easily load your stylesheet and/or javascript files.

In order to add/register/enqueue assets, use the add method. The method handles both stylesheet and javascript files and the parameters are the same as in the WordPress functions:

Here are the method details:

Asset::add($handle, $path, $deps = [], $version = '1.0', $mixed = null, $type = '');

$handle: string. Your custom asset handle name.
$path: string. The relative path of your asset from the resources/assets directory. You can also provide external URL.
$deps: array or boolean. An array of asset dependencies. false if nothing.
$version: string or boolean. A string specifying the asset version number.
$mixed: string or boolean. For stylesheets a string that specify the media type. For javascript files, a boolean that indicate if the asset is loaded before the closing </head> tag or in the footer (the theme must insert the wp_head() and wp_footer() functions).
$type: string Use this parameter if your external asset do not have a file extension. Use script to define a JS file and style to define a CSS file.

Load assets

By default the add method loads the assets in the front-end.

// Load a CSS file stored in resources/assets/css/screen.css
Asset::add('my-handle', 'css/screen.css', false, '1.0', 'all');

// Load a JS file stored in resources/assets/js/main.js
Asset::add('my-other-handle', 'js/main.js', ['jquery'], '1.0', true);

This example loads, in the front-end of your website/application, a screen.css file in the head for all media type and a main.js file in the footer.

Load asset in the WordPress admin

In order to change the location for your asset, simply use the to() method on your asset:

// This js file is loaded in WordPress admin only
// and is stored in resources/assets/js/custom.js
Asset::add('my-handle', 'js/custom.js', ['backbone'], '1.0', true)->to('admin');

Chain the to() method after you added your asset.

Load asset in login screen

Asset::add('my-handle', 'js/custom.js', ['jquery'], '1.0', false)->to('login');

Note: You can only load JS files to the login screen using the Asset API. CSS files are not supported.

The to() method only accepts two values:

admin : Loads the asset in the WordPress admin area.
login : Loads the asset in the WordPress login area.

Load external assets

The Asset class allows you to load external assets from CDN and others, ... Simply specify the absolute URL of your asset as a second argument to the add() method:

Asset::add('gg-jquery', '//ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js', false, '2.1.1', true);

The class is looking for the asset extension in order to define if it is a stylesheet or a javascript file. Some externals assets do not show the file extension. In those cases, simply add the $type argument. Use script to specify that you load a JS file and use style for a CSS file.

Asset::add('gg-map', 'https://maps.googleapis.com/maps/api/js?key=mysecretkey', false, '3.22', true, 'script');

This will load the Google Maps API JS file in the footer of your theme.

In case if the Asset class can't register your asset, the class returns a WP_Error object. Other alternatives to load those assets is to add them in your header file or use the wp_head or wp_footer action hooks.

Load an asset on a specific request

By using the routes.php

Inside your Route callback function, you can call the Asset::add() method in order to load the asset for the specific URI/page request.

Simply add your code before returning a view:

Route::is('home', function()
{
    Asset::add('my-handle', 'js/file.js', ['jquery'], '1.0', true);
    return View::make('home');
});

By using a controller

First specify a controller inside your routes.php file.

Route::is('home', 'home@index');

Then use the constructor method of your controller to load your asset for this specific URI/page request.

// File stored in resources/controllers/HomeController.php
class HomeController
{
    public function __construct()
    {       
        // This asset is only available to the home page
        Asset::add('my-handle', 'css/tool.css', array('main-style'), '1.0', 'screen');
    }

    // Method responsible to render the home view
    public function index()
    {   
        return View::make('home');
    }
}

By using a view composer

View composer allows you to run code when a specific view is rendered.

View::composer('home', function()
{
    Asset::add('my-handle', 'js/myscript.js', false, '1.0.0', true);
});

Check the views guide for more information regarding View composers.

Localize

WordPress allows you to output as a JSON object any data for use in your JS files using the wp_localize_script() function.

The asset API directly implements a localize() method with same benefits plus saving you some character input. Once defined, WordPress will output your data right before your script tag so it's available for script use.

Here is an example of the localize method:

// Register script asset.
$asset = Asset::add('js-handle', 'js/myscript.js', ['backbone'], '1.0.0', true);

// Localize data for script use.
$asset->localize('variableName', ['book' => 'A book title']);

The above code will output this:

<script type="text/javascript">
/* <![CDATA[ */
    var variableName = {
        "book": "A book title"
    };
/* ]]> */
</script>

Simply provide a JS variable name and your data to the localize method. You can pass any data you want as a second parameter: string, boolean, object, array.

Then inside your js/myscript.js file, you can access the data like so:

// Retrieve book title.
var title = variableName.book;

Asset

Newsletter