The Asset class is responsible to easily load your stylesheet javascript files.
In order to enqueue asset, 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, $dependencies = [], $version = null, $arg = null);dist directory. You can also provide an external URL.</head> tag or in the footer (the theme must insert the wp_head() and wp_footer() functions).Calling the add method no longer automatically loads the asset. In order to load the asset, call the to() method like so:
// Load a CSS file stored in dist/css/screen.css
Asset::add('my-handle', 'css/screen.css', [], '1.0', 'all')->to();
// Load a JS file stored in dist/js/main.js
Asset::add('my-other-handle', 'js/main.js', ['jquery'], '1.0', true)->to();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.
By default, calling the to() method only enqueue the asset on the front-end.
In order to load the asset for the WordPress administration, simply pass the admin parameter the to() method of 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');Pass the login parameter on the to() method:
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.
In order to load an asset to the customizer, pass the customizer parameter on the to() method:
Asset::add('my-handle', 'js/custom.js', ['backbone'], '2.0', true)->to('customizer');If you need to load an asset on both the front-end and the administration of your application, you can pass an array of locations on the to() method like so:
Asset::add('handle', 'js/script.js', [], '1.0', true)->to(['front', 'admin']);The to() method accepts the following values:
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', [], '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 call the setType() method:
Asset::add('gg-map', 'https://maps.googleapis.com/maps/api/js?key=mysecretkey', [], '3.22', true)
->setType('script');Use script to the setType() method to specify that you're loading a JavaScript file and use style for a CSS file.
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)->to();
return view('home');
});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.
<?php
namespace App\Http\Controllers;
use Themosis\Support\Facades\Asset;
class Pages extends Controller
{
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')->to();
return view('home');
}
}View composer allows you to run code when a specific view is rendered. You can also enqueue an asset through the view composer call:
View::composer('home', function () {
Asset::add('my-handle', 'js/myscript.js', [], '1.0.0', true)->to();
});Check the views guide for more information regarding View composers.
WordPress allows you to output as a JSON object any data for use in your JavaScript 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)->to();
// 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 JavaScript 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;You can also define custom HTML attributes to your assets. Use the attributes() method like so:
$asset = Asset::add('gg-map', 'https://maps.googleapis.com/maps/api/js?key=mysecretkey', [], '3.22', false)
->setType('script')
->attributes(['defer', 'data-city' => 'Brussels'])
->to();The above code will add the defer and data-city="Brussels" attributes to your loaded asset.
You can add inline code in order to accompany your loaded 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', [], '1.3.0', 'all')->to();
$css->inline('.panel-main { border: 1px solid blue; }');
// Inline JS
$js = Asset::add('typekit', 'https://use.typekit.net/fdsjhizo.js', [], false)->to();
$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 JavaScript asset.
The second argument allows you to define the position of the inline code. You can render your code before or after the asset tag. By default, inline code is rendered "after" the asset. If you want to render the inline code before the asset, simply pass false to the position parameter:
$js->inline('var app = app || {}', false);You can define custom assets locations for your application in the root config/assets.php configuration file.
In order to register a new asset location, you can pass a key value pair to the configuration paths property where the key is the path to your compiled asset and the value its URL:
'paths' => [
web_path('dist') => rtrim(config('app.url'), '\/').'/dist'
],Additional assests locations may also be defined by plugins and themes using the $plugin->assets() and $theme->assets() calls.
The Themosis theme boilerplate is configured to load assets from its dist directory (configured in functions.php). Same is configured for Themosis plugin boilerplate (in plugin-name.php).
Themosis searches for the (non-external) assets files set up by Asset::add() in the configured assets locations in the order the locations are added.
In other words Themosis loads the first matching asset file found in this order:
config/assets.php file, one-by-one, in the order they are added.If the asset file cannot be found under any of these locations, an Themosis\Asset\AssetException is thrown.
Please note, that the particular order in which different plugins are loaded is controlled by WordPress. Must use plugins are loaded before other plugins, but the exact order between the different plugins may vary. Therefore it is not recommended to rely on the load order of plugins when loading assets.
When your application uses multiple Themosis plugins, it is best to use unique asset names to prevent conflicts between them. It is also advisable to set unique name for theme assets, as any matching file in an active plugins assets location can potentially "hijack" the loading of the theme asset files. A unique asset name may as well be achieved by using a unique subfolder together with a generic filename e.g.: 'js/some-unique-string/main.js' or 'css/some-unique-string/style.js'
Made in Belgium