openeuropa/oe_whitelabel

OpenEuropa Whitelabel theme.

1.6.0 2024-03-13 09:12 UTC

Requires

• php: >=8.1
• cweagans/composer-patches: ^1.7
• drupal/core: ^10
• drupal/daterange_compact: ^2.0.1
• drupal/twig_field_value: ^2.0.2
• openeuropa/composer-artifacts: ^1.0.0-alpha1
• openeuropa/oe_bootstrap_theme: ^1.4.0

Requires (Dev)

• composer/installers: ^1.11
• drupal/better_exposed_filters: ^6.0.3
• drupal/composite_reference: ^2.2
• drupal/config_devel: ~1.9
• drupal/core-composer-scaffold: ^10
• drupal/core-dev: ^10
• drupal/description_list_field: ^1.0@alpha
• drupal/entity_reference_revisions: ^1.11
• drupal/extra_field: ^2.3
• drupal/facets_form: ^1.0.0-alpha6
• drupal/field_group: ^3.4
• drupal/search_api: ^1.29
• drupal/search_api_autocomplete: ^1.7
• drupal/typed_link: ^2.0.1
• drush/drush: ^12
• mikey179/vfsstream: ^1.6.10
• nikic/php-parser: ^4
• openeuropa/code-review: ^2.0.0-alpha6
• openeuropa/oe_authentication: ^1.11
• openeuropa/oe_contact_forms: ~1.11
• openeuropa/oe_content: ^3
• openeuropa/oe_content_extra: ^1.1.0
• openeuropa/oe_corporate_blocks: ^4.13
• openeuropa/oe_link_lists: ^1.0
• openeuropa/oe_list_pages: ^1.0.0
• openeuropa/oe_multilingual: ^1.14
• openeuropa/oe_paragraphs: ^1.19
• openeuropa/oe_starter_content: ^1.2.0
• openeuropa/oe_subscriptions: ^1.0@alpha
• openeuropa/task-runner-drupal-project-symlink: ^1.0-beta6
• phpspec/prophecy-phpunit: ^2

EUPL-1.2

README

Sub-theme of OpenEuropa Bootstrap base theme, with theming for OpenEuropa library features.

Features

Paragraphs

The paragraphs below are not yet themed therefore not recommended for usage:

• Contextual navigation
• Document

Some paragraphs are considered "internal", and only meant to be used inside other paragraphs:

• Listing item: To be used as item paragraph within 'Listing item block'.
• Fact: To be used as item paragraph within 'Facts and figures'.

Usage as a dependency

Website projects can use oe_whitelabel either as an active theme, or they can create a custom theme using oe_whitelabel as a base theme.

Requirements

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

Ideally this project should be managed with Docker and Docker Compose, but this is not a hard requirement.

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"
                }
            },
            "openeuropa/oe_whitelabel": {
                "dist": {
                    "url": "https://github.com/{name}/releases/download/{pretty-version}/{project-name}-{pretty-version}.zip",
                    "type": "zip"
                }
            }
        }
    }

While this package is still in its alpha phase, you need an extra step in composer, to avoid getting anything from the obsolete and unsupported 0.x branch.

One option is to set minimum-stability and require the ^1.0 version. You should also set prefer-stable to mitigate the impact on other dependencies. Review this again when the site goes into production.

composer config minimum-stability alpha
composer config prefer-stable true
composer require openeuropa/oe_whitelabel:^1.0

Alternatively, if you don't want to set minimum-stability, you need to specify explicit versions for all dependencies with alpha versions:

composer require openeuropa/oe_whitelabel:^1.0@alpha openeuropa/oe_bootstrap_theme:^1.0@alpha

Review the installed package versions.

composer show -i | grep oe_

Enable and configure

Enable required and optional submodules:

# Always required.
./vendor/bin/drush en oe_whitelabel_helper

# Required, if you use oe_paragraphs module, or if you copied any paragraph
# types from that module.
./vendor/bin/drush en oe_whitelabel_paragraphs

# Other submodules are optional - check the /modules/ folder.
./vendor/bin/drush en <modulename>

Enable the theme and set as default:

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

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

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.

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 the package

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

Run the tests

To run the grumphp checks:

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

To run the phpunit tests:

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

Upgrade from older versions

Upgrade to 1.0.0-alpha7

Paragraphs migration

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

Special paragraphs fields that were introduced in oe_bootstrap_theme_paragraphs are being renamed in oe_whitelabel_paragraphs.

If you have the oe_paragraphs module enabled, you should create a hook_post_update_NAME() in your code, to enable the oe_whitelabel_paragraphs module during deployment.

function EXAMPLE_post_update_00001(): void {
  \Drupal::service('module_installer')->install(['oe_whitelabel_paragraphs']);
}

This is needed to make sure that the install hook for oe_whitelabel_paragraphs runs before config-import during a deployment.

Note that drush updb will also trigger update hooks in oe_bootstrap_theme_helper, which will uninstall the legacy module oe_bootstrap_theme_paragraphs.

Upgrade to 1.0.0-alpha6

This release contains some bugs, please move directly to alpha7.