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 a set of configuration options. The system.yaml file contains the default values; 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 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 the number of do assets.addCss() calls inside this block.

• The {% do %} tag allows you to handle variables without any output which is built into 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 the addCss() method renders out the HTML tags from CSS assets.

The JavaScript assets are used in the same way as the 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 −

Options

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

For CSS

• priority − It takes an integer value and the 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 supports 3 values such as empty, async and defer.

• group − It consists of a string that specifies unique name for a group. And the default value is set to true.

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 the 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 can 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 the HTML JS link tags. Based on the pipeline attribute, the list can 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 the 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; the collections 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 programmatically with the following 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 the 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 the url() helper method. For example, when you want to refer an image from the theme, then you can use the following syntax.

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

The url() helper method optionally takes the 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 the relative URL.

Example

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