Writing Extensions¶

Plugins: An Overview¶

Plugins are created as classes inheriting from either the Plugin or SingletonPlugin base classes. Most Extensions use the SingletonPlugin base class and we advise you to use this if possible.

Having created your class you need to inherit from one or more plugin interfaces to allow CKAN to interact with your extension. When specifying the interfaces that will be implemented you must remember to either (a) define all methods required by the interface or (b) use the inherits=True parameter which will use the interfaces default methods for any that you have not defined.

Libraries Available To Extensions¶

As well as using the variables made available to them by implementing various plugin hooks, extensions will likely want to be able to use parts of the CKAN core library. To allow this, CKAN provides a stable set of modules that extensions can use safe in the knowledge the interface will remain stable, backward-compatible and with clear deprecation guidelines as development of CKAN core progresses. This interface is available in Plugins Toolkit.

Example Extension¶

# Example Extension
# This extension adds a new template helper function `hello_world` when
# enabled templates can `{{ h.hello_world() }}` to add this html snippet.

import ckan.plugins as p

class HelloWorldPlugin(p.SingletonPlugin):

    p.implements(p.ITemplateHelpers)

    @staticmethod
    def hello_world():
        # This is our simple helper function.
        html = '<span>Hello World</span>'
        return p.toolkit.literal(html)

    def get_helpers(self):
        # This method is defined in the ITemplateHelpers interface and
        # is used to return a dict of named helper functions.
        return {'hello_world': hello_world}

Guidelines for writing extensions¶

• Use the plugins Plugins Toolkit.
• Extensions should use actions via get_action(). This function is available in the toolkit.
• No foreign key constraints into core as these cause problems.

Creating CKAN Extensions¶

All CKAN extensions must start with the name ckanext-. You can create your own CKAN extension like this (you must be in your CKAN pyenv):

(pyenv)$ paster create -t ckanext ckanext-myextension

You’ll get prompted to complete a number of variables which will be used in your dataset. You change these later by editing the generated setup.py file.

Once you’ve run this, you should now install the extension in your virtual environment:

(pyenv)$ cd ckanext-myextension
(pyenv)$ python setup.py develop

Testing¶

cd ckanext-dgu
nosetests ckanext/stats/tests --ckan
nosetests ckanext/stats/tests --ckan --with-pylons=test-core.ini

from ckan import plugins

class TestMyPlugin(TestCase):

   @classmethod
   def setup_class(cls):
       # Use the entry point name of your plugin as declared
       # in your package's setup.py
       plugins.load('my_plugin')

   @classmethod
   def teardown_class(cls):
       plugins.reset()

from pylons import config
import paste.fixture
from ckan.config.middleware import make_app

class TestMyRoutesPlugin(TestCase):

    @classmethod
    def setup_class(cls):
        cls._original_config = config.copy()
        config['ckan.plugins'] = 'my_routes_plugin'
        wsgiapp = make_app(config['global_conf'], **config.local_conf)
        cls.app = paste.fixture.TestApp(wsgiapp)

    @classmethod
    def teardown_class(cls):
        config.clear()
        config.update(cls._original_config)

Plugin API Documentation¶