Drupal WxT – Development

Docs: Architecture

Mon, 01 Jan 0001 00:00:00 +0000

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

What WxT offers is 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. However a great deal of optional extensions are available that can provide additional functionality generally beneficial to Government departments.

Note: In the future we are looking into providing a list of community modules that are build to work with the distribution but are “out of tree”.

All of the optional modules are located in the wxt_ext folder named after WxT Extend and can be enabled during the initial site installation by passing the following flag via the drush cli:

wxt_extension_configure_form.select_all='TRUE'

Note: If you wish to only install the minimum set of dependencies please remove the wxt_extension_configure_form.select_all='TRUE' flag in its entirety.

In order to provide a list of the optional enabled extensions during the installation that can be checked, all that any module 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 discussed above.

For more information on some of the history leading to this design:

Docs: Composer

Mon, 01 Jan 0001 00:00:00 +0000

A reminder that composer is required for the installation and updating of Drupal WxT.

We highly recommend using our Composer Project Template to build and maintain your WxT derived project’s codebase.

Getting Started

The following command is all you need to get started:

composer create-project drupalwxt/wxt-project:5.1.1 <site-name>

Note: For development you may also specify a branch using drupalwxt/wxt-project:5.1.x-dev.

You can see a working example of a fully generated Composer Project Template over at:

Site WxT

Where the following is the command that was used for the initial generation:

composer create-project drupalwxt/wxt-project:5.1.1 site-wxt

Note: Remember to keep the composer.json and composer.lock files that exist above docroot in source control as they are controlling your dependencies.

Maintenance

List of common commands are as follows:

Task	Composer
Installing a contrib project (latest version)	`composer require drupal/PROJECT`
Installing a contrib project (specific version)	`composer require drupal/PROJECT:1.0.0-beta5`
Updating all projects including Drupal Core	`composer update`
Updating a single contrib project	`composer update drupal/PROJECT_NAME`
Updating Drupal Core	`composer update drupal/core`

Note: Composer is a dependency manager and helps us keep track of what code and at what version our application relies on so that it always get installed the right way on every copy of that application.

Specifying a version

A specific version can be specified from the cli:

composer require drupal/<modulename>:<version>

However please note if you specify a branch, such as 1.x you must add -dev to the end of the version:

composer require drupal/token:1.x-dev

Source Control

Taking a look at the .gitignore file, you will discover that certain directories, including all those directories containing contributed projects, are excluded from source control which is by design.

Note: Unlike Drush in a Composer derived project you should never commit your install dependencies to source control.

Composer will create composer.lock file, which is a list of dependencies that were installed, and in which versions.

Note: In general you should always commit your composer.lock file to source control so that others via a quick composer install can have everything installed along with the correct versions specified in the composer.lock file.

How to update Drupal Core?

Please don’t add drupal/core to your project’s composer.json since WxT manages Drupal Core for you along with the series of patches on top of it.

For example:

drupalwxt/wxt:~5.2.0 will require Drupal Core 10.2.x
drupalwxt/wxt:~5.1.0 will require Drupal Core 10.1.x

When you need to update Drupal Core as an example from 10.1.x to 10.2.x, all you would do is change your requirement for drupalwxt/wxt in your composer.json file:

composer require --no-update drupalwxt/wxt:~5.2.0
composer update

Compatibility table

WxT version	Drupal Core version	Drush version	PHP version
`5.2.x`	`10.2.x`	`>=12.4`	`8.2`
`5.1.x`	`10.1.x`	`>=12.1`	`8.1`

Docs: Configuration Management

Mon, 01 Jan 0001 00:00:00 +0000

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;

Docs: Performance

Mon, 01 Jan 0001 00:00:00 +0000

Below are some recommended settings that improve the performance of Drupal WxT sites.

Docs: Release Process

Mon, 01 Jan 0001 00:00:00 +0000

Select a version number

WxT releases are numbered using a form of semantic versioning. More information can be found in our Versioning page.

MAJOR.FEATURE.SPRINT

In general, when preparing a release: increment the FEATURE when Drupal Core has a major release (ie. 9.5.x to 10.0.x) otherwise simply increment the SPRINT number.

Create an issue on GitHub.com

Create an issue in the Drupal WxT project on GitHub for release tracking, title it Release x.x.x (where x.x.x is the incremented version number).

This issue should contain the following checklist as well as any other related steps or information regarding preparing the release.

See the [full release documentation](https://drupalwxt.github.io/docs/development/release-process/) for more detail.

- [ ] All related projects (wxt_library and wxt_bootstrap) tagged and released on GitHub.com and Drupal.org
- [ ] Version number selected
- [ ] CHANGELOG.md updated
- [ ] composer.json updated
- [ ] Run version.sh for hook_updates and wxt contrib
- [ ] CI build passes
- [ ] Releases tagged and pushed to GitHub.com and Drupal.org
- [ ] WxT released on Drupal.org (https://drupalwxt.github.io/docs/development/release-process/#release)
- [ ] Add changelog information to published tag once CI is done

Update changelog

Ensure the changelog contains an entry for the release and is updated as issues and changes are resolved (in the next steps or when committing code / changes).

Review dependent wxt modules

Review contrib modules in composer.json (or in a site install; extend->update) and update as necessary.
If necessary, tag wxt_library and update wxt’s composer.json file
If necessary, tag wxt_bootstrap and update wxt’s composer.json file

All projects must be released on drupal.org (and github).

Note: Changes to composer.json file (specifically dev dependencies and repositories) should be mentioned in the CHANGELOG.

Drupal.org version

Drupal.org does not currently support semantic versioning. Instead, the version number on drupal.org is 10.x-X.YZZ, where:

X = MAJOR
Y = FEATURE
ZZ = SPRINT (two digits - add leading zero for < 10)

Check composer.json

If the wxt dependent modules are updated, we need to reflect this in wxt composer.json and the CHANGELOG.

git clone https://github.com/drupalwxt/wxt.git
Confirm or update that it’s using appropriate tags of wxt_library + wxt_bootstrap (composer.json)
Push to github.com and drupal.org repositories any changes
Ensure GitHub Actions build passes

Tag WxT

GitHub.com and Drupal.org

git tag MAJOR.FEATURE.SPRINT
git push $GITHUB_REMOTE MAJOR.FEATURE.SPRINT

Release

GitHub.com

Go to Tags page
Click … and select create release on the tag
Enter the version number in the release title
Copy the changelog entry for this release into the release notes
Click publish release

Drupal.org

The builds on Drupal.org are incomplete as they don’t fully support Composer yet which is why we host a tarball on GitHub for those not using Composer.

Drupal WxT Release Page
Select the tag
Copy/paste the following blurb into the release notes:

<strong>CHANGELOG</strong>

See the <a href="https://github.com/drupalwxt/wxt/blob/5.2.x/CHANGELOG.md">changelog.md</a> file.

Docs: Theming

Mon, 01 Jan 0001 00:00:00 +0000

Largely when doing any theme related work with Drupal WxT this almost always should be done in a sub-theme.

For more on creating sub-themes please consult the official documentation:

Creating sub-themes

To assist with sub-theme creation WxT Bootstrap provides an example starterkit that should be of benefit.

Note: Sub-themes are just like any other theme except they inherit the parent theme’s resources.

Sub Theme Configuration

a) Replace every instance of THEMENAME with your chosen machine name often of the pattern <prefix>_bootstrap.

b) Enable your new sub-theme preferably via drush:

drush en `<prefix>_bootstrap`
drush cc css-js

c) Point to your new sub theme for WxT Library to properly load assets under Themes Visibility on the /admin/config/wxt/wxt_library page.

Notes

Inheriting Block Templates

If the theme you are extending has custom block templates these won’t be immediately inherited because a sub-theme creates copies of all the blocks in the parent theme and renames them with the sub-theme’s name as a prefix. Twig block templates are derived from the block’s name, so this breaks the link between these templates and their block.

Fixing this problem currently requires a hook in the THEMENAME.theme file and should have the following contents:

/**
 * Implements hook_theme_suggestions_HOOK_alter().
 */
function THEMENAME_theme_suggestions_block_alter(&$suggestions, $variables) {
 // Load theme suggestions for blocks from parent theme.
 // https://www.drupal.org/project/wxt/issues/3310485#comment-14715969
 for ($i = 0; $i < count($suggestions); $i++) {
 if (str_contains($suggestions[$i], 'THEMENAME_')) {
 $new_suggestions = [
 str_replace('THEMENAME_', '', $suggestions[$i]),
 str_replace('THEMENAME_', 'wxt_bootstrap_', $suggestions[$i]),
 ];
 array_splice($suggestions, $i, 0, $new_suggestions);
 $i += 2;
 }
 }
}

Programmatic Logic

The following provides an example of how you can configure your sub theme to be installed as the default on a module install:

/**
 * Implements hook_modules_installed().
 */
function MODULENAME_modules_installed($modules) {
 if (in_array('wxt', $modules)) {
 \Drupal::configFactory()
 ->getEditable('system.theme')
 ->set('default', 'THEMENAME')
 ->set('admin', 'claro')
 ->save(TRUE);
 }
 }
}

The following provides an example of how you can configure wxt_library to use your sub theme by creating a config/install/wxt_library.settings.yml file with the following contents:

url:
 visibility: 0
 pages:
 - 'admin*'
 - 'imagebrowser*'
 - 'img_assist*'
 - 'imce*'
 - 'node/add/*'
 - 'node/*/edit'
 - 'print/*'
 - 'printpdf/*'
 - 'system/ajax'
 - 'system/ajax/*'
theme:
 visibility: 1
 themes:
 THEMENAME: THEMENAME
 wxt_bootstrap: wxt_bootstrap
minimized:
 options: 1
files:
 types:
 css: css
 js: js
wxt:
 theme: theme-gcweb

Docs: Versioning

Mon, 01 Jan 0001 00:00:00 +0000

The Drupal WxT distribution is following semantic versioning.

WxT typically makes a sprint release every four to six weeks. We will also use sprint releases to package new minor releases of Drupal Core with WxT as they become available.

In addition, we will also increment the major version number of WxT about once every four to six months.

Extensions

Support for semantic versioning for extensions (modules, themes, etc) is still ongoing.

Support semantic versioning for extensions (modules, themes, etc)

The three parts of our versioning system are MAJOR.FEATURE.SPRINT.

Given the following tag: 10.x-2.00:


10	Major version of Drupal Core
x
5	Major version of WxT
0	Feature release of WxT. Also increments with minor core releases.
0	Sprint release between feature releases

Note: Due to the constraints of drupal.org, there is no separator between the FEATURE and SPRINT digits.