Skip to content

Latest commit

 

History

History
85 lines (65 loc) · 3.42 KB

webassets.rst

File metadata and controls

85 lines (65 loc) · 3.42 KB
Raw

Adding CSS and files using Webassets

If you're adding CSS files to your theme, you can add them using Webassets rather than the simple extra_public_paths method described in static-files. If you're adding a module, you must use Webassets.

Using Webassets to add and CSS files takes advantage of Webassets' features, such as automatically serving minified files in production, caching and bundling files together to reduce page load times, specifying dependencies between files so that the files a page needs (and only the files it needs) are always loaded, and other tricks to optimize page load times.

Note

CKAN will only serve *.js and *.css files as Webassets resources, other types of static files (eg. image files, PDF files) must be added using the extra_public_paths method described in static-files.

Adding a custom or CSS file to CKAN using Webassets is simple. We'll demonstrate by changing our previous custom CSS example (see css) to serve the CSS file with Webassets.

  1. First, create an assets directory in your extension and move the CSS file from public into assets:

    ckanext-example_theme/
  ckanext/
    example_theme/
      public/
        promoted-image.jpg
      assets/
        example_theme.css

  2. Use CKAN's :py~ckan.plugins.toolkit.add_resource() function to register your assets directory with CKAN. Edit the update_config() method in your plugin.py file:

    /../ckanext/example_theme_docs/v15_webassets/plugin.py

  3. Finally, edit your extension's templates/base.html file and use CKAN's custom Jinja2 tag {% asset %} instead of the normal <link> tag to import the file:

    /../ckanext/example_theme_docs/v15_webassets/templates/base.html

Note

You can put {% asset %} tags anywhere in any template, and Webassets will insert the necessary <style> and <script> tags to include your CSS and files. But the best place for related asset types is corresponding styles and scripts Jinja2's block.

Assets will not be included on the line where the {% asset %} tag is.

Note

A config file must be used to configure how Webassets should serve each asset file (whether or not to bundle files, what order to include files in, whether to include files at the top or bottom of the page, dependencies between files, etc.) See /contributing/frontend/assets for details.

X-Sendfile

For web servers which support the X-Sendfile feature, you can set ckan.webassets.use_x_sendfile config option to true and configure the web server (eg Nginx) in order to serve static files in a more efficient way. Static files served under the URI /webassets/<PATH_TO_STATIC_FILE> are stored in the file system under the path specified by ckan.webassets.path the config option. If ckan.webassets.path is not specified, static files are stored inside a webassests folder defined by the ckan.storage_path config option.