Notification trigger implementation

README.md

@@ -1,31 +1,33 @@
 # Project: Search UI
 
-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.
+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.
 
 ## References
 
 - Coveo Headless: https://docs.coveo.com/en/headless/latest/
+- GCWeb: https://wet-boew.github.io/GCWeb/index-en.html
 
 ## Key details
 
 ### Sponsor / Contact
 
-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.
+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.
 
 ### Timeline and frequency
 
 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.
 
-**Removal date** will coincide with end of contract with vendor.
+**Removal date** would align with end of contract with current vendor.
 
 ### Improvement plan
 
 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.
 
-In the medium to long term, some activities may take place related to:
-- stabilization of the query suggestion combobox;
-- porting of some parts of the codebase to GCWeb;
-- addition of machine learning features.
+Example of code contributions may be related to:
+
+- development/configurations of AI-powered features and other innovations
+- bug fixes, accessibility and security improvements
+- project maintenance chores
 
 For more details, please [consult full checklist of to do items](todo.md).
 
@@ -41,7 +43,7 @@ Search UI follows [Semantic Versioning 2.0.0](https://semver.org/)
 
 ## Getting started
 
-This rubric is for developers.
+This rubric is for developers and testers.
 
 ### Build files for release or to test code quality before opening a Pull request
 
@@ -54,30 +56,36 @@ This rubric is for developers.
 #### Test locally
 
 1. Install Docker
-2. Add an API key to your site settings as described below in [Setting an API key](#setting-an-api-key). Otherwise, please see [Alternative to the API key by getting a token](#alternative-to-the-api-key-by-getting-a-token) below.
+2. Add an API key to your site settings as described below in [Setting an API key](#setting-an-api-key).
 3. run `docker compose up --build`
 
 ##### Setting an API key
 
-1. 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, please see the next section on how to use a token as described below.
+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.
+
+#### Testing through GitHub Pages 
 
-##### Alternative to the API key by getting a token
+##### Main website
 
-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:
+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/. 
 
-1. Go to a search page on the Canada.ca Preview server such as: **/en/sr/srb.html**.
-2. Open the inspector (developer tool) and look for the `div` tag that has the attribute called `data-gc-search`.
-3. Inside this attribute, you'll find a Javascript object that has a field called `accessToken`. Grab the value of that token.
-4. a) If you are **testing locally**, 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. Add the token value as the key in `[API KEY HERE]`. b) If you are **testing through GitHub pages**, replace instances of `{{ site.data.token.API_KEY }}` with the token, on HTML pages would like to test.
-5. If the token doesn't seem valid or if you have passed the 24 hours time-to-live (TTL), go back to step one and take another one from the Canada.ca Preview server.
+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.
 
-#### Testing through GitHub Pages 
+##### In your fork
 
-1. Add the required token on HTML pages would like to test by [following the instructions on Alternative to the API key by getting a token](#alternative-to-the-api-key-by-getting-a-token). 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.
-2. Push your code to a branch of your choice in your origin remote (fork). It is recommended that you use a dedicated branch for testing, one that you would never open a Pull request from.
+This is usually to test your changes before opening a pull request, or to conduct usability testing and accessibility assessments.
+
+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.
+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.
 3. Make sure your repository has GitHub Pages enabled, on that specific above-mentioned branch.
 4. Your site is live on GitHub pages!
 
+**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.
+
+##### Getting a token
+
+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.
+
 ### Deployment
 
 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.
@@ -102,14 +110,16 @@ They must be used within the `[data-gc-search]` attribute. See the **/test/src-e
 : 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`
 - `numberOfSuggestions`
 : Number of suggestions to show in the Query Suggestion (QS) box. This will activate the QS feature on your search page. Default: `0`
+- `minimumCharsForSuggestions`
+: Number of characters entered by the users needed to trigger the QS feature
 - `enableHistoryPush`
 : Allows for UI elements that are not hyperlink tags to register their action in the history, such as pagination. Default: `true`
 - `isContextSearch`
 : 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`
 - `isAdvancedSearch`
 : 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`
 - `originLevel3`
-: 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).
+: 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
 
 #### Templates
 
@@ -218,10 +228,118 @@ Sometimes your search pages contain more than one input relevant to the search's
 - `filetype`
 : 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`
 - `originLevel3`
-: Allows for mimicking a specific search page/context by setting its path through this URL parameter
+: 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
 
 ### Other
 
 #### Analytics tracking
 
-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).
+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:
+
+- interfaceLoad
+: Search interface was initially loaded (or refreshed) with a search term
+- searchboxSubmit
+: any subsequent searches from the search box
+- omniboxAnalytics
+: User clicks on a query suggestion
+- documentOpen
+: User clicks on a search result
+
+And the main event type for when an action cause is not provided:
+
+- getMoreResults
+: User clicked on a pagination button
+
+They each carry the following fields in their respective payloads:
+
+##### interfaceLoad
+
+- language
+- userAgent
+- originContext
+- originLevel1
+- originLevel2
+- originLevel3
+- splitTestRunName
+- splitTestRunVersion
+- customData
+    - context_searchPageUrl
+    - c_context_searchpagerelativeurl
+    - coveoHeadlessVersion
+- facetState
+- anonymous
+- clientId
+- queryText
+- responseTime
+- results
+    - documentUri
+    - documentUriHash
+- numberOfResults
+- queryPipeline
+- actionCause
+- searchQueryUid
+
+##### searchboxSubmit
+
+Same as [interfaceLoad](#interfaceLoad).
+
+##### documentOpen
+
+Same as [interfaceLoad](#interfaceLoad), plus the following:
+
+- collectionName
+- documentAuthor
+- documentPosition
+- documentTitle
+- documentUri
+- documentUriHash
+- documentUrl
+- rankingModifier
+- sourceName
+- customData
+    - context_searchPageUrl
+    - c_context_searchpagerelativeurl
+    - coveoHeadlessVersion
+    - contentIDKey
+    - contentIDValue
+
+##### omniboxAnalytics
+
+Same as [interfaceLoad](#interfaceLoad), plus the following:
+
+- customData
+    - context_searchPageUrl
+    - c_context_searchpagerelativeurl
+    - coveoHeadlessVersion
+    - suggestionRanking
+    - partialQuery
+    - partialQueries
+    - suggestions
+    - querySuggestResponseId
+    - queryText
+
+##### getMoreResults
+
+- language
+- userAgent
+- originContext
+- originLevel1
+- originLevel2
+- originLevel3
+- splitTestRunName
+- splitTestRunVersion
+- customData
+    - context_searchPageUrl
+    - c_context_searchpagerelativeurl
+    - coveoHeadlessVersion
+    - pagerNumber
+- facetState
+- anonymous
+- clientId
+- eventType
+- eventValue
+- lastSearchQueryUid
+
+#### Removing on-page content from index
+
+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.

index.html

@@ -7,17 +7,20 @@
 <p class="lead">This is a demo site for the GC Search UI.</p>
 
 <h2 id="test">Test pages</h2>
+<p>To test search pages, please make sure you <a href="test/index.html">have a valid token</a>.</p>
 
 <h3>Regular pages</h3>
 <ul>
 	<li><a href="test/srb-en.html">Basic search page</a></li>
 	<li><a href="test/sra-en.html">Advanced search page</a></li>
 	<li><a href="test/src-en.html">Contextual search page</a></li>
-	<li><a href="test/qs-en.html">Search page with Query Suggestions (type-ahead)</a></li>
+	<li><a href="test/no-qs-en.html">Search without Query Suggestions (QS)</a></li>
+	<li><a href="test/qs-en.html">Search with custom QS configuration</a></li>
 	<li><a href="test/srb-fr.html" hreflang="fr" lang="fr">Page de recherche (base)</a></li>
 	<li><a href="test/sra-fr.html" hreflang="fr" lang="fr">Page de recherche (avancée)</a></li>
 	<li><a href="test/src-fr.html" hreflang="fr" lang="fr">Page de recherche (contextuelle)</a></li>
-	<li><a href="test/qs-fr.html" hreflang="fr" lang="fr">Page de recherche avec Suggestions de termes</a></li>
+	<li><a href="test/no-qs-fr.html" hreflang="fr" lang="fr">Recherche sans Suggestions de termes</a></li>
+	<li><a href="test/qs-fr.html" hreflang="fr" lang="fr">Recherche avec configuration de Suggestions personnalisée</a></li>
 </ul>
 
 <h3>Advanced tests</h3>

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "search-ui",
-	"version": "1.5.0",
+	"version": "1.6.0",
 	"description": "Canada.ca Search UI with Headless",
 	"main": "index.html",
 	"repository": {