Adding CSS and JavaScript 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 Adding static files. If you’re adding a JavaScript module, you must use Webassets.

Using Webassets to add JavaScript 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 Adding static files.

Adding a custom JavaScript or CSS file to CKAN using Webassets is simple. We’ll demonstrate by changing our previous custom CSS example (see Customizing CKAN’s 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 add_resource() function to register your assets directory with CKAN. Edit the update_config() method in your plugin.py file:

       def update_config(self, config: CKANConfig):
   
           # Add this plugin's templates dir to CKAN's extra_template_paths, so
           # that CKAN will use this plugin's custom templates.
           toolkit.add_template_directory(config, 'templates')
   
           # Add this plugin's public dir to CKAN's extra_public_paths, so
           # that CKAN will use this plugin's custom static files.
           toolkit.add_public_directory(config, 'public')
   
           # Register this plugin's assets directory with CKAN.
           # Here, 'assets' is the path to the webassets directory
           # (relative to this plugin.py file), and 'example_theme' is the name
           # that we'll use to refer to this assets directory from CKAN
           # templates.
           toolkit.add_resource('assets', 'example_theme')
   

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:

   {% ckan_extends %}
   
   {% block styles %}
     {{ super() }}
   
     {# Import example_theme.css using Webassets.  'example_theme/' is
       the name that the example_theme/webassets directory was registered
       with when the toolkit.add_resource() function was called.
       'example_theme' is the name to the Webassets bundle file,
       registered inside webassets.yml file. #}
     {% asset 'example_theme/example_theme' %}
   
   {% endblock %}
   

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 JavaScript 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 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.