Assets

Note

Assets are only supported on CKAN 2.9 and above. If you are using CKAN <= 2.8, refer to the legacy Fanstatic resources documentation.

Assets are .css and .js files that may be included in an html page. Assets are included in the page by using the {% asset %} tag. CKAN then uses Webassets to serve these assets.

{% asset 'library_name/asset_name' %}

Assets are grouped into libraries and the full asset name consists of <library name>/<asset name>. For example:

{% asset 'my_webassets_library/my_javascript_file.js' %}

It is important to note that these assets will be added to the page as defined by the assets configuration, not in the location of the {% asset %} tag. Duplicate assets will not be added and any dependencies will be included as well as the assets, all in the correct order (see below for details).

Extensions can add new libraries to CKAN using a helper function defined in the :doc:` plugins-toolkit <plugins-toolkit>`. See below.

In debug mode assets are served un-minified and un-bundled (ie each asset is served separately). In non-debug mode the files are served minified and bundled (where allowed).

Note

When adding js and css files to the repository, they should be supplied as un-minified files. Minified files will be created automatically when serving them.

Assets within extensions

To add an asset from an extension, use the add_resource(path, name) function:

ckan.plugins.toolkit.add_resource('path/to/my/webassets/library/dir',
       'my_webassets_library')

The first argument is the path to the asset directory relative to the file calling the function (generally plugin.py). The second argument, is the name of the library (to be used by templates when they want to include an asset from the library using the {% asset %} tag as, so for instance my_webassets_library in the example shown above).

webassets.yml

The webassets.yml file is used to define the assets in a directory and its sub-folders. Here is an example file. Each section is described below

# Example webassets.yml file

select2-css:
  contents:
    - select2/select2.css
  output: my_webassets_library/%(version)s_select2.css
  filters: cssrewrite

jquery:
  contents:
    - jquery.js
  filters: rjsmin
  output: my_webassets_library/%(version)s_jquery.js

vendor:
  contents:
    - jed.js
    - moment-with-locales.js
    - select2/select2.js
  filters: rjsmin
  output: my_webassets_library/%(version)s_vendor.js
  extra:
    preload:
      - my_webassets_library/select2-css
      - my_webassets_library/jquery

Top level items

These are names of the available assets

select2-css

This asset should be added via {% asset 'my_webassets_library/select2-css' %}.

jquery

This asset should be added via {% asset 'my_webassets_library/jquery' %}.

vendor

This asset should be added via {% asset 'my_webassets_library/vendor' %}. If it is present in the template, select2-css and jquery can be omitted (because they are explicitly defined in vendor.extra.preload)

[contents] (required)

List of relative paths to source files that will be used to generate final asset.

Important

An asset must only include files of the same type. I.e, one cannot mix JS and CSS files in the same asset.

[output] (optional)

Assets will be compiled the first time they are included in a template. Output files are located either on the path specified by the ckan.webassets.path config directive or at {{ ckan.storage_path }}/webassets if the former is not provided. The file specified by the output option will be created there. If it’s not provided, the file will be created in a webassets-external sub-folder. The %(version)s fragment is a dynamic part that will be replaced with a hash of the generated file content. This technique is useful to address a number of cache issues for static files.

[filters] (optional)

These are the pre-processors that are applied to the file before producing the final asset. cssrewrite for CSS and rjsmin for JS are supported out of the box. Details and other options can be found in the Webassets documentation

[extra] (optional)

Additional configuration details. Currently, only one option is supported: preload.

preload

Defines list of assets in format asset_library/asset_name, that must be included into HTML output before the current asset.