This CKAN Extension demonstrates some common patterns for customising a CKAN instance.
- A CKAN Extension "plugin" at ckanext/example/plugin.py which, when
loaded, overrides various settings in the core ini-file to provide:
- A path to local customisations of the core templates and stylesheets
- A "stream filter" that replaces arbitrary strings in rendered templates
- A "route" to override and extend the default behaviour of a core CKAN page
- A custom Pylons controller for overriding some core CKAN behaviour
- A custom Package edit form
- A custom Group edit form
- A plugin that allows for custom forms to be used for datasets based on their "type".
- A custom User registration and edition form
- Some simple template customisations
To install this package, from your CKAN virtualenv, run the following from your CKAN base folder (e.g. pyenv/):
pip install -e git+https://github.com/okfn/ckanext-example#egg=ckanext-example
Then activate it by setting ckan.plugins = example in your main ini-file.
Examine the source code, starting with ckanext/example/plugin.py
To understand the nuts and bolts of this file, which is a CKAN Extension, read in conjunction with the "Extension documentation": http://docs.ckan.org/en/latest/extensions.html
One thing the extension does is set the values of extra_public_paths and extra_template_paths in the CKAN config, which are "documented here": http://docs.ckan.org/en/latest/configuration.html#extra-template-paths
These are set to point at directories within ckanext/example/theme/ (in this package). Here we:
- override the home page HTML ckanext/example/theme/templates/home/index.html
- provide some extra style by serving extra.css (which is loaded using the ckan.template_head_end option
- customise the navigation and header of the main template in the file layout.html.
The latter file is a great place to make global theme alterations. It uses the _layout template_ pattern "described in the Genshi documentation":http://genshi.edgewall.org/wiki/GenshiTutorial#AddingaLayoutTemplate. This allows you to use Xpath selectors to override snippets of HTML globally.
The custom package edit form at package_form.py follows a deprecated way to make a form (using FormAlchemy). This part of the Example Theme needs updating. In the meantime, follow the instructions at: http://docs.ckan.org/en/latest/forms.html
To add example tag vocabulary data to the database, from the ckanext-example directory run:
paster example create-example-vocabs -c <path to your ckan config file>
This data can be removed with
paster example clean -c <path to your ckan config file>