search

openeuropa / oe_theme

Drupal 10 theme based on the Europa Component Library (ECL).
European Union Public License 1.2
31 stars 31 forks source link

readme

OpenEuropa theme

Build Status Packagist

Drupal 10 theme based on the Europa Component Library (ECL).

Table of contents:

Requirements

This depends on the following software:

Installation

The recommended way of installing the OpenEuropa 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 ECL templates and other assets. Simply Running composer require openeuropa/oe_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": {
            "openeuropa/oe_theme": {
                "dist": {
                    "url": "https://github.com/{name}/releases/download/{pretty-version}/{project-name}-{pretty-version}.tar.gz",
                    "type": "tar"
                }
            }
        },
    }

Once you are done, run:

composer require openeuropa/oe_theme

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

If you are not using Composer, then simply download a release artifact here (i.e. a oe_theme-[x.y.z].tar.gz file) and install it as described here.

Enable the theme

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

  1. Enable the OpenEuropa Theme Helper module ./vendor/bin/drush en oe_theme_helper
  2. Enable the OpenEuropa Theme and set it as default
./vendor/bin/drush theme:enable oe_theme
./vendor/bin/drush config-set system.theme default oe_theme

Step 1. is necessary until the following Drupal core issue is resolved. Alternatively you can patch Drupal core with this patch and enable the theme: the patched core will then enable the required OpenEuropa Theme Helper module.

The OpenEuropa theme supports both the EC and EU component libraries:

The theme uses the "European Commission" component library by default, you can change that by visiting the theme setting page.

Note for developers: changing the component library will only load different CSS and JS assets, the actual HTML is the same between the two libraries.

Each component library can use one of the following ECL brandings:

To learn more about EC/EU families and ECL branding visit the ECL website.

Upgrade to 4.0.0

The following patterns have been removed:

The following variants of the button pattern have been removed:

The language_switcher field of the page_header pattern has been removed. The additional_information field of the list_item pattern has been removed. The text_highlight and image_overlay variants fo the banner pattern have been replaced by a single variant text_overlay.

Two ECL components have been replaced:

Colors

In order to accommodate the color changes in ECL 4.0.0 we have added two twig functions to determine the correct color for border and background based on the component library (European Union or European Commission):

New patterns

Content display changes

All the teaser templates are using the vertical variant for displaying the lists.

Upgrade to 3.0.0

Page header pattern

ECL v3 adds the following features to the page header component:

In order to accommodate these changes we have added the following optional fields to the "Page header" pattern:

thumbnail:
  type: "ImageValueObject"
  label: "Thumbnail"
  description: "Thumbnail displayed alongside the description."
background_image_url:
  type: "array"
  label: "Background image URL"
  description: "Background image URL, only displayed when the theme ECL branding is set to 'Core'."
overlay:
  type: "text"
  label: "Overlay"
  description: "Optional overlay on top of background image (can be 'light', 'dark'). Only used on EC sites"

We have also removed the following deprecated fields:

identity:
  type: "text"
  label: "Identity (deprecated)"
  description: "The site name. Deprecated from ECL 2.30."
infos:
  type: "array"
  label: "Infos (deprecated)"
  description: "A list of infos of the current page. Deprecated from ECL 2.30."

In addition, the customization that allowed the content language switcher to be rendered inside the page header has been deprecated in favor of the new ECL composition. Instead, the OpenEuropa Content Language Switcher block provided by OpenEuropa Multilingual needs to be used in its place. Sites updating to OpenEuropa Theme V3 are advised to place this block in the page header region if they wish still need the functionality.

Content item compositions

We have removed the following compositions from our theme:

templates/compositions/ec-component-content-item/content-item-date.html.twig
templates/compositions/ec-component-content-item/content-item.html.twig

Consider using the List item pattern and its variants instead.

Text with Featured media pattern

The pattern Text with Featured media now supports the following 4 variants:

If no variant is set, then the pattern will be visualized using the default one. This guarantees backward compatibility.

Site header

ECL v3 supports the horizontal menu in both Core and Standardised branding. In order to accommodate this, we removed the visibility condition of the Main navigation block:

visibility:
  oe_theme_helper_current_branding:
    id: oe_theme_helper_current_branding
    branding: standardised
    negate: false
    context_mapping: {  }

Upgrade to 2.17.0

Dropdown UI pattern

In 2.17.0 we dropped support for the Dropdown pattern, which will be removed in the next major version. The pattern is still available, albeit hidden on the pattern overview page. The new Dropdown pattern is based on the ECL Expandable component and should work as a drop-in replacement of the old one.

Upgrade to 2.15.0

Social media links pattern

In 2.15.0 we introduced a new pattern "Social media links" with two variants:

Therefore patterns "Social media links: horizontal" and "Social media links: vertical" are now deprecated. Use the "Social media links" pattern with an appropriate variant instead.

Upgrade to 2.10.0

ECL page header

In 2.10.0 we dropped supporting the following elements in the "Page header" pattern:

As a result, if your PageHeaderMetadata plugins provide such data, it will no longer be displayed.

ECL branding

In 2.10.0 we introduced support for ECL branding (read above for more information). The OpenEuropa Theme will use the "Core" branding, visit the theme configuration page if you need to change that and use the "Standardised" branding instead.

To know which branding your site is supposed to use check the ECL website.

Upgrade to 2.9.0

Content type teasers

If you are using the oe_content module together with the OpenEuropa theme then updating to 2.9.0 or later will affect your existing teaser displays. The 2.9.0 version updates the teaser display of most content types provided by oe_content so if you want to keep any customization you have made to your site you will need to redo those modifications and override the teaser templates on your own custom theme.

ECL site header

In 2.9.0 we dropped support for the legacy ECL site header. To do so we had to move the language switcher block to the site_header_secondary theme region. This means that:

Upgrade from 1.x to 2.x

Companion sub-modules

Corporate blocks

When using the theme in conjunction with the OpenEuropa Corporate Blocks component changing the component library will show a different footer block, namely:

Image styles

OpenEuropa Theme ships with a number of image styles that should help users follow the guidelines set by the ECL. The following is a list of all the vailable styles and their preferred usage:

Development

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

Make sure you read the developer documentation before starting to use the theme in your projects.

Project setup

Developing the theme requires a local copy of ECL assets, including Twig templates, SASS and JavaScript source files.

In order to fetch the required code you'll need to have Node.js (>= 8) installed locally.

To install required Node.js dependencies run:

npm install

To build the final artifacts run:

npm run build

This will compile all SASS and JavaScript files into self-contained assets that are exposed as Drupal libraries.

In order to download all required PHP code run:

composer install

This will build a fully functional Drupal site in the ./build directory that can be used to develop and showcase the theme.

Before setting up and installing the site make sure to customize default configuration values by copying runner.yml.dist to ./runner.yml and override relevant properties.

To set up the project run:

./vendor/bin/run drupal:site-setup

This will:

Please note: project files and directories are symlinked within the test 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 to re-run drupal:site-setup in order to make sure they are be correctly symlinked.

If you don't want to re-run a full site setup for that, you can simply run:

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

After a successful setup install the site by running:

./vendor/bin/run drupal:site-install

This will:

Using Docker Compose

Alternatively, you can build a development site using Docker and Docker Compose with the provided configuration.

Docker provides the necessary services and tools such as a web server and a database server to get the site running, regardless of your local host configuration.

Requirements:

Configuration

By default, Docker Compose reads two files, a docker-compose.yml and an optional docker-compose.override.yml file. By convention, the docker-compose.yml contains your base configuration and it's provided by default. The override file, as its name implies, can contain configuration overrides for existing services or entirely new services. If a service is defined in both files, Docker Compose merges the configurations.

Find more information on Docker Compose extension mechanism on the official Docker Compose documentation.

Usage

To start, run:

docker-compose up

It's advised to not daemonize docker-compose so you can turn it off (CTRL+C) quickly when you're done working. However, if you'd like to daemonize it, you have to add the flag -d:

docker-compose up -d

Then:

docker-compose exec -u node node npm install
docker-compose exec -u node node npm run build
docker-compose exec web composer install
docker-compose exec web ./vendor/bin/run drupal:site-install

Using default configuration, the development site files should be available in the build directory and the development site should be available at: http://127.0.0.1:8080/build.

Running the tests

To run the grumphp checks:

docker-compose exec web ./vendor/bin/grumphp run

To run the phpunit tests:

docker-compose exec web ./vendor/bin/phpunit

To run the behat tests:

docker-compose exec web ./vendor/bin/behat

Step debugging

To enable step debugging from the command line, pass the XDEBUG_SESSION environment variable with any value to the container:

docker-compose exec -e XDEBUG_SESSION=1 web <your command>

Please note that, starting from XDebug 3, a connection error message will be outputted in the console if the variable is set but your client is not listening for debugging connections. The error message will cause false negatives for PHPUnit tests.

To initiate step debugging from the browser, set the correct cookie using a browser extension or a bookmarklet like the ones generated at https://www.jetbrains.com/phpstorm/marklets/.

Disable Drupal 8 caching

Manually disabling Drupal 8 caching is a laborious process that is well described here.

Alternatively, you can use the following Drupal Console command to disable/enable Drupal 8 caching:

./vendor/bin/drupal site:mode dev  # Disable all caches.
./vendor/bin/drupal site:mode prod # Enable all caches.

Note: to fully disable Twig caching the following additional manual steps are required:

  1. Open ./build/sites/default/services.yml
  2. Set the following parameters:
parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false
  1. Rebuild Drupal cache: ./vendor/bin/drush cr

This is due to the following Drupal Console issue.

Working with ECL components

You can use the ECL components in your Twig templates by referencing them using the ECL Twig Loader as shown below:

{% include '@ecl-twig/logos' with {
  'to': 'https://ec.europa.eu',
  'title': 'European Commission',
} %}

Important: not all ECL templates are available to the theme for include, whenever you need include a new ECL template remember to add it to the copy section of ecl-builder.config.js and run:

npm run build

Update ECL

To update ECL components change the @ec-europa/ecl-preset-full version number in package.json and run:

npm install && npm run build

This will update assets such as images and fonts and re-compile CSS. Resulting changes are not meant to be committed to this repository.

Watching and re-compiling Sass and JS changes

To watch for Sass and JS file changes - /sass folder - in order to re-compile them to the destination folder:

npm run watch

Resulting changes are not meant to be committed to this repository.

Patching ECL components

ECL components can be patched by using the patch-package NPM project.

To patch a component:

  1. Modify its source files directly in ./node_modules/@ecl/[component-name]
  2. Run:
npx patch-package @ecl-twig/[component-name]

Or, when using Docker Compose:

docker-compose exec -u node node git config --global user.email "name@example.com"
docker-compose exec -u node node git config --global user.name "Name"
docker-compose exec -u node node npx patch-package @ecl/[component-name]

Patches will be generated in ./patches and applied when running npm install.

Working with a development version of ECL

To build the theme using a development version of ECL run make ecl-dev instead of the npm install procedure described above, this will:

If you want to create a release using a dev ECL version, make sure that ECL_BUILD is set to dev in .env.dist. You can then control which branch and repo ECL will be built from by setting ECL_BUILD_REF and ECL_BUILD_REPO in the same file.

Contributing

Please read the full documentation for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the available versions, see the tags on this repository.