docs: update docs wrt to language updates #1628

JanssenProject · Jun 29, 2022 · ca32bd5 · ca32bd5
1 parent 04a3a86
commit ca32bd5
Show file tree

Hide file tree

Showing 9 changed files with 45 additions and 13 deletions.
diff --git a/agama/misc/template.ftlh b/agama/misc/template.ftlh
@@ -1,9 +1,8 @@
 <#macro root pageTitle="">
 
-<!DOCTYPE html>
+<!doctype html>
 <html>
     <head>
-        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 		<meta name="viewport" content="width=device-width, initial-scale=1">
 		<#if pageTitle?length gt 0><title>${pageTitle}</title></#if>
 		<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet"

diff --git a/docs/agama/dsl-full.md b/docs/agama/dsl-full.md
@@ -407,6 +407,16 @@ Finish it
 	<tr>
 <td>
 
+```
+Finish "as9233Qz"
+```
+
+</td>
+		<td>Shorthand for <code>{ success: true, data: { userId: "as9233Qz" } }</code></td>
+	</tr>
+	<tr>
+<td>
+
 ```
 it = { nonsense: [ null ] }
 Finish it.nonsense
@@ -820,6 +830,18 @@ Call p2 translate -1 1
 	<tr>
 <td>
 
+```
+cls1 = Call java.lang.CharSequence#class
+cls2 = Call java.lang.Integer#class
+Call cls2 parseInt "FF" 16
+```
+
+</td>
+		<td>Stores in <code>cls1</code> a reference to interface class <code>CharSequence.class</code>.<br/>Stores in <code>cls2</code> a reference to <code>Integer.class</code>.<br/>The 3rd line statement achieves the same effect of <code>Call java.lang.Integer#parseInt "FF" 16</code></td>
+	</tr>
+	<tr>
+<td>
+
 ```
 L = [ "A", "B", "C" ]
 S = Call java.util.Set#of 0 2 4 6

diff --git a/docs/agama/dsl.md b/docs/agama/dsl.md
@@ -198,6 +198,16 @@ Finish it
 </td>
 		<td>Flow failed. Error description attached</td>
 	</tr>
+	<tr>
+<td>
+
+```
+Finish "as9233Qz"
+```
+
+</td>
+		<td>Shorthand for <code>{ success: true, data: { userId: "as9233Qz" } }</code></td>
+	</tr>
 </table>
 
 <!--

diff --git a/docs/agama/faq.md b/docs/agama/faq.md
@@ -13,7 +13,7 @@ A Java invocation of the form `Call package.className#new ...` is passing a numb
 
 ### Unable to find a method called ... with arity ... in class ...
 
-A java invocation is attempting to call a method that is not part of the given class or the number of parameters passed for the method is not correct. 
+A java invocation is attempting to call a method that is not part of the given class or the number of parameters passed for the method is not correct.
 
 ## Classes added on the fly
 

diff --git a/docs/agama/flows-lifecycle.md b/docs/agama/flows-lifecycle.md
@@ -21,7 +21,7 @@ Additionally, the engine by default sends responses with proper HTTP headers so
 
 ## Finishing flows
 
-Carefully decide how use the [`Finish`](./dsl-full.md#flow-finish) directive in a flow. Specially when terminating sucessfully, many times developers would like to attach the identity of the user in question, like `{ success: true, data: { userId: ... } }`. This results in a successful authentication event and makes sense, but this is not always desired. Sometimes due to decomposition practices (in order to favor re-use and better organization), small flows can arise that should not carry the `userId`.
+Carefully decide how use the [`Finish`](./dsl-full.md#flow-finish) directive in a flow. Specially when terminating sucessfully, many times developers would like to attach the identity of the user in question, as in `Finish userId`. This results in a successful authentication event and makes sense, but this is not always desired. Sometimes due to decomposition practices (in order to favor re-use and better organization), small flows can arise that should not carry the user identifier.
 
 As an example, suppose several flows exist for OTP (one-time passcode) authentication, like SMS, e-mail, token-based, etc. These would receive the user identifier as an input and act accordingly by verifying the passcode the user has entered at the browser. A parent flow can be used to prompt for a username and password first, and then forward the user to the OTP flow that better matches the user's preferences. This sounds fine, however, since any flow can be triggered by means of an authentication request, a skilled individual might try to launch one of the OTP flows directly passing proper parameters. This would result in authentications using a single factor (i.e. no password) which is undesirable.   
 

diff --git a/docs/agama/hello_world.png b/docs/agama/hello_world.png
diff --git a/docs/agama/quick-start.md b/docs/agama/quick-start.md
@@ -74,15 +74,13 @@ A line-by-line description follows:
 
 - Line 6: RRF is used to send a response to the user's browser: it takes the path to a template (`hello/index.ftlh`) and injects a value into it (`in` in this case). The produced (**R**endered) markup is sent (**R**eplied) to the browser. Finally, the result of the interaction of the user with the page can be retrieved (**F**etched), however, this is skipped here because we are no capturing anything at the client side.
 
-- The contents of [index.ftlh](TODO) should be familiar to web developers. The `${...}` notation is used to dynamically insert values in the markup: the text `John` in this case. Expressions like this are integral part of Freemarker. Once form submission occurs, flow execution continues at line 8.       
+- The contents of [index.ftlh](TODO) should be familiar to web developers. The `${...}` notation is used to dynamically insert values in the markup: the text `John` in this case. Expressions like this are integral part of Freemarker. Once form submission occurs, flow execution continues at line 8.
 
-- Line 8: another assignment to a map variable. `true` denotes the boolean value all coders know.
+- Line 8: a logging statement. This appends the text `Done!` to the flow's log. The `Log` instruction is pretty versatile; it is used in its simplest form here.
 
-- Line 9: a logging statement. This appends the text `Done!` to the flow's log. The `Log` instruction is pretty versatile; it is used in its simplest form here.
+- Line 9: marks the flow ending. `Finish` has several forms but here a shorthand notation is used where we always report a positive success and supply the identifier of a user. If it turns out your local user database contains a user identified by `john_doe`, this will be the subject that will get authenticated by the server, otherwise an error page will be shown.
 
-- Line 10: marks the flow ending. `Finish` generally has to be supplied a map (`outcome` in this case) with at least a key named `success` whose value is boolean. Here we always report a positive success (unrealistic for sure). Additionally in a key named `data` a `userId` is supplied. If it turns out your local user database contains a user identified by `john_doe`, this will be the subject that will get authenticated by the server, otherwise an error page will be shown.
-
-This flow is extremely static but showcases minimal key elements for flow building. Please **do not** try this flow in any of your production servers.
+This flow is extremely static and unrealistic but showcases minimal key elements for flow building. Please **do not** try this flow in any of your production servers.
 
 ### Add the flow to the server
 
@@ -108,7 +106,7 @@ Let's start by changing the salutation. (TODO)
 
 Generate an authentication request again and launch it. You will be able to see the changes. Feel free to edit `index.ftlh` and re-upload - templates changes are picked up immediately.
 
-Now pick an existing username from your user base and alter the flow's code so that such user gets authenticated. Edit line 8. (TODO)
+Now pick an existing username from your user base and alter the flow's code so that such user gets authenticated. Edit line 9. (TODO)
 
 If things went fine, after the form submission your browser should have been taken to the `redirect_uri` defined for the authentication request. Depending on how evolved your client application is, it may have created a session for such user and obtained profile data already!.
 

diff --git a/docs/agama/test b/docs/agama/test
@@ -5,6 +5,5 @@ Flow test
 in = { name: "John" }
 RRF "index.ftlh" in
 
-outcome = { success: true, data: { userId: "john_doe" } }
 Log "Done!"
-Finish outcome
+Finish "john_doe"
diff --git a/docs/agama/ui-pages.md b/docs/agama/ui-pages.md
@@ -23,6 +23,10 @@ In agama, every template is generally "injected" some data, see [RRF](./dsl.md#r
 
 - `msgs`. It gives access to the localized messages of jans-auth application. Some developers might know this as the "internationalization labels" or "resource bundle" of an application. This is a collection of `.properties` files where common UI-related messages in different languages can be found. A message (label) is identified by a key, so in a template `${msgs.<KEY>}` could be used. As most keys in resource bundles have dot characters, the alternative notation `${webCtx["KEY"]}` works better for FreeMarker, for example `${msgs["login.errorMessage"]}`.
 
+## Output encoding
+
+The character encoding of the response sent to browser is by default `UTF-8`. To specify a different encoding the `ftl` directive can be used, for instance, `<#ftl encoding="ISO-8859-5">`. Place this at the top of the template. 
+
 ## Reusable templates
 
 A widespread practice in web page authoring is to compose pages based on reusable pieces. As an example, the need for a common header and footer is ubiquitous in HTML projects. With FreeMarker composition can be achieved by means of [macros](https://freemarker.apache.org/docs/ref_directive_macro.html). These are the equivalent to functions in programming, they can generate output based on parameters passed and can be called anywhere in a template.