Merge pull request #49 from podium-lib/include-exclude

docs: api docs for new feature in client

Author: wkillerud

docs/api/layout.md

@@ -1705,15 +1705,34 @@ 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 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                                                                                     |
+| 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).              |
+| excludeBy | `object`  |         |          | Lets you define a set of rules where a `fetch` call will not be resolved if it matches.                                                                      |
+| includeBy | `object`  |         |          | Inverse of `excludeBy`. Setting both at the same time will throw.                                                                                            |
+
+##### `excludeBy` and `includeBy`
+
+These options are used by `fetch` to conditionally skip fetching the podlet content based on values on the request. It's an alternative to conditionally fetching podlets in your request handler. Setting both at the same time will throw.
+
+Example: exclude a header and footer in a hybrid web view.
+
+```js
+import Client from "@podium/client";
+const client = new Client();
+
+const footer = client.register({
+  uri: "http://footer.site.com/manifest.json",
+  name: "footer",
+  excludeBy: {
+    deviceType: ["hybrid-ios", "hybrid-android"], // when footer.fetch(incoming) is called, if the incoming request has the header `x-podium-device-type: hybrid-ios`, `fetch` will return an empty response.
+  },
+});
+```
 
 ### .client.refreshManifests()