68 lines
3.8 KiB
Plaintext
68 lines
3.8 KiB
Plaintext
# Workbench and ChatGPT
|
|
|
|
import { CanonicalCustomWidgetExample } from "@site/src/components/custom-widget-code";
|
|
|
|
The desktop workbench keeps code and preview side by side. Mobile uses Configure and Preview tabs. Save and preview actions stay available while the form scrolls.
|
|
|
|
CodeMirror edits requests, options, and JSX. The editor supplies installed Mantine components, request/source IDs, option names, temporary input names, runtime components, and icons. The request toolbar jumps to a declaration and atomically renames its invalidation, dynamic-option, and JSX references. Diagnostics are copyable and secret-free.
|
|
|
|
The **Schema** action beside Undo, Redo, and Format expands the generated JSON Schema plus minimal and full examples. These references are generated from the same validators used by imports, MCP, Workshop, and saved definitions.
|
|
|
|
## Manual workflow
|
|
|
|
1. Add the API source and select its network scope and authentication mode.
|
|
2. Enter credentials. Existing values are shown only as configured; plaintext is never revealed.
|
|
3. Declare named load/manual queries and actions.
|
|
4. Define persisted item options.
|
|
5. Write JSX using `data`, `status`, `options`, and temporary `inputs`.
|
|
6. Test requests, preview compact/standard/wide layouts, and inspect runtime and accessibility diagnostics.
|
|
7. Save, then select the definition and its options in the board widget picker.
|
|
|
|
## ChatGPT copy/paste
|
|
|
|
Enter a short request and optional API documentation URL, then select **Copy AI prompt**. Its dropdown also offers a self-contained version with the Custom Widget skill embedded for models that cannot discover skills or MCP resources. Paste either prompt into ChatGPT or another model. The model must return exactly:
|
|
|
|
1. A fenced `json` block with one complete widget and `template: "__HOMARR_TEMPLATE__"`.
|
|
2. A fenced `jsx` block with the readable template.
|
|
|
|
Use **Paste AI response** to fill the workbench. Enter credentials yourself, test, and preview. If validation or a request fails, select **Copy diagnostics for AI** and paste the correction back into Homarr.
|
|
|
|
The prompt is under 8,000 characters. It includes the installed Mantine version and capability rules but not a complete prop list, MCP workflow, server URL, or credentials.
|
|
|
|
## Options
|
|
|
|
Options use a restricted object JSON Schema. Supported controls include text, textarea, number, switch, select, multi-select, slider, date, time, color, URL, nested groups, conditions, and advanced JSON.
|
|
|
|
Credentials are not widget options. Credential-like option names and static default values are rejected; configure authentication under the widget's API source so values stay encrypted and out of exports and board configuration.
|
|
|
|
Dynamic selects use `x-homarr.optionsSource` and a named query. Add `itemsPath` when the response wraps its result array, then use `valuePath` and `labelPath` relative to each item. These requests run only while configuring the item and use the same protected server executor as widget requests.
|
|
|
|
### 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.
|
|
|
|
<CanonicalCustomWidgetExample
|
|
id="named-widget-requests"
|
|
label="Named queries and actions"
|
|
example="requests"
|
|
height="420px"
|
|
/>
|
|
|
|
### Options schema and defaults
|
|
|
|
Defaults must validate against the options schema. Keep secrets out of both documents.
|
|
|
|
<CanonicalCustomWidgetExample
|
|
id="widget-options-schema"
|
|
label="Widget options schema"
|
|
example="optionsSchema"
|
|
height="380px"
|
|
/>
|
|
|
|
<CanonicalCustomWidgetExample
|
|
id="widget-default-options"
|
|
label="Default option values"
|
|
example="defaultOptions"
|
|
height="160px"
|
|
/>
|