Version
Version

Asset

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 a dist directory. You can also provide an 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 or false for no versioning.
  • $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 dist/css/screen.css
Asset::add('my-handle', 'css/screen.css', false, '1.0', 'all');

// Load a JS file stored in dist/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 dist/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 by WordPress.

Load asset in customizer

Asset::add('my-handle', 'js/custom.js', ['backbone'], '2.0', true)->to('customizer');

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.
  • customizer : Loads the asset in the WordPress Customizer area.

Load external assets

The Asset class allows you to load external assets from CDN and others locations,... 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 inside 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('home');
});

By using a controller

First specify a controller inside your routes.php file.

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

Then use the constructor or method of your controller to load your asset for this specific URI/page request. If you're using a controller class to handle multiple routes, call the asset from its constructor will "share" the asset between all requests. Use a controller method instead if you want to load the asset for a specific route.

namespace Theme\Controllers;

use Themosis\Facades\Asset;
use Themosis\Route\BaseController;

class Pages extends BaseController
{
    public function __construct()
    {		
        // Call assets here in order to share them between multiple requests.
    }
	
    // Method responsible to render the home view
    public function index()
    {	
        // This asset is only available to the home page
        Asset::add('my-handle', 'css/tool.css', ['main-style'], '1.3', 'screen');
        return view('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 the 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;

Custom attributes

Since release 1.3.0, you can also define custom HTML attributes to your assets. For example, when using external scripts, sometimes we do want to add a defer attribute for better performance.

Use the addAttributes() method like so:

$asset = Asset::add('gg-map', 'https://maps.googleapis.com/maps/api/js?key=mysecretkey', false, '3.22', false, 'script');
$asset->addAttributes(['defer', 'data-city' => 'Brussels']);

The above code will add the defer and data-city="Brussels" attributes to your loaded asset.

Inline code

You can add inline code in order to accompany your loaded assets, both JS and CSS assets.

Use the inline() method in order to add code at asset output like so:

// Inline CSS
$css = Asset::add('my-theme', 'css/screen.min.css', false, '1.3.0', 'all');
$css->inline('.panel-main { border: 1px solid blue; }');

// Inline JS
$js = Asset::add('typekit', 'https://use.typekit.net/fdsjhizo.js', false, false);
$js->inline('try{Typekit.load({ async: true });}catch(e){}');

By default inline code is always added after loaded asset. For JS assets, you can specify a before position in order to load your inline script before your asset:

$js->inline('var app = app || {};', 'before');

In above example, the inline script is rendered before the JS asset. The position parameters can accept two values:

  • after (default)
  • before

Register assets locations

You can define custom assets locations different than the pre-configured theme dist directory for example. This is useful for plugin development if you need to store custom assets related to your plugin features.

In order to register a new asset location, retrieve an assets finder instance and call its addPaths() method and pass it an array of key value pairs where the key is the URL to your (compiled) assets base directory and its value is the PATH:

container('asset.finder')->addPaths([
    themosis_theme_assets() => themosis_path('theme').'dist'
]);

You can add multiple locations. The above example is from the themosis-theme theme where the themosis_theme_assets() helper function return our theme dist URL as a key and the value contains the PATH.

Newsletter

Subscribe to our mailing list and stay notified regarding future framework releases and other related services*.

Made in Belgium