Plugin interfaces reference

ckan.plugins contains a few core classes and functions for plugins to use:

ckan.plugins

class ckan.plugins.SingletonPlugin(**kwargs)

Base class for plugins which are singletons (ie most of them)

One singleton instance of this class will be created when the plugin is loaded. Subsequent calls to the class constructor will always return the same singleton instance.

class ckan.plugins.Plugin(**kwargs)

Base class for plugins which require multiple instances.

Unless you need multiple instances of your plugin object you should probably use SingletonPlugin.

ckan.plugins.implements(interface, namespace=None, inherit=False, service=True)

Can be used in the class definition of Plugin subclasses to declare the extension points that are implemented by this interface class.

If the inherits option is True, then this Plugin class inherits from the interface class.

ckan.plugins.interfaces

A collection of interfaces that CKAN plugins can implement to customize and extend CKAN.

class ckan.plugins.interfaces.IMiddleware

Hook into Pylons middleware stack

make_middleware(app, config)

Return an app configured with this middleware

make_error_log_middleware(app, config)

Return an app configured with this error log middleware

class ckan.plugins.interfaces.IRoutes

Plugin into the setup of the routes map creation.

before_map(map)

Called before the routes map is generated. before_map is before any other mappings are created so can override all other mappings.

Parameters:map – Routes map object Returns:Modified version of the map object

after_map(map)

Called after routes map is set up. after_map can be used to add fall-back handlers.

Parameters:map – Routes map object Returns:Modified version of the map object

class ckan.plugins.interfaces.IMapper

A subset of the SQLAlchemy mapper extension hooks. See http://docs.sqlalchemy.org/en/rel_0_9/orm/deprecated.html#sqlalchemy.orm.interfaces.MapperExtension

Example:

>>> class MyPlugin(SingletonPlugin):
...
...     implements(IMapper)
...
...     def after_update(self, mapper, connection, instance):
...         log(u'Updated: %r', instance)

before_insert(mapper, connection, instance)

Receive an object instance before that instance is INSERTed into its table.

before_update(mapper, connection, instance)

Receive an object instance before that instance is UPDATEed.

before_delete(mapper, connection, instance)

Receive an object instance before that instance is PURGEd. (whereas usually in ckan ‘delete’ means to change the state property to deleted, so use before_update for that case.)

after_insert(mapper, connection, instance)

Receive an object instance after that instance is INSERTed.

after_update(mapper, connection, instance)

Receive an object instance after that instance is UPDATEed.

after_delete(mapper, connection, instance)

Receive an object instance after that instance is PURGEd. (whereas usually in ckan ‘delete’ means to change the state property to deleted, so use before_update for that case.)

class ckan.plugins.interfaces.ISession

A subset of the SQLAlchemy session extension hooks.

after_begin(session, transaction, connection)

Execute after a transaction is begun on a connection

before_flush(session, flush_context, instances)

Execute before flush process has started.

after_flush(session, flush_context)

Execute after flush has completed, but before commit has been called.

before_commit(session)

Execute right before commit is called.

after_commit(session)

Execute after a commit has occured.

after_rollback(session)

Execute after a rollback has occured.

class ckan.plugins.interfaces.IDomainObjectModification

Receives notification of new, changed and deleted datasets.

notify(entity, operation)

Send a notification on entity modification.

Parameters:

• entity – instance of module.Package.
• operation – ‘new’, ‘changed’ or ‘deleted’.

notify_after_commit(entity, operation)

Send a notification after entity modification.

Parameters:

• entity – instance of module.Package.
• operation – ‘new’, ‘changed’ or ‘deleted’.

class ckan.plugins.interfaces.IFeed

Allows extension of the default Atom feeds

get_feed_class()

Allows plugins to provide a custom class to generate feed items.

Returns:feed class Return type:type

The feed item generator’s constructor is called as follows:

feed_class(
    feed_title,        # Mandatory
    feed_link,         # Mandatory
    feed_description,  # Mandatory
    language,          # Optional, always set to 'en'
    author_name,       # Optional
    author_link,       # Optional
    feed_guid,         # Optional
    feed_url,          # Optional
    previous_page,     # Optional, url of previous page of feed
    next_page,         # Optional, url of next page of feed
    first_page,        # Optional, url of first page of feed
    last_page,         # Optional, url of last page of feed
)

get_item_additional_fields(dataset_dict)

Allows plugins to set additional fields on a feed item.

Parameters:dataset_dict (dictionary) – the dataset metadata Returns:the fields to set Return type:dictionary

class ckan.plugins.interfaces.IResourceUrlChange

Receives notification of changed urls.

notify(resource)

Give user a notify is resource url has changed.

:param resource, instance of model.Resource

class ckan.plugins.interfaces.IResourceView

Add custom view renderings for different resource types.

info()

Returns a dictionary with configuration options for the view.

The available keys are:

Parameters:

• name – name of the view type. This should match the name of the actual plugin (eg image_view or recline_view).
• title – title of the view type, will be displayed on the frontend. This should be translatable (ie wrapped on toolkit._('Title')).
• default_title – default title that will be used if the view is created automatically (optional, defaults to ‘View’).
• default_description – default description that will be used if the view is created automatically (optional, defaults to ‘’).
• icon – icon for the view type. Should be one of the Font Awesome types without the icon- prefix eg. compass (optional, defaults to ‘picture’).
• always_available – the view type should be always available when creating new views regardless of the format of the resource (optional, defaults to False).
• iframed – the view template should be iframed before rendering. You generally want this option to be True unless the view styles and JavaScript don’t clash with the main site theme (optional, defaults to True).
• preview_enabled – the preview button should appear on the edit view form. Some view types have their previews integrated with the form (optional, defaults to False).
• full_page_edit – the edit form should take the full page width of the page (optional, defaults to False).
• schema –

  schema to validate extra configuration fields for the view (optional). Schemas are defined as a dictionary, with the keys being the field name and the values a list of validator functions that will get applied to the field. For instance:

  {
      'offset': [ignore_empty, natural_number_validator],
      'limit': [ignore_empty, natural_number_validator],
  }
  

Example configuration object:

{'name': 'image_view',
 'title': toolkit._('Image'),
 'schema': {
    'image_url': [ignore_empty, unicode]
 },
 'icon': 'picture',
 'always_available': True,
 'iframed': False,
 }

Returns:a dictionary with the view type configuration Return type:dict

can_view(data_dict)

Returns whether the plugin can render a particular resource.

The data_dict contains the following keys:

Parameters:

• resource – dict of the resource fields
• package – dict of the full parent dataset

Returns:

True if the plugin can render a particular resource, False otherwise

Return type:

bool

setup_template_variables(context, data_dict)

Adds variables to be passed to the template being rendered.

This should return a new dict instead of updating the input data_dict.

The data_dict contains the following keys:

Parameters:

• resource_view – dict of the resource view being rendered
• resource – dict of the parent resource fields
• package – dict of the full parent dataset

Returns:

a dictionary with the extra variables to pass

Return type:

dict

view_template(context, data_dict)

Returns a string representing the location of the template to be rendered when the view is displayed

The path will be relative to the template directory you registered using the add_template_directory() on the update_config method, for instance views/my_view.html.

Parameters:

• resource_view – dict of the resource view being rendered
• resource – dict of the parent resource fields
• package – dict of the full parent dataset

Returns:

the location of the view template.

Return type:

string

form_template(context, data_dict)

Returns a string representing the location of the template to be rendered when the edit view form is displayed

The path will be relative to the template directory you registered using the add_template_directory() on the update_config method, for instance views/my_view_form.html.

Parameters:

• resource_view – dict of the resource view being rendered
• resource – dict of the parent resource fields
• package – dict of the full parent dataset

Returns:

the location of the edit view form template.

Return type:

string

class ckan.plugins.interfaces.IResourcePreview

Warning

This interface is deprecated, and is only kept for backwards compatibility with the old resource preview code. Please use IResourceView for writing custom view plugins.

can_preview(data_dict)

Return info on whether the plugin can preview the resource.

This can be done in two ways:

1. The old way is to just return True or False.
2. The new way is to return a dict with three keys:
   • can_preview (boolean) True if the extension can preview the resource.
   • fixable (string) A string explaining how preview for the resource could be enabled, for example if the resource_proxy plugin was enabled.
   • quality (int) How good the preview is: 1 (poor), 2 (average) or 3 (good). When multiple preview extensions can preview the same resource, this is used to determine which extension will be used.

Parameters:data_dict (dictionary) – the resource to be previewed and the dataset that it belongs to.

Make sure to check the on_same_domain value of the resource or the url if your preview requires the resource to be on the same domain because of the same-origin policy. To find out how to preview resources that are on a different domain, read Resource Proxy.

setup_template_variables(context, data_dict)

Add variables to c just prior to the template being rendered. The data_dict contains the resource and the package.

Change the url to a proxied domain if necessary.

preview_template(context, data_dict)

Returns a string representing the location of the template to be rendered for the read page. The data_dict contains the resource and the package.

class ckan.plugins.interfaces.ITagController

Hook into the Tag controller. These will usually be called just before committing or returning the respective object, i.e. all validation, synchronization and authorization setup are complete.

before_view(tag_dict)

Extensions will recieve this before the tag gets displayed. The dictionary passed will be the one that gets sent to the template.

class ckan.plugins.interfaces.IGroupController

Hook into the Group controller. These will usually be called just before committing or returning the respective object, i.e. all validation, synchronization and authorization setup are complete.

before_view(pkg_dict)

Extensions will recieve this before the group gets displayed. The dictionary passed will be the one that gets sent to the template.

class ckan.plugins.interfaces.IOrganizationController

Hook into the Organization controller. These will usually be called just before committing or returning the respective object, i.e. all validation, synchronization and authorization setup are complete.

before_view(pkg_dict)

Extensions will recieve this before the organization gets displayed. The dictionary passed will be the one that gets sent to the template.

class ckan.plugins.interfaces.IPackageController

Hook into the package controller. (see IGroupController)

after_create(context, pkg_dict)

Extensions will receive the validated data dict after the package has been created (Note that the create method will return a package domain object, which may not include all fields). Also the newly created package id will be added to the dict.

after_update(context, pkg_dict)

Extensions will receive the validated data dict after the package has been updated (Note that the edit method will return a package domain object, which may not include all fields).

after_delete(context, pkg_dict)

Extensions will receive the data dict (tipically containing just the package id) after the package has been deleted.

after_show(context, pkg_dict)

Extensions will receive the validated data dict after the package is ready for display (Note that the read method will return a package domain object, which may not include all fields).

before_search(search_params)

Extensions will receive a dictionary with the query parameters, and should return a modified (or not) version of it.

search_params will include an extras dictionary with all values from fields starting with ext_, so extensions can receive user input from specific fields.

after_search(search_results, search_params)

Extensions will receive the search results, as well as the search parameters, and should return a modified (or not) object with the same structure:

{‘count’: ‘’, ‘results’: ‘’, ‘facets’: ‘’}

Note that count and facets may need to be adjusted if the extension changed the results for some reason.

search_params will include an extras dictionary with all values from fields starting with ext_, so extensions can receive user input from specific fields.

before_index(pkg_dict)

Extensions will receive what will be given to the solr for indexing. This is essentially a flattened dict (except for multli-valued fields such as tags) of all the terms sent to the indexer. The extension can modify this by returning an altered version.

before_view(pkg_dict)

Extensions will recieve this before the dataset gets displayed. The dictionary passed will be the one that gets sent to the template.

class ckan.plugins.interfaces.IResourceController

Hook into the resource controller.

before_create(context, resource)

Extensions will receive this before a resource is created.

Parameters:

• context (dictionary) – The context object of the current request, this includes for example access to the model and the user.
• resource (dictionary) – An object representing the resource to be added to the dataset (the one that is about to be created).

after_create(context, resource)

Extensions will receive this after a resource is created.

Parameters:

• context (dictionary) – The context object of the current request, this includes for example access to the model and the user.
• resource (dictionary) – An object representing the latest resource added to the dataset (the one that was just created). A key in the resource dictionary worth mentioning is url_type which is set to upload when the resource file is uploaded instead of linked.

before_update(context, current, resource)

Extensions will receive this before a resource is updated.

Parameters:

• context (dictionary) – The context object of the current request, this includes for example access to the model and the user.
• current (dictionary) – The current resource which is about to be updated
• resource (dictionary) – An object representing the updated resource which will replace the current one.

after_update(context, resource)

Extensions will receive this after a resource is updated.

Parameters:

• context (dictionary) – The context object of the current request, this includes for example access to the model and the user.
• resource (dictionary) – An object representing the updated resource in the dataset (the one that was just updated). As with after_create, a noteworthy key in the resource dictionary url_type which is set to upload when the resource file is uploaded instead of linked.

before_delete(context, resource, resources)

Extensions will receive this before a previously created resource is deleted.

Parameters:

• context (dictionary) – The context object of the current request, this includes for example access to the model and the user.
• resource (dictionary) – An object representing the resource that is about to be deleted. This is a dictionary with one key: id which holds the id string of the resource that should be deleted.
• resources (list) – The list of resources from which the resource will be deleted (including the resource to be deleted if it existed in the package).

after_delete(context, resources)

Extensions will receive this after a previously created resource is deleted.

Parameters:

• context (dictionary) – The context object of the current request, this includes for example access to the model and the user.
• resources – A list of objects representing the remaining resources after a resource has been removed.

before_show(resource_dict)

Extensions will receive the validated data dict before the resource is ready for display.

Be aware that this method is not only called for UI display, but also in other methods like when a resource is deleted because showing a package is used to get access to the resources in a package.

class ckan.plugins.interfaces.IPluginObserver

Plugin to the plugin loading mechanism

before_load(plugin)

Called before a plugin is loaded This method is passed the plugin class.

after_load(service)

Called after a plugin has been loaded. This method is passed the instantiated service object.

before_unload(plugin)

Called before a plugin is loaded This method is passed the plugin class.

after_unload(service)

Called after a plugin has been unloaded. This method is passed the instantiated service object.

class ckan.plugins.interfaces.IConfigurable

Initialization hook for plugins.

See also IConfigurer.

configure(config)

Called during CKAN’s initialization.

This function allows plugins to initialize themselves during CKAN’s initialization. It is called after most of the environment (e.g. the database) is already set up.

Note that this function is not only called during the initialization of the main CKAN process but also during the execution of paster commands and background jobs, since these run in separate processes and are therefore initialized independently.

Parameters:config (ckan.common.CKANConfig) – dict-like configuration object

class ckan.plugins.interfaces.IConfigurer

Configure CKAN environment via the config object

See also IConfigurable.

update_config(config)

Called by load_environment at earliest point when config is available to plugins. The config should be updated in place.

Parameters:config – config object

update_config_schema(schema)

Return a schema with the runtime-editable config options

CKAN will use the returned schema to decide which configuration options can be edited during runtime (using ckan.logic.action.update.config_option_update()) and to validate them before storing them.

Defaults to ckan.logic.schema.default_update_configuration_schema(), which will be passed to all extensions implementing this method, which can add or remove runtime-editable config options to it.

Parameters:schema (dictionary) – a dictionary mapping runtime-editable configuration option keys to lists of validator and converter functions to be applied to those keys Returns:a dictionary mapping runtime-editable configuration option keys to lists of validator and converter functions to be applied to those keys Return type:dictionary

class ckan.plugins.interfaces.IActions

Allow adding of actions to the logic layer.

get_actions()

Should return a dict, the keys being the name of the logic function and the values being the functions themselves.

By decorating a function with the ckan.logic.side_effect_free decorator, the associated action will be made available by a GET request (as well as the usual POST request) through the action API.

class ckan.plugins.interfaces.IValidators

Add extra validators to be returned by ckan.plugins.toolkit.get_validator().

get_validators()

Return the validator functions provided by this plugin.

Return a dictionary mapping validator names (strings) to validator functions. For example:

{'valid_shoe_size': shoe_size_validator,
 'valid_hair_color': hair_color_validator}

These validator functions would then be available when a plugin calls ckan.plugins.toolkit.get_validator().

class ckan.plugins.interfaces.IAuthFunctions

Override CKAN’s authorization functions, or add new auth functions.

get_auth_functions()

Return the authorization functions provided by this plugin.

Return a dictionary mapping authorization function names (strings) to functions. For example:

{'user_create': my_custom_user_create_function,
 'group_create': my_custom_group_create}

When a user tries to carry out an action via the CKAN API or web interface and CKAN or a CKAN plugin calls check_access('some_action') as a result, an authorization function named 'some_action' will be searched for in the authorization functions registered by plugins and in CKAN’s core authorization functions (found in ckan/logic/auth/).

For example when a user tries to create a package, a 'package_create' authorization function is searched for.

If an extension registers an authorization function with the same name as one of CKAN’s default authorization functions (as with 'user_create' and 'group_create' above), the extension’s function will override the default one.

Each authorization function should take two parameters context and data_dict, and should return a dictionary {'success': True} to authorize the action or {'success': False} to deny it, for example:

def user_create(context, data_dict=None):
    if (some condition):
        return {'success': True}
    else:
        return {'success': False, 'msg': 'Not allowed to register'}

The context object will contain a model that can be used to query the database, a user containing the name of the user doing the request (or their IP if it is an anonymous web request) and an auth_user_obj containing the actual model.User object (or None if it is an anonymous request).

See ckan/logic/auth/ for more examples.

Note that by default, all auth functions provided by extensions are assumed to require a validated user or API key, otherwise a ckan.logic.NotAuthorized: exception will be raised. This check will be performed before calling the actual auth function. If you want to allow anonymous access to one of your actions, its auth function must be decorated with the auth_allow_anonymous_access decorator, available on the plugins toolkit.

For example:

import ckan.plugins as p

@p.toolkit.auth_allow_anonymous_access
def my_search_action(context, data_dict):
    # Note that you can still return {'success': False} if for some
    # reason access is denied.

def my_create_action(context, data_dict):
    # Unless there is a logged in user or a valid API key provided
    # NotAuthorized will be raised before reaching this function.

class ckan.plugins.interfaces.ITemplateHelpers

Add custom template helper functions.

By implementing this plugin interface plugins can provide their own template helper functions, which custom templates can then access via the h variable.

See ckanext/example_itemplatehelpers for an example plugin.

get_helpers()

Return a dict mapping names to helper functions.

The keys of the dict should be the names with which the helper functions will be made available to templates, and the values should be the functions themselves. For example, a dict like: {'example_helper': example_helper} allows templates to access the example_helper function via h.example_helper().

Function names should start with the name of the extension providing the function, to prevent name clashes between extensions.

class ckan.plugins.interfaces.IDatasetForm

Customize CKAN’s dataset (package) schemas and forms.

By implementing this interface plugins can customise CKAN’s dataset schema, for example to add new custom fields to datasets.

Multiple IDatasetForm plugins can be used at once, each plugin associating itself with different package types using the package_types() and is_fallback() methods below, and then providing different schemas and templates for different types of dataset. When a package controller action is invoked, the type field of the package will determine which IDatasetForm plugin (if any) gets delegated to.

When implementing IDatasetForm, you can inherit from ckan.plugins.toolkit.DefaultDatasetForm, which provides default implementations for each of the methods defined in this interface.

See ckanext/example_idatasetform for an example plugin.

package_types()

Return an iterable of package types that this plugin handles.

If a request involving a package of one of the returned types is made, then this plugin instance will be delegated to.

There cannot be two IDatasetForm plugins that return the same package type, if this happens then CKAN will raise an exception at startup.

Return type:iterable of strings

is_fallback()

Return True if this plugin is the fallback plugin.

When no IDatasetForm plugin’s package_types() match the type of the package being processed, the fallback plugin is delegated to instead.

There cannot be more than one IDatasetForm plugin whose is_fallback() method returns True, if this happens CKAN will raise an exception at startup.

If no IDatasetForm plugin’s is_fallback() method returns True, CKAN will use DefaultDatasetForm as the fallback.

Return type:boolean

create_package_schema()

Return the schema for validating new dataset dicts.

CKAN will use the returned schema to validate and convert data coming from users (via the dataset form or API) when creating new datasets, before entering that data into the database.

If it inherits from ckan.plugins.toolkit.DefaultDatasetForm, a plugin can call DefaultDatasetForm‘s create_package_schema() method to get the default schema and then modify and return it.

CKAN’s convert_to_tags() or convert_to_extras() functions can be used to convert custom fields into dataset tags or extras for storing in the database.

See ckanext/example_idatasetform for examples.

Returns:a dictionary mapping dataset dict keys to lists of validator and converter functions to be applied to those keys Return type:dictionary

update_package_schema()

Return the schema for validating updated dataset dicts.

CKAN will use the returned schema to validate and convert data coming from users (via the dataset form or API) when updating datasets, before entering that data into the database.

If it inherits from ckan.plugins.toolkit.DefaultDatasetForm, a plugin can call DefaultDatasetForm‘s update_package_schema() method to get the default schema and then modify and return it.

CKAN’s convert_to_tags() or convert_to_extras() functions can be used to convert custom fields into dataset tags or extras for storing in the database.

See ckanext/example_idatasetform for examples.

Returns:a dictionary mapping dataset dict keys to lists of validator and converter functions to be applied to those keys Return type:dictionary

show_package_schema()

Return a schema to validate datasets before they’re shown to the user.

CKAN will use the returned schema to validate and convert data coming from the database before it is returned to the user via the API or passed to a template for rendering.

If it inherits from ckan.plugins.toolkit.DefaultDatasetForm, a plugin can call DefaultDatasetForm‘s show_package_schema() method to get the default schema and then modify and return it.

If you have used convert_to_tags() or convert_to_extras() in your create_package_schema() and update_package_schema() then you should use convert_from_tags() or convert_from_extras() in your show_package_schema() to convert the tags or extras in the database back into your custom dataset fields.

See ckanext/example_idatasetform for examples.

Returns:a dictionary mapping dataset dict keys to lists of validator and converter functions to be applied to those keys Return type:dictionary

setup_template_variables(context, data_dict)

Add variables to the template context for use in templates.

This function is called before a dataset template is rendered. If you have custom dataset templates that require some additional variables, you can add them to the template context ckan.plugins.toolkit.c here and they will be available in your templates. See ckanext/example_idatasetform for an example.

new_template()

Return the path to the template for the new dataset page.

The path should be relative to the plugin’s templates dir, e.g. 'package/new.html'.

Return type:string

read_template()

Return the path to the template for the dataset read page.

The path should be relative to the plugin’s templates dir, e.g. 'package/read.html'.

If the user requests the dataset in a format other than HTML, then CKAN will try to render a template file with the same path as returned by this function, but a different filename extension, e.g. 'package/read.rdf'. If your extension (or another one) does not provide this version of the template file, the user will get a 404 error.

Return type:string

edit_template()

Return the path to the template for the dataset edit page.

The path should be relative to the plugin’s templates dir, e.g. 'package/edit.html'.

Return type:string

search_template()

Return the path to the template for use in the dataset search page.

This template is used to render each dataset that is listed in the search results on the dataset search page.

The path should be relative to the plugin’s templates dir, e.g. 'package/search.html'.

Return type:string

history_template()

Return the path to the template for the dataset history page.

The path should be relative to the plugin’s templates dir, e.g. 'package/history.html'.

Return type:string

resource_template()

Return the path to the template for the resource read page.

The path should be relative to the plugin’s templates dir, e.g. 'package/resource_read.html'.

Return type:string

package_form()

Return the path to the template for the dataset form.

The path should be relative to the plugin’s templates dir, e.g. 'package/form.html'.

Return type:string

resource_form()

Return the path to the template for the resource form.

The path should be relative to the plugin’s templates dir, e.g. 'package/snippets/resource_form.html'

Return type:string

validate(context, data_dict, schema, action)

Customize validation of datasets.

When this method is implemented it is used to perform all validation for these datasets. The default implementation calls and returns the result from ckan.plugins.toolkit.navl_validate.

This is an adavanced interface. Most changes to validation should be accomplished by customizing the schemas returned from show_package_schema(), create_package_schema() and update_package_schama(). If you need to have a different schema depending on the user or value of any field stored in the dataset, or if you wish to use a different method for validation, then this method may be used.

Parameters:

• context (dictionary) – extra information about the request
• data_dict (dictionary) – the dataset to be validated
• schema (dictionary) – a schema, typically from show_package_schema(), create_package_schema() or update_package_schama()
• action (string) – 'package_show', 'package_create' or 'package_update'

Returns:

(data_dict, errors) where data_dict is the possibly-modified dataset and errors is a dictionary with keys matching data_dict and lists-of-string-error-messages as values

Return type:

(dictionary, dictionary)

class ckan.plugins.interfaces.IGroupForm

Allows customisation of the group controller as a plugin.

The behaviour of the plugin is determined by 5 method hooks:

• group_form(self)
• form_to_db_schema(self)
• db_to_form_schema(self)
• check_data_dict(self, data_dict)
• setup_template_variables(self, context, data_dict)

Furthermore, there can be many implementations of this plugin registered at once. With each instance associating itself with 0 or more group type strings. When a group controller action is invoked, the group type determines which of the registered plugins to delegate to. Each implementation must implement two methods which are used to determine the group-type -> plugin mapping:

• is_fallback(self)
• group_types(self)
• group_controller(self)

Implementations might want to consider mixing in ckan.lib.plugins.DefaultGroupForm which provides default behaviours for the 5 method hooks.

is_fallback()

Returns true if this provides the fallback behaviour, when no other plugin instance matches a group’s type.

There must be exactly one fallback controller defined, any attempt to register more than one will throw an exception at startup. If there’s no fallback registered at startup the ckan.lib.plugins.DefaultGroupForm used as the fallback.

group_types()

Returns an iterable of group type strings.

If a request involving a group of one of those types is made, then this plugin instance will be delegated to.

There must only be one plugin registered to each group type. Any attempts to register more than one plugin instance to a given group type will raise an exception at startup.

group_controller()

Returns the name of the group controller.

The group controller is the controller, that is used to handle requests of the group type(s) of this plugin.

If this method is not provided, the default group controller is used (group).

new_template()

Returns a string representing the location of the template to be rendered for the ‘new’ page. Uses the default_group_type configuration option to determine which plugin to use the template from.

index_template()

Returns a string representing the location of the template to be rendered for the index page. Uses the default_group_type configuration option to determine which plugin to use the template from.

read_template()

Returns a string representing the location of the template to be rendered for the read page

history_template()

Returns a string representing the location of the template to be rendered for the history page

edit_template()

Returns a string representing the location of the template to be rendered for the edit page

group_form()

Returns a string representing the location of the template to be rendered. e.g. group/new_group_form.html.

form_to_db_schema()

Returns the schema for mapping group data from a form to a format suitable for the database.

db_to_form_schema()

Returns the schema for mapping group data from the database into a format suitable for the form (optional)

check_data_dict(data_dict)

Check if the return data is correct.

raise a DataError if not.

setup_template_variables(context, data_dict)

Add variables to c just prior to the template being rendered.

validate(context, data_dict, schema, action)

Customize validation of groups.

When this method is implemented it is used to perform all validation for these groups. The default implementation calls and returns the result from ckan.plugins.toolkit.navl_validate.

This is an adavanced interface. Most changes to validation should be accomplished by customizing the schemas returned from form_to_db_schema() and db_to_form_schema() If you need to have a different schema depending on the user or value of any field stored in the group, or if you wish to use a different method for validation, then this method may be used.

Parameters:

• context (dictionary) – extra information about the request
• data_dict (dictionary) – the group to be validated
• schema (dictionary) – a schema, typically from form_to_db_schema(), or db_to_form_schama()
• action (string) – 'group_show', 'group_create', 'group_update', 'organization_show', 'organization_create' or 'organization_update'

Returns:

(data_dict, errors) where data_dict is the possibly-modified group and errors is a dictionary with keys matching data_dict and lists-of-string-error-messages as values

Return type:

(dictionary, dictionary)

class ckan.plugins.interfaces.IFacets

Customize the search facets shown on search pages.

By implementing this interface plugins can customize the search facets that are displayed for filtering search results on the dataset search page, organization pages and group pages.

The facets_dict passed to each of the functions below is an OrderedDict in which the keys are CKAN’s internal names for the facets and the values are the titles that will be shown for the facets in the web interface. The order of the keys in the dict determine the order that facets appear in on the page. For example:

{'groups': _('Groups'),
 'tags': _('Tags'),
 'res_format': _('Formats'),
 'license': _('License')}

To preserve ordering, make sure to add new facets to the existing dict rather than updating it, ie do this:

facets_dict['groups'] = p.toolkit._('Publisher')
facets_dict['secondary_publisher'] = p.toolkit._('Secondary Publisher')

rather than this:

facets_dict.update({
   'groups': p.toolkit._('Publisher'),
   'secondary_publisher': p.toolkit._('Secondary Publisher'),
})

Dataset searches can be faceted on any field in the dataset schema that it makes sense to facet on. This means any dataset field that is in CKAN’s Solr search index, basically any field that you see returned by package_show().

If there are multiple IFacets plugins active at once, each plugin will be called (in the order that they’re listed in the CKAN config file) and they will each be able to modify the facets dict in turn.

dataset_facets(facets_dict, package_type)

Modify and return the facets_dict for the dataset search page.

The package_type is the type of package that these facets apply to. Plugins can provide different search facets for different types of package. See IDatasetForm.

Parameters:

• facets_dict (OrderedDict) – the search facets as currently specified
• package_type (string) – the package type that these facets apply to

Returns:

the updated facets_dict

Return type:

OrderedDict

group_facets(facets_dict, group_type, package_type)

Modify and return the facets_dict for a group’s page.

The package_type is the type of package that these facets apply to. Plugins can provide different search facets for different types of package. See IDatasetForm.

The group_type is the type of group that these facets apply to. Plugins can provide different search facets for different types of group. See IGroupForm.

Parameters:

• facets_dict (OrderedDict) – the search facets as currently specified
• group_type (string) – the group type that these facets apply to
• package_type (string) – the package type that these facets apply to

Returns:

the updated facets_dict

Return type:

OrderedDict

organization_facets(facets_dict, organization_type, package_type)

Modify and return the facets_dict for an organization’s page.

The package_type is the type of package that these facets apply to. Plugins can provide different search facets for different types of package. See IDatasetForm.

The organization_type is the type of organization that these facets apply to. Plugins can provide different search facets for different types of organization. See IGroupForm.

Parameters:

• facets_dict (OrderedDict) – the search facets as currently specified
• organization_type (string) – the organization type that these facets apply to
• package_type (string) – the package type that these facets apply to

Returns:

the updated facets_dict

Return type:

OrderedDict

class ckan.plugins.interfaces.IAuthenticator

EXPERIMENTAL

Allows custom authentication methods to be integrated into CKAN. Currently it is experimental and the interface may change.

identify()

called to identify the user.

If the user is identified then it should set c.user: The id of the user c.userobj: The actual user object (this may be removed as a requirement in a later release so that access to the model is not required)

login()

called at login.

logout()

called at logout.

abort(status_code, detail, headers, comment)

called on abort. This allows aborts due to authorization issues to be overriden

class ckan.plugins.interfaces.ITranslation

Allows extensions to provide their own translation strings.

i18n_directory()

Change the directory of the .mo translation files

i18n_locales()

Change the list of locales that this plugin handles

i18n_domain()

Change the gettext domain handled by this plugin

class ckan.plugins.interfaces.IUploader

Extensions implementing this interface can provide custom uploaders to upload resources and group images.

get_uploader(upload_to, old_filename)

Return an uploader object to upload general files that must implement the following methods:

__init__(upload_to, old_filename=None)

Set up the uploader.

Parameters:

• upload_to (string) – name of the subdirectory within the storage directory to upload the file
• old_filename (string) – name of an existing image asset, so the extension can replace it if necessary

update_data_dict(data_dict, url_field, file_field, clear_field)

Allow the data_dict to be manipulated before it reaches any validators.

Parameters:

• data_dict (dictionary) – data_dict to be updated
• url_field (string) – name of the field where the upload is going to be
• file_field (string) – name of the key where the FieldStorage is kept (i.e the field where the file data actually is).
• clear_field (string) – name of a boolean field which requests the upload to be deleted.

upload(max_size)

Perform the actual upload.

Parameters:max_size (int) – upload size can be limited by this value in MBs.

get_resource_uploader()

Return an uploader object used to upload resource files that must implement the following methods:

__init__(resource)

Set up the resource uploader.

Parameters:resource (dictionary) – resource dict

Optionally, this method can set the following two attributes on the class instance so they are set in the resource object:

filesize (int): Uploaded file filesize. mimetype (str): Uploaded file mimetype.

upload(id, max_size)

Perform the actual upload.

Parameters:

• id (string) – resource id, can be used to create filepath
• max_size (int) – upload size can be limited by this value in MBs.

get_path(id)

Required by the resource_download action to determine the path to the file.

Parameters:id (string) – resource id

class ckan.plugins.interfaces.IPermissionLabels

Extensions implementing this interface can override the permission labels applied to datasets to precisely control which datasets are visible to each user.

Implementations might want to consider mixing in ckan.lib.plugins.DefaultPermissionLabels which provides default behaviours for these methods.

See ckanext/example_ipermissionlabels for an example plugin.

get_dataset_labels(dataset_obj)

Return a list of unicode strings to be stored in the search index as the permission lables for a dataset dict.

Parameters:dataset_obj (Package model object) – dataset details Returns:permission labels Return type:list of unicode strings

get_user_dataset_labels(user_obj)

Return the permission labels that give a user permission to view a dataset. If any of the labels returned from this method match any of the labels returned from get_dataset_labels() then this user is permitted to view that dataset.

Parameters:user_obj (User model object or None) – user details Returns:permission labels Return type:list of unicode strings