Skip to content

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

4 watching

Forks

Repository files navigation

Tests

ckanext-nswdesignsystem

A theme extension that implements the NSW Design System for CKAN.

Originally built as a collection of standalone macros, this extension has been rewritten to provide theme implementations integrated with ckanext-theming. By utilizing ckanext-theming, this extension delivers a decoupled, macro-based UI theme that makes it easy to apply the NSW Design System look and feel to your CKAN portal.


Themes Provided

This extension registers the following themes with the ckanext-theming framework:

  1. nds-ui: A base UI library theme containing core macros (buttons, cards, alerts, etc.) structured using NSW Design System HTML and CSS.
  2. nsw-design-system: The primary end-user theme that inherits from nds-ui and applies the complete NSW Design System visual layout, colors, and typography across CKAN pages.

Compatibility

CKAN version Compatible?
2.9 no
2.10 yes
2.12 yes

Note

To use the theme integration features, ckanext-theming must be installed.


Screenshots

Below are placeholders for screenshots of the NSW Design System theme in action. (These will be populated soon!)

Homepage

Homepage Mockup / Screenshot Placeholder

Dataset Search / Registry page

Dataset Search Mockup / Screenshot Placeholder

Dataset Detail page

Dataset Detail Mockup / Screenshot Placeholder


Installation

1. Install the Extensions

Ensure your CKAN virtual environment is activated, then install both ckanext-theming and ckanext-nswdesignsystem:

pip install ckanext-theming
pip install ckanext-nswdesignsystem

2. Update CKAN Configuration

Add both theming and nswdesignsystem to the ckan.plugins setting in your CKAN configuration file (e.g., ckan.ini):

ckan.plugins = ... theming nswdesignsystem

Enable the NSW Design System theme by specifying it in the ckan.ui.theme config option:

ckan.ui.theme = nsw-design-system

Configuration Settings

You can customize the extension behavior by adding the following settings to your CKAN configuration file:

Config Option Type Default Description
ckanext.nswdesignsystem.legacy_enabled bool true Enable legacy templates and components created before the theming integration. (Deprecated; will be removed in a future release)
ckanext.nswdesignsystem.css_enabled bool true Automatically load NSW Design System CSS assets.
ckanext.nswdesignsystem.js_enabled bool true Automatically load NSW Design System JavaScript assets.
ckanext.nswdesignsystem.debug bool false Enable debug options for CSS and JS assets.

Legacy Usage

Important

The legacy macros are deprecated and planned for removal. Users are strongly encouraged to migrate to the new ckanext-theming base themes.

If you have enabled ckanext.nswdesignsystem.legacy_enabled = true, you can use the old standalone components:

  1. Visit the /nswdesignsystem/components page to view implemented components and code examples.
  2. Call components in templates using macro syntax:
    {{ masthead() }}
    Or:
    {% call masthead() %}
        {# additional content for masthead #}
    {% endcall %}

Development

To install ckanext-nswdesignsystem for development, activate your CKAN virtualenv and run:

git clone https://github.com/DataShades/ckanext-nswdesignsystem.git
cd ckanext-nswdesignsystem
pip install -e .

Contributing and Commit Messages

We follow the Conventional Commits specification:

  • Features: feat: <description>
  • Bug Fixes: fix: <description>
  • Maintenance / Chores: chore: <description>

Updating the NSW Design System Assets

The extension wraps the official nsw-design-system package. To update the underlying NSW Design System library:

  1. Update the library using npm:
    npm up nsw-design-system
  2. Copy compiled assets into the vendor folder:
    make vendor
  3. Update source files in the assets directory:
    make nsw-source

(Note: Custom behaviors are applied via patches located in the patches/ folder during the build process.)

Locally Hosted Fonts

make vendor and make nsw-source do not replace the locally hosted fonts in public/nswdesignsystem/fonts. If an NSW Design System update changes the font family, weights, or icon font requirements, update the font files, fonts.css, checksums, and licenses together.

External Resource Policy

Fonts and the optional Chartist chart component are served from this extension's public/ directory. make vendor and make nsw-source do not replace those assets. The NSW Design System package assets loaded from unpkg are version-pinned and include Subresource Integrity metadata.

The conditional Google reCAPTCHA loader remains an exception: its response is dynamic, so a fixed SRI hash would break the challenge. It is rendered only when g.recaptcha_publickey is configured.


Tests

To execute tests, run:

pytest

Releasing a New Version

To publish a new release of ckanext-nswdesignsystem on PyPI:

  1. Update the version number in setup.cfg.
  2. Make sure you have the required release tools:
    pip install -U twine build git-changelog -r dev-requirements.txt
  3. Build and update the changelog:
    make changelog
  4. Create source and binary distributions:
    python -m build
  5. Upload to PyPI:
    twine upload dist/*
  6. Commit and push the tag:
    git commit -a
    git push
    git tag v0.2.19  # Replace with actual version from pyproject.toml
    git push --tags

---

## License

[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.en.html)

About

No description, website, or topics provided.

Resources

Stars

3 stars

Watchers

4 watching

Forks

Releases

Packages

Used by

Contributors

Languages