update DESIGN doc with new token features

packages/electrode-react-webapp/DESIGN.md

@@ -14,11 +14,73 @@ The design of the rendering flow took the following into consideration.
 
 ## Tokens
 
-Within the HTML file, special tokens can be specified with `<!--%{token}-->`.
+- Within the HTML file, special tokens can be specified with `<!--%{token}-->`.
 
-- Where `token` is the string referring to a token or name of a processor module.
+  - Where `token` is the string referring to a token or name of a processor module.
 
-- To specify a processor module, start the token with `#`. ie: `<!--%{#module_name}-->`, where `module_name` specifies a name for a [Custom Processor Module](#custom-processor-module). The module will be loaded with `require`. If the `module_name` starts with `.`, then the module is loaded from CWD. For example, `<!--${#./lib/custom}-->` will load the module `./lib/custom` from under CWD.
+  - To specify a processor module, start the token with `#`. ie: `<!--%{#module_name}-->`, where `module_name` specifies a name for a [Custom Processor Module](#custom-processor-module). The module will be loaded with `require`. If the `module_name` starts with `.`, then the module is loaded from CWD. For example, `<!--${#./lib/custom}-->` will load the module `./lib/custom` from under CWD.
+
+  - Tokens can also be multi lines.
+
+  - Comments can be added as lines that starts with `//`.
+
+For example:
+
+```html
+<!--{
+  // my custom token
+  custom-token-name
+}-->
+```
+
+### Token Props
+
+- You can specify Key Value Pair props for your tokens in the form of `name=value`
+
+  - ie: `<!--%{my-token prop1="test" prop2=false prop3=[a, b, c]}-->`
+
+  - Prop value must be string enclode in `"` or `'`.
+
+  - Values started with `[` will be parsed with [string-array](https://www.npmjs.com/package/string-array)
+
+  - Any other values will be parsed with `JSON.parse`, so only `false`, `true`, numbers, `null`, or a stringified JSON that has absolutely no space.
+
+- If you want, you can specify a single JSON object following the token in anyway you like to act as the props object.
+
+For example:
+
+````html
+<!--{ token-with-json
+  {
+    "foo": "bar",
+    "hello": [ "world" ],
+    "test": [ 1, 2, 3, 4 ]
+  }
+}-->
+
+### `_call` Props
+
+If your token loads a custom processor module, then you can use a `_call` prop to specify the name of a function from that module to call.
+
+For example:
+
+```html
+<!--{#./my-token-module _call="setup1" }-->
+```
+
+You can also use a [string-array](https://www.npmjs.com/package/string-array) to have additional strings params passed to the function.
+
+For example:
+
+```html
+<!--{#./my-token-module _call=[setup1, [param1, param2]] }-->
+```
+
+This will call the function `setup1(context, options, a, b)` from your module like this:
+
+```js
+tokenModule.setup1(context, options, "param1", "param2")
+```
 
 ## Predefined Tokens and Handler
 
@@ -60,7 +122,7 @@ module.exports = function setup(options) {
     SSR_CONTENT: (context, [next]) => {}
   };
 };
-```
+````
 
 `options` will contain the following:
 

packages/electrode-react-webapp/README.md

@@ -2,9 +2,9 @@
 
 [![NPM version][npm-image]][npm-url] [![Dependency Status][daviddm-image]][daviddm-url] [![devDependency Status][daviddm-dev-image]][daviddm-dev-url] [![npm downloads][npm-downloads-image]][npm-downloads-url]
 
-This module helps render and serve your Electrode React application's `index.html`.  It will handle doing server side rendering and embedding all the necessary JS and CSS bundles for your application.
+This module helps render and serve your Electrode React application's `index.html`. It will handle doing server side rendering and embedding all the necessary JS and CSS bundles for your application.
 
-All the defaults are configured out of the box, but your index page is extensible.  You can specify your own index template file with the `htmlFile` option.
+All the defaults are configured out of the box, but your index page is extensible. You can specify your own index template file with the `htmlFile` option.
 
 See [design](./DESIGN.md) for details on how the template can be extended.
 
@@ -50,14 +50,12 @@ const config = {
           }
         },
         unbundledJS: {
-          enterHead: [
-            {src: "http://cdn.com/js/lib.js"}
-          ]
+          enterHead: [{ src: "http://cdn.com/js/lib.js" }]
         }
       }
     }
   }
-}
+};
 
 require("electrode-server")(config);
 ```
@@ -88,22 +86,22 @@ The current defaults are:
 
 What you can do with the options:
 
--   `pageTitle` `(String)` The value to be shown in the browser's title bar
--   `webpackDev` `(Boolean)` whether to use webpack-dev-server's URLs for retrieving CSS and JS bundles.
--   `serverSideRendering` `(Boolean)` Toggle server-side rendering.
--   `htmlFile` `(String)` Absolute or relative path to the application root html file.
--   `paths` `(Object)` An object of key/value pairs specifying paths within your application with their view and (optionally) initial content for server-side render
-    -   _path_ `(Object)`
-        -   `htmlFile` `(String)` Name of the view file to be used for this path **optional**
-        -   `content` Content to be rendered by the server when server-side rendering is used _optional_ [see details](#content-details)
--   `unbundledJS` (Object) Specify JavaScript files to be loaded at an available extension point in the index template
-    -   `enterHead` (Array) Array of script objects (`{ src: "path to file" }`) to be inserted as `<script>` tags in the document `head` before anything else. To load scripts asynchronously use `{ src: "...", async: true }` or `{ src: "...", defer: true }`
-    -   `preBundle` (Array) Array of script objects (`{ src: "path to file" }`) to be inserted as `<script>` tags in the document `body` before the application's bundled JavaScript
--   `devServer` `(Object)` Options for webpack's DevServer
-    -   `host` `(String)` The host that webpack-dev-server runs on
-    -   `port` `(String)` The port that webpack-dev-server runs on
--   `prodBundleBase` `(String)` Base path to locate the JavaScript, CSS and manifest bundles. Defaults to "/js/". Should end with "/".
--   `cspNonceValue` `(Function|Object|undefined)` Used to retrieve a CSP nonce value. If this is a function it will be passed the request and the nonce type (`'script'` or `'style'`), and must return the corresponding nonce. If this is an object, it may have properties `script`, `style` or both, and the value for each should be the path from the request object to the nonce value (For example, if you have a hapi plugin that puts a nonce value at `request.plugins.myCspGenerator.nonce` you might set `cspNonceValue` to `{ script: 'plugins.myCspGenerator.nonce' }`).  The nonce, if present, will be included on any `script` or `style` elements that directly contain scripts or style (e.g. any SSR preloaded state). If this property is undefined, or if the value at that location is undefined, no nonce will be added.
+- `pageTitle` `(String)` The value to be shown in the browser's title bar
+- `webpackDev` `(Boolean)` whether to use webpack-dev-server's URLs for retrieving CSS and JS bundles.
+- `serverSideRendering` `(Boolean)` Toggle server-side rendering.
+- `htmlFile` `(String)` Absolute or relative path to the application root html file.
+- `paths` `(Object)` An object of key/value pairs specifying paths within your application with their view and (optionally) initial content for server-side render
+  - _path_ `(Object)`
+    - `htmlFile` `(String)` Name of the view file to be used for this path **optional**
+    - `content` Content to be rendered by the server when server-side rendering is used _optional_ [see details](#content-details)
+- `unbundledJS` (Object) Specify JavaScript files to be loaded at an available extension point in the index template
+  - `enterHead` (Array) Array of script objects (`{ src: "path to file" }`) to be inserted as `<script>` tags in the document `head` before anything else. To load scripts asynchronously use `{ src: "...", async: true }` or `{ src: "...", defer: true }`
+  - `preBundle` (Array) Array of script objects (`{ src: "path to file" }`) to be inserted as `<script>` tags in the document `body` before the application's bundled JavaScript
+- `devServer` `(Object)` Options for webpack's DevServer
+  - `host` `(String)` The host that webpack-dev-server runs on
+  - `port` `(String)` The port that webpack-dev-server runs on
+- `prodBundleBase` `(String)` Base path to locate the JavaScript, CSS and manifest bundles. Defaults to "/js/". Should end with "/".
+- `cspNonceValue` `(Function|Object|undefined)` Used to retrieve a CSP nonce value. If this is a function it will be passed the request and the nonce type (`'script'` or `'style'`), and must return the corresponding nonce. If this is an object, it may have properties `script`, `style` or both, and the value for each should be the path from the request object to the nonce value (For example, if you have a hapi plugin that puts a nonce value at `request.plugins.myCspGenerator.nonce` you might set `cspNonceValue` to `{ script: 'plugins.myCspGenerator.nonce' }`). The nonce, if present, will be included on any `script` or `style` elements that directly contain scripts or style (e.g. any SSR preloaded state). If this property is undefined, or if the value at that location is undefined, no nonce will be added.
 
 ### `htmlFile` view details
 
@@ -113,18 +111,18 @@ Also each _path_ can specify the same option to override the top level one.
 
 This option specifies the view template for rendering your path's HTML output.
 
--   If it's `undefined`, then the built-in `index.html` view template is used.
+- If it's `undefined`, then the built-in `index.html` view template is used.
 
--   If it's a string, then it must point to a valid view template file.
-    -   If it's not an absolute path, then `process.cwd()` is prepended.
+- If it's a string, then it must point to a valid view template file.
+  - If it's not an absolute path, then `process.cwd()` is prepended.
 
 You can see this module's [build-in index.html](./lib/index.html) for details on how to create your own view template.
 
 See [design doc](./DESIGN.md) for details on extending the template.
 
 ### Content details
 
-The content you specify for your path is the entry to your React application when doing Server Side Rendering.  Ultimately, a `string` should be acquired from the content and will replace the `SSR_CONTENT` marker in the view.
+The content you specify for your path is the entry to your React application when doing Server Side Rendering. Ultimately, a `string` should be acquired from the content and will replace the `SSR_CONTENT` marker in the view.
 
 It can be a string, a function, or an object.
 
@@ -150,11 +148,11 @@ In an Electrode app, the module `electrode-redux-router-engine` and its `render`
 
 #### `object`
 
-If it's an object, it can specify a `module` field which is the name of a module that will be `require`ed.  The module should export either a string or a function as specified above.
+If it's an object, it can specify a `module` field which is the name of a module that will be `require`ed. The module should export either a string or a function as specified above.
 
 ### Disabling SSR
 
-If you don't want any Server Side Rendering at all, you can set the option `serverSideRendering` to `false`, and you can skip setting `content`.  This will make the server to **not** even load your React app.
+If you don't want any Server Side Rendering at all, you can set the option `serverSideRendering` to `false`, and you can skip setting `content`. This will make the server to **not** even load your React app.
 
 For example:
 
@@ -168,9 +166,7 @@ const config = {
           "/{args*}": {}
         },
         unbundledJS: {
-          enterHead: [
-            {src: "http://cdn.com/js/lib.js"}
-          ]
+          enterHead: [{ src: "http://cdn.com/js/lib.js" }]
         },
         serverSideRendering: false
       }
@@ -180,18 +176,10 @@ const config = {
 ```
 
 [npm-image]: https://badge.fury.io/js/electrode-react-webapp.svg
-
 [npm-url]: https://npmjs.org/package/electrode-react-webapp
-
 [daviddm-image]: https://david-dm.org/electrode-io/electrode/status.svg?path=packages/electrode-react-webapp
-
 [daviddm-url]: https://david-dm.org/electrode-io/electrode?path=packages/electrode-react-webapp
-
 [daviddm-dev-image]: https://david-dm.org/electrode-io/electrode/dev-status.svg?path=packages/electrode-react-webapp
-
 [daviddm-dev-url]: https://david-dm.org/electrode-io/electrode?path=packages/electrode-react-webapp?type-dev
-
 [npm-downloads-image]: https://img.shields.io/npm/dm/electrode-react-webapp.svg
-
 [npm-downloads-url]: https://www.npmjs.com/package/electrode-react-webapp
-