`<bmx-form-designer>`

The designer for bmx-form: fields dragged from a palette onto a page, arranged into sections, repeating sections and pages, and set up in a properties panel - labels, names, options, widths, checks, conditions and worked-out values - with a live preview and the JSON beside it.

8 properties · 2 events · 11 methods · 10 parts

Example

Drag a field from the list onto the page, or click one to add it after the chosen field. Choose a field to set its label, checks and conditions; renaming it rewrites every condition that reads it. Preview runs the form, JSON is the schema a bmx-form takes, and Start from… offers templates.

Show markup

<bmx-form-designer id="ex-fd" style="--bmx-form-designer-height: 46rem"></bmx-form-designer>

<div class="row" style="margin-block-start: 1rem">
  <span class="note" id="ex-fd-out">
    Drag a field from the list onto the page, or click one to add it after the chosen field. Choose a field to set its
    label, checks and conditions; renaming it rewrites every condition that reads it. <em>Preview</em> runs the form,
    <em>JSON</em> is the schema a <code>bmx-form</code> takes, and <em>Start from…</em> offers templates.
  </span>
</div>

<script type="module">
  await customElements.whenDefined('bmx-form-designer');
  const designer = document.getElementById('ex-fd');
  const out = document.getElementById('ex-fd-out');

  await designer.loadTemplate('order');
  designer.addEventListener('bmxFormDesignerChange', event => {
    const fields = JSON.stringify(event.detail.schema).length;
    out.textContent = `bmxFormDesignerChange - ${event.detail.action}; the schema is ${fields} characters of JSON.`;
  });
</script>

WHAT IT DOES FOR YOU

Names follow labels until you change them. Renaming a field rewrites every condition, calculation, rule and {{ placeholder }} that reads it. A condition can be built from a field, a test and a value, or typed as an expression that is checked as you type. Problems - a name used twice, a condition reading a field that does not exist, totals that work each other out - are counted in the toolbar and marked on the fields. Every change can be undone. Templates (a contact form, a registration in steps, an order with lines and totals, a survey) give a start.

THE RESULT

schema is the form: give it to a bmx-form (or save it, from bmxFormDesignerChange). It is plain JSON, and the JSON view edits it directly.

KEYBOARD

The fields are a tree: arrow keys move between them (Right into a section, Left out of it), Alt+Up and Alt+Down move a field, Alt+Left takes it out of its section and Alt+Right puts it into the section above. Enter goes to its properties, Delete removes it, Ctrl+D duplicates it, Ctrl+Z and Ctrl+Y undo and redo. A field in the palette is added with Enter, after the chosen one.

Properties

Property	Attribute	Type	Default	Description
`functions`	property only	`Record<string, BmxFormFunction>`	—	Functions the form's expressions may call, so the designer knows them and the preview runs them. A property.
`label`	`label`	`string`	—	The designer's accessible name.
`locale`	`locale`	`string`	—	The language the preview shows numbers and dates in.
`readonly`	`readonly`	`boolean`	`false`	Shows the form without letting it be changed.
`schema`	`schema`	`BmxFormSchema \| string`	`{}`	The form being designed, as a property or JSON. Changes write back here.
`strings`	`strings`	`Partial<BmxFormDesignerStrings> \| string`	—	Replacements for the designer's own wording, as a property or JSON.
`templates`	`templates`	`boolean`	`true`	Offers the templates in the toolbar.
`view`	`view`	`BmxFormDesignerView`	`'design'`	`design`, `preview` or `json`.

Events

Event	Detail	Description
`bmxFormDesignerChange`	`BmxFormDesignerChangeDetail`	The form changed.
`bmxFormDesignerSelect`	`BmxFormDesignerSelectDetail`	Another field was chosen.

Methods

Method	Signature	Description
`addField`	`addField(type: BmxFormFieldType, path?: number[]) => Promise<number[]>`	Adds a field of a type: after the chosen field, or at a place (`[page, index]`).
`downloadJSON`	`downloadJSON(fileName?: string) => Promise<void>`	Saves the form as a JSON file through the browser's download.
`getProblems`	`getProblems() => Promise<BmxFormDesignProblem[]>`	What is wrong with the form.
`getSchema`	`getSchema() => Promise<BmxFormSchema>`	The form as it now is.
`loadTemplate`	`loadTemplate(id: string) => Promise<boolean>`	Replaces the form with a template, by id: `blank`, `contact`, `registration`, `order` or `survey`.
`redo`	`redo() => Promise<boolean>`
`removeField`	`removeField(path?: number[]) => Promise<void>`	Removes a field (the chosen one, by default).
`selectField`	`selectField(path: number[] \| null) => Promise<void>`	Chooses a field, by place, or none.
`setFocus`	`setFocus() => Promise<void>`	Moves focus to the chosen field, or the first.
`setSchema`	`setSchema(schema: BmxFormSchema) => Promise<void>`	Replaces the form (an undo step).
`undo`	`undo() => Promise<boolean>`

CSS shadow parts

Part	Description
`canvas`	the page being designed.
`card`	one field on the canvas. Also `card-selected`, `card-problem`.
`drop-marker`	where a dragged field will land.
`inspector`	the properties panel.
`json`	the JSON view.
`page-tabs`	the pages of a form in steps.
`palette`	the list of field types.
`palette-item`	one type in it.
`preview`	the preview of the form.
`toolbar`	the bar across the top.

CSS custom properties

Property	Description
`--bmx-form-designer-accent`	The chosen card, the drop marker and active tabs.
`--bmx-form-designer-border`	Lines between the panels and around cards.
`--bmx-form-designer-canvas-background`	Behind the page being designed.
`--bmx-form-designer-height`	How tall the designer is.
`--bmx-form-designer-panel-background`	The palette and properties panels.
`--bmx-form-designer-paper-background`	The page itself.