ckanext-theming

This is a prototype of CKAN theming proposal. It defines a standard way to customize the look and feel of a CKAN instance. It allows developers and designers to create and apply themes without modifying core CKAN code, ensuring easier upgrades and maintenance.

Theme implementations:

Requirements

Compatibility with core CKAN versions:

Overview

The CKAN Theming Extension introduces a modern theming system that provides a structured approach to UI customization. The system is built around a macro-based UI framework that allows themes to provide consistent, reusable components across CKAN instances.

Traditional CKAN Theme Implementation

• Uses snippets for complex widgets
• Majority of UI elements is implemented directly as template code with HTML
• Contains framework-specific HTML with CSS classes directly in templates
• Example: Input macros are called with Bootstrap classes as parameters

Suggested macro-based approach

• Creates a collection of UI macros that abstract the underlying CSS framework
• Developers use semantic calls like {{ ui.button("Click Me", style="primary") }} instead of writing HTML
• Different themes can implement the same macros with different CSS frameworks (Bootstrap 5, Tailwind, Bulma, Pico CSS, etc.)
• The theme system allows switching between completely different CSS frameworks by changing one configuration setting
• Each theme provides its own implementation of the same set of macros using its specific CSS framework classes
• Provides a consistent API regardless of the underlying CSS framework

Core Philosophy

ckanext-theming is designed to be optional and non-intrusive. You don't have to rewrite your existing code to use it. You can adopt it incrementally, using it only for new features or specific components where you want to benefit from theme portability.

For a deeper dive into what this project is (and isn't), check out the Philosophy & Goals page in our documentation.

Installation

To install ckanext-theming:

1. Activate your CKAN virtual environment:

   pip install ckanext-theming
   

2. Add theming to the ckan.plugins setting in your CKAN config file:

   ckan.plugins = ... theming
   

3. Specify theme using ckan.ui.theme config option. Check available themes using ckan theme list CLI command

   ckan.ui.theme = classic-polyfill
   

Usage

Registering Themes

Extensions can register themes by implementing the ITheme interface in their plugin class:

import ckan.plugins as p
from ckanext.theming.interfaces import ITheme
from ckanext.theming.lib import Theme

class MyThemePlugin(ITheme, p.SingletonPlugin):

    def register_themes(self):
        return [
            Theme("my_theme", "/path/to/my_theme/root"),
            Theme("extended_my_theme", "/path/to/extended_my_theme/root", parent="my_theme"),
        ]

Using UI Macros

Once a theme is active, UI macros can be used in templates:

{{ ui.button("Click Me", style="primary", type="button") }}
{{ ui.card("Card content here", title="My Card") }}
{{ ui.alert("Success message", style="success") }}

Creating Custom Themes

For detailed instructions on creating custom themes, see theming guide.