This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

General

Userguide for all of the general information related to the maintenance and operation of Drupal WxT.

1 - Installation

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

Server Requirements

As Drupal WxT is a Drupal distribution, the official guide for Drupal system requirements will apply.

Installation

  • Composer Download
  • Tarball Download
  • Site Installation
  • Standalone Installation
  • Default Content via Migrate

Composer Download

Run this command and replace DIRECTORY with the directory of your choice this is where WxT will be installed.

composer self-update
composer create-project drupalwxt/site-wxt:9.4.x-dev <site-name> --no-interaction

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

Tarball Download

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.

Containers

For the (optional) container based local development workflow please consult our documentation site:

Site Installation

a) The Drupal Root is in <site-name>/html

b) You can install Drupal WxT through the browser as any other drupal installation or use drush site-install to install the WxT installation profile:

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

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.

c) You can download up-to-date translations using:

drush locale-check
drush locale-update

d) If you work for the Government of Canada you will want to enable the canada.ca theme:

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

Note: You can navigate to the admin/config/wxt/wxt_library settings page.

e) The Drupal WxT site should now be sucessfully installed and you can loging via the /user page.

Note: Please always go to the admin/report/status page and confirm there are no warnings and / or errors.

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.

Note: We highly recommend that you use the distribution method as limited support is provided for the standalone method.

Default Content via Migrate

The following is an example of how to use the Migrate API module to import common design patterns for Canada.ca aligning to the C&IA specifications:

# Set the WxT theme to GCWeb
drush config-set wxt_library.settings wxt.theme theme-gcweb -y

# Import design patterns for Canada.ca
drush migrate:import --group wxt --tag 'Core'
drush migrate:import --group gcweb --tag 'Core'
drush migrate:import --group gcweb --tag 'Menu'

drush cr

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

2 - Update Process

Drupal WxT relies on Drupal’s configuration system for configuring default features and functionality. A consequence of this is, once you have installed Drupal WxT, that we cannot modify the sites configuration without having an impact on your site. Drupal WxT will, however, offer to make changes to your configuration as part of the update process.

If you’ve installed WxT using our Composer-based project template, all you need to do is following the given steps below.

Update Process

These are the typical steps you should following when updating Drupal WxT:

a) Read the release notes for the release to which you are updating along with any releases in between.

b) To update your WxT codebase you would replace [VERSION] with the release version you wish to use.

composer self update
composer require drupalwxt/wxt:[VERSION]
composer update

Note: We highly recommend that you are using the v2.x.x line of Composer.

c) Run any database updates:

drush cache:rebuild
drush updatedb

Note: You may instead go to /admin/config/development/performance to clear caches and /update.php to run database updates.

d) Run any WxT configuration updates:

drush cache:rebuild
drush update:wxt

Note: You may instead go to /admin/config/development/performance to clear caches and /update.php to run WxT updates.

Configuration Management

If you are using configuration management to move your configuration between development, staging, and production environments, you should follow the standard Drupal process.

a) Export the new configuration:

drush cache:rebuild
drush config:export

b) Commit the code and configuration changes to your source code repository and push them to your environment.

c) Import any configuration changes:

drush cache:rebuild
drush config:import

3 - Releases

Releases of Drupal WxT

The following table is a list of all the releases that are housed under the Drupal WxT organization on GitHub:

Release Created Date Description
4.4.0 2022-11-26

Features / Updates:

  • Updates for Drupal Core
    • Patch (bugfix) release of Drupal Core to v9.4.8
  • Updates for WxT
    • Update to D9 core 9.4.x #3284468
    • Remove Lightning from composer required for upgrade path in v9.3.x branch
    • Can’t add multiple fontawesome icons in CKEditor #3316393
    • Fontawesome icons not working with Limit Allowed HTML #3315230
    • Text formats using non-ckeditor editors give error #3314829
    • Layout Builder and Ajax Submit Error #3317048
    • Update of some contributed modules (admin_toolbar, diff, entityqueue, search_api, token_filter, …)
    • Custom block type for WET Carousel #3313685
    • TypeError when exporting config with wxt_ext_config #3315821
    • Make webform content type translatable #3320521
    • Custom block type for WET Carousel #3313685
    • WxT Carousel support nolink #3319559
    • Improve block_content management #3318099
    • Move wxt_ext_layout config to optional #3319806
    • wxt_ext_media PHP 8.1 deprecation #3322200
    • Update the PageTitle block patch #3322590
    • Update drupal/menu_block to 1.10.0 #3304838
  • Updates for WxT Library
    • DateTimeBlock class $time can sometimes not be an integer #3316405
    • Support horizontal main menu in GCWeb #3310969
  • Updates for WxT Bootstrap
    • Canada.ca flyout menu doesn’t work (missing french menu) #3236799
    • Update starterkit readme file #3310485
    • Support horizontal main menu in GCWeb #3310969
    • Horizontal main menu more links #3321303

Upgrade path:

Important: Please backup your database before running the upgrade process for this release.

  • Update your codebase:

    • composer update

  • Run database updates:

    • drush cache:rebuild
    • drush updatedb

  • Run WxT configuration updates:

    • drush cache:rebuild
    • drush update:wxt

Note(s):

Lightning has been removed from composer required for upgrade path in v9.3.x branch.
4.3.4 2022-10-01

Features / Updates:

  • Security Updates for Drupal Core (v9.3.22)
  • Updates for WxT
    • CKEditor improvement leverage responsive images #3280946
    • Update blog listing page to latest spec #3306505
    • Translate the History tab #3311926
    • Brand menu in French no editable #3312412
    • Correct mislabelled wxt_extension.yml files
  • Updates for WxT Bootstrap
    • CKEditor improvement leverage responsive images #3280946
    • Update blog listing page to latest spec #3306505
    • Fix GCintranet link in header on French pages #3308918
    • Adjust theme suggestion alter in starterkit #3310485

Upgrade path:

Important: Please backup your database before running the upgrade process for this release.

  • Update your codebase:

    • composer update

  • Run database updates:

    • drush cache:rebuild
    • drush updatedb

  • Run WxT configuration updates:

    • drush cache:rebuild
    • drush update:wxt

Note(s):

This will be the last release which includes the Lightning modules, even though they have been uninstalled in an earlier release.
4.3.3 2022-08-19

Features / Updates:

  • Updates for Drupal Core
    • Patch (bugfix) release of Drupal Core to v9.3.21
  • Updates for Drupal Contrib
    • ckeditor_codemirror update to 2.4
    • core_context update to 1.0
    • ctools module update to ^3.9
    • inline_entity_form to ^2.7
    • layout_builder_restrictions to ^2.14
    • pathauto to ^1.8
  • Updates for WxT
    • [Deprecate] Remove Lightning Core #3302473
    • [Deprecate] Remove Lightning Media #3301875
    • Corrected bulk of reported issues by phpcs
    • FilterHtml throws Unsupported operand types #3300111
    • Core patch causing error when serializing top-level terms #3302126
    • WSOD on node forms with fresh install of WxT or ctools update #3300983
  • Updates for WxT Bootstrap
    • Preprocess field issue with video #3300986
    • Provide favicons with starterkit #3304675
    • Facet improvements (WCAG) #3282148
  • Updates for WxT Library
    • Switch to dynamic menu handling for wxt_library
    • Update to theme-gc-intranet theme to 4.0.43.1
    • SearchCanadaBlockForm missing dependency injection #3300107

Upgrade path:

Important: Please backup your database before running the upgrade process for this release.

  • Update your codebase:

    • composer update

  • Run database updates:

    • drush cache:rebuild
    • drush updatedb

  • Run WxT configuration updates:

    • drush cache:rebuild
    • drush update:wxt

Note(s):

To facilitate keeping the distribution lightweight and because soon the Lightning Contrib modules will be EOL we need to remove all of the Lightning contrib in a way that doesn’t break an upgrade path and documents the modules removed in case site builders will want to manually add them to their own composer.json file

Note: that all error messages stating “Currently using Missing or invalid module” will be resolved after running the drush updatedb step above.

a) [Deprecate] Remove Lightning Core #3302473

Please read over the above issue and consult the below list of the removed composer entries in case you are depending on any of them and need to apply them manually to your composer.json file.

"drupal/acquia_telemetry-acquia_telemetry": "^1.0-alpha3",
"drupal/contact_storage": "^1.0",

All of the Lightning Core functionality was directly ported to support an upgrade path and an update script written in the wxt_core_update_8433 function.

Note: Any Lightning sub modules will also be uninstalled.

b) [Deprecate] Remove Lightning Media #3301875

Please read over the above issue and consult the below list of the removed composer entries in case you are depending on any of them and need to apply them manually to your composer.json file.

Nothing removed at the moment

c) All of the Lightning Media functionality was directly ported to support an upgrade path and an update script written in the wxt_core_update_8433 function.

Note: Any Lightning sub modules will also be uninstalled.

d) Finally check your custom modules and / or configuration objects for any reference to lightning_core, lightning_page and lightning_media as some of your config objects (that we couldn’t automatically correct) might reference the old modules and this step will be important to get your configuration objects properly loaded.

Note: These references should be replaced by their new counterparts wxt_core, wxt_ext_page and wxt_ext_media. As some of your config objects might reference the old modules this step is important to get your config loaded.
4.3.2 2022-07-23

Features / Updates:

  • HotFix
    • Autosave missing OverrideHelper #3299197
  • Security Updates for Drupal Core (v9.3.19)
  • Updates for WxT
    • Translation patch causes whitescreen #3291183
    • Main menu in French not editable #3291230
    • [Deprecate] Remove Lightning Layout #3298505
    • [Deprecate] Remove Lightning Workflow #3295862
    • [Deprecate] SubProfile Generator #3295858
    • Incompatible version for ckeditor/fakeobjects #3298214
  • Updates for WxT Bootstrap
    • Corrected all reported issues by phpcs
    • Main menu in French not editable #3291230
    • PHP 8.1 compatibility #3294596
    • GCIntranet WxT search form label visible on mobile #3294629
    • Set dynamic wrapper element for Did you find webform block #3291816
  • Updates for WxT Library
    • Corrected all reported issues by phpcs
    • Passing null to parameter #1 ($string) #3286651

Upgrade path:

Important: Please backup your database before running the upgrade process for this release.

  • Update your codebase:

    • composer update

  • Run database updates:

    • drush cache:rebuild
    • drush updatedb

  • Run WxT configuration updates:

    • drush cache:rebuild
    • drush update:wxt

Note(s):

To facilitate keeping the distribution lightweight and because soon the Lightning Contrib modules will be EOL we need to remove all of the Lightning contrib in a way that doesn’t break an upgrade path and documents the modules removed in case site builders will want to manually add them to their own composer.json file

Note: that all error messages stating “Currently using Missing or invalid module” will be resolved after running the drush updatedb step above.

a) [Deprecate] Remove Lightning Layout #3298505

Please read over the above issue and consult the below list of the removed composer entries in case you are depending on any of them and need to apply them manually to your composer.json file.

"drupal/bg_image_formatter": "^1.10",
"drupal/panelizer": "^4.1 || ^5.0",
"drupal/simple_gmap": "^3.0"

All of the Lightning Layout functionality was directly ported to support an upgrade path and an update script written in the wxt_core_update_8431 function.

Note: Any Lightning sub modules will also be uninstalled.

b) [Deprecate] Remove Lightning Workflow #3295862

Please read over the above issue and consult the below list of the removed composer entries in case you are depending on any of them and need to apply them manually to your composer.json file.

"drupal/conflict": "^2.0-alpha2",
"drupal/moderation_dashboard": "^1.0",
"drupal/moderation_sidebar": "^1.2"

All of the Lightning Workflow functionality was directly ported to support an upgrade path and an update script written in the wxt_core_update_8431 function.

Note: Any Lightning sub modules will also be uninstalled.
4.3.1 2022-07-21

Features / Updates:

  • Security Updates for Drupal Core (v9.3.19)
  • Updates for WxT
    • Translation patch causes whitescreen #3291183
    • Main menu in French not editable #3291230
    • [Deprecate] Remove Lightning Layout #3298505
    • [Deprecate] Remove Lightning Workflow #3295862
    • [Deprecate] SubProfile Generator #3295858
    • Incompatible version for ckeditor/fakeobjects #3298214
  • Updates for WxT Bootstrap
    • Corrected all reported issues by phpcs
    • Main menu in French not editable #3291230
    • PHP 8.1 compatibility #3294596
    • GCIntranet WxT search form label visible on mobile #3294629
    • Set dynamic wrapper element for Did you find webform block #3291816
  • Updates for WxT Library
    • Corrected all reported issues by phpcs
    • Passing null to parameter #1 ($string) #3286651

Upgrade path:

Important: Please backup your database before running the upgrade process for this release.

  • Update your codebase:

    • composer update

  • Run database updates:

    • drush cache:rebuild
    • drush updatedb

  • Run WxT configuration updates:

    • drush cache:rebuild
    • drush update:wxt

Note(s):

To facilitate keeping the distribution lightweight and because soon the Lightning Contrib modules will be EOL we need to remove all of the Lightning contrib in a way that doesn’t break an upgrade path and documents the modules removed in case site builders will want to manually add them to their own composer.json file

Note: that all error messages stating “Currently using Missing or invalid module” will be resolved after running the drush updatedb step above.

a) [Deprecate] Remove Lightning Layout #3298505

Please read over the above issue and consult the below list of the removed composer entries in case you are depending on any of them and need to apply them manually to your composer.json file.

"drupal/bg_image_formatter": "^1.10",
"drupal/panelizer": "^4.1 || ^5.0",
"drupal/simple_gmap": "^3.0"

All of the Lightning Layout functionality was directly ported to support an upgrade path and an update script written in the wxt_core_update_8431 function.

Note: Any Lightning sub modules will also be uninstalled.

b) [Deprecate] Remove Lightning Workflow #3295862

Please read over the above issue and consult the below list of the removed composer entries in case you are depending on any of them and need to apply them manually to your composer.json file.

"drupal/conflict": "^2.0-alpha2",
"drupal/moderation_dashboard": "^1.0",
"drupal/moderation_sidebar": "^1.2"

All of the Lightning Workflow functionality was directly ported to support an upgrade path and an update script written in the wxt_core_update_8431 function.

Note: Any Lightning sub modules will also be uninstalled.

Repositories for Drupal WxT

The following table is a list of all the repositories that are housed under the Drupal WxT organization on GitHub:

Name Website Description Size
composer-extdeps drupalwxt/composer-extdeps Composer repository for external dependencies on Drupal WxT Size: 48 Bytes
docker-scaffold drupalwxt/docker-scaffold Docker Scaffold for Drupal WxT Size: 120 Bytes
drupalwxt.github.io drupalwxt/drupalwxt.github.io GitHub Pages for Drupal WxT. Size: 7903 Bytes
helm-drupal drupalwxt/helm-drupal Helm chart for running Drupal on Kubernetes Size: 56147 Bytes
site-wxt drupalwxt/site-wxt An example composer project for the Drupal WxT distribution used for integration testing. Size: 2007 Bytes
terraform-kubernetes-drupalwxt drupalwxt/terraform-kubernetes-drupalwxt Terraform module for Drupal WxT Size: 54 Bytes
themes-cdn drupalwxt/themes-cdn Content Delivery Network (CDN) files for the theme repositories of the Web Experience Toolkit (WET) Size: 12445 Bytes
wxt drupalwxt/wxt Drupal 9 variant of the Web Experience Toolkit (WxT). Size: 1964 Bytes
wxt-project drupalwxt/wxt-project Composer project template for Drupal 9 sites built with the WxT distribution. Size: 69 Bytes
wxt_bootstrap drupalwxt/wxt_bootstrap Bootstrap derived sub-theme aligned for use with the Web Experience Toolkit jQuery Framework. Size: 1206 Bytes
wxt_library drupalwxt/wxt_library Web Experience Toolkit Framework integration for Drupal. Size: 113 Bytes

4 - Resources

The following are links to some useful resources:

General

Drupal

Advanced

5 - Roadmap

The core distribution will always strive to be:

  • As minimal as possible on top of Drupal Core providing performance, scalability, and security features on top of it
  • Provide best practices for users to follow which includes our Composer workflow, CI / CD methodologies, and deployment strategies
  • Provide a place for all Government Departments to inherit the base requirements such as Language Handling, GC Approved Themes, and other functionalities such as Date Format, Metadata Output, and Accessibility improvements

Beyond the above the distribution will provide extensible features that can be opted into through the wxt_ext suite of modules:

  • Each of these modules must explicitly state all of there contributed dependencies
  • Governance around these “extension” modules can be a bit looser
  • These modules should be clear in focus and not try to do to much other then an immediate task at hand
  • These modules should have an modulename.wxt_extension.yml file so can be enabled as optional extension during profile installation

In addition, Drupal WxT will offer out of tree (external) modules that implement specific features:

  • These features are not included by the core platform because they are only used by a subset of users
  • These modules may be subject to change though update hooks will always be provided
  • Community supported modules will also be listed in our README of additional modules but will not be supported by the Drupal WxT team

Note: The governance around the core distribution will always be much stricter then the governance around adding a wxt_ext or an out of tree module.