2017 © Pedro Peláez
 

drupal-theme oe_theme

OpenEuropa base theme.

image

openeuropa/oe_theme

OpenEuropa base theme.

  • Tuesday, July 31, 2018
  • by ademarco
  • Repository
  • 22 Watchers
  • 7 Stars
  • 734 Installations
  • PHP
  • 1 Dependents
  • 0 Suggesters
  • 4 Forks
  • 1 Open issues
  • 29 Versions
  • 158 % Grown

The README.md

OpenEuropa theme

Build Status Packagist, (*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)

  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

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)

  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)

The Versions