Download the PHP package openeuropa/oe_theme without Composer
On this page you can find all versions of the php package openeuropa/oe_theme. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package oe_theme
OpenEuropa theme
Drupal 10 theme based on the Europa Component Library (ECL).
Table of contents:
- Requirements
- Installation
- Enable the theme
- Upgrade to 3.0.0
- Upgrade to 2.17.0
- Upgrade to 2.15.0
- Upgrade to 2.10.0
- Upgrade to 2.9.0
- Upgrade from 1.x to 2.x
- Companion sub-modules
- Corporate blocks
- Image styles
- Development
- Project setup
- Using Docker Compose
- Disable Drupal 8 caching
- Working with ECL components
- Contributing
- Versioning
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:
Then add the following section, in your project's composer.json
:
Once you are done, run:
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:
- Enable the OpenEuropa Theme Helper module
- Enable the OpenEuropa Theme and set it as default
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.
Each component library can use one of the following ECL brandings:
- Standardized: standardised websites host thematic content owned by a specific DG/Agency. This is the default solution to host DG-specific content (policy) and is closely aligned with the core site.
- Core: core websites host general information shared by different websites or departments and serve as hubs for onward navigation to further thematic content and/or specific services. For example, the main European Commission website (https://ec.europa.eu) uses ECL core branding.
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:
banner_hero
banner_page
social_media_links_horizontal
social_media_links_vertical
The following variants of the button pattern have been removed:
form
form_primary
splash_page
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:
- Message component (
twig-component-message
) replaced by Notification component (twig-component-notification
) - Language list component (
twig-component-language-list
) replaced by Splash page (twig-component-splash-page
)
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):
ecl_class_border_color
ecl_class_background_color
The grey color used in typography case has been replaced with dark.
New patterns
- Highlighted list pattern (
highlighted_list
) - used for displaying a main highlighted item along with 3 secondary items placed on the right side of the page. All the items are using thelist_item
pattern's structure withdefault
. - Tabs pattern (
tabs
) - used mainly for navigation links. We are using this to render the Drupal local tasks.
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:
- The possibility of displaying a thumbnail right next to the page description
- The possibility of adding a background image
- The possibility of adding an overlay on top of the background image, to compensate for poor text contrast
In order to accommodate these changes we have added the following optional fields to the "Page header" pattern:
We have also removed the following deprecated fields:
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:
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:
- Left simple /
left_simple
: text on the left, simple call to action. This is the default behaviour. - Right simple /
right_simple
: text on the right, simple call to action. - Left featured /
left_featured
: text on the left, featured call to action. - Right featured /
right_featured
: text on the right, featured call to action.
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:
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:
horizontal
: social media links will be arranged horizontally.vertical
: social media links will be arranged vertically.
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:
identity
: used to show site-identifying information (such as the site name).infos
: used to show secondary meta information, below the page header introduction text.
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:
- If your site does not use a sub-theme, then you have nothing to worry about, as we will move the block there for you in a post-update hook (if we find one)
- If your site does use a sub-them which displays the language switcher block, then you'll need to move it to the
site_header_secondary
region yourself
Upgrade from 1.x to 2.x
- The following patterns have been removed on 2.x:
dialog
file_link
- The
variant
field on thefield
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.
Companion sub-modules
- OpenEuropa Theme Contact Forms
- OpenEuropa Content Call for tenders companion module
- OpenEuropa Content Corporate Entity Contact companion module
- OpenEuropa Content Corporate Entity Organisation companion module
- OpenEuropa Content Corporate Entity Venue companion module
- OpenEuropa Content Event companion module
- OpenEuropa Content News companion module
- OpenEuropa Content Page companion module
- OpenEuropa Content Policy companion module
- OpenEuropa Content Project companion module
- OpenEuropa Content Publication companion module
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. - Full width (3840) (
oe_theme_full_width
): Full width image (3840px x 3840px).Banner image styles for different ratios
- Full width banner 3:1 (
oe_theme_full_width_banner_3_1
) - Extra large banner 3:1 (
oe_theme_extra_large_3_1_banner
) - Large banner 3:1 (
oe_theme_large_3_1_banner
) - Medium banner 3:1 (
oe_theme_medium_3_1_banner
) - Small banner 3:1 (
oe_theme_small_3_1_banner
) - Full width banner 4:1 (
oe_theme_full_width_banner_4_1
) - Extra large banner 4:1 (
oe_theme_extra_large_4_1_banner
) - Large banner 4:1 (
oe_theme_large_4_1_banner
) - Medium banner 4:1 (
oe_theme_medium_4_1_banner
) - Small banner 4:1 (
oe_theme_small_4_1_banner
) - Full width banner 5:1 (
oe_theme_full_width_banner_5_1
) - Extra large banner 5:1 (
oe_theme_extra_large_5_1_banner
) - Large banner 5:1 (
oe_theme_large_5_1_banner
) - Medium banner 5:1 (
oe_theme_medium_5_1_banner
) - Small banner 5:1 (
oe_theme_small_5_1_banner
)
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:
To build the final artifacts run:
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:
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:
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
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:
After a successful setup install the site by running:
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:
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:
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
:
Then:
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:
To run the phpunit tests:
To run the behat tests:
Step debugging
To enable step debugging from the command line, pass the XDEBUG_SESSION
environment variable with any value to
the container:
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:
Note: to fully disable Twig caching the following additional manual steps are required:
- Open
./build/sites/default/services.yml
-
Set the following parameters:
- 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:
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:
Update ECL
To update ECL components change the @ec-europa/ecl-preset-full
version number in package.json and run:
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:
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:
- Modify its source files directly in
./node_modules/@ecl/[component-name]
- Run:
Or, when using Docker Compose:
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:
- Checkout a working copy of the ECL repository from the branch you indicate in
.env.dist
. - Build ECL using the above codebase.
- Copy Twig templates and CSS/JS assets where the theme expects them to be.
- Compile theme's SASS files using the ECL's dev version
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.