User Guides

Assets Configuration

The assets configuration controls which assets are compiled and included in your website.

Assets are configured in the assets.yaml config file, there are three main types of assets defined in this file. Those are: styles, scripts and sprites.


CSS / JavaScript Assets

This section is probably best explained by starting with an example assets config file.

# Styles
styles:
  files:
    - https://some-cdn.com/some-stylesheet.css
    - style.css:
        css:
          - some-stylesheet.css
          - some-other-stylesheet.css
        less:
          - some-less-file.less
          - some-other-less-file.less

# Scripts
scripts:
  files:
    - https://some-cdn.com/some-script-file.js
    - script.js:
        js:
          - some-script-file.js
          - some-other-script-file.js
        coffee:
          - some-coffee-file.coffee
          - some-other-coffee-file.coffee

As you can see from the example above, both style and script assets share a similar configuration structure. Styles are configured under the styles key and scripts are configured under the scripts key of the config file.

Each key contains a files key, which is an array of files to be included in your website. If a file is defined as an absolute URL, it will be included straight into you website without any further processing. If a file is defined as a relative path, it must also define an array of files that will be passed through their respective pre-processors, concatenated together and saved in the defined file. This file will then be included into your website.

Script Settings

There are also a couple of settings that can be defined for script assets, these should be defined in the settings key under the scripts key.

A list of available settings is outlined below:

Key Base value (default) Description
async false When true, this will add the async attribute to your script tags
defer false When true, this will add the defer attribute to your script tags

For example, the following assets config would include a script file named script.js into your website with an async attribute:

scripts:
  settings:
    async: true
  files:
    - script.js:
        js:
          - some-script-file.js
          - some-other-script-file.js

Sprites

LexasCMS can also take care of generating a sprite sheet of images that will be available to your website. Sprites are enabled by default and will use images located in the /assets/sprites directory to generate the sprite sheet. They are configured under the sprites key of the assets.yaml config file.

Using Sprites

To display a sprite on your website you simply need to add the class sprite and the class sprite-SOME_SPRITE_NAME to an element on your website. For example, if you had a sprite file named 'logo.png' and wanted to place the logo onto a page as a link, you would do the following:

<a href="#" class="sprite sprite-logo"></a>

Hover State

Sprites may also provide a mouse hover state by appending '@hover' to the filename, for example you may upload a file named 'logo@hover.png' to provide a hover state to the logo from the previous example.

Retina Sprites

By default, sprites are generated with a pixel ratio of '1', this means that if you view your website on a device with a retina display, the sprites may look blurred. You can resolve this by setting the ratio key in the sprites config to the required value.

For example if you wanted to support devices with a pixel ratio of 2 (most common), your sprites config would look like:

sprites:
  ratio: 2

This would generate two sprite sheets, one for devices with a pixel ratio of 1 and another for devices with a pixel ratio of 2.

Of course, you can enter whatever pixel ratio you like and this would add support for sprites on all devices up to the specified pixel ratio.

For example, the following config would add support for devices with pixel ratios of 1, 2, 3, 4 and 5. Though it is not recommended.

sprites:
  ratio: 5

When a ratio of more than 1 is specified, the source image file must be supplied at the greater matching size. For example, if the sprite is 100x100px and the sprite ratio is set to 2, then the supplied image should be 200x200px.