SR-454: Improve developemnt env w/ Jekyll & Docker

.gitignore

@@ -154,3 +154,13 @@ nbproject/*
 /.project
 .settings
 .vscode/*
+
+# Jekyll
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+vendor
+Gemfile.lock
+
+_data/token.yml

404.html

@@ -0,0 +1,8 @@
+---
+permalink: /404.html
+title: 404
+---
+
+<div class="container">
+	<p class="lead"><strong>Page not found | <span lang="fr">Page introuvable</span></strong></p>
+</div>

Gemfile

@@ -0,0 +1,27 @@
+source "https://rubygems.org"
+
+# Hello! This is where you manage which Jekyll version is used to run.
+# When you want to use a different version, change it below, save the
+# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
+#
+#     bundle exec jekyll serve
+#
+# This will help ensure the proper Jekyll version is running.
+# Happy Jekylling!
+gem "jekyll", "~> 4.3.3"
+
+gem 'jekyll-remote-theme'
+
+# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
+# and associated library.
+platforms :mingw, :x64_mingw, :mswin, :jruby do
+  gem "tzinfo", ">= 1", "< 3"
+  gem "tzinfo-data"
+end
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
+
+# Lock `http_parser.rb` gem to `v0.6.x` on JRuby builds since newer versions of the gem
+# do not have a Java counterpart.
+gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]

README.md

@@ -43,27 +43,42 @@ Search UI follows [Semantic Versioning 2.0.0](https://semver.org/)
 
 This rubric is for developers.
 
-### Build files
+### Build files for release or to test code quality before opening a Pull request
 
 1. run: npm install -g grunt-cli
 2. run: npm install
 3. run: grunt (build script; tasks to lint, test & minify content in "dist")
 
 ### Test as end-user
 
+#### Locally (with Docker)
+
+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.
+3. run `docker compose up --build`
+
+#### Through GitHub Pages 
+
 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.
 2. Make sure your repository has GitHub Pages enabled, on that specific above-mentioned branch.
-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:
-	1. Go to a search page on the Canada.ca preview 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. Replace `XYZ` with the token on any page within the /test/ folder of this project, such as **srb-en.html**.
-	5. If you are planning on opening a pull request with your changes, do not forget to put `XYZ` back into the files.
-	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.
+
+#### Setting an API key
+
+1. 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.
+
+#### Alternative to the API key by getting a token
+
+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:
+
+1. Go to a search page on the Canada.ca preview 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. Add a file named `token.yml` in 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]`.
+5. 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.
 
 ### Deployment
 
-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
+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.
 
 ### Configurations, templates and parameters
 
@@ -84,9 +99,7 @@ They must be used within the `[data-gc-search]` attribute. See the **/test/src-e
 - `lang`
 : 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 box. Default: `0`
-- `unsupportedSuggestions`
-: Extra mechanism to allow the use of the very early on Query suggestion feature. Default: `false`
+: Number of suggestions to show in the Query Suggestion (QS) box. This will activate the QS feature on your search page. Default: `0`
 - `enableHistoryPush`
 : Allows for UI elements that are not hyperlink tags to register their action in the history, such as pagination. Default: `true`
 - `isContextSearch`
@@ -202,3 +215,9 @@ Sometimes your search pages contain more than one input relevant to the search's
 : 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
+
+### 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).

_config.yml

@@ -1,10 +1,35 @@
+plugins:
+  - jekyll-remote-theme
+
 remote_theme: wet-boew/gcweb-jekyll
+
 title: Search UI for Canada.ca Search
 
-#
-# Page front matter defaults
 defaults:
   - scope:
       path: "" # Ensure it's applied to all pages
     values:
       layout: default
+
+exclude:
+  - .sass-cache/
+  - .jekyll-cache/
+  - gemfiles/
+  - Gemfile
+  - Gemfile.lock
+  - node_modules/
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+  - docker-compose.yml
+  - Gruntfile.js
+  - dist/
+  - package.json
+  - package-lock.json
+  - LICENSE
+  - CONDE_OF_CONDUCT.md
+  - CONTRIBUTING.md
+  - SECURITY.md
+  - README.md
+  - todo.md

docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  jekyll:
+    image: bretfisher/jekyll-serve
+    container_name: search-ui-site
+    volumes:
+      - .:/site
+    ports:
+      - '4000:4000'

index.html

@@ -2,15 +2,21 @@
 title: Search user interface (UI) with Headless
 ---
 
-<p class="lead">This is a demo site for the Search UI.</p>
+<p class="lead">This is a demo site for the GC Search UI.</p>
 
-<h2 id="test">Testing</h2>
+<h2 id="test">Test pages</h2>
 
 <ul>
-	<li><a href="test/srb-en.html">Sample basic search page</a></li>
-	<li><a href="test/sra-en.html">Sample advanced search page</a></li>
-	<li><a href="test/src-en.html">Sample contextual search page</a></li>
-	<li><a href="test/srb-fr.html" hreflang="fr" lang="fr">Exemple de page de résultats de la recherche (base)</a></li>
-	<li><a href="test/sra-fr.html" hreflang="fr" lang="fr">Exemple de page de résultats de la recherche (avancée)</a></li>
-	<li><a href="test/src-fr.html" hreflang="fr" lang="fr">Exemple de page de résultats de la recherche (contextuelle)</a></li>
+	<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/tpl-en.html">Search page with custom summary and results templates</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/tpl-fr.html" hreflang="fr" lang="fr">Page de recherche avec gabarits de résumé et résultats personnalisés</a></li>
 </ul>
+
+<p>Please <a href="https://github.com/ServiceCanada/search-ui">refer to the README documentation</a> to get more information on the GC Search UI.</p>