Asset

Basics of assets

All application assets should be defined inside app\Http\assets.php file. This file is included on application bootstrap by the App\Providers\HttpServiceProvider class.

Adding asset

Providing application assets is really simple. Call add method on Asset facade and specify slug and file path in arguments. Asset type will be automatically detected by extension.

Asset::add('my-styles', ['path' => 'css/my-styles.css']);

Asset::add('my-script', ['path' => 'js/my-script.js']);

External asset

Adding assets directly form external resources (CDNs) is also supported.

Asset::add('purecss', [
    'path' => 'https://cdnjs.cloudflare.com/ajax/libs/pure/0.6.0/pure.css'
]);

Asset::add('vuejs', [
    'path' => 'https://cdnjs.cloudflare.com/ajax/libs/vue/1.0.25/vue.min.js'
]);

Getting asset

You can pick previously registered asset with get method and it's slug as argument.

Asset::get('my-script');

Loading asset

Sometimes you need to load asset that is already shiped with WordPress. To add this kind of assets you only need to enter it's slug and type.

Asset::load('jquery', ['type' => 'script']);

Queuing asset

Assets can be queued. It basicaly register asset, but don't dispatch it immediately. This allows for adding asset only to specific views.

First queue asset inside assets.php.

Asset::queue('my-script', ['path' => 'js/my-script.js']);

Then, in the selected view or controller, simply get desired asset and call add method.

// ..somewhere in the blade template or controller.
Asset::get('my-script')->add();

Removing asset

Sometimes you want to remove assets that was already added, for example by third-party plugin. You can easily do that with remove call. Provide the slug and type of the removed script as method arguments.

Asset::remove('third-party-script', ['type' => 'script']);

Asset::remove('third-party-styles', ['type' => 'style']);

Asset status

You are able to check asset status with is method.

Assets can have these statuses:

  • registered - script was registered
  • enqueued - script was enqueued
  • done - script has been printed
  • to_do - script has not yet been printed
Asset::get('jquery')->is('enqueued');

Dispach areas

Assets can be add only to these areas: website, admin and login. By default, if area is not specifed, it will be a website.

Asset::add('my-admin-script', [
    'path' => 'js/my-admin-script.js'
])->area('admin');

Area can be defined inside arguments too.

Asset::add('my-login-script', [
    'path' => 'js/my-login-script.js',
    'area' => 'login',
]);

Placement and media types

For assets of script type

You can define where <script> markup of your asset should be printed. Scripts can be placed in head and footer. By default, it is footer.

Asset::add('my-script', [
    'path' => 'js/my-script.js',
    'placement' => 'head'
]);

For assets of style type

Placement of styles reflects targeted devices. They can be added into diffrent media types. By default, it is screen.

All available values you can see in W3C specification.

Asset::add('my-styles', [
    'path' => 'js/my-styles.css',
    'placement' => 'print'
]);

Dependences

Setting asset dependences will enforce assets to load in specified order. For example, if your script requires jQuery, set 'jquery' slug as your asset dependency. This will give you assurance that your asset will be loaded only when jQuery are ready.

Asset::add('my-script', [
    'path' => 'js/my-script.js',
    'dependences' => ['jquery']
]);

Localizing with data

Use localize method for localizing assets with some sort of data. It accepts two arguments. First is variable name under which the data will be available. Second is a callback, which should return an array.

Asset::queue('my-script', [
    'path' => 'js/my-script.js'
])->localize('variable', function() {
    return ['data' => 'value']
});

This method use wp_localize_script and outputs global javascript variable before asset markup tag.

<script type="text/javascript">
/* <![CDATA[ */
    var variable = {
        'data': 'value'
    };
/* ]]> */
</script>

<script src="public/js/my-script.js"></script>

You can simply access this variable inside your javascript scripts.

console.log(variable, window['variable']);

Asyncing and defering

Assets can be asynced or defered. You can setup these execution attributes with async and defer methods.

// Execute asynchronously
Asset::add('my-script', [
    'path' => 'js/my-async-script.js'
])->async();

// Defer execution
Asset::add('my-script', [
    'path' => 'js/my-defer-script.js'
])->defer();

This methods simply adds to the <script> element special HTML Attributes. For example, above assets will output these markup.

<script src="public/js/my-async-script.js" async></script>

<script src="public/js/my-defer-script.js" defer></script>

Arguments

Here is list of all asset arguments with short description.

Argument Default value Descreption
path null Path to the asset file
area theme Asset destination area
type false Asset file type
media screen Asset media type
placement footer Asset html element placement
version null Asset version number
localize false Asset localization data
dependences [] List of asset dependences
execution [] List of asset exectution attributes