From cb2cef0fc8729dd61767718d1f23df5250a720d9 Mon Sep 17 00:00:00 2001
From: Graham Dumpleton <Graham.Dumpleton@gmail.com>
Date: Thu, 22 Aug 2024 14:09:14 +1000
Subject: [PATCH] Add more details on redirections and notifications.

---
 .../exercises/htdocs/javascript-redirect.html |  5 +-
 .../content/10-browser-redirection.md         |  6 +--
 .../workshop/content/11-iframe-redirection.md |  4 +-
 .../workshop/content/12-iframe-vs-window.md   |  6 +--
 .../content/13-javascript-redirect.md         |  4 +-
 .../content/14-event-notifications.md         | 53 +++++++++++++++++++
 .../workshop/content/99-workshop-summary.md   |  4 +-
 7 files changed, 68 insertions(+), 14 deletions(-)
 create mode 100644 workshops/lab-lookup-consumption/workshop/content/14-event-notifications.md

diff --git a/workshops/lab-lookup-consumption/exercises/htdocs/javascript-redirect.html b/workshops/lab-lookup-consumption/exercises/htdocs/javascript-redirect.html
index 8a1c316..950b4dc 100644
--- a/workshops/lab-lookup-consumption/exercises/htdocs/javascript-redirect.html
+++ b/workshops/lab-lookup-consumption/exercises/htdocs/javascript-redirect.html
@@ -7,6 +7,7 @@
     <script>
         function redirectToTarget() {
             var target = new URLSearchParams(window.location.search).get('target');
+            var notification = new URLSearchParams(window.location.search).get('notification');
             if (target) {
                 try {
                     window.top.location.href = target;
@@ -19,8 +20,8 @@
     </script>
 
     <h1>Redirect Page</h1>
-    <p id="redirectMessage">Redirection failed. Please click the button below to redirect.</p>
-    <button id="redirectButton" onclick="redirectToTarget()">Redirect</button>
+    <p id="redirectMessage" style="display: none;">Redirection failed. Please click the button below to redirect.</p>
+    <button id="redirectButton" style="display: none;" onclick="redirectToTarget()">Redirect</button>
 
     <script>
         redirectToTarget();
diff --git a/workshops/lab-lookup-consumption/workshop/content/10-browser-redirection.md b/workshops/lab-lookup-consumption/workshop/content/10-browser-redirection.md
index 83678d8..e475b27 100644
--- a/workshops/lab-lookup-consumption/workshop/content/10-browser-redirection.md
+++ b/workshops/lab-lookup-consumption/workshop/content/10-browser-redirection.md
@@ -40,9 +40,9 @@ embedded Javascript to close the browser page, however it is possible a browser
 may block this and only allow a browser page to be closed from the same source
 that originally opened the browser page to begin with.
 
-A third and final option is to still attempt to automatically close the browser
-page where a browser allows it, but otherwise display a message thanking the
-user for doing the workshop and telling them it is now safe to close their
+A third and final option is thus to still attempt to automatically close the
+browser page where a browser allows it, but otherwise display a message thanking
+the user for doing the workshop and telling them it is now safe to close their
 browser page.
 
 You can test out how your browser behaves by ensuring you have terminated any
diff --git a/workshops/lab-lookup-consumption/workshop/content/11-iframe-redirection.md b/workshops/lab-lookup-consumption/workshop/content/11-iframe-redirection.md
index 0a19a5a..1ba5398 100644
--- a/workshops/lab-lookup-consumption/workshop/content/11-iframe-redirection.md
+++ b/workshops/lab-lookup-consumption/workshop/content/11-iframe-redirection.md
@@ -2,11 +2,11 @@
 title: IFrame Redirection
 ---
 
-The issue of `iframe` redirection arises where instead of a custom front end web
+The issue of iframe redirection arises where instead of a custom front end web
 portal popping out a workshop session into a new browser window, it embeds the
 workshop session dashboard within another web page.
 
-To demonstrate what is meant here, run the following command to created a web
+To demonstrate what is meant here, run the following command to create a web
 page which embeds the workshop session dashboard returned when a workshop is
 requested.
 
diff --git a/workshops/lab-lookup-consumption/workshop/content/12-iframe-vs-window.md b/workshops/lab-lookup-consumption/workshop/content/12-iframe-vs-window.md
index 938bba8..c3e09be 100644
--- a/workshops/lab-lookup-consumption/workshop/content/12-iframe-vs-window.md
+++ b/workshops/lab-lookup-consumption/workshop/content/12-iframe-vs-window.md
@@ -15,9 +15,9 @@ popup windows is pressed, it uses Javascript running in the web browser to
 override the target URL for the top most HTML frame displayed by the web
 browser.
 
-If you terminate the workshop session you started demonstrating where it was
-embedded, you should see this as rather than the result being nested, the whole
-browser window is correctly redirected to the target web site.
+When you terminated the workshop session you started to demonstrate embedding,
+you should have seen this rather than the result being nested, as the whole
+browser window should have been correctly redirected to the target web site.
 
 So under normal circumstances everything works fine and as one would expect.
 Because though interaction with the workshop session dashboard is part mediated
diff --git a/workshops/lab-lookup-consumption/workshop/content/13-javascript-redirect.md b/workshops/lab-lookup-consumption/workshop/content/13-javascript-redirect.md
index 9f373cd..a40dce2 100644
--- a/workshops/lab-lookup-consumption/workshop/content/13-javascript-redirect.md
+++ b/workshops/lab-lookup-consumption/workshop/content/13-javascript-redirect.md
@@ -2,8 +2,8 @@
 title: Javascript Redirect
 ---
 
-Although we noted that some web browsers may place restrictions on when
-automatically run Javascript can trigger a redirection, it is recommended that
+Although we noted that some web browsers may place restrictions on when one can
+automatically run Javascript to trigger a redirection, it is recommended that
 when specifying `clientIndexUrl` with a workshop request, that instead of
 passing the URL for where you ultimately what the user redirected, that you pass
 a URL which targets a special URL handler or web page, which attempts to force
diff --git a/workshops/lab-lookup-consumption/workshop/content/14-event-notifications.md b/workshops/lab-lookup-consumption/workshop/content/14-event-notifications.md
new file mode 100644
index 0000000..25e57d7
--- /dev/null
+++ b/workshops/lab-lookup-consumption/workshop/content/14-event-notifications.md
@@ -0,0 +1,53 @@
+---
+title: Event Notifications
+---
+
+You may have noticed when the redirection happened upon terminating a workshop
+session, that the URL displayed in the web browser for the target URL had a
+query string parameter appended with parameter name `notification`.
+
+When using the native web interface for the training portal, this is passed
+so that the web interface can display a message banner.
+
+The possible values of this query string parameter will be:
+
+* `session-deleted` - Used when the workshop session was completed or restarted.
+* `startup-timeout` - Used when a startup timeout was specified for a workshop
+  and it didn’t start within the required time.
+* `session-invalid` - Used when an attempt is made to access a session which
+  doesn’t exist. This can occur when the workshop dashboard is refreshed
+  sometime after the workshop session has expired and been deleted.
+
+Other values exist for `notification`, but it is believed these situations
+should not arise when the REST API is used to request a workshop as HTTP errors
+would be returned by the REST API call instead. 
+
+* `workshop-invalid` - Used when the name of the workshop environment supplied
+  when attempting to create the workshop was invalid.
+* `session-unavailable` - Used when capacity has been reached and a workshop
+  session cannot be created.
+
+These other possible values are thus listed here only for informational
+purposes, in case they occur for some unknown reason.
+
+For the cases when a notification message is supplied in this way, it will be
+added to the query string parameters passed to the URL when redirection is done.
+The URL handler or web page can use this to display it's own message banner. It
+may also want to rewrite the URL shown in the URL bar of the browser to remove
+the notification query string parameter to avoid it being added as part of a
+bookmark by a user.
+
+{{< warning >}} Note that there is currently a
+[bug](https://github.com/vmware-tanzu-labs/educates-training-platform/issues/558)
+in the training portal, whereby if the URL passed to `clientIndexUrl` has its
+own query string parameters, the query string parameter list including
+`notification` is blindly added to the end of the full URL, rather than parsing
+the URL to separate out any query string parameters and adding to the set of
+parameters and reconstructing the URL. This means that if the last query string
+parameter was itself a URL, the notification parameter is being added to it,
+rather than the initially targeted URL. This means that a URL handler as
+previously shown for handling redirection, will need to remove the notification
+query string parameter from the target redirection URL. This issue will be fixed
+in an upcoming update to Educates, and this workshop updated further to explain
+how to handle these notifications.
+{{< /warning >}}
diff --git a/workshops/lab-lookup-consumption/workshop/content/99-workshop-summary.md b/workshops/lab-lookup-consumption/workshop/content/99-workshop-summary.md
index f1a08b8..5204c34 100644
--- a/workshops/lab-lookup-consumption/workshop/content/99-workshop-summary.md
+++ b/workshops/lab-lookup-consumption/workshop/content/99-workshop-summary.md
@@ -3,8 +3,8 @@ title: Workshop Summary
 ---
 
 {{< danger title="More Coming Soon" >}}
-This workshop is still in the process of being completed. Check back soon for
-further updates.
+This workshop is still in the process of being polished and further changes
+may be made. Check back soon for further updates.
 {{< /danger >}}
 
 You have reached the end of this workshop on using the Educates lookup service.