You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Purpose of this repository is to provide MWS pages with the proper JS and CSS assets to achieve a working search page with the vendor's (Coveo) technology called Headless.
3
+
Purpose of this repository is to provide MWS pages with the proper JS and CSS assets to achieve working search pages with the vendor's (Coveo) technology called Headless, sitting on top of GCWeb.
This project is led by Principal Publisher at ESDC. The key contact in case of questions related to the project is Francis Gorman, who can be reached at francis.gorman@hrsdc-rhdcc.gc.ca. If no reply is received from this person, fallback contact is ESDC.SD.DEV-DEV.DS.EDSC@servicecanada.gc.ca.
14
+
This project is led by Principal Publisher at Service Canada (ESDC). The key contact in case of questions related to the project is Francis Gorman, who can be reached at francis.gorman@hrsdc-rhdcc.gc.ca. If no reply is received from this person, fallback contact is ESDC.SD.DEV-DEV.DS.EDSC@servicecanada.gc.ca.
14
15
15
16
### Timeline and frequency
16
17
17
18
The goal is to continue to refine and improve this code base on a regular basis. Every 6 months, if no activity is recorded on this repository, the key contact shall be reached out to in order to ensure it isn't stale.
18
19
19
-
**Removal date**will coincide with end of contract with vendor.
20
+
**Removal date**would align with end of contract with current vendor.
20
21
21
22
### Improvement plan
22
23
23
24
To manage development activities related to this project, a standard internal issue tracking system used at Principal Publisher will be used. Also, regular touchpoints with the search vendor, as well as formal service requests entered through their portal, could also spark some development activities from a vendor perspective.
24
25
25
-
In the medium to long term, some activities may take place related to:
26
-
- stabilization of the query suggestion combobox;
27
-
- porting of some parts of the codebase to GCWeb;
28
-
- addition of machine learning features.
26
+
Example of code contributions may be related to:
27
+
28
+
- development/configurations of AI-powered features and other innovations
29
+
- bug fixes, accessibility and security improvements
30
+
- project maintenance chores
29
31
30
32
For more details, please [consult full checklist of to do items](todo.md).
31
33
32
34
## Releases and API
33
35
34
36
All changes contributed through Pull requests will be packaged as releases. Releases are completed through the "Releases" tab in this GitHub repository; then, deployment to MWS follows the reguar release management cycle accordingly.
35
37
36
-
Each new verion of this project is defined based on an evaluaton of the impacts of changes against any formerly up-to-date Search UI implementation. The scope constitutes of all files within the "dist" folder (distribution files), which are JavaScript scripts and CSS styles. The usage of feautures can also be considered as part of the evaluation of impact. For example, a feature of the Javascript which is known by certitude to have never been used in a production environment, wouldn't cause any breaking change if modified and therefore, wouldn't generate a major version.
38
+
Each new verion of this project is defined based on an evaluaton of the impacts of changes against any formerly up-to-date LIVE Search UI implementation on Canada.ca. The scope constitutes of all files within the "dist" folder (distribution files), which are JavaScript scripts and CSS styles. Additionally, volume of usage for features can also be taken into consideration as part of the evaluation of impact on versioning. For example, an interactive feature from the Javascript which is known by certitude to have never been used in a production environment, wouldn't cause any breaking change if modified and therefore, wouldn't generate a major version.
### Build files for release or to test code quality before opening a Pull request
47
49
48
50
1. run: npm install -g grunt-cli
49
51
2. run: npm install
50
52
3. run: grunt (build script; tasks to lint, test & minify content in "dist")
51
53
52
54
### Test as end-user
53
55
54
-
1. Push to a branch in your origin remote, in a branch of your choice. It is recommended that you use a dedicated branch for testing, which is different from one where you would be opening a Pull request from.
55
-
2. Make sure your repository has GitHub Pages enabled, on that specific above-mentioned branch.
56
-
3. Since you need a token to communicate with the Coveo API, you can do the following to go to get a token valid for 24 hrs:
57
-
1. Go to a search page on the Canada.ca preview such as: **/en/sr/srb.html**.
58
-
2. Open the inspector (developer tool) and look for the `div` tag that has the attribute called `data-gc-search`.
59
-
3. Inside this attribute, you'll find a Javascript object that has a field called `accessToken`. Grab the value of that token.
60
-
4. Replace `XYZ` with the token on any page within the /test/ folder of this project, such as **srb-en.html**.
61
-
5. If you are planning on opening a pull request with your changes, do not forget to put `XYZ` back into the files.
62
-
6. If the token doesn't seem valid, take another one from the Canada.ca Preview server or you may have passed the 24 hours TTL of the token; get another one.
56
+
#### Test locally
57
+
58
+
1. Install Docker
59
+
2. Add an API key to your site settings as described below in [Setting an API key](#setting-an-api-key).
60
+
3. run `docker compose up --build`
61
+
62
+
##### Setting an API key
63
+
64
+
Create a `_data` folder at the root. Then, add a file named `token.yml` inside the `_data` folder. This file needs to simply have a key-value pair of `API_KEY: "[API KEY HERE]"` on line 1. The key value can be found at https://github.com/ServiceCanada/devops-documentation/blob/master/search/local-testing.md to replace the `[API KEY HERE]`. If you do not have access to the previous link and/or are unable to get an API key, you can use a token instead; in which case, see the [Getting a token](#getting-a-token) section below.
65
+
66
+
#### Testing through GitHub Pages
67
+
68
+
##### Main website
69
+
70
+
At all time, you can visit the GitHub website to view and test the GC Search UI with the latest Pull requests merged at play: https://servicecanada.github.io/search-ui/.
71
+
72
+
Since search pages need a token to communicate with the Coveo API and functioning properly, you will need to get your token by following the instructions in the [Getting a token](#getting-a-token) section below. You can then take this token and save it through the form linked from the website's index page under the "Test pages" section. Your token will be saved for the duration of your session on the website. If you close the tab or stay inactive for a while, you will need to go back and generate a new one.
73
+
74
+
##### In your fork
75
+
76
+
This is usually to test your changes before opening a pull request, or to conduct usability testing and accessibility assessments.
77
+
78
+
1. Do not use the `token.yml` approach documented for testing locally, since it may generate potential a [security risk](SECURITY.md) in the context of GitHub pages. Instead, get a token described in the [Getting a token](#getting-a-token) section below and replace instances of `{{ site.data.token.API_KEY }}` with the token, on HTML pages would like to test.
79
+
2. Push your code to a branch of your choice in your origin remote (fork). It is recommendeded that you use a dedicated branch for testing, one that you would never open a Pull request from.
80
+
3. Make sure your repository has GitHub Pages enabled, on that specific above-mentioned branch.
81
+
4. Your site is live on GitHub pages!
82
+
83
+
**Important note:** A token is only available for 24 hrs, after which a new one must be generated. Alternatively, instead of putting a token on all pages, you can let the user get their own token through the same process as described in the [Main website](#main-website) section above.
84
+
85
+
##### Getting a token
86
+
87
+
While on the GC network, go to the [Search token](https://canada-preview.adobecqms.net/en/service-canada/francis/get-sr-token.html) page and copy the value of the entire token loaded inside the page.
63
88
64
89
### Deployment
65
90
66
-
1.Take the content of the "dist" folder and put it on a server. Make sure you have a mechanism in place to handle a key/token
91
+
1.The content of the "dist" folder is what's needed for a release / deployment. See [Build files](#build-files) section above to generate this folder.
67
92
68
93
### Configurations, templates and parameters
69
94
@@ -84,17 +109,17 @@ They must be used within the `[data-gc-search]` attribute. See the **/test/src-e
84
109
-`lang`
85
110
: Langague of the text to output, in short format (`en` or `fr`). Will detect the langauge of the HTML page if not defined. If not determined, default is: `en`
86
111
-`numberOfSuggestions`
87
-
: Number of suggestions to show in the Query suggestion box. Default: `0`
88
-
-`unsupportedSuggestions`
89
-
: Extra mechanism to allow the use of the very early on Query suggestion feature. Default: `false`
112
+
: Number of suggestions to show in the Query Suggestion (QS) box. This will activate the QS feature on your search page. Default: `0`
113
+
-`minimumCharsForSuggestions`
114
+
: Number of characters entered by the users needed to trigger the QS feature
90
115
-`enableHistoryPush`
91
116
: Allows for UI elements that are not hyperlink tags to register their action in the history, such as pagination. Default: `true`
92
117
-`isContextSearch`
93
118
: Set the search behavior of the page as a contextual search. This is optional since it will detect automatically from the path of your page if it is contextual. If not determined, default is: `false`
94
119
-`isAdvancedSearch`
95
120
: Set the search behavior of the page as an advanced search. This is optional since it will detect automatically from the path of your page if it is advanced. If not determined, default is: `false`
96
121
-`originLevel3`
97
-
: Allows for mimicking a specific search page/context, such as the ESDC contextual search if you set it to: `/en/employment-social-development/search.html`. Default is the current page relative location (domain agnostic).
122
+
: Allows for mimicking a specific search page/context, such as the ESDC contextual search if you set it to: `/en/employment-social-development/search.html`; this value can be be relative or absolute and is used to differentiate and contextualize a search page from another both in terms of scoping the search results and in terms of knowledge base for machine learning-powered features. Default is set to the current page's absolute URL
98
123
99
124
#### Templates
100
125
@@ -187,7 +212,7 @@ Sometimes your search pages contain more than one input relevant to the search's
187
212
-`noneq`
188
213
: Search for anything but the search terms in input
189
214
-`fqocct`
190
-
: Search for all of the search terms in input
215
+
: Search for all of the search terms in input, matching on title or URL only
191
216
-`fqupdate`
192
217
: Search for search terms in input, on pages that have been modified only since a certain amount of time. Options are: `datemodified_dt:[now-1day to now]`, `datemodified_dt:[now-7days to now]`, `datemodified_dt:[now-1month to now]`, `datemodified_dt:[now-1year to now]`
193
218
-`dmn`
@@ -197,8 +222,124 @@ Sometimes your search pages contain more than one input relevant to the search's
197
222
-`elctn_cat`
198
223
: Used specifically for Elections Canada, to define a scope of search amongst their collection. See **/src/connector.js** to see all the options available
199
224
-`site`
200
-
: Used specifically for Elections Canada, to search within a specific site
225
+
: Used specifically for Canada Gazette, to search within a specific site
226
+
-`year`
227
+
: Used specifically for budget limit search results to be created or modified on a given year, with minimum being 2000 and max being current year +1
201
228
-`filetype`
202
229
: Search , within documents of a certain file type. Options are: `application/pdf`, `ps`, `application/msword`, `application/vnd.ms-excel`, `application/vnd.ms-powerpoint`, `application/rtf`
203
230
-`originLevel3`
204
-
: Allows for mimicking a specific search page/context by setting its path through this URL parameter
231
+
: Allows for mimicking a specific search page/context by setting its path through this URL parameter; this takes precedence over the configuration through data attribute
232
+
233
+
### Other
234
+
235
+
#### Analytics tracking
236
+
237
+
Custom event named `searchEvent` can used to hook onto from Analytics tools, such as Adobe Analytics. This allows to listen to search actions, more specifically "doing a search", since the Search UI is acting similar to a Single Page App (SPA). The payload varies based on the event type triggered, which is usually dictated by the `actionCause`. In the case where there is no `actionCause` in the payload of a beacon, then the `eventType` will tell you more about it. List of action causes:
238
+
239
+
- interfaceLoad
240
+
: Search interface was initially loaded (or refreshed) with a search term
241
+
- searchboxSubmit
242
+
: any subsequent searches from the search box
243
+
- omniboxAnalytics
244
+
: User clicks on a query suggestion
245
+
- documentOpen
246
+
: User clicks on a search result
247
+
248
+
And the main event type for when an action cause is not provided:
249
+
250
+
- getMoreResults
251
+
: User clicked on a pagination button
252
+
253
+
They each carry the following fields in their respective payloads:
254
+
255
+
##### interfaceLoad
256
+
257
+
- language
258
+
- userAgent
259
+
- originContext
260
+
- originLevel1
261
+
- originLevel2
262
+
- originLevel3
263
+
- splitTestRunName
264
+
- splitTestRunVersion
265
+
- customData
266
+
- context_searchPageUrl
267
+
- c_context_searchpagerelativeurl
268
+
- coveoHeadlessVersion
269
+
- facetState
270
+
- anonymous
271
+
- clientId
272
+
- queryText
273
+
- responseTime
274
+
- results
275
+
- documentUri
276
+
- documentUriHash
277
+
- numberOfResults
278
+
- queryPipeline
279
+
- actionCause
280
+
- searchQueryUid
281
+
282
+
##### searchboxSubmit
283
+
284
+
Same as [interfaceLoad](#interfaceLoad).
285
+
286
+
##### documentOpen
287
+
288
+
Same as [interfaceLoad](#interfaceLoad), plus the following:
289
+
290
+
- collectionName
291
+
- documentAuthor
292
+
- documentPosition
293
+
- documentTitle
294
+
- documentUri
295
+
- documentUriHash
296
+
- documentUrl
297
+
- rankingModifier
298
+
- sourceName
299
+
- customData
300
+
- context_searchPageUrl
301
+
- c_context_searchpagerelativeurl
302
+
- coveoHeadlessVersion
303
+
- contentIDKey
304
+
- contentIDValue
305
+
306
+
##### omniboxAnalytics
307
+
308
+
Same as [interfaceLoad](#interfaceLoad), plus the following:
309
+
310
+
- customData
311
+
- context_searchPageUrl
312
+
- c_context_searchpagerelativeurl
313
+
- coveoHeadlessVersion
314
+
- suggestionRanking
315
+
- partialQuery
316
+
- partialQueries
317
+
- suggestions
318
+
- querySuggestResponseId
319
+
- queryText
320
+
321
+
##### getMoreResults
322
+
323
+
- language
324
+
- userAgent
325
+
- originContext
326
+
- originLevel1
327
+
- originLevel2
328
+
- originLevel3
329
+
- splitTestRunName
330
+
- splitTestRunVersion
331
+
- customData
332
+
- context_searchPageUrl
333
+
- c_context_searchpagerelativeurl
334
+
- coveoHeadlessVersion
335
+
- pagerNumber
336
+
- facetState
337
+
- anonymous
338
+
- clientId
339
+
- eventType
340
+
- eventValue
341
+
- lastSearchQueryUid
342
+
343
+
#### Removing on-page content from index
344
+
345
+
You can add the class `sr-no-index` to any HTML element inside the main content of your page if you wish for that content to be ignored by the search engine. In which case, said content won't be indexed nor returned in the search result excerpts.
Copy file name to clipboardExpand all lines: SECURITY.md
+6-2Lines changed: 6 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,14 @@
2
2
3
3
# Security
4
4
5
-
**Do not post any security issues on the public repository!** Security vulnerabilities must be reported via a contact method listed on Principal Publisher's GCpedia page: https://www.gcpedia.gc.ca/wiki/Principal_Publisher_at_Service_Canada.
5
+
**Do not post any security issues on the public repository!** Example of a security issue would be to expose the restricted API key provided through the instructions on the README.
6
+
7
+
Security vulnerabilities must be reported via a contact method listed on Principal Publisher's GCxchange site: https://gcxgce.sharepoint.com/teams/10001402/SitePages/Search.aspx.
6
8
7
9
______________________
8
10
9
11
## Sécurité
10
12
11
-
**Ne publiez aucun problème de sécurité sur le dépôt publique!** Les vulnérabilités de sécurité doivent être signalées via une méthode de contact proposée sur la page GCpédia de l'Éditeur principal : https://www.gcpedia.gc.ca/wiki/%C3%89diteur_principal_de_Service_Canada.
13
+
**Ne publiez aucun problème de sécurité sur le dépôt publique!** Un exemple de problème de sécurité serait d'exposer la clé API limitée fournie à travers les instructions du README.
14
+
15
+
Les vulnérabilités de sécurité doivent être signalées via une méthode de contact proposée sur le site GCéchange de l'Éditeur principal : https://gcxgce.sharepoint.com/teams/10001402/SitePages/fr/Home.aspx.
0 commit comments