Quick implementation guide - GCWeb theme

This is an implementation guide for the Canada.ca theme with version 4.x of the Web Experience Toolkit (WET-BOEW).

The code name for the Canada.ca theme is GCWeb. We use these two terms interchangeably. GCWeb is built on top of WET-BOEW 4.

Set up your template

1. Download the GCWeb library

Version history - Canada.ca theme (GCWeb)

Every release contains the following assets (at the end of the release notes):

• themes-dist-[version]-gcweb.zip: this is the file you need in order to build your GCWeb site.
• themes-cdn-[version]-gcweb.zip: this file only contains the GCWeb builder (excludes WET-BOEW builder).
• Source code (zip): this file contains a snapshot of the GCWeb repository at the moment of the release. To be used only if you intend to build your site using GCWeb-Jekyll or contribute to the project.

2. Copy the content to your Web Server

After downloading the zip file (themes-dist-[version]-gcweb.zip), copy the following folders to your Web server:

• GCWeb/
• wet-boew/

The rest of the zip file contains complementary information and demos.

3. Create your page template

As a baseline to create your template, we recommend using a static page, like the generic content page. You can then copy your template from page to page. However, you will need to modify the following parts of the template:

• Page title
• Page description
• Page metadata
• Opposite page language link
• Breadcrumb items
• Page content (body)
• Page date modified
• Relative link to GCWeb and wet-boew folder for:
  • CSS files
  • Images
  • Javascript
• Where the search form is submited

If you are designing a bilingual template skeleton, you will also need to:

• Toggle the lang attribute for the proper language
• Create partials for each template content pieces such as:
  • Skip links
  • Language selection
  • FIP - Text and image for the Governement of Canada Organization publisher
  • Search form
  • Top menu - You might want to leverage the CDN menu by changing the data-ajax attribute value
  • Breadcrumb
  • Report a problem
  • Date modified
  • Page footer

To help you create your pages, take a look at the following sections of our documentation:

• Components: contains GC components and design pattern to be used in your page content area.
• Templates: contains pages component layout (ex. Institutional template) and special page template (ex. Splash page)
• Sites: contains components for the Canada.ca site baseline template.

Customize your template

The Digital Transformation Office at Treasury Board Secretariat (DTO-TBS) provides the guidance on how to use the components implemented in our reference implementation of the Canada.ca theme. While DTO-TBS allows customization for transactional scenarios and campaigns, we recommend you read the guidance for more detailed information about what is allowed:

• Canada.ca design system
• Content and IA specification

Use only the Canada.ca style without WET-BOEW's Javascript

GCWeb is designed to work with WET-BOEW. It is compliant with WCAG 2.0 Level AA and fully relies on the WET-BOEW 4 framework. If you are only using the CSS and the base HTML markup, you are encouraged to:

• Peform a full WCAG assessment for every published pages
• Create your own JS for the top menu behaviour
• Re-create and maintain every plugin, design pattern and behaviour implemented by WET-BOEW.

Migrate your content

Before you migrate your content, we recommend you to:

• Create a content inventory
• Identify your top tasks and top pages in order to prioritize your content review
• Complete a content cleanup exercise that at least consists of:
  • Taking action for redundant outdated trivial (ROT) content
  • Fixing any HTML link issue that could be reported by the W3C HTML5 validation software
  • Removing any custom and inline CSS – if this is not possible, identify these pages and centralize the CSS in one file

Converting your content pages into GCWeb compatible markup means:

• You are using valid HTML5 markup
• There is no custom CSS and no inline CSS
• You are leveraging the Bootstrap 3 CSS grid
• You are using GCWeb CSS and WET 4 CSS, documented in:
  • wet-boew style guide
  • notes and other resources on GCWeb
  • the code sample and published page templates in GCWeb (such as the Topic template).
• You are using WET4 plugins and GCWeb plugins
  • WET 4 plugins
  • GCWeb plugins

Here are some well-known challenges regarding migrating a site from WET-BOEW 3:

• The grid system, .span-* needs to be converted into a combination of div.row and div.col-*-*.
• Any callout module would need to be converted into alerts or panels in combination with a CSS grid. They need to be coded in a distinct markup
• Other changes that are not fully documented, like the CSS class mapping

<div class="module-info span-3">
	<h3>…</h3>
	<p>…</p>
</div>

<div class=”row”>
	<div class=”col-md-6”>
		<section class=”alert alert-info”>
			<h3>…</h3>
			<p>…</p>
		</section>
	</div>
</div>

Stay up-to-date

Every GCWeb release follows a strict version numbering and the release notes contain all the information needed to update your implementation. This includes:

• a list of all changes that are marked as Major, Minor or Patch
• an overview of all changes that were applied to the WET-BOEW 4 dependency
• a list of modified files that you would need to replace
• links to all “Subresource integrity” (SRI) hashes
• ad hoc details on specific content updates that do not have their own documentation page yet

Since February 2019, we have been using and releasing versions in accordance with the semantic versioning 2.0.0 (Design decision #6) where our API is defined by the Design decision #3.

We try and avoid to make breaking changes that impact web authors. Most of our breaking changes impact only the site baseline template and all major changes have a backwards support for at least one (1) year to ease the transition.

Please note that while we work on improving the documentation of all our components, there are still a few gaps. If you have any questions regarding those gaps, feel free to ask us during our weekly office hours.

Get help

• Consult the documentation published on GCWeb and on the Canada.ca design system
• Look at the list of current and closed GitHub issues
• Submit a new issue on Github
• Attend the weekly WET Office hours (every Tuesday) and ask questions.

CDN Menu

Principal Publisher updates the following HTML fragment file every time there is a change to the Canada.ca top menu:

• English: https://www.canada.ca/content/dam/canada/sitemenu/sitemenu-v2-en.html
• French: https://www.canada.ca/content/dam/canada/sitemenu/sitemenu-v2-fr.html

Static header and footer

Here are static HTML headers and footers that you can copy and paste into your project, with slight modifications (e.g. metadata).