CKAN Documentation 2.1.5 documentation » Writing Extensions »

Plugins Toolkit

To allow a safe way for extensions to interact with ckan a toolkit is provided. We aim to keep this toolkit stable across ckan versions so that extensions will work across different versions of ckan.


It is advised that when writing extensions that all interaction with ckan is done via the toolkit so that they do not break when new versions of ckan are released.

Over time we will be expanding the functionality available via this toolkit.

Example extension that registers a new helper function available to templates via h.example_helper()

import ckan.plugins as p

class ExampleExtension(p.SingletonPlugin):


    def update_config(self, config):
        # add template directory that contains our snippet
        p.toolkit.add_template_directory(config, 'templates')

    def example_helper(cls, data=None):
        # render our custom snippet
        return p.toolkit.render_snippet('custom_snippet.html', data)

    def get_helpers(self):
        # register our helper function
        return {'example_helper': self.example_helper}

The following functions, classes and exceptions are provided by the toolkit.

class BAseController
Base class for building controllers.
class CkanCommand
Base class for building paster functions.
class DefaultDatasetForm
base class for IDatasetForm.
exception CkanVersionException
Exception raised if required ckan version is not available.
exception NotAuthorized
Exception raised when an action is not permitted by a user.
exception ObjectNotFound
Exception raised when an object cannot be found.
exception ValidationError
Exception raised when supplied data is invalid. it contains details of the error that occurred.
exception UnknownConverter
Exception raised when a converter cannot be found.
exception UnknownValidator
Exception raised when a validator cannot be found.
_ (value)

Mark a string for translation. Returns the localized unicode string of value.

Mark a string to be localized as follows:

_('This should be in lots of languages')
add_public_directory (config, relative_path)
Function to aid adding extra public paths to the config. The path is relative to the file calling this function.
add_template_directory (config, relative_path)
Function to aid adding extra template paths to the config. The path is relative to the file calling this function.
asbool (obj)
part of paste.deploy.converters: convert strings like yes, no, true, false, 0, 1 to boolean
asint (obj)
part of paste.deploy.converters: convert stings to integers
aslist (obj, sep=None, strip=True)
part of paste.deploy.converters: convert string objects to a list
check_access (action, context, data_dict=None)
check that the named action with the included context and optional data dict is allowed raises NotAuthorized if the action is not permitted or True.
check_ckan_version (min_version=None, max_version=None)
Check that the ckan version is correct for the plugin.
get_action (action)
Get the requested action function.
get_converter (coverter)
Get the requested converter function.
get_validator (validator)
Get the requested validator function.
literal (html)
Treat the html as a literal that will not get escaped.
render (template_name, data=None)
Main template render function.
render_snippet (template_name, data=None)
helper for the render_snippet function similar to the render function.
render_text (template_name, data=None)
Render genshi text template.
requires_ckan_version (min_version, max_version=None)
Check that the ckan version is correct for the plugin.
request object
This is the http request and contains the environ, cookies etc.
response object
This is the http response.
abort (error_code, error_message)
Aborts the current request.
This causes a http redirect to be returned to the client.
This function can be used to create urls.
side_effect_free decorator
This marks action functions as accessible via the action api.
auth_sysadmins_check decorator
This marks auth functions as needing to be run for sys admins. Usually sysadmins are automatically allowed to run actions etc.
get_or_bust (data_dict, keys)
Try and get values from dictionary and if they are not there raise a ValidationError.