diff --git a/extend/component/ui-options/configuration-schema.md b/extend/component/ui-options/configuration-schema.md index 5cfb600e..f3e9460c 100644 --- a/extend/component/ui-options/configuration-schema.md +++ b/extend/component/ui-options/configuration-schema.md @@ -22,13 +22,58 @@ Using the configuration schema also allows us to validate the user input on fron JSON schemas are well documented on the [json-schema.org](https://json-schema.org/) website. -We use [JSON Editor](https://github.com/json-editor/json-editor) for displaying a schema. -The supported formatting options for -the editor are available in the [official editor documentation](https://github.com/json-editor/json-editor#format). - -For developing and testing, -use, for example, JSON Editor available [on-line](http://jeremydorn.com/json-editor/), or the -[JSON-Editor Interactive Playground](https://pmk65.github.io/jedemov2/dist/demo.html). +We use [RJSF (React JSON Schema Form)](https://rjsf-team.github.io/react-jsonschema-form/) for rendering schemas +into forms. The schema supports standard JSON Schema properties as well as custom extensions documented +in [UI Element Examples](/extend/component/ui-options/configuration-schema/examples/) and +[Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/). + +### Supported Formats + +The following `format` values are supported in property definitions. The **Type** column shows the underlying JSON Schema `type`; italicized entries are descriptive notes, not literal `type` values. + +| Format | Type | Description | +|---|---|---| +| `password` | string | Masked password input with show/hide toggle | +| `textarea` | string | Multi-line text area | +| `editor` | string/object | CodeMirror code editor (JSON, SQL, Python, etc.) | +| `date` | string | Date picker input | +| `checkbox` | boolean | Checkbox toggle | +| `radio` | string | Radio button group (requires `enum`) | +| `trim` | string | Standard text input with automatic whitespace trimming | +| `grid` / `grid-strict` | object | Responsive grid layout for grouped fields | +| `tabs` / `tabs-top` / `categories` | object | Tabbed layout for grouped fields | +| `table` | array | Editable table for arrays of objects | +| `info` | *any JSON Schema type* | Static informational alert (uses `title` as message; Keboola UI extension) | +| `ssh-editor` | object | SSH key/form editor | +| `sync-action` | *Keboola UI button widget* | Action button triggering a sync action (not a JSON Schema `type`) | +| `test-connection` | *Keboola UI button widget* | Connection test button (not a JSON Schema `type`) | + +### Supported Options + +The following `options` keys can be used in property definitions: + +| Option | Description | +|---|---| +| `options.async` | Dynamic option loading via sync actions. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/). | +| `options.dependencies` | Conditional field visibility based on other field values. See [Dynamic Options](/extend/component/ui-options/configuration-schema/examples/#conditionally-showing-fields-based-on-selection). | +| `options.tags` | Enable tag-style input for multi-select arrays | +| `options.creatable` | Allow user-created values in select dropdowns | +| `options.tooltip` | Help text displayed as a tooltip icon next to the field label. Supports Markdown syntax. | +| `options.documentation` | Documentation link rendered as a book icon next to the field label. Value: `{ "link": "https://...", "tooltip": "optional hover text" }` | +| `options.enum_titles` | Display labels for `enum` values | +| `options.hidden` | Hide the field from the UI | +| `options.collapsed` | Start object sections in collapsed state | +| `options.disable_collapse` | Prevent collapsing of object sections | +| `options.enabled` | Set to `false` to disable a field | +| `options.grid_columns` | Number of grid columns (1–12) in `grid`/`grid-strict` layouts | +| `options.grid_break` | Force a new row in grid layouts | +| `options.editor` | CodeMirror editor options: `mode`, `lineNumbers`, `lint`, `input_height` | +| `options.input_height` | Height for textarea fields (e.g., `"100px"`) | +| `options.inputAttributes` | HTML input attributes (e.g., `placeholder`) | +| `options.only_keys` | SSH editor variant showing only key fields | +| `options.disable_array_add` | Disable adding items to arrays | +| `options.disable_array_delete` | Disable removing items from arrays | +| `options.disable_array_reorder` | Disable reordering items in arrays | ### Example Let's assume your component accepts the following configuration: @@ -98,8 +143,30 @@ The form above can be created using this JSON Schema: {% endhighlight %} ### Links Example -If you want to provide links to external resources, keep in mind that the configuration schema does not support markdown, -but it has a `links` feature. The above example can be modified so that the links are clickable: + +***Note:** The `links` feature is deprecated. Use `options.documentation` instead (see [Supported Options](#supported-options)).* + +If you want to provide links to external resources, use `options.documentation` to add a clickable documentation icon next to the field label: + +{% highlight json %} +{ + "dateFrom": { + "title": "Date from", + "type": "string", + "description": "Any date accepted by the strtotime function", + "options": { + "documentation": { + "link": "https://www.php.net/manual/en/function.strtotime.php", + "tooltip": "strtotime Documentation" + } + } + } +} +{% endhighlight %} + +#### Legacy links feature (deprecated) + +The old `links` property is **no longer supported**. If you have existing schemas using it, migrate to `options.documentation`: {% highlight json %} { @@ -130,7 +197,7 @@ but it has a `links` feature. The above example can be modified so that the link "dateFrom": { "title": "Date from", "type": "string", - "description": "Any date accepted by the strtotime function", + "description": "Any date accepted by the strtotime function", "minLength": 1, "default": "", "propertyOrder": 3, @@ -163,3 +230,15 @@ Which renders like this: {: .image-popup} ![Configuration Schema with links](/extend/component/ui-options/configuration-schema-2.png) + +### Legacy Features + +The following features are still supported for backwards compatibility but have preferred alternatives: + +- **`enumSource` / `watch`** — Dynamic enum population based on other field values. For new schemas, prefer `options.async` with sync actions instead. See [Sync Action Examples](/extend/component/ui-options/configuration-schema/sync-action-examples/#autoload). + +### Deprecated Features + +The following features from the legacy JSON Editor library are **no longer supported**: + +- **`links`** — Clickable links on field descriptions. Use `options.documentation` with `link` and optional `tooltip` instead. diff --git a/extend/component/ui-options/ui-examples/configuration-schema-examples.md b/extend/component/ui-options/ui-examples/configuration-schema-examples.md index 0d93bc0a..01f58ce7 100644 --- a/extend/component/ui-options/ui-examples/configuration-schema-examples.md +++ b/extend/component/ui-options/ui-examples/configuration-schema-examples.md @@ -404,13 +404,13 @@ The above code will create the following user interface: ![optional block](/extend/component/ui-options/ui-examples/optional_block_array.gif) -### Changing Set of Options Dynamically Based on Selection +### Conditionally Showing Fields Based on Selection -In some cases, a different set of options is available for different types of the same object, e.g., Report type. -JSON Schema allows to define different schemas based on selection. -This may be useful in the configuration rows scenario, where each row could represent a different type of Report, Endpoint, etc. +In some cases, additional options should only be shown when a related setting is enabled, e.g., when a particular report feature is turned on. +JSON Schema UI options allow you to control field visibility based on the values of other fields. +This may be useful in configuration rows, where each row can expose extra options depending on how a user configures it. -This can be achieved via [dependencies](https://github.com/json-editor/json-editor#dependencies).* +This can be achieved via `options.dependencies`. When the dependency conditions are met, the field is shown; otherwise it is hidden. ```json @@ -463,3 +463,217 @@ You can also react on multiple array values or on multiple elements at the same } } ``` + +You can also reference nested fields using dot notation with a `root.` prefix: + +```json +"options": { + "dependencies": { + "root.credentials.#api_token": "" + } +} +``` + +This shows the field only when the `#api_token` field inside the `credentials` object is empty. + + +### Tooltips and Documentation Links + +Use `options.tooltip` to add a help icon next to the field label. The tooltip content supports **Markdown** syntax: + +```json +{ + "api_key": { + "type": "string", + "title": "API Key", + "options": { + "tooltip": "Your API key from the [dashboard](https://example.com/dashboard).\n\n**Note:** Keep this value secret." + } + } +} +``` + +Use `options.documentation` to add a clickable documentation link icon: + +```json +{ + "query": { + "type": "string", + "title": "SQL Query", + "options": { + "documentation": { + "link": "https://docs.example.com/sql-reference", + "tooltip": "Open SQL reference" + } + } + } +} +``` + +### Radio Buttons + +Use `format: "radio"` with an `enum` to render radio buttons instead of a dropdown: + +```json +{ + "output_format": { + "type": "string", + "title": "Output Format", + "enum": ["csv", "json", "parquet"], + "format": "radio", + "default": "csv", + "propertyOrder": 1 + } +} +``` + + +### Date Picker + +Use `format: "date"` for a date input with a calendar picker. Values are stored as `YYYY-MM-DD` strings: + +```json +{ + "start_date": { + "type": "string", + "title": "Start Date", + "format": "date", + "propertyOrder": 1 + } +} +``` + + +### Grid Layout + +Use `format: "grid"` or `format: "grid-strict"` on an object to arrange its properties in a responsive 12-column grid. +Each property can specify `options.grid_columns` (1–12) to control its width. Use `options.grid_break` to force a new row: + +```json +{ + "connection": { + "type": "object", + "title": "Connection", + "format": "grid-strict", + "properties": { + "host": { + "type": "string", + "title": "Hostname", + "propertyOrder": 1, + "options": { "grid_columns": 8 } + }, + "port": { + "type": "integer", + "title": "Port", + "propertyOrder": 2, + "options": { "grid_columns": 4 } + }, + "database": { + "type": "string", + "title": "Database", + "propertyOrder": 3, + "options": { "grid_break": true } + } + } + } +} +``` + + +### Collapsible Sections + +Use `options.collapsed` on an object to make it collapsible. Set `options.disable_collapse` to prevent the user from collapsing it: + +```json +{ + "advanced": { + "type": "object", + "title": "Advanced Settings", + "options": { + "collapsed": true + }, + "properties": { + "timeout": { "type": "integer", "title": "Timeout" } + } + } +} +``` + + +### Disabled Fields + +Use `options.enabled: false` to render a field as read-only: + +```json +{ + "locked_field": { + "type": "string", + "title": "Locked Value", + "default": "Cannot be changed", + "options": { + "enabled": false + } + } +} +``` + + +### Info Blocks + +Use `format: "info"` to display a static informational message. The `title` property is used as the message text: + +```json +{ + "notice": { + "title": "This component requires an API token to function.", + "format": "info", + "propertyOrder": 1 + } +} +``` + +#### Alert Type + +By default, info blocks render as an informational (blue) alert. Use `options.alert_type` to change the visual style. Supported values: `"info"` (default), `"warning"`, `"error"`, `"success"`. + +```json +{ + "missing_token_warning": { + "title": "WARNING: API token is required!", + "format": "info", + "options": { + "alert_type": "warning" + } + } +} +``` + +```json +{ + "config_error": { + "title": "Configuration is invalid.", + "description": "Please check the required fields below.", + "format": "info", + "options": { + "alert_type": "error" + } + } +} +``` + +Info blocks can be combined with `options.dependencies` to show warnings conditionally: + +```json +{ + "missing_token_warning": { + "title": "WARNING: API token is required!", + "format": "info", + "options": { + "alert_type": "warning", + "dependencies": { + "root.credentials.#api_token": "" + } + } + } +} +```