Metadata-Version: 2.4
Name: ckanext-theming
Version: 0.0.1
Author-email: DataShades <datashades@linkdigital.com.au>, Sergey Motornyuk <sergey.motornyuk@linkdigital.com.au>, Oleksandr Cherniavskyi <mutantsan@gmail.com>
Maintainer-email: DataShades <datashades@linkdigital.com.au>
License: AGPL
Project-URL: Homepage, https://github.com/DataShades/ckanext-theming
Keywords: CKAN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest-ckan; extra == "test"
Requires-Dist: pytest-benchmark; extra == "test"
Requires-Dist: pytest-pretty; extra == "test"
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: pymdown-extensions; extra == "docs"
Requires-Dist: mkdocstrings[python]; extra == "docs"
Requires-Dist: mkdocs-autorefs; extra == "docs"
Requires-Dist: mkdocs-macros; extra == "docs"
Requires-Dist: mkdocs-glightbox; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest-ckan; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"
Requires-Dist: pytest-pretty; extra == "dev"
Requires-Dist: mkdocs; extra == "dev"
Requires-Dist: mkdocs-material; extra == "dev"
Requires-Dist: pymdown-extensions; extra == "dev"
Requires-Dist: mkdocstrings[python]; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest-playwright; extra == "dev"
Requires-Dist: mkdocs-autorefs; extra == "dev"
Requires-Dist: mkdocs-macros; extra == "dev"
Requires-Dist: mkdocs-glightbox; extra == "dev"
Dynamic: license-file

[![Tests](https://github.com/DataShades/ckanext-theming/workflows/Tests/badge.svg?branch=main)](https://github.com/DataShades/ckanext-theming/actions)

# 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.

## Requirements

Compatibility with core CKAN versions:

| CKAN version | Compatible? |
|--------------|-------------|
| 2.11         | no          |
| 2.12         | yes         |

## 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


The key benefit is the complete separation of content structure from styling. This means users can
completely change the visual appearance of their CKAN instance (from Bootstrap to Tailwind, for example) by
just changing the theme configuration, without modifying any templates or code.



## Installation

To install ckanext-theming:

1. Activate your CKAN virtual environment:

   ```sh
   pip install ckanext-theming
   ```

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

   ```ini
   ckan.plugins = ... theming
   ```

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

   ```ini
   ckan.ui.theme = bare
   ```

## Usage

### Registering Themes

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

```python
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:

```jinja
{{ 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](https://datashades.github.io/ckanext-theming/theme/).
