OpenEuropa theme

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

Table of contents:

• Requirements
• Installation
• Companion sub-modules
• Image styles
• Upgrade from 1.x to 2.x
• Development
  • Project setup
  • Using Docker Compose
  • Disable Drupal 8 caching
  • Working with ECL components
• Contributing
• Versioning

Requirements

This depends on the following software:

• PHP 7.2 or 7.3

Installation

The recommended way of installing the OpenEuropa theme is via Composer.

composer require openeuropa/oe_theme

If you are not using Composer then download the release package and install it as described here.

Note: Release archives are built by the continuous integration system and include code coming from third-party libraries, such as ECL templates and other assets. Make sure you use an actual release and not the source code archives.

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

• Use the "European Commission" component library for European Commission websites hosted under the ec.europa.eu domain
• Use the "European Union" component library for European Union websites hosted under the europa.eu domain

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.

Companion sub-modules

• OpenEuropa Theme News
• OpenEuropa Theme Page
• OpenEuropa Theme Policy
• OpenEuropa Theme Publication

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:

• The European Commission footer, shipping with a set of links and references that must be present on all European Commission sites.
• The European Union footer, shipping with a set of links and references that must be present on all European Union sites.

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:

• List item (oe_theme_list_item): To be used on content lists with small thumbnails.
• Featured list item (oe_theme_list_item_featured): To be used on highlights and content lists with big thumbnails.
• Medium (oe_theme_medium_no_crop): Medium sized image, part of the Main content responsive image style.
• Small (oe_theme_small_no_crop): Small sized image, part of the Main content responsive image style.
• Main content (oe_theme_main_content): Responsive image style, to be used on any image that is rendered inside a content page.

Upgrade from 1.x to 2.x

• The following patterns have been removed on 2.x:
  • dialog
  • file_link
• The variant field on the field pattern has been removed. Instead, ui_patterns variants definition is used. Read ui_patterns pattern definition documentation for how it works.
• OpenEuropa Corporate Blocks 1.x is not supported anymore, you should use version 2.x instead.

Development

The OpenEuropa Theme 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 Composer.
• Every change to the code base will be automatically tested using Drone.

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:

• Symlink the theme in ./build/themes/custom/oe_theme so that it's available to the target site
• Setup Drush and Drupal's settings using values from ./runner.yml.dist
• Setup PHPUnit and Behat configuration files using values from ./runner.yml.dist

After a successful setup install the site by running:

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

This will:

• Install the target site
• Set the OpenEuropa Theme as the default theme
• Enable OpenEuropa Theme Demo and Configuration development modules

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:

• Docker
• Docker Compose

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

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

3. 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-twig/[component-name]
2. Run:

npx patch-package @ecl-twig/[component-name]

Or, when using Docker Compose:

docker-compose exec -u node node npx patch-package @ecl-twig/[component-name]

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

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.