rework readme to group content (#26)

WizardSoftware · Aug 24, 2022 · 138cdef · 138cdef
1 parent ee189f4
commit 138cdef
Showing 1 changed file with 62 additions and 45 deletions.
diff --git a/README.md b/README.md
@@ -4,45 +4,19 @@ Web-Direct Landing page for Wizard Web-Direct deployed solutions.
 
 ## Features
 
+- Land multiple interfaces on a single site across different FileMaker Servers.
 - `onbeforeunload` support.
-
-Best effort to warn users that refreshing the page, or otherwise navigating away will lose their place in the system. Support varies by browser.
-
 - Back button suppression / integration.
 
-Avoid back button taking the user out of the solution, and provide support for solutions to listen to the native browser back button and react accordingly.
-
-## Back Button Integration
-
-WebDLanding provides an opportunity for back button support to be added, by posting a message to child iframes that the back button was pressed.
+Use WebDLanding as a sort of reverse proxy for Web-Direct.
 
-A sample of the web viewer content that must be provided on each layout:
+Provide a best effort to warn users that refreshing the page, or otherwise navigating away will lose their place in the web-direct application. Note: support varies by browser.
 
-```html
-<!DOCTYPE html>
-<html lang="en">
+Avoid browser back button taking the user out of the solution. Provide support for solutions to listen to the native browser back button and react accordingly.
 
-<head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1" />
-</head>
+## FileMaker Server Setup
 
-<body></body>
-
-<script>
-    window.addEventListener("message", (d) => {
-        if (d.data === "BackButtonPressed") {
-            FileMaker.PerformScript("back_button", "");
-        }
-    });
-</script>
-
-</html>
-```
-
-## FileMaker Server Configuration for basic support
-
-Update web.config in the http server directory
+Update web.config in the FMServer Root Site `/HTTPServer/conf`:
 
 ```xml
 <add name="Content-Security-Policy" value="frame-ancestors 'self' https://*.wizardsoftware.net" />
@@ -72,9 +46,43 @@ Update the `jwpc_prefs.xml` file located in the `/Web Publishing/conf/jwpc_prefs
 
 ### Restart FileMaker Services
 
-🪟➕R => services.msc => FileMaker Server => Restart
+🪟+ R => services.msc => FileMaker Server => Restart
+
+## Back Button Integration
+
+WebDLanding captures the Browser Back Button being pressed. When that occurrs, WebDLanding uses the `postMessage` api to signal that the back button was pressed. Web Viewers inside the solution can be configured to receive this event and react accordingly.
 
-### Add postMessage forwarding script as referenced in <https://github.com/WizardSoftware/WebDLanding/issues/6>
+### Web Viewer content for each layout
+
+In order to receive this event, a web viewer must exist on the layout with the following content to receive the event posted from the parent window.
+
+A sample of the web viewer content that must be provided on each layout:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1" />
+</head>
+
+<body></body>
+
+<script>
+    window.addEventListener("message", (d) => {
+        if (d.data === "BackButtonPressed") {
+            FileMaker.PerformScript("back_button", "");
+        }
+    });
+</script>
+
+</html>
+```
+
+### Add postMessage forwarding script to out going FileMaker Web-Direct requests
+
+Because the WebDLanding uses an iframe hosted (possibly) on a different site the intermediate Web-Direct responses must be amended to include the following script to forward events from its parent, down into its children.
 
 Add the following snippet as a file named `message-forward.js` to FMServer Root Site `/HTTPServer/conf`:
 
@@ -91,24 +99,40 @@ window.addEventListener("message", d => {
 });
 ```
 
-#### Web.Config Mods
+### Web.Config Mods
+
+We need to modify the web.config in FMServer Root Site `/HTTPServer/conf` to add an extra script tag that will forward messages sent from the parent page down into the web viewers.
 
-Rewrite Section
+Update the existing inbound rule: `FMWebPublishing` adding two http server variables:
+
+```xml
+<set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="{HTTP_ACCEPT_ENCODING}" />
+<set name="HTTP_ACCEPT_ENCODING" value="" />
+```
+
+Essentially what this does, is store the original accept encoding and clear the actual accept encoding. This is necessary because the server behind the IIS Reverse Proxy uses gzip, which means we can't easily insert our script snipet.
 
 Add two new Outbound Rules
 
+For requests that had their accept encoding removed, restore it on the way back out.
+
 ```xml
 <rule name="RestoreAcceptEncoding" preCondition="NeedsRestoringAcceptEncoding">
 <match serverVariable="HTTP_ACCEPT_ENCODING" pattern="^(.*)" />
   <action type="Rewrite" value="{HTTP_X_ORIGINAL_ACCEPT_ENCODING}" />
 </rule>
+```
+
+For requests with a `</body>` tag, add our script tag to it.
+
+```xml
 <rule name="AddPostMessageForwarding" preCondition="IsHTML" patternSyntax="ExactMatch">
   <match filterByTags="None" pattern="&lt;/body>" />
   <action type="Rewrite" value="&lt;script type='text/javascript' src='/message-forward.js'>&lt;/script>&lt;/body>" />
 </rule>
 ```
 
-Add two PreConditions
+Add two PreConditions which are used by both outgoing rules.
 
 ```xml
 <preConditions>
@@ -121,14 +145,7 @@ Add two PreConditions
 </preConditions>
 ```
 
-Update the existing inbound rule: `FMWebPublishing` adding two http server variables:
-
-```xml
-<set name="HTTP_X_ORIGINAL_ACCEPT_ENCODING" value="{HTTP_ACCEPT_ENCODING}" />
-<set name="HTTP_ACCEPT_ENCODING" value="" />
-```
-
-Add both of the above variables to the allowed variables list:
+Finally add both of the above variables to the allowed variables list:
 
 ```xml
 <allowedServerVariables>