Web Experience Toolkit: Drupal WxT

Important

Drupal WxT for Drupal 9 is released and provides an upgrade path from the 3.0.x line.

Important Links

• Documentation Website: drupalwxt.github.io
• Installation Profile: github.com/drupalwxt/wxt
• Composer Project: github.com/drupalwxt/site-wxt
• Composer Project Template: github.com/drupalwxt/wxt-project
• Helm Chart for Kubernetes: github.com/drupalwxt/helm-drupal
• Docker Containers: hub.docker.com/r/drupalwxt/site-wxt
• Drupal Repository: drupal.org/project/wxt
• Issue Queue: drupal.org/project/wxt/issues
• Changelog: CHANGELOG.md
• GitHub Actions: github.com/drupalwxt/wxt/actions
• GitHub Tarball: github.com/drupalwxt/wxt/releases

Note: For up-to-date documentation please always consult our README.md file.

Overview

The Drupal WxT distribution is a web content management system which assists in building and maintaining innovative Web sites that are accessible, usable, and interoperable. This distribution is open source software led by the Government of Canada and free for use by departments and external Web communities. This distribution relies on and integrates with the Web Experience Toolkit for its conformance to the Web Content Accessibility Guideline (WCAG 2.0) and its compliance to the Standards on Web Accessibility, Web Usability, and Web Interoperability.

Architecture

Please consult our Architectural Diagram for a example implementation on Kubernetes:

• Architectural Diagram

The goal of WxT 4.1.x line is to make the installation profile very minimal by default but providing additional extensions that can be enabled as desired.

WxT offers some light enhancements to Drupal Core, mainly around security and performance, and integration with the Web Experience Toolkit. By default, the distribution offers minimal functionality to allow full customizations by users. A set of optional extensions is available that provide additional functionality generally beneficial to Government departments. A community repository of modules and graduation process will be available to enable collaboration between users in the future.

All of the additional contributed modules and Lightning integration have been moved into the WxT Extend wxt_ext extensions which can now be installed a la carte for fresh installations via the GUI or passed as flags via Drush.

wxt_extension_configure_form.select_all='TRUE'

In order to provide a list of the optional enabled extensions during the installation that can be checked, all that any module now has to do is provide a modulename.wxt_extension.yml file in their root and they will be picked as installable during the profile install and also respond to the additional drush flag.

For more information please consult the following:

• WxT Minimal Install
• Upgrade Path from 3.0.x -> 4.1.x
• Roadmap for Drupal 9
• Subprofile install of modules and wxt_extensions

Lightning Components

For the optional extensions that Drupal WxT provides we make use of the following Lightning modules:

• Lightning API
• Lightning Core
• Lightning Layout
• Lightning Media
• Lightning Workflow

Note: Originally we were leveraging the Lightning installation profile but since Lightning now provides support for the individual components outside of the profile we now leverage them directly.

For more information about Lightning:

• https://www.acquia.com/products-services/acquia-lightning
• https://www.acquia.com/blog/building-drupal-8-sites-acquia-lightning-cuts-costs-100000
• https://www.drupal.org/docs/8/distributions/degov/about-degov
• https://github.com/govcms/govcms8

Installing WxT

We highly recommend using our Composer-based project template to build and maintain your WxT derived project’s codebase.

composer self-update
composer create-project drupalwxt/wxt-project:4.1.x-dev MYPROJECT

Note: Normally you will pass a stable tag to the above command rather then just pulling from the development branch.

If you don't want to use Composer, you can install WxT the traditional way by downloading a tarball from WxT's GitHub releases page.

Note: That the tarball generated by the Drupal.org packager does not include the required Composer dependencies and should not be used without following the specialized instructions.

Site Installation

Install the site using drush which should take approximately 4-5 minutes depending on your system.

drush si wxt
  --sites-subdir=default \
  --db-url=mysql://root:WxT@mysql:3306/wxt \
  --account-name=admin \
  --account-pass=WxT \
  --site-mail=admin@example.com \
  --site-name="Drupal Install Profile (WxT)" \
  install_configure_form.update_status_module='array(FALSE,FALSE)' \
  --yes

drush locale-check
drush locale-update

Note: If you work for the Government of Canada you might want to enable the canada.ca theme. You can navigate to the WxT Library settings page or run the Drush command below.

drush config-set wxt_library.settings wxt.theme theme-gcweb -y

StandAlone Installation

The standalone install is provided as an additional method for those who do not wish to have the full weight of a distribution and its required dependencies. You will need to add at the minimum the below listed modules and themes (including Bootstrap base theme) as well as the WxT jQuery Framework assets installed into the /libraries folder with the proper naming scheme.

• WxT Bootstrap
• WxT Library
• WxT jQuery Framework assets

Note: We heavily recommend that you use the distribution method. Limited support is provided for the standalone method.

Generating a Sub Profile

You can customize your installation by creating a sub-profile which uses WxT as its base profile.

WxT includes a Drush command which will generate a sub-profile for you:

drush --root=/var/www/html/sites/default generate wxt-subprofile

Installing from exported config

WxT can be installed from a set of exported configuration (e.g., using the --existing-config option with drush site:install).

Installation of Default Content via Migrate

drush config-set wxt_library.settings wxt.theme theme-gcweb -y

drush migrate:import --group wxt --tag 'Core'
drush migrate:import --group gcweb --tag 'Core'
drush migrate:import --group gcweb --tag 'Menu'

drush migrate:import --group wxt_translation --tag 'Core'
drush migrate:import --group gcweb_translation --tag 'Core'
drush migrate:import --group gcweb_translation --tag 'Menu'

drush cr

WxT

Imports examples of common design patterns for WxT branded sites.

drush migrate:import --group wxt --tag 'Core'

Note: There is a group wxt_translation for importing the corresponding french content.

Canada

Imports examples of common design patterns for Canada.ca aligning to C&IA specification.

drush migrate:import --group wxt --tag 'Core'
drush migrate:import --group gcweb --tag 'Core'
drush migrate:import --group gcweb --tag 'Menu'

Note: There is a group gcweb_translation for importing the corresponding french content.

Groups

We also provide an example of importing groups via a json feed from open.canada.ca that will create a group for every government department where you can isolate content acess.

drush en wxt_ext_group -y
drush migrate:import --group gcweb --tag 'Group'

Note: Make sure to only have one set of menu's imported for each of the supported themes. Leverage migrate:rollback to assist with this requirement.

Configuration Management

Drupal WxT thanks to the work done by the Acquia Team is able to use advanced configuration management strategies.

At the moment this remains an opt-in process and you will have to add the following modules to your composer.json before you add the code snippet below to your settings.php file.

• Configuration Split
• Configuration Ignore

Once enabled all default configuration will be stored in /sites/default/files/config/default/ and then depending on your environment additionally configuration splits can be leveraged depending on your SDLC.

/**
 * Configuration Split for Configuration Management
 *
 * WxT is following the best practices given by Acquia for configuration
 * management. The "default" configuration directory should be shared between
 * all multi-sites, and each multisite will override this selectively using
 * configuration splits.
 *
 * To disable this functionality simply set the following parameters:
 * $wxt_override_config_dirs = FALSE;
 * $settings['config_sync_directory'] = $dir . "/config/$site_dir";
 *
 * See https://github.com/acquia/blt/blob/12.x/settings/config.settings.php
 * for more information.
 */

use Drupal\wxt\Robo\Common\EnvironmentDetector;

if (!isset($wxt_override_config_dirs)) {
  $wxt_override_config_dirs = TRUE;
}
if ($wxt_override_config_dirs) {
  $config_directories['sync'] = $repo_root . "/var/www/html/sites/default/files/config/default";
  $settings['config_sync_directory'] = $repo_root . "/var/www/html/sites/default/files/config/default";
}
$split_filename_prefix = 'config_split.config_split';
if (isset($config_directories['sync'])) {
  $split_filepath_prefix = $config_directories['sync'] . '/' . $split_filename_prefix;
}
else {
  $split_filepath_prefix = $settings['config_sync_directory'] . '/' . $split_filename_prefix;
}

/**
 * Set environment splits.
 */
$split_envs = [
  'local',
  'dev',
  'test',
  'qa',
  'prod',
  'ci',
];
foreach ($split_envs as $split_env) {
  $config["$split_filename_prefix.$split_env"]['status'] = FALSE;
}
if (!isset($split)) {
  $split = 'none';
  if (EnvironmentDetector::isLocalEnv()) {
    $split = 'local';
  }
  if (EnvironmentDetector::isCiEnv()) {
    $split = 'ci';
  }
  if (EnvironmentDetector::isDevEnv()) {
    $split = 'dev';
  }
  elseif (EnvironmentDetector::isTestEnv()) {
    $split = 'test';
  }
  elseif (EnvironmentDetector::isQaEnv()) {
    $split = 'qa';
  }
  elseif (EnvironmentDetector::isProdEnv()) {
    $split = 'prod';
  }
}
if ($split != 'none') {
  $config["$split_filename_prefix.$split"]['status'] = TRUE;
}

/**
 * Set multisite split.
 */
// $config["$split_filename_prefix.SITENAME"]['status'] = TRUE;

Docker Containers (Optional)

For the (optional) container based development workflow this is roughly the steps that are followed.

Note: The docker-scaffold has now been moved to its own repository. Should you wish to use the docker workflow you simply need to run the following command in the site-wxt repository's working directory.

# Git clone docker scaffold
git clone https://github.com/drupalwxt/docker-scaffold.git docker

# Create symlinks
ln -s docker/docker-compose.yml docker-compose.yml
ln -s docker/docker-compose-ci.yml docker-compose-ci.yml

# Composer install
export COMPOSER_MEMORY_LIMIT=-1 && composer install

# Make our base docker image
make build

# Bring up the dev stack
docker-compose -f docker-compose.yml build --no-cache
docker-compose -f docker-compose.yml up -d

# Install Drupal
make drupal_install

# Development configuration
./docker/bin/drush config-set system.performance js.preprocess 0 -y && \
./docker/bin/drush config-set system.performance css.preprocess 0 -y && \
./docker/bin/drush php-eval 'node_access_rebuild();' && \
./docker/bin/drush config-set wxt_library.settings wxt.theme theme-gcweb -y && \
./docker/bin/drush cr

# Migrate default content
./docker/bin/drush migrate:import --group wxt --tag 'Core' && \
./docker/bin/drush migrate:import --group gcweb --tag 'Core' && \
./docker/bin/drush migrate:import --group gcweb --tag 'Menu'

Version History

Changelog

• CHANGELOG.md

Releases

• GitHub Releases

Contributor(s)

Contributors: https://github.com/drupalwxt/wxt/graphs/contributors

Acknowledgements

Extended with code and lessons learned by the Acquia Team over at Lightning and BLT.