Merge pull request #738 from brucejo75/brucejo75/hookRuntimeConfig

Document addRuntimeConfigHook

Author: StorytellerCZ

source/packages/webapp.md

@@ -25,26 +25,8 @@ WebApp.connectHandlers.use('/hello', (req, res, next) => {
 });
 ```
 
-`WebApp.connectHandlers.use([path], handler)` has two arguments:
-
-**path** - an optional path field.
-This handler will only be called on paths that match
-
-this string. The match has to border on a `/` or a `.`. For example, `/hello`
-will match `/hello/world` and `/hello.world`, but not `/hello_world`.
-
-**handler** - this is a function that takes three arguments:
-
-- **req** - a Node.js
-[IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
-object with some extra properties. This argument can be used to get information
-about the incoming request.
-- **res** - a Node.js
-[ServerResponse](http://nodejs.org/api/http.html#http_class_http_serverresponse)
-object. Use this to write data that should be sent in response to the
-request, and call `res.end()` when you are done.
-- **next** - a function. Calling this function will pass on the handling of
-this request to the next relevant handler.
+{% apibox "WebApp.connectHandlers" %}
+{% apibox "connectHandlersCallback(req, res, next)" %}
 
 ### Serving a Static Landing Page
 
@@ -119,3 +101,62 @@ We're reading the contents of index.html using the [Assets](https://docs.meteor.
 We're using the [connect-route](https://www.npmjs.com/package/connect-route) NPM package to simplify WebApp route processing. But you can use any package you want to understand what is being requested.
 
 And finally, if you decide to use this technique you'll want to make sure you understand how conflicting client side routing will affect user experience.
+
+### Dynamic Runtime Configuration
+
+In some cases it is valuable to be able to control the __meteor_runtime_config__ variable that initializes Meteor at runtime.
+
+#### Example
+There are occasions when a single Meteor server would like to serve multiple cordova applications that each have a unique `ROOT_URL`.  But there are 2 problems:
+1. The Meteor server can only be configured to serve a single `ROOT_URL`.
+2. The `cordova` applications are build time configured with a specific `ROOT_URL`.
+
+These 2 conditions break `autoupdate` for the cordova applications. `cordova-plugin-meteor-webapp` will fail the update if the `ROOT_URL` from the server does not match the build time configured `ROOT_URL` of the cordova application.
+
+To remedy this problem `webapp` has a hook for dynamically configuring `__meteor_runtime_config__` on the server.
+
+#### Dynamic Runtime Configuration Hook
+```js
+WebApp.addRuntimeConfigHook(({arch, request, encodedCurrentConfig, updated}) => {
+ // check the request to see if this is a request that requires
+ // modifying the runtime configuration
+  if(request.headers.domain === 'calling.domain') {
+    // make changes to the config for this domain
+    // decode the current runtime config string into an object
+    const config = WebApp.decodeRuntimeConfig(current);
+    // make your changes
+    config.newVar = 'some value';
+    config.oldVar = 'new value';
+    // encode the modified object to the runtime config string
+    // and return it
+    return WebApp.encodeRuntimeConfig(config);
+  }
+  // Not modifying other domains so return undefined
+  return undefined;
+})
+```
+{% apibox "WebApp.addRuntimeConfigHook" %}
+{% apibox "addRuntimeConfigHookCallback(options)" %}
+
+Additionally, 2 helper functions are available to decode the runtime config string and encode the runtime config object.
+
+{% apibox "WebApp.decodeRuntimeConfig" %}
+{% apibox "WebApp.encodeRuntimeConfig" %}
+
+### Updated Runtime Configuration Hook
+```js
+const autoupdateCache;
+// Get a notification when the runtime configuration is updated
+// for each arch
+WebApp.addUpdatedNotifyHook(({arch, manifest, runtimeConfig}) => {
+  // Example, see if runtimeConfig.autoupdate has changed and if so
+  // do something
+  if(!_.isEqual(autoupdateCache, runtimeConfig.autoupdate)) {
+    autoupdateCache = runtimeConfig.autoupdate;
+    // do something...
+  }
+})
+```
+
+{% apibox "WebApp.addUpdatedNotifyHook" %}
+{% apibox "addUpdatedNotifyHookCallback(options)" %}