From 62971e17f9f1814e38b31713e4e71a81a6540e99 Mon Sep 17 00:00:00 2001 From: Joel Chen Date: Thu, 14 Jun 2018 16:40:42 -0700 Subject: [PATCH] update DESIGN doc with new token features --- packages/electrode-react-webapp/DESIGN.md | 70 +++++++++++++++++++++-- packages/electrode-react-webapp/README.md | 66 +++++++++------------ 2 files changed, 93 insertions(+), 43 deletions(-) diff --git a/packages/electrode-react-webapp/DESIGN.md b/packages/electrode-react-webapp/DESIGN.md index b68223220a..01d058d024 100644 --- a/packages/electrode-react-webapp/DESIGN.md +++ b/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 ``. +- Within the HTML file, special tokens can be specified with ``. -- 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: ``, 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, `` will load the module `./lib/custom` from under CWD. + - To specify a processor module, start the token with `#`. ie: ``, 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, `` 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 + +``` + +### Token Props + +- You can specify Key Value Pair props for your tokens in the form of `name=value` + + - ie: `` + + - String 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 + + +### `_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 + +``` + +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 + +``` + +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: diff --git a/packages/electrode-react-webapp/README.md b/packages/electrode-react-webapp/README.md index d91e08960c..bd170ccb09 100644 --- a/packages/electrode-react-webapp/README.md +++ b/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 `