Note
Resources are only supported in the new Jinja2 style templates in Ckan 2.0 and above.
Resources are .css and .js files that may be included in an html page. Resources are included in the page by using the {% resource [full resource name] %} tag. Resources are grouped into libraries and the full resource name consists of <library name>/<resource name>. It is important to note that these resources will be added to the page as defined by the resources not in the location of the {% resource %} tag. Duplicate resources will not be added and any dependencies will be included as well as the resources adding in the correct order (see below for details).
Libraries can be added to Ckan from extensions using the toolkit helper function add_resource(path, name) where path is the path to the resource directory relative to the file calling the function and name is the name of the library. Resources will the be created for the library for any .js and .css files found in the directory or it's subfolders. The resource name being the name of the file including any path needed to get to it from the resource directory. For greater control of the creation a resource.config file can be created and placed in the resource directory (see below for details).
In debug mode resources are served un minified and unbundled (each resource is served separately). In non-debug mode the files are served minified and bundled (where allowed).
Note
.js and .css resources must be supplied as un-minified files. Minified files will be created. It is advised to include a .gitignore file to prevent minified files being added to the repository.
This file is used to define the resources in a directory and is sub folders. Here is an example file. The general layout of the file and allowed syntax is the same as for the .ini config file.
- ::
[main] dont_bundle = jquery.js
force_top = html5.js
order = jquery.js jed.js
[IE conditional]
lte IE 8 = html5.js block_html5_shim IE 7 = font-awesome/css/font-awesome-ie7.css others = html5.js
[custom render order]
block_html5_shim = 1 html5.js = 2 select2/select2.css = 9
[inline scripts]
- block_html5_shim =
var html5 = {shivMethods: false};
[depends]
vendor = jquery.js
[groups]
- vendor =
jed.js html5.js select2/select2.js select2/select2.css bootstrap/js/bootstrap-transition.js bootstrap/js/bootstrap-modal.js bootstrap/js/bootstrap-alert.js bootstrap/js/bootstrap-tab.js bootstrap/js/bootstrap-button.js font-awesome/css/font-awesome-ie7.css
This can contain the following values
The resources listed will be placed in the head of the page. This is only relevant to .js files which will by default will be added to the bottom of the page.
Bundeling resources causes them to be served to the browser as a single resource to prevent multiple requests to the server. The resources listed will not be bundled. By default items will be bundled where possible. Note that .css files can only be bundled if they are in the same directory.
This is used to make sure that resources are created in the order specified. It should not generally be needed but is available if there are problems.
This allows IE conditionals to be wrapped around resources eg <!--[if IE lte 8]--><script src="my_script.js"></script><![end if]-->
The condition is supplied followed by a list of resources that need that condition.
This is a special condition that means that the resource will also be available for none IE browsers.
By default resources have a render order this is 10 for .css and 20 for .js resources. Sometimes we need to add resources before or after they would be included an example being the html5shim.js that needs including before .css resources. By providing a custom render order for the resource it's placement can be altered. Lower numbered resources are rendered earlier. Note that resources rendered in the head will still be placed before ones rendered in the body.
It is possible to define inline scripts in the resource.config file this can be helpful in some situations but is probably best avoided if possible.
Some times one resource depends on another eg many scripts need jquery.js included in the page before them. External resource libraries will automatically depend on the core ckan JavaScript modules so do not need to specify this.
Groups of resources can be specified this allows the group to be included by just using it's name rather than having to specify each resource individuality when requesting them. Groups can be referred to in many places in the resource.config file eg. [depends]