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 = '');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).script to define a JS file and style to define a CSS file.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.
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.
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.
Asset::add('my-handle', 'js/custom.js', ['backbone'], '2.0', true)->to('customizer');The to() method only accepts two 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', 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_Errorobject. Other alternatives to load those assets is to add them in your header file or use thewp_headorwp_footeraction hooks.
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');
});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');
}
}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.
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;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.
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:
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.
Made in Belgium