fix(custom-widgets): require explicit request bindings
This commit is contained in:
23 files changed
+363
-52
No files matched your search
@@ -39,7 +39,25 @@ Dynamic selects use `x-homarr.optionsSource` and a named query. Add `itemsPath`
|
||||
|
||||
### Named requests and parameter bindings
|
||||
|
||||
Request parameters are a map from parameter name to `string`, `number`, or `boolean`. Query and body templates reference them with `{ "$param": "name" }`. Load queries receive matching widget options automatically; manual queries and actions receive `params` from their runtime component.
|
||||
Request parameters are a map from parameter name to `string`, `number`, or `boolean`. Query and body templates reference them with `{ "$param": "name" }`. Declaring a parameter does not give it a value, even when an option or temporary input has the same name.
|
||||
|
||||
For a load query, bind every parameter explicitly in `optionsBinding`. Each entry is either `{ "$option": "optionName" }` or a primitive literal matching the declared parameter type:
|
||||
|
||||
```json
|
||||
{
|
||||
"pathTemplate": "/api/endpoints/{endpointId}/docker/containers/json",
|
||||
"parameters": { "endpointId": "string", "showAll": "boolean" },
|
||||
"queryTemplate": { "all": { "$param": "showAll" } },
|
||||
"optionsBinding": {
|
||||
"endpointId": { "$option": "endpointId" },
|
||||
"showAll": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For manual queries and actions, `SubFetch`, `ActionButton`, or `ToggleSwitch` supplies the complete parameter object through its `params` prop. This is the only route from JSX values such as `inputs.search` or a loop variable into a request.
|
||||
|
||||
Dynamic option requests also run without a JSX invoker. If they declare parameters, give them explicit `optionsBinding` entries so the configuration form can resolve those values.
|
||||
|
||||
<CanonicalCustomWidgetExample
|
||||
id="named-widget-requests"
|
||||
|
||||
@@ -13,7 +13,7 @@ Queries and actions support GET, POST, PUT, PATCH, and DELETE. `kind`, not metho
|
||||
|
||||
Successful actions evict the declared queries from both the browser and server response cache before refetching them.
|
||||
|
||||
Path parameters use `{name}`. Structured query/body templates use `{ "$param": "name" }`. Runtime values can come from validated options, temporary `inputs`, and explicit action parameters.
|
||||
Path parameters use `{name}`. Structured query/body templates use `{ "$param": "name" }`. Every declared parameter has an explicit source: load queries use `optionsBinding` entries containing `{ "$option": "optionName" }` or a primitive literal, while manual queries and actions receive the full parameter object from the invoking component's `params` prop. Homarr never matches parameter names to option or input names implicitly.
|
||||
|
||||
## Protections
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Use the first schema/JSX diagnostic and its path. Ensure source/request IDs are
|
||||
|
||||
## Request fails
|
||||
|
||||
Check the source network scope, base URL, credentials, request method/path/body, runtime parameters, and board permission. The preview journal shows redacted method, request ID, path template, status, and duration without credentials.
|
||||
Check the source network scope, base URL, credentials, request method/path/body, runtime parameters, and board permission. For “invalid placeholder” or an unresolved parameter on a load query, first verify that every declared parameter has an explicit `optionsBinding` option reference or literal. Matching parameter and option names are not a binding. The preview journal shows redacted method, request ID, path template, status, and duration without credentials.
|
||||
|
||||
## Mantine prop warning
|
||||
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { fetchApi } from "@homarr/api/client";
|
||||
import { customWidgetDefinitionSchema } from "@homarr/custom-widgets/core";
|
||||
import { customWidgetDefinitionSchema, resolveCustomWidgetOptionsBinding } from "@homarr/custom-widgets/core";
|
||||
import type { CustomWidgetSource, HomarrCustomWidgetV2 } from "@homarr/custom-widgets/core";
|
||||
import type { CustomWidgetFormValues } from "@homarr/custom-widgets/workbench";
|
||||
import type { UseFormReturnType } from "@mantine/form";
|
||||
@@ -70,13 +70,8 @@ export async function loadPreviewQueries(definition: HomarrCustomWidgetV2, sessi
|
||||
const data: Record<string, unknown> = {};
|
||||
const status: Record<string, unknown> = {};
|
||||
for (const request of definition.requests.filter((entry) => entry.kind === "query" && entry.trigger === "load")) {
|
||||
const params = Object.fromEntries(
|
||||
Object.entries(request.parameters).flatMap(([name, type]) => {
|
||||
const value = definition.defaultOptions[name];
|
||||
return typeof value === type ? [[name, value as string | number | boolean]] : [];
|
||||
}),
|
||||
);
|
||||
try {
|
||||
const params = resolveCustomWidgetOptionsBinding(request, definition.defaultOptions);
|
||||
const result = await fetchApi.customWidget.previewQuery.query({ sessionId, requestId: request.id, params });
|
||||
data[request.id] = result.data;
|
||||
status[request.id] = { loading: false, ...result };
|
||||
|
||||
@@ -3,6 +3,7 @@ import { Badge, Box, Container, Group, Paper, Stack, Text, Title } from "@mantin
|
||||
|
||||
import { api } from "@homarr/api/server";
|
||||
import { auth } from "@homarr/auth/next";
|
||||
import { resolveCustomWidgetOptionsBinding } from "@homarr/custom-widgets/core";
|
||||
import CustomJsxDisplay from "@homarr/widgets/custom-api/custom-jsx-display";
|
||||
|
||||
export default async function CustomWidgetPreviewPage({ params }: { params: Promise<{ id: string }> }) {
|
||||
@@ -15,14 +16,11 @@ export default async function CustomWidgetPreviewPage({ params }: { params: Prom
|
||||
const loadRequests = preview.requests.filter((request) => request.kind === "query" && request.trigger === "load");
|
||||
const results = await Promise.all(
|
||||
loadRequests.map(async (request) => {
|
||||
const requestParams = Object.fromEntries(
|
||||
Object.entries(request.parameters).flatMap(([name, type]) => {
|
||||
const value = preview.defaultOptions[name];
|
||||
return typeof value === type ? [[name, value as string | number | boolean]] : [];
|
||||
}),
|
||||
);
|
||||
const result = await api.customWidget
|
||||
.previewQuery({ sessionId: id, requestId: request.id, params: requestParams })
|
||||
const result = await Promise.resolve()
|
||||
.then(() => resolveCustomWidgetOptionsBinding(request, preview.defaultOptions))
|
||||
.then((requestParams) =>
|
||||
api.customWidget.previewQuery({ sessionId: id, requestId: request.id, params: requestParams }),
|
||||
)
|
||||
.catch((cause: unknown) => ({
|
||||
ok: false,
|
||||
status: 0,
|
||||
|
||||
Reference in new issue
Block a user