Merge pull request #45 from podium-lib/more-restructuring

refactor: collect guides in one category and fix link warnings

Author: wkillerud

blog/2019-08-19-version-4.2.0.md

@@ -46,10 +46,10 @@ will translate into the following HTML element:
 Please see the following documentation for the options the different methods
 can now take:
 
- * @podium/podlet [`.css()`](/docs/api/podlet#cssoptions-options) method
- * @podium/podlet [`.js()`](/docs/api/podlet#jsoptions-options) method
- * @podium/layout [`.css()`](/docs/api/layout#cssoptions-options) method
- * @podium/layout [`.js()`](/docs/api/layout#jsoptions-options) method
+- @podium/podlet [`.css()`](/docs/api/podlet#cssoptionsoptions) method
+- @podium/podlet [`.js()`](/docs/api/podlet#jsoptionsoptions) method
+- @podium/layout [`.css()`](/docs/api/layout#cssoptionsoptions) method
+- @podium/layout [`.js()`](/docs/api/layout#jsoptionsoptions) method
 
 For further information on how assets are handled in general, please see the
 [asset section](/docs/api/assets).

docs/api/layout.md

@@ -1705,15 +1705,15 @@ layout.client.fooBar.fetch();
 
 #### options (required)
 
-| option     | type      | default | required | details                                                                                                                                                                        |
-| ---------- | --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| uri        | `string`  |         | ✓  | Uri to the manifest of a podlet                                                                                                                                                |
-| name       | `string`  |         | ✓  | Name of the component. This is used to reference the component in your application, and does not have to match the name of the component itself                                |
-| retries    | `number`  | `4`     |          | The number of times the client should retry to settle a version number conflict before terminating. Overrides the `retries` option in the layout constructor                   |
-| timeout    | `number`  | `1000`  |          | Defines how long, in milliseconds, a request should wait before the connection is terminated. Overrides the `timeout` option in the layout constructor                         |
-| throwable  | `boolean` | `false` |          | Defines whether an error should be thrown if a failure occurs during the process of fetching a podlet. [See handling podlet unavailability](../layout/unavailable_podlets.md). |
-| resolveJs  | `boolean` | `false` |          | Defines whether to resolve relative URIs to absolute URIs for JavaScript assets                                                                                                |
-| resolveCss | `boolean` | `false` |          | Defines whether to resolve relative URIs to absolute URIs for CSS assets                                                                                                       |
+| option     | type      | default | required | details                                                                                                                                                      |
+| ---------- | --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| uri        | `string`  |         | ✓  | Uri to the manifest of a podlet                                                                                                                              |
+| name       | `string`  |         | ✓  | Name of the component. This is used to reference the component in your application, and does not have to match the name of the component itself              |
+| retries    | `number`  | `4`     |          | The number of times the client should retry to settle a version number conflict before terminating. Overrides the `retries` option in the layout constructor |
+| timeout    | `number`  | `1000`  |          | Defines how long, in milliseconds, a request should wait before the connection is terminated. Overrides the `timeout` option in the layout constructor       |
+| throwable  | `boolean` | `false` |          | Defines whether an error should be thrown if a failure occurs during the process of fetching a podlet. [See Fallbacks](/docs/guides/fallbacks).              |
+| resolveJs  | `boolean` | `false` |          | Defines whether to resolve relative URIs to absolute URIs for JavaScript assets                                                                              |
+| resolveCss | `boolean` | `false` |          | Defines whether to resolve relative URIs to absolute URIs for CSS assets                                                                                     |
 
 ### .client.refreshManifests()
 
@@ -1736,8 +1736,7 @@ await layout.client.refreshManifests();
 
 ### .client.state
 
-What state the client is in. See the section
-"[Podlet update life cycle](#podlet-update-life-cycle)" for more information.
+What state the client is in.
 
 The value will be one of the following values:
 
@@ -1753,8 +1752,7 @@ The Client instance emits the following events:
 
 #### state
 
-When there is a change in state. See the section
-"[Podlet update life cycle](#podlet-update-life-cycle)" for more information.
+When there is a change in state.
 
 ```js
 layout.client.on("state", (state) => {

docs/api/podlet.md

@@ -1711,7 +1711,7 @@ The prefix will be ignored if value is an absolute URL.
 
 Method for defining proxy targets to be mounted in a layout server. For a
 detailed overview of how proxying works, please see the
-[proxying guide](podlet/proxying.md) for further details.
+[proxying guide](/docs/guides/proxying) for further details.
 
 When a podlet is put in development mode (`development` is set to `true` in the constructor) these proxy endpoints will also be mounted in the podlet for ease of development and you will then have the same proxy endpoints available in development as you do when working with a layout.
 

docs/introduction/assets.md renamed to docs/guides/assets.md

@@ -124,7 +124,3 @@ Using the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_comp
 With `podlet.css()` the end result is a `<link />` tag in the HTML document's `<head />`. If your podlet's content renders inside a shadow DOM that CSS won't be able to reach the podlet.
 
 With a declarative shadow DOM you have to include your own `<link />` to the CSS from inside the shadow DOM.
-
-## Next steps
-
-Next you might want to familiarise yourself with the Podium context.

docs/podlet/podlet_to_podlet_communication.md renamed to docs/guides/client-side-communication.md

@@ -1,6 +1,5 @@
 ---
-id: podlet_to_podlet_communication
-title: Podlet to podlet communication in the browser
+title: Client-side communication in a Podium app
 ---
 
 Podium provides a client side library called [@podium/browser] that includes a [MessageBus](/docs/api/browser#messagebus). The message bus simplifies passing data between different podlets' client-side JavaScript.

docs/introduction/context.md renamed to docs/guides/context.md

@@ -125,10 +125,6 @@ podlet.defaults({
 });
 ```
 
-## Next steps
-
-Next you may want to look at the different guides for podlets and layouts which cover some common scenarios.
-
 [bcp47]: https://tools.ietf.org/html/bcp47
 [kebab case]: https://en.wikipedia.org/wiki/Kebab_case
 [camel case]: https://en.wikipedia.org/wiki/Camel_case

docs/podlet/fallbacks.md renamed to docs/guides/fallbacks.md

@@ -3,15 +3,15 @@ id: fallbacks
 title: Fallbacks
 ---
 
-What happens if a podlet server is down? Unresponsive? Responding too slowly? By default Podium will simply render an empty string in its place. You might, however, want to have some measure of control over what gets shown. Enter fallbacks.
+What happens to a layout if a podlet is down, unresponsive, or slow? By default the layout will render an empty string in its place. However, you might want to have control what gets shown, such as a simplified static version of a complex dynamic podlet. Fallbacks let you do this.
 
 ## How do fallbacks work?
 
 On the first request to a podlet a layout will read the podlet’s [manifest](/docs/api/manifest). The manifest includes the location of the fallback. The layout then makes a request to the fallback route and caches the response.
 
 Later, if the podlet server cannot be reached for any reason, or the request returns a non 200 response, the layout will use the podlet’s cached fallback content instead.
 
-Note that the podlet’s assets will still be served, so the fallback can depend on both JS and CSS being present once it’s rendered. This assumes the assets are hosted on a server [separate from the podlet](/docs/introduction/assets#use-a-cdn).
+Note that the podlet’s assets will still be served, so the fallback can depend on both JS and CSS being present once it’s rendered. This assumes the assets are hosted on a server [separate from the podlet](/docs/guides/assets#use-a-cdn).
 
 ## Defining a fallback route
 
@@ -55,3 +55,35 @@ const podlet = new Podlet(/*...*/);
 
 podlet.fallback("https://www.example.com/my-fallback");
 ```
+
+## Throwable podlets
+
+By default a layout will substitute a fallback (or empty string) for a podlet's content whenever the podlet either fails to respond with a 2xx status code or the podlet fails to respond within 1000 milliseconds.
+
+In some cases it may make no sense to show a page at all if some of its content is not available. You may prefer to show an error page rather than fallback content or an empty string. This is especially true for dynamic content that is the main focus of a page. If all you can show is a header and footer, it might be better to show an error page explaining the situation to the user.
+
+In order to facilitate this, it is possible to set a podlet as `throwable` when it is registered.
+
+```js
+const gettingStarted = layout.client.register({
+  throwable: true,
+});
+```
+
+When the layout fetch the podlet, if that podlet is not available, then the fetch will reject with an error that you can then handle as you see fit.
+
+Error objects are instances of [Boom](https://www.npmjs.com/package/@hapi/boom) errors and are decorated with the HTTP status code from the podlet response.
+
+```js
+app.get(layout.pathname(), (req, res, next) => {
+    try {
+        const content = await gettingStarted.fetch(res.locals.podium);
+    } catch(err) {
+        // you might respond to the error here
+        // res.status(err.statusCode).end();
+
+        // or pass the error on to be handled in error handling middleware
+        next(err);
+    }
+});
+```