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 - Overview

The Drupal WxT distribution is designed for organizations that must meet accessibility and bilingualism standards. It attempts to integrate with the design patterns found in the WET-BOEW and Canada.ca design system, including the mandatory Content and Information Architecture (C&IA) Specification for the Government of Canada.

To make working with Drupal WxT easier, there are potentially three ways you can approach it.

Distribution

The Drupal WxT distribution method stands out as a preferred choice for web developers and organizations seeking a robust web development solution.

Unlike a standalone installation, the distribution provides a comprehensive package of features and workflows that have been vetted and tested by the Drupal WxT community based on real world use cases.

This means users can leverage a well-established framework with proven capabilities, saving time and effort in development while ensuring stability and reliability.

By opting for the distribution method, teams gain access to shared resources, ongoing support, and a community-driven ecosystem, hopefully helping to build accessible, and bilingual web experiences with confidence.

Benefits

  • Many canadian departments and organizations have contributed features and improvements
  • Has received several security and accessibility audits to the codebase and markup
  • Will stay on top of security releases within a maximum of 72 hours of posting
  • Creation of many plugins in order to more fully integrate with the WET-BOEW and Canada.ca design system
  • Best effort open source support from a community of developers
  • Provides upgrade paths for all supported components
  • Additional functionality is provided by WxT Extend modules which target a specific feature
  • Stays on top of performance related issues taking into account both MySQL and PostgreSQL

Components

ComponentFeaturesMachine NameType
WxT
  • Provides a custom installation profile
wxtDistribution
WxT Bootstrap
  • Provides Templates to adhere to the WET-BOEW and Canada.ca Design System and C&IA Specification
  • #3393668 - Toggle webforms between “Report a Problem” and “Did you find what you were lolking for?” on a per page basis
wxt_bootstrapStandalone
WxT Library
  • Integrates Drupal with WET-BOEW Framework Assets (CSS/JS)
wxt_libraryStandalone
WxT Admin
  • Provides the default configuration and various helper methods for administrative tasks
wxt_adminDistribution
WxT Core
  • Provides the core configuration and all update related hooks for WxT as a whole
wxt_coreDistribution
WxT Extend
  • Provides 40+ micro modules where target only a specific feature within the WET-BOEW and Canada.ca design system:
    • Archived: Creates an archived alert block triggered by a checkbox field on a entity // #3097228
    • Blocks: Creates custom blocks of type Basic, Search, Spotlight, and Modal (ability to use blocks as modal for CKEditor // #3391443
    • Blog: Creates a default Blog listing layout page // #3306505
    • Book: Configures book module to support GC Subway functionality // #3219195)
    • Breadcrumb: Configures breadcrumb and related functionality // #3203791
    • Carousel: Creates custom block of type Carousel // #3313685
    • Comment: Default comment functionality
    • Editor: CKEditor integration with filters for Data Tables and addition of several plugins (WET Alert, Panels) // #3255971
    • Font Awesome: Default fontawesome functionality
    • Group: Default Group functionality along with mappings to import all departments through Migrate using the Open Data API
    • Landing Page: Default Landing Page functionality
    • Layout: Default Layout functionality and enhancements
    • Media: Default Media functionality and enhancements
    • Media Audio: Default Audio entity type for Media
    • Media Bulk Upload: Default improvements to Bulk Upload for Media
    • Media Document: Default Document entity type for Media
    • Media Image: Default Image entity type for Media
    • Media Image Responsive: Responsive image support for Media
    • Media Instagram: Default Instagram entity type for Media
    • Media Slideshow: Default Slideshow entity type for Media
    • Media Twitter: Default Twitter entity type for Media
    • Media Video: Default Video entity type for Media
    • Metatag: Allow setting GC Adobe Analytics metatag attributes // #3415924
    • Migration: Extensive Migration functionality along with numerous plugins and default content
    • Page: Customizations for the Page content type, including Lead Title // #3389645
    • Paragraph: Default Paragraph functionality
    • Password Policy: Default strong ISM password policy // #3252532
    • Queue: Queue functionality along with views argument plugins related to SubQueue support
    • Search: Default setup for Search API
    • Search DB: Default setup for Search w/Database Backend
    • Sitemap: Default Sitemap functionality
    • Taxonomy: Default taxonomy vocabularies used for categorizing content
    • Theme: Default Theme setup for frontend and backend
    • User: Default User functionality along with plugin for User Dropdown block
    • Webform: Webform enhancements along with custom plugins (Report a Problem, Did you Find) and SCCAI 2019 support // #3111375
    • Workflow: Workflow enhancements to improve content editing experience
wxt_extendDistribution
WxT Translation
  • Ensures that both of the official languages for Canada are setup correctly
  • Provides additional functionality for interacting with Drupal Core’s language subsystem:
    • Translation helper class for importing translations for a given module
    • Various other helper methods for enabling, importing and updating translations
    wxt_translationDistribution

    Standalone Installation

    A standalone installation allows you to install and configure the standalone components type discussed in the previous section separately without relying on a pre-packaged distribution (composer project).

    A composer project will often include multiple modules whether both custom and contributed along with the various configuration and dependencies they will rely on.

    Drupal WxT offers a standalone installation as an alternative for those users who don’t want the full weight of a distribution and prefer more control over their setup while still conforming to the Government of Canada C&IA Specification.

    Instead users can opt to create their own distribution (composer project) and install only the specific modules and themes required for their needs.

    At a minimum and to comply with the WET-BOEW and Canada.ca design system you only need use 2 components.

    Benefits

    Components

    ComponentFeaturesMachine NameType
    WxT Bootstrap (Theme)
    • Provides Templates to adhere to the C&IA Specification
    wxt_bootstrapStandalone
    WxT Library (Module)
    • Integrates Drupal with WET-BOEW Framework Assets (CSS/JS)
    wxt_libraryStandalone

    For the WET-BOEW Framework Assets it is mandatory that you follow the expected naming convention and that these files be placed within the /libraries folder.

    For you convenience all of these components are already part of a composer repository that can be added very easily to your new or existing composer project.

    {
        ...
        "require": {
            ...
            "drupal/wxt_bootstrap": "^8.0",
            "drupal/wxt_library": "^8.0",
        },
        ...
        "repositories": [
            {
                "type": "composer",
                "url": "https://drupalwxt.github.io/composer-extdeps/"
            }
        ],
        ...
    }
    

    Note: It is still recommended to use the distribution method, as the standalone option receives limited support and you will lose out on some of the functionality / plugins that help to more fully integrate with the WET-BOEW and Canada.ca design system.

    Leverage as a Reference Implementation

    If you prefer full control over your codebase and want to reduce external dependencies, you can use Drupal WxT as a reference implementation.

    This means that, as long as you provide proper attribution, you have the freedom to copy or fork any part of the codebase and incorporate it into your own project.

    The main drawback of this approach is that you won’t receive community support and also won’t have the same tight integration of features with the WET-BOEW and Canada.ca design system.

    However you can selectively choose exactly what you need for your project, potentially saving some time and reducing additional external dependencies.

    Our advice at the end of the day is you must consider what is best for your department or organization in the long term.

    2 - 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 the following commands (choosing your version) and replace site-name with the directory of your choice this is where WxT will be installed.

    # Requires PHP 8.1
    composer self-update
    composer create-project drupalwxt/site-wxt:10.1.x-dev <site-name> --no-interaction
    
    # Requires PHP 8.2
    composer self-update
    composer create-project drupalwxt/site-wxt:10.2.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@2024 \
      --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.

    3 - 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
    

    4 - 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:

    ReleaseCreated DateDescription
    5.3.02024-11-04
    • Build Infrastructure
      • Varnish Ban / Purge logic
      • Allow to specify composer version
    • Security Updates for Drupal Core
    • Updates for Drupal Core Patch (bugfix) release of Drupal Core to v10.3.5
    • Updates for Drupal Contrib + WxT
      • Invalid Mapping Definition in upload_validators Config Schema 3477356
      • Ignore useless method overriding on ArchivedField::__construct() 3472183
      • Remove default_argument_skip_url from Views 3472124
      • Enable GitLab CI automated testing 3472183
      • Remove calls to file_validate() which is deprecated 3472120
      • Add schema file to wxt_ext_editor to prevent error on text format edit/save 3457046
      • Update footnotes, toc_filter, and url_embed to fix error on CKE5 text format admin form 3457046
      • Add ArchivedField.php constructor back to fix install error 3457046
    • Updated for WxT Bootstrap
      • N/A
    • Updates for WxT Library
      • N/A

    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):

    Update to Drupal Core 10.3.x line.

    5.2.32024-07-02
    • Build Infrastructure
      • N/A
    • Security Updates for Drupal Core
      • N/A
    • Updates for Drupal Core Patch (bugfix) release of Drupal Core to v10.2.7
    • Updates for Drupal Contrib + WxT
      • wxt_ext_layout deprecations in Panels 4.8 3457046
      • LB inline blocks are no longer translatable 3456872
      • Layout Builder ST not listed in modules list 3456863
      • PHP deprecation issues with AutoSaveFormBuilder 3444515
      • Split contextual footer menu migration 3456754
      • Update file_entity in composer.json 3445800
      • SKAUGHT: Security advisory for group module 3406903
    • Updated for WxT Bootstrap
      • Use Bootstrap to v3.31
      • Use content language for footer menu visibility conditions 3456827
    • Updates for WxT Library
      • Add latest releases of wet-boew and gcweb (v4.0.75 and v14.6.0)

    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):

    The Group module has been updated to the 2.2.x branch as an intermediate step required to get to the recommended 3.2.x branch.

    5.2.22024-04-15
    • Build Infrastructure
      • N/A
    • Security Updates for Drupal Core
      • N/A
    • Updates for Drupal Core Patch (bugfix) release of Drupal Core to v10.2.5
    • Updates for Drupal Contrib + WxT
      • N/A
    • Updated for WxT Bootstrap
      • Make gc-thickline default for H1 3403484
      • Fix for duplicate footer in update GCWeb theme 3436553
    • Updates for WxT Library
      • Add latest releases of wet-boew and gcweb 3422762
      • WxT Library (language block) warning when viewing the latest version node page in some cases 3403484

    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):

    The Group module has been downgraded to the 8.x-1.6 release + alongside the flexible permissions module which has been added.

    This is needed for an immediate upgrade path for groups and the next release will have groups using again the 2.2.x branch.

    5.2.12024-02-19
    • Build Infrastructure
      • N/A
    • Security Updates for Drupal Core
      • N/A
    • Updates for Drupal Core Patch (bugfix) release of Drupal Core to v10.2.3
    • Updates for Drupal Contrib + WxT
      • Deprecated function: str_contains(): Passing null to parameter #1 3415945
      • Security advisory for group module [3406903](https://www.drupal.org/node/3406903
      • Allow setting GC Adobe Analytics metatag attributes 3415924
      • Patch for 3107212 no longer applies in 5.2.0 3418450
      • Patch identified as “Temporary” has been in use for approximately 6 years 3421777
      • Remove unnecessary usort patch from WxT build 3421776
    • Updated for WxT Bootstrap
      • Starterkit fixes and add some README.md instructions 3420710
      • Lead title styling still displays even if field is empty 3420910
      • Menu Block doesn’t reflect expand state correctly 3419328
    • Updates for WxT Library
      • SearchApiBlockForm missing title 3418164

    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):

    The Group module has been updated to the 2.2.x branch as an intermediate step required to get to the recommended 3.2.x branch.

    5.2.02024-01-18
    • Build Infrastructure
      • N/A
    • Security Updates for Drupal Core
    • Updates for Drupal Core
      • N/A
    • Updates for Drupal Contrib + WxT
      • N/A
    • Updated for WxT Bootstrap
      • N/A
    • Updates for WxT Library
      • N/A

    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 release is functionality equivalent to v5.1.1 but against Drupal Core 10.2.x.

    Repositories for Drupal WxT

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

    NameWebsiteDescriptionSize
    composer-extdepsdrupalwxt/composer-extdepsComposer repository for external dependencies on Drupal WxTSize: 76 Bytes
    docker-scaffolddrupalwxt/docker-scaffoldDocker Scaffold for Drupal WxTSize: 206 Bytes
    drupalwxt.github.iodrupalwxt/drupalwxt.github.ioGitHub Pages for Drupal WxT.Size: 15431 Bytes
    helm-drupaldrupalwxt/helm-drupalHelm Chart for deploying an enterprise-grade Drupal environment.Size: 67692 Bytes
    site-wxtdrupalwxt/site-wxtAn example composer project for the Drupal WxT distribution used for integration testing.Size: 4142 Bytes
    terraform-kubernetes-drupalwxtdrupalwxt/terraform-kubernetes-drupalwxtTerraform module for Drupal WxTSize: 32 Bytes
    themes-cdndrupalwxt/themes-cdnContent Delivery Network (CDN) files for the theme repositories of the Web Experience Toolkit (WET)Size: 12445 Bytes
    wxtdrupalwxt/wxtDrupal variant of the Web Experience Toolkit (WxT).Size: 3458 Bytes
    wxt-projectdrupalwxt/wxt-projectComposer project template for Drupal 9 sites built with the WxT distribution.Size: 72 Bytes
    wxt_bootstrapdrupalwxt/wxt_bootstrapBootstrap derived sub-theme aligned for use with the Web Experience Toolkit jQuery Framework.Size: 1335 Bytes
    wxt_librarydrupalwxt/wxt_libraryWeb Experience Toolkit Framework integration for Drupal.Size: 147 Bytes

    6 - 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.