Skip to content

README.md

Latest commit

 

History

History
139 lines (116 loc) · 6.4 KB

README.md

File metadata and controls

139 lines (116 loc) · 6.4 KB
Raw

AdminForth JSON Form Plugin

Render a rich, schema-driven form for a JSON column instead of a raw text area. You describe the shape of the data with a JSON Schema (extended with a few x-* keywords for layout & validation messages) and the form is generated by jedison, a JSON-Schema form generator, mounted inside the AdminForth create/edit/show views.

JSON Form

Installation

npm i @adminforth/json-form

Usage

The plugin works only with json columns. If the target column is not of type json, the plugin throws during config validation.

import JsonFormPlugin from '@adminforth/json-form';
import { AdminForthDataTypes } from 'adminforth';

export default {
  // ...
  columns: [
    // ...
    {
      name: 'config',
      type: AdminForthDataTypes.JSON,   // required: must be JSON
      label: 'Config',
    },
  ],
  plugins: [
    new JsonFormPlugin({
      fieldName: 'config',
      schema: {
        title: 'RPG Character Creator',
        description: 'Create and customize your adventurer',
        type: 'object',
        'x-format': 'nav-vertical',
        properties: {
          identity: {
            title: 'Identity',
            type: 'object',
            'x-format': 'grid',
            required: ['name'],
            properties: {
              name: {
                title: 'Name',
                type: 'string',
                minLength: 2,
                'x-grid': { columns: 6 },
                'x-messages': { required: 'Every adventurer needs a name!' },
                default: 'Thalion Oakenshield',
              },
              // ...
            },
          },
          // ...
        },
      },
    }),
  ],
} as AdminForthResourceInput;

Options

Option Type Description
fieldName string Name of the JSON column the form edits. Required.
schema JsonFormSchema JSON-Schema-like description of the form. Required.

Supported schema

Standard JSON-Schema keywords: type (object / array / string / integer / number / boolean), properties, required, items, enum, const, oneOf, default, minLength, maxLength, minimum, maximum, minItems, maxItems, uniqueItems, readOnly, title, description.

Rendering keywords (x-format)

Container x-format Result
object nav-vertical Each property becomes a section in a vertical tab bar
object grid Properties laid out on a 12-column grid (see x-grid)
object (none) Properties stacked vertically
array nav-horizontal One tab per item; add / remove / reorder
array table / table-object Editable table of rows
array checkboxes-inline Inline checkbox group (arrays of enum values)
array (enum, none) Multi-select dropdown
scalar textarea Multi-line text
scalar color Color picker + hex input
scalar range Slider with live value
scalar radios / radios-inline Radio group (for enum or boolean)
scalar checkbox Single checkbox (for boolean)
scalar (none) Text / number input, enum → dropdown, boolean → dropdown

Other x-* keywords

Keyword Applies to Description
x-grid object properties { columns: 1..12 } placement inside a grid object
x-enumTitles enum / boolean Human-readable labels for each enum value (same order)
x-messages any Per-rule custom validation messages, e.g. { minLength, required }
x-titleIconClass fields Icon class rendered near the field title (e.g. bi bi-person-fill)
x-sortable arrays Enables reordering controls
x-titleTemplate array items Tab title template, e.g. {{ i1 }}) {{ value.name }}
x-discriminator oneOf objects Property name used to distinguish oneOf branches
x-switcherTitle oneOf branch Label of the branch in the variant switcher
x-enforceConst const markers Keeps a discriminator's const value locked (hidden from the UI)

Validation

Validation is performed live by jedison as the user edits. Failing rules block the form from being submitted and show an inline message next to the affected field. Messages can be customized per rule via x-messages; jedison's defaults are used otherwise.

Rendering & theming

The form is generated by jedison and mounted into the field's create/edit/show slot. The plugin ships a custom jedison theme (adminforthJedisonTheme.ts) plus CSS that styles the form with AdminForth's own design tokens — primary color, input borders/radius, labels and light/dark themes — so it blends into the admin panel. Object properties declared with x-format: nav-vertical render as a left-hand tab column (one tab per property), and nav-horizontal arrays render as a top tab bar; the theme also implements proper active-tab/pane switching (the stock jedison default theme relies on :target, which is unusable inside a SPA).

jedison is declared as a dependency of the plugin's frontend components (custom/package.json) and is installed automatically into the AdminForth SPA bundle.

License

MIT