OpenEuropa Bootstrap base theme

Drupal 8/9 theme based on Bootstrap 5, UI Patterns and the OpenEuropa Bootstrap Component Library.

Usage as a dependency

Requirements

The package is meant for Drupal projects that manage their Drupal dependencies via Composer.

The usage of Docker in the dependent project is suggested, but not required.

Check the composer.json for required PHP version and other dependencies.

Add the composer package

Add this manually in composer.json, or combine with existing entries:

    "extra": {
        "artifacts": {
            "openeuropa/oe_bootstrap_theme": {
                "dist": {
                    "url": "https://github.com/{name}/releases/download/{pretty-version}/{project-name}-{pretty-version}.zip",
                    "type": "zip"
                }
            }
        }
    }

Require with composer:

composer require openeuropa/oe_bootstrap_theme:^1.0@alpha

Review the installation

Review the installed version with composer info | grep oe_.

Review the installation directory with composer info openeuropa/oe_bootstrap_theme | grep path. Depending on your setup, this could be build/themes/contrib/oe_bootstrap_theme.

If installation was successful, the instance of oe_bootstrap_theme should contain a number of subdirectories within /assets/, including /assets/bcl/.

Enable and configure

Enable the required helper module:

./vendor/bin/drush en oe_bootstrap_theme_helper

Enable the theme itself and set it as default:

./vendor/bin/drush config-set system.theme default oe_bootstrap_theme

Generate a sub-theme

The package provides a task-runner command to generate a sub-theme.

# Install the task runner:
composer require openeuropa/task-runner
# Learn more about the create-subtheme command:
./vendor/bin/run help oe_bootstrap_theme:create-subtheme
# Generate a sub-theme
./vendor/bin/run oe_bootstrap_theme:create-subtheme [...]

After using the command, first commit the generated sub-theme in git, then review all of it, and determine which parts you can remove or you have to alter.

An older, manual way to create a sub-theme is described in kits/README.md.

Backward compatibility layer

This component follows semantic versioning as per OpenEuropa initiative.
The theme provides an API to its sub-themes, which consists of PHP classes and methods, Twig templates, JavaScript, and CSS/SASS, which can all be altered or overridden by the sub-theme.

Bug fixes and improvements that break backward compatibility on the theme layer (Twig, JS, CSS) are shipped in minor versions.
Backward compatibility is assured by dedicated "Backward compatibility settings", configurable in the theme settings page. These settings allow to restore the previous backward compatible behaviour.
When upgrading the theme in an existing installation, new backward compatibility settings will be automatically enabled. They can be disabled when a developer updates the sub-theme code.
For new installations, all the backward compatibility settings are disabled.

This approach eases the adoption of changes or improvements that would be otherwise tied to a new major. It allows developers to contribute changes to the current major and selectively enable them without having to update the theme completely to a new major release.

"Version 2.x" patterns

For version 2.x of this theme, we want to reduce the number of preprocess needed to use the patterns, and instead be able to use formatters and view modes directly as much as possible.
We started to ship in version 1.x patterns that already embrace this new approach. They have been tagged with category "Version 2.x".
We will do the best to avoid any breaking changes to these patterns during the 1.x lifecycle. But it might be that some changes will be still needed. We will communicate such changes together with the release.

Development setup

Using LAMP stack or similar

This is not officially supported. You are on your own.

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

Override docker settings

The package provides default settings for Docker Compose in docker-compose.yml. Most of the time these are sufficient.

An optional docker-compose.override.yml file can be created to selectively override specific values, or to define entirely new services.

For services that are defined in both files, Docker Compose applies merge rules that are documented in the official Docker Compose documentation.

Start the container

If you have other (daemonized) containers running, you might want to stop them first:

docker stop $(docker ps -q)

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

Optionally purge existing installation

If you already had the package installed, and want a clean start:

docker-compose exec web rm composer.lock
docker-compose exec web rm -rf vendor/
docker-compose exec web rm -rf build/

Install and build

Install dependencies, build artifacts, and install Drupal.

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

Visit the development site

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 or http://web:8080/build.

Run the tests

Run the grumphp checks:

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

Run the phpunit tests:

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

Patch BCL components

BCL components can be patched by using the patch-package NPM project.

To patch a component:

1. Modify its source files directly in ./node_modules/@openeuropa/bcl-theme-default
2. Run:

docker-compose exec -u node node git config --global user.email "[email protected]"
docker-compose exec -u node node git config --global user.name "Name"
docker-compose exec -u node node npx patch-package @openeuropa/bcl-theme-default --patch-dir=patches/npm

Patches will be generated in ./patches/npm and applied when running npm install.
Note: generate patches only inside the docker container to use the same version of npm/npx.

Contribute

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.

Upgrade from older versions

Upgrade to 1.0.0-beta2

Dependencies to the following packages have been removed in composer.json:

• drupal/description_list_field
• openeuropa/oe_content
• openeuropa/oe_media
• openeuropa/oe_paragraphs

Be sure to require the component if you need any of them.

Upgrade to 1.0.0-alpha8

Paragraphs migration

Paragraphs-related theming and functionality has been moved from the OpenEuropa Bootstrap base theme to OpenEuropa Whitelabel.

If you are using openeuropa/oe_whitelabel, and you want paragraphs functionality, you should upgrade it to 1.0.0-alpha6 or higher, and refer to the upgrade instructions found there.