Adding CSS and JavaScript files using Fanstatic

extra_public_paths

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.

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

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')

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.