diff --git a/.npmrc b/.npmrc index 43c97e7..0ca8d2a 100644 --- a/.npmrc +++ b/.npmrc @@ -1 +1,2 @@ package-lock=false +save-exact=true diff --git a/docs/guides/browser-extension.md b/docs/guides/browser-extension.md new file mode 100644 index 0000000..6696516 --- /dev/null +++ b/docs/guides/browser-extension.md @@ -0,0 +1,34 @@ +--- +title: Browser extension +--- + +Developing layouts and podlets mostly works the same way as other web servers. Still, there are a couple of scenarios where the built-in developer tools in your browser can fall a bit short. The Podium Developer Tools browser extension can help. + +## Download the browser extension + +The Podium browser extension is available for Firefox and Chromium-based browsers. + +- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/podium-developer-tools/) +- [Chromium](https://chromewebstore.google.com/detail/podium-development-extens/jdlcejoeifgnnnckhnhapbmgieajaipl) based browsers + +## Using the browser extension + +First, you may have to allow the extension to run on the page you're debugging. In Firefox this is shown with a mark by the extensions drawer, and on the extension itself. + +![](/img/browser-extension-permissions.png) + +The extension adds two new panes to your browser's developer tools that cover two main use-cases. You may have to open an overflow menu to see them. + +![](/img/browser-extension-devtools-panes.png) + +### The Podium Context pane + +This pane is used when developing podlets to change the default values set on the [Podium context](/docs/guides/context). Say you want to test how your podlet behaves when given a different `deviceType` value. You could make changes in code, restart the server and then do your test, or you can use the extension and it's [partner middleware](https://github.com/podium-lib/dev-tool/tree/main/packages/server) to quickly swap values at runtime. + +### The Podium Headers pane + +This pane helps you set HTTP headers on requests to the server. It's mainly designed for use with Podium layouts, but can be used to set any header for any server. It comes with presets for [hybrid HTTP headers](/docs/guides/hybrid#hybrid-http-headers), but you can add and remove any headers you might need. + +## Missing a feature? + +If you have ideas for additional features that would help you develop and debug Podium applications, please [open an issue in the dev-tool repo](https://github.com/podium-lib/dev-tool/issues). If an issue allready exists, give it a thumbs-up. diff --git a/docs/guides/context.md b/docs/guides/context.md index 22632c0..a667be6 100644 --- a/docs/guides/context.md +++ b/docs/guides/context.md @@ -125,6 +125,12 @@ podlet.defaults({ }); ``` +:::tip + +Get the [browser extension](/docs/guides/browser-extension) and the accompanying [dev-tool middleware](https://github.com/podium-lib/dev-tool/tree/main/packages/server) to make it possible to change these defaults without changing code and restarting your server. + +::: + [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 diff --git a/docs/guides/hybrid.md b/docs/guides/hybrid.md index ac4dea3..f7e1a3e 100644 --- a/docs/guides/hybrid.md +++ b/docs/guides/hybrid.md @@ -14,19 +14,43 @@ Layouts and podlets need to be able to adapt to requests from a hybrid web view. ### Hybrid HTTP headers +:::tip + +Get the [browser extension](/docs/guides/browser-extension) to make it easier to set the hybrid HTTP headers when developing locally. + +::: + | Header | Example | Description | | ------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------- | | `x-podium-app-id` | `com.yourcompany.app@1.2.3` | To identify clients in logs | | `x-podium-base-font-size` | `1rem` | To set base font size variable in CSS based on accessibility settings in the native host. | | `x-podium-device-type` | `hybrid-ios`, `hybrid-android` | To give hints to the server what should be included in the response. | -| `Authorization` | `Bearer eyJhbGciOiJIU...` | Optional. Signifies a logged-in user. | -#### Podium developer tools extension +### Podium context + +Requests that include the hybrid HTTP headers have their values added to the Podium context, in addition to the [default context variables](/docs/guides/context#default-context-variables). + +| Header | Context name | Description | +| ------------------------- | -------------- | --------------------------------------------------------------------- | +| `x-podium-app-id` | `appId` | | +| `x-podium-base-font-size` | `baseFontSize` | | +| `x-podium-device-type` | `deviceType` | Overrides the value that would otherwise be derived from `User-Agent` | -Get the extension to make it easier to set these HTTP headers when developing locally: +### Conditionally fetch podlets + +In a hybrid web view setting your layout may want to exclude things like the header and footer. These are likely podlets, and Podium has an option when you register podlets to exclude them by device type. + +```js +const headerPodlet = layout.client.register({ + name: "header", + uri: "http://header/manifest.json", + excludeBy: { + deviceType: ["hybrid-ios", "hybrid-android"], + }, +}); +``` -- [Firefox](https://addons.mozilla.org/en-US/firefox/addon/podium-developer-tools/) -- [Chromium](https://chromewebstore.google.com/detail/podium-development-extens/jdlcejoeifgnnnckhnhapbmgieajaipl) based browsers +In this case, if a request has the `x-podium-device-type: hybrid-ios` HTTP header, Podium will serve an empty response to the `headerPodlet.fetch()` call. ## Client-side communcication diff --git a/docs/guides/podlet-development.md b/docs/guides/podlet-development.md index 5d2995a..c8866ad 100644 --- a/docs/guides/podlet-development.md +++ b/docs/guides/podlet-development.md @@ -99,6 +99,12 @@ podlet.defaults({ }); ``` +:::tip + +Get the [browser extension](/docs/guides/browser-extension) and the accompanying [dev-tool middleware](https://github.com/podium-lib/dev-tool/tree/main/packages/server) to make it possible to change these defaults without changing code and restarting your server. + +::: + ### HTML pages and page fragments In production, your podlet's content route will be responding with an HTML fragment devoid of its wrapping `` or `` tags. However, in development you will want to wrap your fragment in a light HTML page, especially if your podlet makes use of client side assets such as JavaScript or CSS. diff --git a/package.json b/package.json index 2cce079..dafea6a 100644 --- a/package.json +++ b/package.json @@ -14,19 +14,19 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "^3.3.2", - "@docusaurus/plugin-client-redirects": "^3.3.2", - "@docusaurus/preset-classic": "^3.3.2", - "@mdx-js/react": "^3.0.0", - "clsx": "^1.2.1", + "@docusaurus/core": "3.4.0", + "@docusaurus/plugin-client-redirects": "3.4.0", + "@docusaurus/preset-classic": "3.4.0", + "@mdx-js/react": "3.0.1", + "clsx": "2.1.1", "docusaurus-lunr-search": "3.5.0", - "prism-react-renderer": "^2.1.0", - "react": "^18.0.0", - "react-dom": "^18.0.0" + "prism-react-renderer": "2.3.1", + "react": "18.3.1", + "react-dom": "18.3.1" }, "devDependencies": { - "@docusaurus/module-type-aliases": "^3.3.2", - "@docusaurus/types": "^3.3.2" + "@docusaurus/module-type-aliases": "3.4.0", + "@docusaurus/types": "3.4.0" }, "browserslist": { "production": [ @@ -41,6 +41,6 @@ ] }, "engines": { - "node": ">=18.0" + "node": ">=20.0" } } diff --git a/sidebars.js b/sidebars.js index 1a034e5..3a83767 100644 --- a/sidebars.js +++ b/sidebars.js @@ -40,6 +40,7 @@ const sidebars = { { type: "doc", id: "guides/layout-development" }, { type: "doc", id: "guides/podlet-development" }, { type: "doc", id: "guides/hybrid" }, + { type: "doc", id: "guides/browser-extension" }, ], }, { diff --git a/static/img/browser-extension-devtools-panes.png b/static/img/browser-extension-devtools-panes.png new file mode 100644 index 0000000..69ffc6b Binary files /dev/null and b/static/img/browser-extension-devtools-panes.png differ diff --git a/static/img/browser-extension-permissions.png b/static/img/browser-extension-permissions.png new file mode 100644 index 0000000..91f26fe Binary files /dev/null and b/static/img/browser-extension-permissions.png differ