The CKAN Plugins Toolkit is a powerful framework that allows developers to extend and customise the functionality of CKAN. This toolkit provides a structured way to develop plugins that can enhance the core behaviour, extend the data model, add new features, or integrate CKAN with other systems. CKAN plugins are in effect Python packages that implement specific interfaces defined by the CKAN core.
Here’s an overview of how to use the CKAN Plugins Toolkit:
Key Concepts and Components
- Plugin Interfaces:
- IConfigurer: Allows customization of the CKAN configuration. It is used to modify the configuration object, templates, public assets, etc.
- IMapper: Extends or modifies the database schema and mapping.
- IRoutes: Adds new routes and controllers to handle custom pages and actions.
- ITemplateHelpers: Provides custom template helper functions that can be used in Jinja2 templates.
- IAuthFunctions: Customises authorization logic.
- IActions: Defines new actions that can be exposed via the API.
- Plugin Class:
- Each plugin is a Python class that inherits from the ckan.plugins.SingletonPlugin and implements one or more interfaces.
- Entry Points:
- Plugins are registered in the CKAN setup using entry points defined in the setup.py file of the plugin package.
In my example I will alter the IAuthFunctions interface.
Overview of IAuthFunctions
The IAuthFunctions interface is used to define custom authorization logic for different actions within CKAN. By implementing this interface, developers can specify who has permission to perform various actions, such as creating datasets, editing resources, or managing organisations and groups.
Key Points of IAuthFunctions
- Interface Definition:
- IAuthFunctions is defined in the ckan.plugins.interfaces module.
- It provides a set of methods that plugins can implement to control access.
- Core Methods:
- The primary method in IAuthFunctions is get_auth_functions, which returns a dictionary mapping action names to authorization functions.
- Authorization Functions:
- An authorization function checks whether a user is authorised to perform a specific action.
- These functions typically return a dictionary with the key ‘success’ set to True or False, indicating whether the action is allowed. If ‘success’ is False, an optional ‘msg’ key can provide an error message explaining why the action is not permitted.
- Custom Authorization Logic:
- By implementing IAuthFunctions, developers can define custom rules for various actions.
- This is useful for scenarios where the default CKAN authorization rules do not meet specific requirements.
For this example we will create a new CKAN group called “pigeons” and if you are a member of the “pigeons” group you can add a new group. If you are not an admin user or a member of “pigeons” you cannot add a new group
In the plugin.py file we uncheck the following interfaces:
As we can see below the get_auth_functions() method overrides the default group_create() function with a custom one. This custom function gets the name of the logged in user, the list of all members of the “pigeon” group and checks to see if the logged in user is a member of this group. It returns “True” if it is and “False” if it is not. If the user is a member of the pigeon group it will then have the ability to “Add a new CKAN group
Below we see within the “My Groups” tab the logged in user is a member of the “pigeons” group as I have the “Add Group” button on the screen. If the logged in user was not in the pigeons group it would not have this button on the screen
That’s it! You can also watch the 12-minute video version of this tutorial on the Link Digital YouTube channel.
Related articles
How to install CKAN using Docker Containers
How to install DataStore and DataPusher on CKAN
Create a CKAN development environment and install a new extension
