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.

Installation
- Use the base theme
- Use the components without the base theme
Run the demo site locally
Run the demo site as a Docker service
Development

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:

Enable the ILO base theme companion module
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 /patterns.

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.

Run the demo site locally

This project also ships with a buildable demo site, which allows developers to preview the base theme with ease. To do so run:

make

This will build a fully functional Drupal site with the ILO Base Theme enabled by default. After the installation is done visit:

http://localhost:8080

Note: the command above builds a demo site as self-contained service. To do so it performs the following commands in the container:

Run npm install to fetch the ILO Design System assets
Copy all relevant Drupal-related code in /opt/drupal
Build and install the Drupal site

This means that, when fetching a newer version, you might need to rebuild the demo site from scratch. To do so, run:

make build-dist

Run the demo site as a Docker service

The demo site is also published in the GitHub Docker registry. To run the site use the following command:

docker run --rm -p 8082:80 ghcr.io/international-labour-organization/ilo_base_theme:0.x

The site will then be available at http://localhost:8082.

In order to run the command above, you need to be authenticated, please check the related documentation.

Note: To get the most up-to-date version of 0.x, make sure to remove any pre-existing images by running the following command:

docker rmi -f ghcr.io/international-labour-organization/ilo_base_theme:0.x

If you need to log onto the container, run:

docker run -ti --rm ghcr.io/international-labour-organization/ilo_base_theme:0.x bash

Render patterns on demand

The ilo_base_theme_preview module exposes a /pattern-preview?id=...&variant=...&fields=... route that allows users to render a pattern on demand, by passing its ID, its variant (optional) and its fields as an encoded JSON object.

For example, to render a button, one could pass the following fields as JSON:

{
  "label": "Button",
  "type": "primary",
  "kind": "button",
  "size": "medium"
}

Encoded, that will look like the following:

http://localhost:8081/pattern-preview?id=button&fields=%7b%0a%22label%22%3a%20%22Button%22%2c%0a%22type%22%3a%20%22primary%22%2c%0a%22kind%22%3a%20%22button%22%2c%0a%22size%22%3a%20%22medium%22%0a%7d

Pattern settings need to be passed within the fields object. For example, to render a tooltip pattern, one would use the following:

{
  "label": "test",
  "settings": {
    "icon": true,
    "icontheme": "light",
    "theme": "dark"
  }
}

Note that any HTML needs to be set as Drupal #markup. For example, to render a richtext pattern, one would pass the following JSON to the fields parameter:

{
  "content": {
    "#markup": "<b>this is bold</b>, this is not"
  }
}

The test module above is enabled by default in both dev and dist Docker images but it is not included in the released package.

Development

The project contains all the necessary code and tools for an effective development process, meaning:

All PHP development dependencies (Drupal core included) are required in composer.json
All Node.js development dependencies are required in package.json
Project setup and installation can be easily handled thanks to the integration with the Task Runner project.
All system requirements are containerized using Docker Compose.

Development can be set up via Makefile's targets, as follows:

Start the development environment by running make up-dev install. This will:
- Build the development Drupal container from the dev target of the shipped Dockerfile
- Build a Drupal target site within the project
- Symlink the base theme codebase within the target site
- Mount the target site within the dev container
- Install the target site
- Install NodeJS dependencies by running npm install in the node container.
- Install the Design System
- Build a production ready version of the Drupal Theme
- Expose the site on http://localhost:8081

Please note: project files and directories are symlinked within the target site by using the OpenEuropa Task Runner's Drupal project symlink command.

If you add a new file or directory in the root of the project, you need run:

$ ./vendor/bin/run drupal:symlink-project

When working on the theme you might want to enable Drupal Twig debugging by running:

make twig-debug-on

international-labour-organization / ilo_base_theme

Maintainers

Details