Skip to content

Latest commit

 

History

History
131 lines (113 loc) · 5.41 KB

DEV.md

File metadata and controls

131 lines (113 loc) · 5.41 KB

Developer Manual

List of CKAN documatations required to understand

Setup environment for development

System requirements for developing CKAN plugin

  • Ubuntu 22.04 or newer: To align with offcial CKAN documentation, Ubuntu 22.04 or newer is required, Windows/Mac OS will simply not work or have a lot of issues.
  • Have root privilege

Install CKAN

  • Prepare environment: 
    sudo apt update
sudo apt install build-essential
  • Install Docker Engine on Ubuntu
    • follow the guide to install the latest version, don't install it from apt nor snap
  • Follow the official guide "Installing CKAN from source¶":
  • Create a sysadmin account
  • You may want to modify the CKAN cofig: /etc/ckan/default/ckan.ini, i.e. extend logged in session
  • You should be able to start CKAN: 
    . /usr/lib/ckan/default/bin/activate
ckan -c /etc/ckan/default/ckan.ini run

# You may want to set the environment variable `WERKZEUG_DEBUG_PIN` to enable debugging in browser.
# This sets the debug PIN to 123456 and run ckan
# WERKZEUG_DEBUG_PIN=123456 ckan -c /etc/ckan/default/ckan.ini run

Install ckanext-udc plugin

# Activate the virtual env
. /usr/lib/ckan/default/bin/activate

# Go to ckan's source directory
cd /usr/lib/ckan/default/src

# Download the UDC plugin
git clone https://github.com/csse-uoft/ckanext-udc

# Install dependencies
cd ./ckanext-udc
pip install -e .
pip install -r requirements.txt

Activate the UDC plugin

Add udc to the ckan.plugins setting in your CKAN config file (by default the config file is located at /etc/ckan/default/ckan.ini).

nano /etc/ckan/default/ckan.ini

Look for ckan.plugins

...
## Plugins Settings ############################################################
ckan.plugins = activity
ckan.resource_proxy.timeout = 5
...

Add udc to ckan.plugins:

...
## Plugins Settings ############################################################
ckan.plugins = activity udc
ckan.resource_proxy.timeout = 5
...

Change dataset to catalogue

Look for ckan.default.package_type

## Theming Settings ############################################################
...
ckan.default.package_type = catalogue

Understand the basic structure of UDC plugin

📦ckanext-udc
 ┣ 📂ckanext
 ┃ ┣ 📂udc
 ┃ ┃ ┣ 📂assets         <- Public files that will pass to the browser
 ┃ ┃ ┃ ┣ 📂js
 ┃ ┃ ┃ ┃ ┗ 📜package.js
 ┃ ┃ ┃ ┗ 📜webassets.yml
 ┃ ┃ ┣ 📂templates      <- Jinja2 templates (overrided templates & new templates)
 ┃ ┃ ┃ ┣ 📂admin
 ┃ ┃ ┃ ┃ ┗ 📜config.html
 ┃ ┃ ┃ ┣ 📂package
 ┃ ┃ ┃ ┃ ┣ 📂macros
 ┃ ┃ ┃ ┃ ┃ ┗ 📜ckan_fields.html
 ┃ ┃ ┃ ┃ ┗ 📂snippets
 ┃ ┃ ┃ ┃ ┃ ┣ 📜additional_info.html
 ┃ ┃ ┃ ┃ ┃ ┣ 📜package_basic_information.html
 ┃ ┃ ┃ ┃ ┃ ┣ 📜package_custom_fields.html
 ┃ ┃ ┃ ┃ ┃ ┣ 📜package_form.html
 ┃ ┃ ┃ ┃ ┃ ┗ 📜package_metadata_fields.html
 ┃ ┃ ┣ 📜__init__.py
 ┃ ┃ ┗ 📜plugin.py     <- Main Plugin Entrance.
 ┃ ┗ 📜__init__.py
 ┣ 📜setup.py          <- How this python package should be installed. Invoked by `pip install ...`

Template overrides

Every CKAN page is generated by rendering a particular template. For each page of a CKAN site there’s a corresponding template file. For example the front page is generated from the ckan/templates/home/index.html file, the /about page is generated from ckan/templates/home/about.html.

To customize pages, our plugin needs to register its own custom template directory containing template files that override the default ones.

class UDCPlugin(plugins.SingletonPlugin):
    # Declare that this class implements IConfigurer.
    plugins.implements(plugins.IConfigurer)

    def update_config(self, config: CKANConfig):
        toolkit.add_template_directory(config, 'templates')

CKAN will call this method when it starts up, to give our plugin a chance to modify CKAN’s configuration settings. Our update_config() method calls add_template_directory() to register its custom template directory with CKAN. This tells CKAN to look for template files in ckanext-udc/ckanext/udc/templates whenever it renders a page. Any template file in this directory that has the same name as one of CKAN’s default template files, will be used instead of the default file.

Extend CKAN Schema

TODO

Add custom config & Make config runtime editable

TODO