Embedding Assets

Asset files location

Assets can be stored in src/assets directory and they will be shipped with module in assets subdirectory. However, modules can be loaded from different locations, so it is impossible to set one hard-coded absolute or relative URL for them. It leads to problems like not displaying images.

Using context object

Developer may get proper URL using context object as shown below.

import {context} from './Context';

let moduleBaseUrl = context.getModule().getManifest().url
let assetsBaseUrl = `${moduleBaseUrl}/assets`
let exampleImgUrl = `${assetsBaseUrl}/images/example.jpg`

This way we may get URL for image shipped with current module.

Using URL convention for sources

This works with modules compiled with Concierge >= 5.5.2

Developer may set src attribute of <img> tag without using context object. It may be done as shown below.

<img src="modules/sabre-ngv-example/assets/images/example.jpg" />

This src value will be handled with CSS rule (if such asset exists in sabre-ngv-example module). General form or src format is as follows:

<img src="modules/<module-name>/assets/<asset-name>" />

This form is used to limit mistakes during development but may be shortened to following one:

<img src="<module-name>/assets/<asset-name>" />

eg.

<img src="sabre-ngv-example/assets/images/example.jpg" />

Using CSS Variables / Custom Properties

This works with modules compiled with Concierge >= 5.5.2

In LESS/CSS you may use CSS variables which look similar to URLs created in previous paragraph. Here is an example of using example.jpg image as background of <body> element:

body {
  background: var(--modules\/sabre-ngv-example\/assets\/images\/example\.jpg);
}

As you see, there is no url() used because it is impossible to use var() inside url() - instead of that url() is already contained in CSS variable.

Developer may also use short version of variable:

body {
  background: var(--sabre-ngv-example\/assets\/images\/example\.jpg);
}

In both cases developer must escape some characters like slashes or dots. It may look strange and be not intuitive so `dashed' version of these variables have been also created:

body {
  background: var(--modules--sabre-ngv-example--assets--images--example_jpg);
}

or

body {
  background: var(--sabre-ngv-example--assets--images--example_jpg);
}

They are create by following substitutions:

  • slashes (/) are replaced by double dash (--)

  • dots (.) are replaced by single underscore (_)

  • any other non-alphanumeric characters (not a-zA-Z0-9_-) are replaced by single dash (-)

These replacement rules are generating non-unique names so for example: mąka and męka will generate same name: m-ka. In such situation developer should consider renaming asset or he or she should use CSS variable with escaped slashes and dots.