openeuropa/oe_theme

OpenEuropa base theme.

OpenEuropa theme

, _(*1)

Drupal 8 theme based on the Europa Component Library (ECL)., _(*2)

Table of contents:, _(*3)

• Requirements
• Installation
• Companion sub-modules
• Development
  • Project setup
  • Using Docker Compose
  • Disable Drupal 8 caching
  • Working with ECL components
• Contributing
• Versioning

Requirements

This depends on the following software:, _(*4)

• PHP 7.1

Installation

The recommended way of installing the OpenEuropa theme is via Composer., _(*5)

composer require openeuropa/oe_theme

If you are not using Composer then download the release package and install it as described here., _(*6)

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., _(*7)

Enable the theme

In order to enable the theme in your project perform the following steps:, _(*8)

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., _(*9)

Companion sub-modules

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

Development

The OpenEuropa Theme project contains all the necessary code and tools for an effective development process, meaning:, _(*10)

• 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.

Project setup

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

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

To install required Node.js dependencies run:, _(*13)

npm install

To build the final artifacts run:, _(*14)

npm run build

This will compile all SASS and JavaScript files into self-contained assets that are exposed as Drupal libraries., _(*15)

In order to download all required PHP code run:, _(*16)

composer install

This will build a fully functional Drupal site in the ./build directory that can be used to develop and showcase the theme., _(*17)

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., _(*18)

To set up the project run:, _(*19)

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

This will:, _(*20)

• 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:, _(*21)

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

This will:, _(*22)

• 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., _(*23)

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., _(*24)

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., _(*25)

Find more information on Docker Compose extension mechanism on the official Docker Compose documentation., _(*26)

Usage

To start, run:, _(*27)

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:, _(*28)

docker-compose up -d

Then:, _(*29)

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., _(*30)

Running the tests

To run the grumphp checks:, _(*31)

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

To run the phpunit tests:, _(*32)

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

To run the behat tests:, _(*33)

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., _(*34)

Alternatively, you can use the following Drupal Console command to disable/enable Drupal 8 caching:, _(*35)

./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:, _(*36)

1. Open ./build/sites/default/services.yml
2. Set cache: false in twig.config: property. E.g.:

parameters:
     twig.config:
       cache: false
 ```
3. Rebuild Drupal cache: `./vendor/bin/drush cr`

This is due to the following [Drupal Console issue][15].

### Working with ECL components

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

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

Or:, _(*37)

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

JavaScript components can be accessed by ECL.methodName(), e.g. ECL.accordions()., _(*38)

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:, _(*39)

npm run build

Update ECL

To update ECL components change the @ec-europa/ecl-preset-full version number in package.json and run:, _(*40)

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., _(*41)

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:, _(*42)

npm run watch

Resulting changes are not meant to be committed to this repository., _(*43)

Patching ECL components

ECL components can be patched by using the [patch-package][18] NPM project., _(*44)

To patch a component:, _(*45)

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

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

Or, when using Docker Compose:, _(*46)

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

Patches will be generated in ./patches and applied when running npm install., _(*47)

Contributing

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

Versioning

We use SemVer for versioning. For the available versions, see the tags on this repository., _(*49)