forked from wet-boew/GCWeb
-
Notifications
You must be signed in to change notification settings - Fork 0
/
implementing.html
243 lines (215 loc) · 10 KB
/
implementing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
---
{
"title": "Quick implementation guide - GCWeb theme",
"language": "en",
"altLangPrefix": "implementing",
"breadcrumb": [
{ "title": "GCWeb home", "link": "../index-en.html" }
],
"secondlevel": false,
"dateModified": "2019-12-10",
"share": "true"
}
---
<p>This is an implementation guide for the Canada.ca theme with the Web Experience Toolkit version 4.x.</p>
<p>The code name for "Canada.ca theme" is GCWeb. We use that term interchangeably. GCWeb is built on top of WET-BOEW 4.</p>
<div class="row">
<div class="col-md-7">
<p>WET-BOEW 4 is built on top of various other web project such:</p>
<ul>
<li>Bootstrap 3 SASS (for a CSS baseline layer)</li>
<li>Code prettify</li>
<li>Datatable.net</li>
<li>Flot chart</li>
<li>jQuery</li>
<li>jQuery Validation</li>
<li>Mathjax</li>
<li>Magnific popup</li>
<li>Open Layer</li>
</ul>
</div>
<div class="col-md-5">
<p>GCWeb has some additional plugins like:</p>
<ul>
<li>Data JSON</li>
<li>Do action</li>
<li>URL mapping</li>
<li>Field flow</li>
</ul>
</div>
</div>
<h2>Get your template setup</h2>
<h3>1. Download the GCWeb library</h3>
<p><a href="https://wet-boew.github.io/themes-dist/GCWeb/gcweb-theme/release/index-en.html">Version history - Canada.ca theme (GCWeb)</a></p>
<h3>2. Copy the content of following folder in your Web Server</h3>
<ul>
<li>GCWeb</li>
<li>wet-boew</li>
</ul>
<h3>3. Create your page template</h3>
<p>As a starting point, we recommand to use the <a href="#static-header-footer">Static header and footer</a> for Bootstap 3.</p>
<p>Alternatively you can use a static page, like the <a href="https://wet-boew.github.io/themes-dist/GCWeb/content-en.html">generic content page</a>, as a baseline to create your template.</p>
<p>Here the various part of the template you will need to modify:</p>
<ul>
<li>Page title</li>
<li>Page description</li>
<li>Page metadata</li>
<li>Opposite page language link</li>
<li>Breadcrumb items</li>
<li>Page content (body)</li>
<li>Page date modified</li>
<li>Relative link to GCWeb and wet-boew folder for:
<ul>
<li>CSS files</li>
<li>Images</li>
<li>Javascript</li>
</ul>
</li>
<li>Where the search form is submited</li>
</ul>
<p>Additionally, if you are going to design a bilingual template skeleton, you will need to:</p>
<ul>
<li>Toggle the <code>lang</code> attribute for the proper language</li>
<li>Create partials for each template content pieces such:
<ul>
<li>Skip links</li>
<li>Language selection</li>
<li>FIP - Text and image for the Governement of Canada Organization publisher</li>
<li>Search form</li>
<li>Top menu - You might want to leverage the <a href="#menuCDN">CDN menu</a> which consist to change the data-ajax attribute value</li>
<li>Breadcrumb</li>
<li>Report a problem</li>
<li>Date modified</li>
<li>Page footer</li>
</ul>
</li>
</ul>
<h3>Customize your template</h3>
<p>The <a href="https://www.canada.ca/en/government/about/design-system.html">Canada.ca design system</a> and the <a href="https://www.canada.ca/en/treasury-board-secretariat/services/government-communications/canada-content-information-architecture-specification.html">Content and IA specification</a> allow some customization for transactional scenario and a campaigns. Read those guidance for more detailled information about what is allowed.</p>
<h3>Use only the Canada.ca style without WET-BOEW's Javascript</h3>
<p>GCWeb is designed to work together with WET-BOEW. Its WCAG 2.0 Level AA baseline conformity fully rely on the WET-BOEW 4 framework. If you are only using the CSS and the base HTML markup, you're encouraged to do the following:</p>
<ul>
<li>Peform a full WCAG assessment for every published pages</li>
<li>Create your own JS for the top menu behaviour</li>
<li>Re-create and maintain yourself every plugin, design pattern and behaviour implemented by WET.</li>
</ul>
<h2>Migrate your content</h2>
<p>Before you migrate your content, we recommend to:</p>
<ul>
<li>Create a content inventory</li>
<li>Identify your top task and top pages, usefull to prioritize your content review</li>
<li>Complete a content cleanup exercise that consist at least in:
<ul>
<li>Taking action for redundant outdated trivial (ROT) content</li>
<li>Fixing any HTML lint issue that could be reported by the W3C HTML5 validation software</li>
<li>Removing any custom and inline CSS you have. If you can't then at least identify all those pages and centralize the CSS in one file</li>
</ul>
</li>
</ul>
<p>Converting your content pages into GCWeb compatible markup means:</p>
<ul>
<li>You are using valid HTML5 markup</li>
<li>There is no custom CSS and no inline CSS</li>
<li>You are leveraging the <a href="https://getbootstrap.com/docs/3.3/css/">Bootstrap 3 CSS grid</a></li>
<li>You are using GCWeb CSS and WET 4 CSS, documented in:
<ul>
<li><a href="https://wet-boew.github.io/wet-boew-styleguide/index-en.html">wet-boew style guide</a></li>
<li><a href="https://wet-boew.github.io/themes-dist/GCWeb/index-en.html#notes">Notes and other resource in GCWeb</a></li>
<li>Following the code sample and <a href="https://wet-boew.github.io/themes-dist/GCWeb/index-en.html#templates-common-design">published page template in GCWeb</a>. Like Topic template.</li>
</ul>
</li>
<li>You are using WET4 plugins and GCWeb plugins
<ul>
<li><a href="https://wet-boew.github.io/v4.0-ci/demos/index-en.html">WET 4 plugins</a></li>
<li><a href="https://wet-boew.github.io/themes-dist/GCWeb/index-en.html#plugins">GCWeb plugins</a></li>
</ul>
</li>
</ul>
<p>Note regarding site migrating from WET 3, here are some well known challenges:</p>
<ul>
<li>The grid system, <code>.span-*</code> need to be converted into a combination of <code>div.row</code> and <code>div.col-*-*</code>.</li>
<li>Any callout module would need to be converted into alerts or panels in combinaison with a CSS grid. They need to be coded in distinct markup</li>
<li>Various of other changes that are not fully documented, like the CSS class mapping</li>
</ul>
<h2>Stay up-to-date</h2>
<p>Every release of GCWeb now follows a strict versioning numbering and the release notes now contain all the information you need to update your implementation. This includes information like:</p>
<ul>
<li>List of all changes that are marked as Major, Minor or Patch</li>
<li>An overview of all changes that was applied to the WET 4 dependency</li>
<li>List of modified files that you would need to replace</li>
<li>Link to all Subresource integrity (SRI) hash</li>
<li>Ad hoc details on specific content updates that don't have their own documentation page yet.</li>
</ul>
<p>Since February 2019, we are using and releasing versions in accordance with the semantic versioning 2.0.0 (<a href="https://wet-boew.github.io/wet-boew-documentation/decision/6.html">Design decision #6</a>) where our API is defined by the <a href="https://wet-boew.github.io/wet-boew-documentation/decision/3.html">Design decision #3</a></p>
<h2>Get help</h2>
<ul>
<li>Check at the documentation published on <a href="https://wet-boew.github.io/themes-dist/GCWeb/index-en.html">GCWeb</a> and on the <a href="https://www.canada.ca/en/government/about/design-system.html">Canada.ca design system</a></li>
<li>Look at current and closed <a href="https://github.com/wet-boew/GCWeb/issues">github issues</a></li>
<li>Submit a <a href="https://github.com/wet-boew/GCWeb/issues/new">new issue</a> on Github</li>
<li>Participate and ask your question during one of the weekly WET-BOEW code sprint every Tuesday.</li>
</ul>
<h2 id="menuCDN">Menu CDN</h2>
<p>Principal publisher udpate those following HTML fragment file every time there is a change to Canada.ca top menu.</p>
<ul>
<li>English: <a href="https://www.canada.ca/content/dam/canada/sitemenu/sitemenu-v2-en.html">https://www.canada.ca/content/dam/canada/sitemenu/sitemenu-v2-en.html</a></li>
<li>French: <a href="https://www.canada.ca/content/dam/canada/sitemenu/sitemenu-v2-fr.html">https://www.canada.ca/content/dam/canada/sitemenu/sitemenu-v2-fr.html</a></li>
</ul>
<h2 id="static-header-footer">Static header and footer</h2>
<p>Static HTML header and footer that you can just copy and paste in your project, with slight modifications e.g. metadata.</p>
<table class="table table-bordered table-hover">
<thead>
<tr>
<td></td>
<th>Bootstrap 3</th>
<th>Bootstrap 4 (experimental)</th>
</tr>
</thead>
<tbody>
<tr>
<th>Example</th>
<td>
<ul class="mrgn-bttm-0">
<li><a href="static-header-footer/bootstrap-3.html">English</a></li>
</ul>
</td>
<td>
<ul class="mrgn-bttm-0">
<li><a href="static-header-footer/bootstrap-4.html">English</a></li>
</ul>
</td>
</tr>
<tr>
<th>Header</th>
<td><a href="https://github.com/wet-boew/GCWeb/blob/master/site/pages/gcweb-theme/static-header-footer/bootstrap-3.html#L1-L77" rel="external">Source code, line 1 to 77</a></td>
<td><a href="https://github.com/wet-boew/GCWeb/blob/master/site/pages/gcweb-theme/static-header-footer/bootstrap-4.html#L1-L66" rel="external">Source code, line 1 to 66</a></td>
</tr>
<tr>
<th>Footer</th>
<td><a href="https://github.com/wet-boew/GCWeb/blob/master/site/pages/gcweb-theme/static-header-footer/bootstrap-3.html#L187-L233" rel="external">Source code, line 187 to 233</a></td>
<td><a href="https://github.com/wet-boew/GCWeb/blob/master/site/pages/gcweb-theme/static-header-footer/bootstrap-4.html#L84-L122" rel="external">Source code, line 84 to 122</a></td>
</tr>
<tr>
<th>Notes</th>
<td>
<ul>
<li>Includes WET scripts</li>
<li>Includes GCWeb styles</li>
<li>Needs to have assets paths updated to fit your folder structure</li>
</ul>
</td>
<td>
<ul>
<li>Does not include WET scripts</li>
<li>Does not include GCWeb styles</li>
<li>Does not include the menu</li>
<li>Relies on an experimental stylesheet for a Canada.ca look</li>
</ul>
</td>
</tr>
<tr>
<th>Special assets</th>
<td>All included in the current GCWeb release</td>
<td><a href="https://github.com/wet-boew/GCWeb/blob/master/site/pages/gcweb-theme/static-header-footer/site-assets/x-bootstrap-4.css" rel="external">Download experimental CSS</a></td>
</tr>
</tbody>
</table>