Grav - Asset Manager

In this chapter let's study about Asset Manager. Asset Manager was introduced in Grav 0.9.0 to unify the interface for adding and managing assets like JavaScript and CSS. Adding these assets from themes and plugins will provide advanced capabilities such as ordering and Asset Pipeline.
The Asset Pipeline is used to minify and compress the assets so that it reduces the requirements of the browser and also reduces the size of assets.
Asset Manager is a class and available to use in Grav through plugin event hooks. You can also use Asset Manager class directly in themes by using Twig calls.

Configuration

Asset Manager consists of set of configuration options. The system.yaml file which contains default values and you can override these values in your user/config/system.yaml file.

assets:                                # Configuration for Assets Manager (JS, CSS)
  css_pipeline: false                  # The CSS pipeline is the unification of multiple CSS resources into one file
  css_minify: true                     # Minify the CSS during pipelining
  css_rewrite: true                    # Rewrite any CSS relative URLs during pipelining
  js_pipeline: false                   # The JS pipeline is the unification of multiple JS resources into one file
  js_minify: true                      # Minify the JS during pipelining

Assets in Themes

Antimatter theme comes as default theme when you install Grav. It shows an example of how to add CSS files in your base.html.twig file which is resides in this theme.

{% block stylesheets %}
    {% do assets.addCss('theme://css/pure-0.5.0/grids-min.css', 103) %}
    {% do assets.addCss('theme://css-compiled/nucleus.css',102) %}
    {% do assets.addCss('theme://css-compiled/template.css',101) %}
    {% do assets.addCss('theme://css/custom.css',100) %}
    {% do assets.addCss('theme://css/font-awesome.min.css',100) %}
    {% do assets.addCss('theme://css/slidebars.min.css') %}

    {% if browser.getBrowser == 'msie' and browser.getVersion == 10 %}
        {% do assets.addCss('theme://css/nucleus-ie10.css') %}
    {% endif %}
    {% if browser.getBrowser == 'msie' and browser.getVersion >= 8 and browser.getVersion <= 9 %}
        {% do assets.addCss('theme://css/nucleus-ie9.css') %}
        {% do assets.addJs('theme://js/html5shiv-printshiv.min.js') %}
    {% endif %}
{% endblock %}
{{ assets.css() }}

The above code is explained briefly below.

• The region defined in the block twig tag can be replaced or appended to in templates that extend the one and you can see number of do assets.addCss() calls inside this block.
• The {% do %} tag allows you to handle variables without any output which is built in to Twig itself.
• The CSS assets can be added to Asset Manager by using addCss() method. You can set priority of the stylesheets by passing a numerical value as second parameter. The call to addCss() method renders out the HTML tags from CSS assets.

The JavaScript assets are used in the same way as CSS assets. The JavaScript assets within the block twig tags as shown below.

{% block javascripts %}
    {% do assets.addJs('jquery',101) %}
    {% do assets.addJs('theme://js/modernizr.custom.71422.js',100) %}
    {% do assets.addJs('theme://js/antimatter.js') %}
    {% do assets.addJs('theme://js/slidebars.min.js') %}
    {% do assets.addInineJs('alert(\'This is inline!\')') %}
{% endblock %}
{{ assets.js() }}

Adding Assets

Following table lists the different types of add methods:

Method	Description
add(asset, [options])	Based on the file extension add method matches the asset. It is a proper method for calling one of the direct methods for CSS or JS. You can make use of options to set priority. Whether an asset should be included in combination/minify pipeline or not is controlled by pipeline attribute.
addCss(asset, [options])	By using this method you can add assets to the CSS assets. Based on the priority set in the second parameter, the asset is ordered in the list. If no priority is set then by default 10 is set. Whether an asset should be included in combination/minify pipeline or not is controlled by pipeline attribute.
addDirCss(directory)	By using this method you can add an entity directory consisting of CSS assets which will be arranged in alphabetical order.
addInlineCss(css, [options])	You can provide a string of CSS inside inline style tag by using this method.
addJs(asset, [options])	By using this method you can add assests to the JS assets. If priority is not set then it sets default priority to 10. The pipeline attribute determine whether an asset should be included in combination/minify pipeline or not.
addInlineJs(javascript, [options])	This method allows you to add a string of JS inside inline script tag.
addDirJs(directory)	By using this method you can add an entity directory consisting of JS assets, which will be arranged in alphabetical order.
registerCollection(name, array)	This method allows you to register an array consisting of CSS or JS assets with a name so that it can be used later by using add() method. If you are using multiple themes or plugins, then this method is very useful.

Options

There are many options to pass array of assets which are explained as shown below:

For CSS

• priority: It takes an integer value and default value will be 100.
• pipeline: When an asset is not included in pipeline, it sets to false value. And the default value is set to true.

For JS

• priority: Takes integer value and default value will be 100.
• pipeline: When an asset is not included in pipeline, false is set. And the default value is set to true.
• loading: This option support 3 values such as empty, async and defer.
• group: It consists of a string that specify unique name for a group. And the default value is set to true.

For example:

{% do assets.addJs('theme://js/example.js', {'priority':101, 'pipeline':true, 'loading':'async', 'group':'top'}) %}

Rendering Assets

The current state of the CSS and JS assets can be rendered by using following:

css()

Based on all the CSS assets which have been added to Asset Manager, the css() method renders a list consisting of HTML CSS link tags. Based on the pipeline attribute the list could contain minified file and individual/combined asset.

js()

Based on all the JS assets which have been to Asset Manager, the js() method renders a list consisting of HTML JS link tags. Based on the pipeline attribute the list could contain minified file and individual/combined asset.

Named Assets

Grav allows you to register a collection of CSS and JS assets with a name, so that you can use add assets to Asset Manager by using the registered name. This can be accomplished in Grav by using a feature called named assets. These custom collections are defined in system.yaml, so that it can be used by any theme or plugin.

assets:
  collections:
    jquery: system://assets/jquery/jquery-2.1.3.min.js
    bootstrap:
        - https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css
        - https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css
        - https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js

The registerCollection() method can be used programatically with the below code:

$assets = $this->grav['assets'];
$bootstrapper_bits = [https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap.min.css,
                      https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/css/bootstrap-theme.min.css,
                      https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js];
$assets->registerCollection('bootstrap', $bootstrap_bits);
$assets->add('bootstrap', 100);

Grouped Assets

Grav 0.9.43 was introduced with a new feature called Grouped Assets which allows you to pass options array consisting of optional group while adding Assets. This feature is very useful when you need some JS files or inline JS at specific part of the page.
By using the options syntax you must specify the group when adding the asset as shown below.

{% do assets.addJs('theme://js/example.js', {'priority':102, 'group':'bottom'}) %}

If no group is set for an asset, then head is set as default group. If you want these assets to render in the bottom group you must add following in your theme.

{{ assets.js('bottom') }}

Static Assets

Whenever you want to refer assets without the use of Asset Manager, then you can use url() helper method. For example when you want to refer an image from the theme, then you can use below syntax.

<img src="{{ url("theme://" ~ widget.image) }}" alt="{{ widget.text|e }}" />

The url() helper method optionally takes second parameter to enable the URL to include domain and schema by using true or false values. By default the value is set to false which displays only relative URL.
For example:

url("theme://somepath/mycss.css", true)