Ben Phelps
5 months ago
parent
b3cf985d4a
commit
62674372c5
@ -0,0 +1,50 @@
|
||||
---
|
||||
title: API Guide
|
||||
description: How to fetch data from an API in Homepage widgets.
|
||||
---
|
||||
|
||||
Homepage provides the `useWidgetAPI` hook to help you fetch data from an API. This hook insures that the data is fetched using a proxy, and is critical for security.
|
||||
|
||||
Here is an example of how the `useWidgetAPI` hook looks:
|
||||
|
||||
```js title="Fetch data from the stats endpoint"
|
||||
import useWidgetAPI from "utils/proxy/use-widget-api";
|
||||
|
||||
export default function Component({ service }) {
|
||||
const { data, error } = useWidgetAPI(widget, "stats");
|
||||
}
|
||||
```
|
||||
|
||||
## `useWidgetAPI`
|
||||
|
||||
`useWidgetAPI` takes three possible arguments:
|
||||
|
||||
- `widget`: The widget metadata object.
|
||||
- `endpoint`: The name of the endpoint to fetch data from.
|
||||
- `params`: An optional object containing query parameters to pass to the API.
|
||||
|
||||
### `widget`
|
||||
|
||||
The `widget` argument is the metadata object for the widget. It contains information about the API endpoint, proxy handler, and mappings. This object is used by the `useWidgetAPI` hook to fetch data from the API. This is generally passed in as a prop from the parent component.
|
||||
|
||||
### `endpoint`
|
||||
|
||||
The `endpoint` argument is the name of the endpoint to fetch data from. This is [defined in the widget metadata object](widget.md#endpoint). The `useWidgetAPI` hook uses this argument to determine which endpoint to fetch data from.
|
||||
|
||||
If no endpoint is provided, the `useWidgetAPI` hook will call the API endpoint defined in the widget metadata object directly.
|
||||
|
||||
### `params`
|
||||
|
||||
The `params` argument is an optional object containing query parameters to pass to the API. This is useful for filtering data or passing additional information to the API. This object is passed directly to the API endpoint as query parameters.
|
||||
|
||||
Here is an example of how to use the `params` argument:
|
||||
|
||||
```js title="Fetch data from the stats endpoint with query parameters"
|
||||
import useWidgetAPI from "utils/proxy/use-widget-api";
|
||||
|
||||
export default function Component({ service }) {
|
||||
const { data, error } = useWidgetAPI(widget, "stats", { start: "2021-01-01", end: "2021-12-31" });
|
||||
}
|
||||
```
|
||||
|
||||
The `params` must be [whitelisted in the widget metadata object](widget.md#params). This is done to prevent arbitrary query parameters from being passed to the API.
|
||||
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Component Guide
|
||||
description: How to create and configure Homepage widget components.
|
||||
---
|
||||
|
||||
Homepage widgets are built using React components. These components are responsible for fetching data from the API and rendering the widget UI. Homepage provides a set of hooks and utilities to help you build your widget component.
|
||||
|
||||
## A Basic Widget Component
|
||||
|
||||
Here is an example of a basic widget component:
|
||||
|
||||
```js
|
||||
import { useTranslation } from "next-i18next";
|
||||
|
||||
import Container from "components/services/widget/container";
|
||||
import Block from "components/services/widget/block";
|
||||
import useWidgetAPI from "utils/proxy/use-widget-api";
|
||||
|
||||
export default function Component({ service }) {
|
||||
const { t } = useTranslation();
|
||||
const { widget } = service;
|
||||
const { data, error } = useWidgetAPI(widget, "info");
|
||||
|
||||
if (error) {
|
||||
return <Container service={service} error={error} />;
|
||||
}
|
||||
|
||||
if (!data) {
|
||||
return (
|
||||
<Container service={service}>
|
||||
<Block label="yourwidget.key1" />
|
||||
<Block label="yourwidget.key2" />
|
||||
<Block label="yourwidget.key3" />
|
||||
</Container>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<Container service={service}>
|
||||
<Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
|
||||
<Block label="yourwidget.key2" value={t("common.number", { value: data.key2 })} />
|
||||
<Block label="yourwidget.key3" value={t("common.number", { value: data.key3 })} />
|
||||
</Container>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Breakdown
|
||||
|
||||
We'll cover two sections of the widget component: hooks and components.
|
||||
|
||||
#### Hooks
|
||||
|
||||
**`useTranslation`**
|
||||
|
||||
This hook is used to translate text and numerical content in widgets. Homepage provides a set of helpers to help you localize your widgets. You can learn more about translations in the [Translations Guide](translations.md).
|
||||
|
||||
**`useWidgetAPI`**
|
||||
|
||||
This hook is used to fetch data from the API. We cover this hook in more detail in the [API Guide](api.md).
|
||||
|
||||
#### Components
|
||||
|
||||
- `<Container>`: This component is a wrapper for the widget. It provides a consistent layout for all widgets.
|
||||
- `<Block>`: This component is used to display a key-value pair. It takes a label and value as props.
|
||||
@ -0,0 +1,289 @@
|
||||
---
|
||||
title: Widget Guide
|
||||
description: How to create a custom widget for Homepage.
|
||||
---
|
||||
|
||||
In this guide, we'll walk through the process of creating a custom widget for Homepage. We'll cover the basic structure of a widget, how to use translations, and how to fetch data from an API. By the end of this guide, you'll have a solid understanding of how to build your own custom widget.
|
||||
|
||||
**Prerequisites:**
|
||||
|
||||
- Basic knowledge of React and JavaScript
|
||||
- Familiarity with the Homepage platform
|
||||
- Understanding of JSON and API interactions
|
||||
|
||||
Throughout this guide, we'll use `yourwidget` as a placeholder for the unique name of your custom widget. Replace `yourwidget` with the actual name of your widget. It should contain only lowercase letters and no spaces.
|
||||
|
||||
This guide makes use of a fake API, which would return a JSON response as such, when called with the `v1/info` endpoint:
|
||||
|
||||
```json
|
||||
{ "key1": 123, "key2": 456, "key3": 789 }
|
||||
```
|
||||
|
||||
## Set up the widget definition
|
||||
|
||||
Create a new folder for your widget in the `src/widgets` directory. Name the folder `yourwidget`.
|
||||
|
||||
Inside the `yourwidget` folder, create a new file named `widget.js`. This file will contain the metadata for your widget.
|
||||
|
||||
Open the `widget.js` file and add the following code:
|
||||
|
||||
```js title="src/widgets/yourwidget/widget.js"
|
||||
import genericProxyHandler from "utils/proxy/handlers/generic"; // (1)!
|
||||
|
||||
const widget = /* (2)! */ {
|
||||
api: "{url}/{endpoint}" /* (3)! */,
|
||||
proxyHandler: genericProxyHandler /* (1)! */,
|
||||
|
||||
mappings: /* (4)! */ {
|
||||
info: /* (5)! */ {
|
||||
endpoint: "v1/info" /* (6)! */,
|
||||
},
|
||||
},
|
||||
};
|
||||
|
||||
export default widget;
|
||||
```
|
||||
|
||||
1. We import the `genericProxyHandler` from the `utils/proxy/handlers/generic` module. The `genericProxyHandler` is a generic handler that can be used to fetch data from an API. We then assign the `genericProxyHandler` to the `proxyHandler` property of the `widget` object. There are other handlers available that you can use depending on your requirements. You can also create custom handlers if needed.
|
||||
2. We define a `widget` object that contains the metadata for the widget.
|
||||
3. The API endpoint to fetch data from. You can use placeholders like `{url}` and `{endpoint}` to dynamically generate the API endpoint based on the widget configuration.
|
||||
4. An object that contains mappings for different endpoints. Each mapping should have an `endpoint` property that specifies the endpoint to fetch data from.
|
||||
5. A mapping named `info` that specifies the `v1/info` endpoint to fetch data from. This would be called from the component as such: `#!js useWidgetAPI(widget, "info");`
|
||||
6. The `endpoint` property of the `info` mapping specifies the endpoint to fetch data from. There are other properties you can pass to the mapping, such as `method`, `headers`, and `body`.
|
||||
|
||||
!!! warning "Important"
|
||||
|
||||
All widgets that fetch data from dynamic endpoints should have either `mappings` or an `allowedEndpoints` property.
|
||||
|
||||
## Set up translation strings
|
||||
|
||||
Homepage uses translated and localized strings for **all text and numerical content** in widgets. English is the default language, and other languages can be added via [Crowdin](https://crowdin.com/project/gethomepage). To add the English translations for your widget, follow these steps:
|
||||
|
||||
Open the `public/locales/en/common.js` file.
|
||||
|
||||
Add a new object for your widget to the bottom of the list, like this:
|
||||
|
||||
```json
|
||||
"yourwidget": {
|
||||
"key1": "Value 1",
|
||||
"key2": "Value 2",
|
||||
"key3": "Value 3"
|
||||
}
|
||||
```
|
||||
|
||||
!!! note
|
||||
|
||||
Even if you nativly speak another language, you should only add English translations. You can then add translations in your native language via [Crowdin](https://crowdin.com/project/gethomepage), once your widget is merged.
|
||||
|
||||
## Create the widget component
|
||||
|
||||
Create a new file for your widgets component, named `component.jsx`, in the `src/widgets/yourwidget` directory. We'll build the contents of the `component.jsx` file step by step.
|
||||
|
||||
First, we'll import the necessary dependencies:
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="1"
|
||||
import { useTranslation } from "next-i18next"; // (1)!
|
||||
|
||||
import Container from "components/services/widget/container"; // (2)!
|
||||
import Block from "components/services/widget/block"; // (3)!
|
||||
import useWidgetAPI from "utils/proxy/use-widget-api"; // (4)!
|
||||
```
|
||||
|
||||
1. `#!js useTranslation()` is a hook provided by `next-i18next` that allows us to access the translation strings
|
||||
2. `#!jsx <Container>` and `#!jsx <Block>` are custom components that we'll use to structure our widget.
|
||||
3. `#!jsx <Container>` and `#!jsx <Block>` are custom components that we'll use to structure our widget.
|
||||
4. `#!js useWidgetAPI(widget, endpoint)` is a custom hook that we'll use to fetch data from an API.
|
||||
|
||||
---
|
||||
|
||||
Next, we'll define a functional component named `Component` that takes a `service` prop.
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="7"
|
||||
export default function Component({ service }) {}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
We grab the helper functions from the `useTranslation` hook.
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="8"
|
||||
const { t } = useTranslation();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
We destructure the `widget` object from the `service` prop. The `widget` object contains the metadata for the widget, such as the API endpoint to fetch data from.
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="9"
|
||||
const { widget } = service;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Now, the fun part! We use the `useWidgetAPI` hook to fetch data from an API. The `useWidgetAPI` hook takes two arguments: the `widget` object and the API endpoint to fetch data from. The `useWidgetAPI` hook returns an object with `data` and `error` properties.
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="10"
|
||||
const { data, error } = useWidgetAPI(widget, "info");
|
||||
```
|
||||
|
||||
!!! tip "API Tips"
|
||||
|
||||
You'll see here how part of the API url is built using the `url` and `endpoint` properties from the widget definition.
|
||||
|
||||
In this case, we're fetching data from the `info` endpoint. The `info` endpoint is defined in the `mappings` object. So the full API endpoint will be `"{url}/v1/info"`.
|
||||
|
||||
The mapping and endpoint are often the same, but must be defined regardless.
|
||||
|
||||
---
|
||||
|
||||
Next, we check if there's an error or no data.
|
||||
|
||||
If there's an error, we return a `Container` and pass it the `service` and `error` as props. The `Container` component will handle displaying the error message.
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="12"
|
||||
if (error) {
|
||||
return <Container service={service} error={error} />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
If there's no data, we return a `Container` component with three `Block` components, each with a `label`.
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="16"
|
||||
if (!data) {
|
||||
return (
|
||||
<Container service={service}>
|
||||
<Block label="yourwidget.key1" />
|
||||
<Block label="yourwidget.key2" />
|
||||
<Block label="yourwidget.key3" />
|
||||
</Container>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
This will render the widget with placeholders for the data, i.e., a skeleton view.
|
||||
|
||||
!!! tip "Translation Tips"
|
||||
|
||||
The `label` prop in the `Block` component corresponds to the translation key we defined earlier in the `common.js` file. All text and numerical content should be translated.
|
||||
|
||||
---
|
||||
|
||||
If there is data, we return a `Container` component with three `Block` components, each with a `label` and a `value`.
|
||||
|
||||
Here we use the `t` function from the `useTranslation` hook to translate the data values. The `t` function takes the translation key and an object with variables to interpolate into the translation string.
|
||||
|
||||
We're using the `common.number` translation key to format the data values as numbers. This allows for easy localization of numbers, such as using commas or periods as decimal separators.
|
||||
|
||||
There are a large number of `common` numerical translation keys available, which you can learn more about in the [Translation Guide](translations.md).
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="26"
|
||||
return (
|
||||
<Container service={service}>
|
||||
<Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
|
||||
<Block label="yourwidget.key2" value={t("common.number", { value: data.key2 })} />
|
||||
<Block label="yourwidget.key3" value={t("common.number", { value: data.key3 })} />
|
||||
</Container>
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Here's the complete `component.jsx` file:
|
||||
|
||||
```js title="src/widgets/yourwidget/component.jsx" linenums="1"
|
||||
import { useTranslation } from "next-i18next";
|
||||
|
||||
import Container from "components/services/widget/container";
|
||||
import Block from "components/services/widget/block";
|
||||
import useWidgetAPI from "utils/proxy/use-widget-api";
|
||||
|
||||
export default function Component({ service }) {
|
||||
const { t } = useTranslation();
|
||||
const { widget } = service;
|
||||
const { data, error } = useWidgetAPI(widget, "info");
|
||||
|
||||
if (error) {
|
||||
return <Container service={service} error={error} />;
|
||||
}
|
||||
|
||||
if (!data) {
|
||||
return (
|
||||
<Container service={service}>
|
||||
<Block label="yourwidget.key1" />
|
||||
<Block label="yourwidget.key2" />
|
||||
<Block label="yourwidget.key3" />
|
||||
</Container>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<Container service={service}>
|
||||
<Block label="yourwidget.key1" value={t("common.number", { value: data.key1 })} />
|
||||
<Block label="yourwidget.key2" value={t("common.number", { value: data.key2 })} />
|
||||
<Block label="yourwidget.key3" value={t("common.number", { value: data.key3 })} />
|
||||
</Container>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Add the widget to the Homepage
|
||||
|
||||
To add your widget to the Homepage, you need to register it in the `src/widgets/widgets.js` file.
|
||||
|
||||
Open the `src/widgets/widgets.js` file and import the `Component` from your widget's `component.jsx` file. Please keep the alphabetical order.
|
||||
|
||||
```js
|
||||
// ...
|
||||
import yourwidget from "./yourwidget/widget";
|
||||
// ...
|
||||
```
|
||||
|
||||
Add `yourwidget` to the `widgets` object. Please keep the alphabetical order.
|
||||
|
||||
```js
|
||||
const widgets = {
|
||||
// ...
|
||||
yourwidget: yourwidget,
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
You also need to add the widget to the `components` object in the `src/widgets/components.js` file.
|
||||
|
||||
Open the `src/widgets/components.js` file and import the `Component` from your widget's `component.jsx` file.
|
||||
|
||||
Please keep the alphabetical order.
|
||||
|
||||
```js
|
||||
const components = {
|
||||
// ...
|
||||
yourwidget: dynamic(() => import("./yourwidget/component")),
|
||||
// ...
|
||||
};
|
||||
```
|
||||
|
||||
## Using the widget
|
||||
|
||||
You can now use your custom widget in your Homepage. Open your `services.yaml` file and add a new service with the `yourwidget` widget.
|
||||
|
||||
```yaml
|
||||
- Services:
|
||||
- Your Widget:
|
||||
icon: yourwidget.svg
|
||||
href: https://example.com/
|
||||
widget:
|
||||
type: yourwidget
|
||||
url: http://127.0.0.1:1337
|
||||
```
|
||||
|
||||
!!! tip "API Tips"
|
||||
|
||||
You'll see here how part of the API url is built using the `url` and `endpoint` properties from the widget definition.
|
||||
|
||||
We defined the api endpoint as `"{url}/{endpoint}"`. This is where the `url` is defined. So the full API endpoint will be `http://127.0.0.1:1337/{endpoint}`.
|
||||
|
||||
---
|
||||
|
||||
That's it! You've successfully created a custom widget for Homepage. If you have any questions or need help, feel free to reach out to the Homepage community for assistance. Happy coding!
|
||||
@ -0,0 +1,34 @@
|
||||
---
|
||||
title: Homepage Widget Guides
|
||||
description: How to create and configure Homepage widgets.
|
||||
---
|
||||
|
||||
Widgets are a core component of Homepage. They are used to display information about your system, services, and environment.
|
||||
|
||||
## Overview
|
||||
|
||||
If you are new to Homepage widgets, and are looking to create a new widget, please follow along with the guide here: [Widget Guide](guide.md).
|
||||
|
||||
### Translations
|
||||
|
||||
All text and numerical content in widgets should be translated and localized. English is the default language, and other languages can be added via [Crowdin](https://crowdin.com/project/gethomepage).
|
||||
|
||||
The Homepage community prides itself on being multilingual, and we strongly encourage you to add translations for your widgets.
|
||||
|
||||
If you are looking to learn more about translations, please refer to the guide here: [Translations Guide](translations.md).
|
||||
|
||||
### Widget Component
|
||||
|
||||
The widget component is the core of the widget. It is responsible for [fetching data from the API](api.md) and rendering the widget UI. Homepage provides a set of hooks and utilities to help you build your widget component.
|
||||
|
||||
If you are looking to learn more about widget components, please refer to the guide here: [Component Guide](component.md).
|
||||
|
||||
### Widget Metadata
|
||||
|
||||
Widget metadata defines the configuration of the widget. It defines the API endpoint to fetch data from, the proxy handler to use, and any data mappings.
|
||||
|
||||
If you are looking to learn more about widget metadata, endpoint and data mapping, please refer to the guide here: [Metadata Guide](widget.md).
|
||||
|
||||
If you are looking to learn more about proxy handlers, please refer to the guide here: [Proxies Guide](proxies.md).
|
||||
|
||||
If you are looking to learn more making API calls from inside your widget, please refer to the guide here: [API Guide](api.md).
|
||||
@ -0,0 +1,178 @@
|
||||
---
|
||||
title: Proxies Guide
|
||||
description: How to use and create Homepage widget proxies.
|
||||
---
|
||||
|
||||
Homepage includes a set of built-in proxy handlers that can be used to fetch data from an API. We will go over how to use these proxy handlers and briefly cover how to create your own.
|
||||
|
||||
## Available Proxy Handlers
|
||||
|
||||
Homepage comes with a few built-in proxy handlers that can be used to fetch data from an API. These handlers are located in the `utils/proxy/handlers` directory.
|
||||
|
||||
### `genericProxyHandler`
|
||||
|
||||
A proxy handler that makes generally unauthenticated requests to the specified API endpoint.
|
||||
|
||||
```js
|
||||
import genericProxyHandler from "utils/proxy/handlers/generic";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
proxyHandler: genericProxyHandler,
|
||||
};
|
||||
```
|
||||
|
||||
You can also pass API keys from the widget configuration to the proxy handler, for authenticated requests.
|
||||
|
||||
=== "widget.js"
|
||||
|
||||
```js
|
||||
import genericProxyHandler from "utils/proxy/handlers/generic";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}?key={key}",
|
||||
proxyHandler: genericProxyHandler,
|
||||
};
|
||||
```
|
||||
|
||||
=== "services.yaml"
|
||||
|
||||
```yaml
|
||||
# Widget Configuration
|
||||
- Your Widget:
|
||||
icon: yourwidget.svg
|
||||
href: https://example.com/
|
||||
widget:
|
||||
type: yourwidget
|
||||
url: http://example.com
|
||||
key: your-api-key
|
||||
```
|
||||
|
||||
### `credentialedProxyHandler`
|
||||
|
||||
A proxy handler that makes authenticated by setting request headers. Credentials are pulled from the widgets configuration.
|
||||
|
||||
By default the key is passed as an `X-API-Key` header. If you need to pass the key as something else, either add a case to the credentialedProxyHandler or create a new proxy handler.
|
||||
|
||||
=== "widget.js"
|
||||
|
||||
```js
|
||||
import credentialedProxyHandler from "utils/proxy/handlers/credentialed";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}?key={key}",
|
||||
proxyHandler: credentialedProxyHandler,
|
||||
};
|
||||
```
|
||||
|
||||
=== "services.yaml"
|
||||
|
||||
```yaml
|
||||
- Your Widget:
|
||||
icon: yourwidget.svg
|
||||
href: https://example.com/
|
||||
widget:
|
||||
type: yourwidget
|
||||
url: http://127.0.0.1:1337
|
||||
key: your-api-key
|
||||
```
|
||||
|
||||
### `jsonrpcProxyHandler`
|
||||
|
||||
A proxy handler that makes authenticated JSON-RPC requests to the specified API endpoint. Where the endpoint is the method to call.
|
||||
|
||||
=== "widget.js"
|
||||
|
||||
```js
|
||||
import jsonrpcProxyHandler from "utils/proxy/handlers/jsonrpc";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/jsonrpc",
|
||||
proxyHandler: jsonrpcProxyHandler,
|
||||
|
||||
mappings: {
|
||||
total: { endpoint: "total" },
|
||||
average: { endpoint: "average" },
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
=== "services.yaml"
|
||||
|
||||
```yaml
|
||||
- Your Widget:
|
||||
icon: yourwidget.svg
|
||||
href: https://example.com/
|
||||
widget:
|
||||
type: yourwidget
|
||||
url: http://127.0.0.1:1337
|
||||
username: your-username
|
||||
password: your-password
|
||||
```
|
||||
|
||||
### `synologyProxyHandler`
|
||||
|
||||
A proxy handler that makes authenticated requests to the specified Synology API endpoint. This is used exclusively for Synology DSM services.
|
||||
|
||||
=== "widget.js"
|
||||
|
||||
```js
|
||||
import synologyProxyHandler from "utils/proxy/handlers/synology";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/webapi/{cgiPath}?api={apiName}&version={maxVersion}&method={apiMethod}",
|
||||
proxyHandler: synologyProxyHandler,
|
||||
|
||||
mappings: {
|
||||
system_storage: {
|
||||
apiName: "SYNO.Core.System",
|
||||
apiMethod: 'info&type="storage"',
|
||||
endpoint: "system_storage",
|
||||
}
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
=== "services.yaml"
|
||||
|
||||
```yaml
|
||||
- Your Widget:
|
||||
icon: yourwidget.svg
|
||||
href: https://example.com/
|
||||
widget:
|
||||
type: yourwidget
|
||||
url: http://127.0.0.1:1337
|
||||
username: your-username
|
||||
password: your-password
|
||||
```
|
||||
|
||||
## Creating a Custom Proxy Handler
|
||||
|
||||
You can create your own proxy handler to fetch data from an API. A proxy handler is a function that takes a configuration object and returns a function that makes the API request.
|
||||
|
||||
The proxy handler function takes three arguments:
|
||||
|
||||
- `req`: The request object.
|
||||
- `res`: The response object.
|
||||
- `map`: A function that maps the API response to the widget data.
|
||||
|
||||
The proxy handler function should return a promise that resolves to the API response.
|
||||
|
||||
Here is an example of a simple proxy handler that fetches data from an API and passes it to the widget:
|
||||
|
||||
```js
|
||||
import createLogger from "utils/logger";
|
||||
import { httpProxy } from "utils/proxy/http";
|
||||
|
||||
const logger = createLogger("customProxyHandler");
|
||||
|
||||
export default async function customProxyHandler(req, res, map) {
|
||||
const { url } = req.query;
|
||||
|
||||
const [status, contentType, data] = await httpProxy(url);
|
||||
|
||||
return res.status(status).send(data);
|
||||
}
|
||||
```
|
||||
|
||||
Proxy handlers are a complex topic and require a good understanding of JavaScript and the Homepage codebase. If you are new to Homepage, we recommend using the built-in proxy handlers.
|
||||
@ -0,0 +1,4 @@
|
||||
---
|
||||
title: Translations Guide
|
||||
description: Tips and tricks for translating and localizing Homepage widgets.
|
||||
---
|
||||
@ -0,0 +1,310 @@
|
||||
---
|
||||
title: Metadata Guide
|
||||
description: How to create and configure Homepage widget metadata.
|
||||
---
|
||||
|
||||
Here, we will go over how to create and configure Homepage widget metadata. Metadata is a JS object that contains information about the widget, such as the API endpoint, proxy handler, and mappings. This metadata is used by Homepage to fetch data from the API and pass it to the widget.
|
||||
|
||||
## Widgets Configuration
|
||||
|
||||
Here are some examples of how to configure a widget's metadata object.
|
||||
|
||||
=== "Basic Example"
|
||||
|
||||
```js
|
||||
import genericProxyHandler from "utils/proxy/handlers/generic";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
proxyHandler: genericProxyHandler,
|
||||
|
||||
mappings: {
|
||||
stats: { endpoint: "stats" }
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
=== "Advanced Example"
|
||||
|
||||
```js
|
||||
import credentialedProxyHandler from "utils/proxy/handlers/credentialed";
|
||||
import { asJson, jsonArrayFilter } from "utils/proxy/api-helpers";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
proxyHandler: credentialedProxyHandler,
|
||||
|
||||
mappings: {
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
validate: ["total", "average"],
|
||||
params: ["start", "end"],
|
||||
},
|
||||
notices: {
|
||||
endpoint: "notices",
|
||||
map: (data) => {
|
||||
total: asJson(data).length;
|
||||
},
|
||||
},
|
||||
warnings: {
|
||||
endpoint: "notices",
|
||||
map: (data) => {
|
||||
total: jsonArrayFilter(data, (alert) => alert.type === "warning").length;
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
A widgets metadata is quite powerful and can be configured in many different ways.
|
||||
|
||||
## Configuration Properties
|
||||
|
||||
### `api`
|
||||
|
||||
The `api` property is a string that represents the URL of the API endpoint that the widget will use to fetch data. The URL can contain placeholders that will be replaced with actual values at runtime. For example, the `{url}` placeholder will be replaced with the URL of the configured widget, and the `{endpoint}` placeholder will be replaced with the value of the `endpoint` property in the `mappings` object.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
};
|
||||
```
|
||||
|
||||
### `proxyHandler`
|
||||
|
||||
The `proxyHandler` property is a function that will be used to make the API request. Homepage includes some built-in proxy handlers that can be used out of the box:
|
||||
|
||||
Here is an example of the generic proxy handler that makes unauthenticated requests to the specified API endpoint.
|
||||
|
||||
=== "widget.js"
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
proxyHandler: genericProxyHandler,
|
||||
};
|
||||
```
|
||||
|
||||
=== "services.yaml"
|
||||
|
||||
```yaml
|
||||
- Services:
|
||||
- Your Widget:
|
||||
icon: yourwidget.svg
|
||||
href: https://example.com/
|
||||
widget:
|
||||
type: yourwidget
|
||||
url: http://127.0.0.1:1337
|
||||
```
|
||||
|
||||
If you are looking to learn more about proxy handlers, please refer to the guide here: [Proxies Guide](proxies.md).
|
||||
|
||||
### `mappings`
|
||||
|
||||
The `mappings` property is an object that contains information about the API endpoint, such as the endpoint name, validation rules, and parameter names. The `mappings` object can contain multiple endpoints, each with its own configuration.
|
||||
|
||||
!!! note "Security Note"
|
||||
|
||||
The `mappings` or `allowedEndpoints` property is required for the widget to fetch data from more than a static URL. Homepage uses a whitelist approach to ensure that widgets only access allowed endpoints.
|
||||
|
||||
```js
|
||||
import { asJson } from "utils/proxy/api-helpers";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/stats?start=...&end=...`
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
validate: ["total", "average"],
|
||||
params: ["start", "end"],
|
||||
},
|
||||
// `/api/notices`
|
||||
notices: {
|
||||
endpoint: "notices",
|
||||
map: (data) => {
|
||||
total: asJson(data).length;
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `endpoint`
|
||||
|
||||
The `endpoint` property is a string that represents the name of the API endpoint that the widget will use to fetch data. This value will be used to replace the `{endpoint}` placeholder in the `api` property.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/stats`
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `validate`
|
||||
|
||||
The `validate` property is an array of strings that represent the keys that should be validated in the API response. If the response does not contain all of the specified keys, the widget will not render.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/stats`
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
validate: ["total", "average"],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
This configuration will ensure that the API response contains the `total` and `average` keys before the widget is rendered.
|
||||
|
||||
#### `params`
|
||||
|
||||
The `params` property is an array of strings that represent the keys that should be passed as parameters to the API endpoint. These keys will be replaced with the actual values at runtime.
|
||||
|
||||
=== "widget.js"
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/stats?start=...&end=...`
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
params: ["start", "end"],
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
=== "component.jsx"
|
||||
|
||||
```js
|
||||
const { data: statsData, error: statsError } = useWidgetAPI(widget, "stats", {
|
||||
start: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
|
||||
end: new Date(),
|
||||
});
|
||||
```
|
||||
|
||||
This configuration will pass the `start` and `end` keys as parameters to the API endpoint. The values are passed as an object to the `useWidgetAPI` hook.
|
||||
|
||||
#### `map`
|
||||
|
||||
The `map` property is a function that will be used to transform the API response before it is passed to the widget. This function is passed the raw API response and should return the transformed data.
|
||||
|
||||
```js
|
||||
import { asJson } from "utils/proxy/api-helpers";
|
||||
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/notices`
|
||||
notices: {
|
||||
endpoint: "notices",
|
||||
map: (data) => {
|
||||
total: asJson(data).length;
|
||||
},
|
||||
},
|
||||
// `/api/notices`
|
||||
warnings: {
|
||||
endpoint: "notices",
|
||||
map: (data) => {
|
||||
total: asJson(data).filter((alert) => alert.type === "warning").length;
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `method`
|
||||
|
||||
The `method` property is a string that represents the HTTP method that should be used to make the API request. The default value is `GET`.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/stats`
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
method: "POST",
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `headers`
|
||||
|
||||
The `headers` property is an object that contains additional headers that should be included in the API request. If your endpoint requires specific headers, you can include them here.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/stats`
|
||||
stats: {
|
||||
endpoint: "stats",
|
||||
method: "POST",
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
#### `body`
|
||||
|
||||
The `body` property is an object that contains the data that should be sent in the request body. This property is only used when the `method` property is set to `POST` or `PUT`.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
mappings: {
|
||||
// `/api/graphql`
|
||||
stats: {
|
||||
endpoint: "graphql",
|
||||
method: "POST",
|
||||
body: {
|
||||
query: `
|
||||
query {
|
||||
stats {
|
||||
total
|
||||
average
|
||||
}
|
||||
}
|
||||
`,
|
||||
},
|
||||
headers: {
|
||||
"Content-Type": "application/json",
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### `allowedEndpoints`
|
||||
|
||||
The `allowedEndpoints` property is a RegExp that represents the allowed endpoints that the widget can use. If the widget tries to access an endpoint that is not allowed, the request will be blocked.
|
||||
|
||||
`allowedEndpoints` can be used when endpoint validation is simple and can be done using a regular expression, and more control is not required.
|
||||
|
||||
!!! note "Security Note"
|
||||
|
||||
The `mappings` or `allowedEndpoints` property is required for the widget to fetch data from more than a static URL. Homepage uses a whitelist approach to ensure that widgets only access allowed endpoints.
|
||||
|
||||
```js
|
||||
const widgetExample = {
|
||||
api: "{url}/api/{endpoint}",
|
||||
allowedEndpoints: /^stats|notices$/,
|
||||
};
|
||||
```
|
||||
|
||||
This configuration will only allow the widget to access the `stats` and `notices` endpoints.
|
||||
Loading…
Reference in new issue