international-labour-organization/ilo_base_theme

Drupal base theme for the International Labour Organization.

1.0.0 2024-12-11 14:16 UTC

Requires

• php: >=8.1
• cweagans/composer-patches: ~1.7
• drupal/components: ^3.1
• drupal/twig_tweak: ^3.4
• drupal/ui_patterns: ^1.10
• drupal/ui_patterns_settings: ^2.4
• squirrelphp/twig-php-syntax: ^1.8

Requires (Dev)

• composer/installers: ~1.5
• drupal/coder: ^8.3
• drupal/config_devel: ^1.9
• drupal/core: ^9 || ^10 || ^11
• drupal/core-composer-scaffold: ^9 || ^10 || ^11
• drupal/core-dev: ^9 || ^10 || ^11
• drupal/core-utility: ^9 || ^10 || ^11
• drupal/styleguide: ^2.1
• drush/drush: ~12
• mikey179/vfsstream: ^1.6.10
• openeuropa/task-runner-drupal-project-symlink: ^1.0.0-beta6
• phpspec/prophecy-phpunit: ^2
• symfony/phpunit-bridge: ^6.0

Apache-2.0

README

Drupal 10 theme based on the ILO Design System. The project is structured in the following way:

• A Drupal base theme providing pre-styled core Drupal elements (such as forms, tabs, and navigation), all adhering to the ILO’s design guidelines.
• A theme companion module ilo_base_theme_companion, which exposes all compatible ILO Design System components as Drupal patterns. Check the UI Patterns and the UI Patterns Settings modules for more information.

The theme requires the companion module to be enabled, while one could enable the companion module without enabling the base theme.

Enabling only the companion module is useful for projects that already have the ILO Design System integrated but have not yet adopted patterns, allowing for incremental adoption of the base theme's pattern-based approach.

Table of contents

• Installation
  • Use the base theme
  • Use the components without the base theme
  • Opinionated components
  • Patterns and cache metadata
  • Handling Forms
• How to create a sub-theme
• Development
• NPM commands
• Demo site

Installation

The recommended way of installing the ILO Base Theme is via Composer.

Before proceeding, please note that theme releases are built by a continuous integration system, and include code coming from third-party libraries, such as ILO Design System templates and other assets. Simply Running composer require international-labour-organization/ilo_base_theme will download the raw theme source code, which misses required third-party code.

In order to instruct Composer to download the actual built artifact, you need to require and configure the Composer Artifacts project.

To do so, run:

composer require openeuropa/composer-artifacts

Then add the following section in your project's composer.json:

    "extra": {
        "artifacts": {
            "international-labour-organization/ilo_base_theme": {
                "dist": {
                    "url": "https://github.com/{name}/releases/download/{pretty-version}/{project-name}-{pretty-version}.zip",
                    "type": "zip"
                }
            }
        },
    }

Once you are done, run:

composer require international-labour-organization/ilo_base_theme

This will download the fully built artifact, as opposed to the raw theme source code.

Use the base theme

In order to enable the theme in your project perform the following steps:

1. Enable the ILO base theme companion module
2. Enable the ILO base theme and set it as default

./vendor/bin/drush en ilo_base_theme_companion
./vendor/bin/drush theme:enable ilo_base_theme
./vendor/bin/drush config-set system.theme default ilo_base_theme

Use the components without the base theme

If you already have a theme, and you just want to use the design system components, just enable the companion module, without enabling the theme, like so:

./vendor/bin/drush en ilo_base_theme_companion

The full list of components is available at /admin/appearance/ui/patterns.

Opinionated components

The hero component

The hero component generates a breadcrumb trail based on the current route and ensures proper caching for the breadcrumb metadata.

The navigation component

The ILO base theme has specific conventions for handling the main menu. When the companion module is enabled, a "More" link is automatically created. This menu link serves to group all links under the header's expandable "More" panel. If the "More" link does not contain any child items, it will not be displayed.

In case of a multilingual site, the navigation component also includes a multilingual language switcher links.

Patterns and cache metadata

Displaying render arrays using patterns requires a careful handing of the render array's cache metadata. For example, if you want to use the card pattern to render a news content type teaser, you would typically do the following:

{{ pattern('card', {
  title: content.title,
  link: content.field_link['#url'],
  size: 'fluid',
}, 'feature') }}

The problem with the above is that cache tags and contexts (for example from the link at field_link) are not bubbled up correctly.

In order to solve the issue it is recommended to explicitly bubble up the cache metadata of the render array at hand. You can do that by using the |cache_metadata filter exposed by the Twig Tweak module, as shown below:

{{ pattern('card', {
  title: content.title,
  link: content.field_link['#url'],
  size: 'fluid',
}, 'feature') }}

{{ content|cache_metadata }}

Another recommended module to keep in mind, when working with patterns, is the Twig Field Value, which can help with accessing properties and subfields of render arrays and entities when passing them over to patterns.

Handling Forms

The ILO Design System includes comprehensive styles for forms to ensure consistency and usability across the platform. However, due to the internal workings of Drupal's Form API, UI Patterns cannot be directly used to style forms.

Instead, the ILO Base Theme adopts a traditional Drupal templating approach to style forms, this involves applying relevant ILO Design System classes directly to Drupal form templates.