OpenEuropa theme
, (*1)
Drupal 8 theme based on the Europa Component Library (ECL)., (*2)
Table of contents:, (*3)
Requirements
This depends on the following software:, (*4)
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)
- Enable the OpenEuropa Theme Helper module
./vendor/bin/drush en oe_theme_helper
- 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
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:
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)
- Open
./build/sites/default/services.yml
- 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)
- Modify its source files directly in
./node_modules/@ecl/[component-name]
- 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)
Wallogit.com
