Adding CSS and JavaScript files using Fanstatic

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

Using Fanstatic to add JavaScript and CSS files takes advantage of Fanstatic’s 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 Fanstatic 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 Fanstatic is simple. We’ll demonstrate by changing our previous custom CSS example (see Customizing CKAN’s CSS) to serve the CSS file with Fanstatic.

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

    ckanext-example_theme/
      ckanext/
        example_theme/
          public/
            promoted-image.jpg
          fanstatic/
            example_theme.css
    
  2. Use CKAN’s add_resource() function to register your fanstatic directory with CKAN. Edit the update_config() method in your plugin.py file:

        def update_config(self, config):
    
            # 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 fanstatic directory with CKAN.
            # Here, 'fanstatic' is the path to the fanstatic directory
            # (relative to this plugin.py file), and 'example_theme' is the name
            # that we'll use to refer to this fanstatic directory from CKAN
            # templates.
            toolkit.add_resource('fanstatic', 'example_theme')
    
  3. Finally, edit your extension’s templates/base.html file and use CKAN’s custom Jinja2 tag {% resource %} instead of the normal <link> tag to import the file:

    {% ckan_extends %}
    
    {% block styles %}
      {{ super() }}
    
      {# Import example_theme.css using Fanstatic.
         'example_theme/' is the name that the example_theme/fanstatic directory
         was registered with when the toolkit.add_resource() function was called.
         'example_theme.css' is the path to the CSS file, relative to the root of
         the fanstatic directory. #}
      {% resource 'example_theme/example_theme.css' %}
    {% endblock %}
    

Note

You can put {% resource %} tags anywhere in any template, and Fanstatic will insert the necessary <style> and <script> tags to include your CSS and JavaScript files and their dependencies in the right places in the HTML output (CSS files in the HTML <head>, JavaScript files at the bottom of the page).

Resources will not be included on the line where the {% resource %} tag is.

Note

A config file can be used to configure how Fanstatic should serve each resource 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 Resources for details.