How to modify the front-end template in ckan-docker?

[dev-marcoC]

Hello @mjanez,

I'm currently working with the ckan-docker setup and would like to customize the front-end template. Could you please guide me on how to proceed with modifying the template? Any help or pointers would be greatly appreciated.

Thank you for your time and assistance!

Best regards,
Marco

[mjanez]

Hi Marco, to customize the front-end template in CKAN using the ckan-docker setup, the best approach is to create a CKAN extension where you can override templates, add custom styles, and implement any additional frontend logic you need. Here are the basic steps for developing a custom theme in CKAN:

1. Set up your CKAN extension
   To customize the front-end, you'll need to create an extension. CKAN allows
   overriding its default templates by creating an extension that loads your custom
   templates, styles, assets, helpers, etc. You can follow these basic steps:

   1. Create a CKAN extension: You can use the development mode and ckan-docker documentation.

   2. Structure of the extension: The extension will have the following structure:

   ckanext-yourtheme/
   ├── ckanext/
   │   └── yourtheme/
   │       ├── assets
   │       │   └── css/
   │       │   └── js/
   │       ├── public
   │       └── templates/
   │           └── (template overrides here)
   ├── setup.py
   └── README.md

   3. Override CKAN templates: To customize the frontend, place your templates into the templates directory of your extension. CKAN's core templates are located in the ckan/templates folder. You can override any of the by creating a file with the same name in your extension or by creating news, in your extension: Customizing CKAN templates

   4. Load your extension: Once your extension is ready, enable it by adding it to the CKAN plugins in your ckan.ini configuration file:

      ckan.plugins = yourtheme

2. Modify Templates
   For example, if you want to customize the homepage (home/index.html), you
   would copy the default index.html from the core CKAN templates into your
   extension’s templates directory and then modify it as needed. Make your changes in this file, and CKAN will use it instead of the default one.

3. Use offical docs & existing Extensions as Reference
   The official CKAN documentation is really good and is always a great reference
   for further development:

   • CKAN Code architecture
   • Theming guide
   • Front-End Tests

   For reference, you can check out some of our existing CKAN extensions that customize the front end:

   • ckanext-schemingdcat - This extension demonstrates how to customize forms and
     layouts using custom templates and much more.
   • ckanext-fototeca - Another basic example of customizing CKAN’s frontend and backend by extending templates and functionality.

   These repositories will give you a good idea of how to structure your code, override templates, and add custom logic.

4. Stack Technologies for CKAN Front-End
   CKAN uses a stack of technologies for its frontend, including:

   • Jinja2 for templating.
   • HTML/CSS/JavaScript for static content.
   • Bootstrap for responsive design and default UI components.
   • Flask (which CKAN is built on) for serving dynamic content.
   • htmx: Since CKAN 2.11, info: https://docs.ckan.org/en/2.11/theming/htmx.html

   You'll primarily be working with Jinja2 templates to modify the HTML and extend CKAN’s interface. Additionally, you can customize the look and feel with CSS and add interactivity using JavaScript.

Cheers!

[dev-marcoC]

Hi, I tried to add a custom plugin from a git repository. I followed all your instructions, but the result is always the same.

My plugin doesn't override the scheming template, and my team and I can't figure out why. Could you help us out?

We have verified that the custom plugin is correctly loaded inside the ckan_dev container in the src_extensions folder, but the template located in /srv/app/src/ckan/ckan/templates is still the one from scheming.

[mjanez]

Hi, I tried to add a custom plugin from a git repository. I followed all your instructions, but the result is always the same.

My plugin doesn't override the scheming template, and my team and I can't figure out why. Could you help us out?

We have verified that the custom plugin is correctly loaded inside the ckan_dev container in the src_extensions folder, but the template located in /srv/app/src/ckan/ckan/templates is still the one from scheming.

I try to help you, ckanext-scheming is a bit unique in that you need to leverage its schema system but still want to override its templates. For this, you have to load scheming in your src/ directory - development mode- but avoid including it in the active plugin list. Additionally, you need to implement and inherit from scheming interfaces to ensure you can both use the schema functionality and override the templates correctly.

Here’s how you can adjust your setup:

1. Make sure the scheming extension is available in your src/ folder. You’ve probably already done this.

2. Do not load scheming in the ckan.plugins list (CKAN__PLUGINS)

In your ckan.ini, ensure that scheming is not explicitly listed in the ckan.plugins section. You’ll only load your custom plugin that inherits from scheming.

Example:

ckan.plugins = your_custom_plugin

3. In your custom plugin, you should extend the SchemingDatasetsPlugin class, as you pointed out. This will allow you to inherit the schema functionality while overriding the templates. Here’s an example structure for your plugin from our ckanext-schemingdcat:

from ckanext.scheming.plugins import SchemingDatasetsPlugin
import ckan.plugins as plugins

class CustomSchemingPlugin(SchemingDatasetsPlugin):
    plugins.implements(plugins.IConfigurer)
    plugins.implements(plugins.IConfigurable)
    plugins.implements(plugins.ITemplateHelpers)
    plugins.implements(plugins.IDatasetForm, inherit=True)
    plugins.implements(plugins.IActions)
    plugins.implements(plugins.IValidators)

    def read_template(self):
        # Override the default read template
        return "your_custom_plugin/package/read.html"

    def resource_template(self):
        # Override the default resource template
        return "your_custom_plugin/package/resource_read.html"

    def package_form(self):
        return "your_custom_plugin/package/snippets/package_form.html"

    def resource_form(self):
        return "your_custom_plugin/package/snippets/resource_form.html"

This approach ensures that CKAN will use your custom templates (your_custom_plugin/templates/) instead of the ones from scheming.

4. You still need to register your custom templates directory with CKAN. To do this, add the update_config function in your plugin class:

def update_config(self, config):
    # Add the custom templates directory to CKAN's search path
    plugins.toolkit.add_template_directory(config, 'templates')

If you run into any more issues, feel free to reach out.