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.
Interface
¶
-
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("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.
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
orrecline_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 - name – name of the view type. This should match the name of the
actual plugin (eg
-
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 theupdate_config
method, for instanceviews/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 theupdate_config
method, for instanceviews/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:
- The old way is to just return
True
orFalse
. - 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 theresource_proxy
plugin was enabled.quality
(int
) How good the preview is:1
(poor),2
(average) or3
(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.- The old way is to just return
-
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 theuser
. - resource (dictionary) – An object representing the resource to be added to the dataset (the one that is about to be created).
- context (dictionary) – The context object of the current request, this
includes for example access to the
-
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 theuser
. - 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 toupload
when the resource file is uploaded instead of linked.
- context (dictionary) – The context object of the current request, this
includes for example access to the
-
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 theuser
. - 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.
- context (dictionary) – The context object of the current request, this
includes for example access to the
-
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 theuser
. - 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 dictionaryurl_type
which is set toupload
when the resource file is uploaded instead of linked.
- context (dictionary) – The context object of the current request, this
includes for example access to the
-
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 theuser
. - resource (dictionary) – An object representing the resource that is about
to be deleted. This is a dictionary with one key:
id
which holds the idstring
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).
- context (dictionary) – The context object of the current request, this
includes for example access to the
-
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 theuser
. - resources – A list of objects representing the remaining resources after a resource has been removed.
- context (dictionary) – The context object of the current request, this
includes for example access to the
-
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
¶ Pass configuration to plugins and extensions
-
configure
(config)¶ Called by load_environment
-
-
class
ckan.plugins.interfaces.
IConfigurer
¶ Configure CKAN environment via the
config
object-
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 inckan/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
anddata_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, auser
containing the name of the user doing the request (or their IP if it is an anonymous web request) and anauth_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 theauth_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 theexample_helper
function viah.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()
andis_fallback()
methods below, and then providing different schemas and templates for different types of dataset. When a package controller action is invoked, thetype
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 thetype
of the package being processed, the fallback plugin is delegated to instead.There cannot be more than one IDatasetForm plugin whose
is_fallback()
method returnsTrue
, if this happens CKAN will raise an exception at startup.If no IDatasetForm plugin’s
is_fallback()
method returnsTrue
, CKAN will useDefaultDatasetForm
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 callDefaultDatasetForm
’screate_package_schema()
method to get the default schema and then modify and return it.CKAN’s
convert_to_tags()
orconvert_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 callDefaultDatasetForm
’supdate_package_schema()
method to get the default schema and then modify and return it.CKAN’s
convert_to_tags()
orconvert_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 callDefaultDatasetForm
’sshow_package_schema()
method to get the default schema and then modify and return it.If you have used
convert_to_tags()
orconvert_to_extras()
in yourcreate_package_schema()
andupdate_package_schema()
then you should useconvert_from_tags()
orconvert_from_extras()
in yourshow_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. Seeckanext/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()
andupdate_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()
orupdate_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()
anddb_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()
, ordb_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 anOrderedDict
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. SeeIDatasetForm
.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. SeeIDatasetForm
.The
group_type
is the type of group that these facets apply to. Plugins can provide different search facets for different types of group. SeeIGroupForm
.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. SeeIDatasetForm
.The
organization_type
is the type of organization that these facets apply to. Plugins can provide different search facets for different types of organization. SeeIGroupForm
.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
¶ -
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 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
-