Forms and dialogs

A large part of building an interface is letting the user enter information. In x4js this usually goes through the Form object, most often placed in a Dialog.

Form

A Form is a container that knows how to find its fields. It walks through all its children, at any depth, and keeps those that have a name.

import { Checkbox, Form, TextEdit } from 'x4js';

const form = new Form( {
  content: [
    new TextEdit( { label: "Name", name: "name", value: "", required: true } ),
    new TextEdit( { label: "Age", name: "age", type: "number", value: 30 } ),
    new Checkbox( { label: "Active", name: "active", checked: true } ),
  ]
});

Three methods do most of the work:

Method	Role
`setValues( values )`	Fills the fields from an object.
`getValues( )`	Returns an object with the value of each field.
`validate( )`	Checks the fields and returns the values, or `null` if the form is invalid.

TextEdit suits ordinary labelled fields. Use Input when you need the field alone.

You can put your own controls in a form: they only need a name and to answer the form-element interface.

Dialog

A Dialog is a window with a title, a content and buttons. In the usual case you compose it rather than derive a class from it: a dialog, a form, buttons.

import { Checkbox, Dialog, Form, TextEdit } from 'x4js';

async function editUser( ) {
  const dlg = new Dialog( {
    title: "User",
    modal: true,
    movable: true,
    form: new Form( {
      content: [
        new TextEdit( { label: "Name", name: "name", value: "", required: true } ),
        new TextEdit( { label: "Age", name: "age", type: "number", value: 30 } ),
        new Checkbox( { label: "Active", name: "active", checked: true } ),
      ]
    }),
    buttons: [ "ok.outline.default", "cancel.outline" ],
  });

  // wait until the user closes the dialog
  if( await dlg.showAsync( )=="ok" ) {
    const values = dlg.getValues( );
    console.log( values.name, values.age, values.active );
  }
}

showAsync returns the name of the button that closed the dialog.

Buttons

Buttons are declared by name. The predefined names are ok, cancel, yes, no, retry, abort and save, and their text follows the current language. Options are added after a dot:

Syntax	Result
`"ok"`	OK button.
`"ok.default"`	OK button, marked as the default button.
`"cancel.outline"`	Cancel button, in outline style.
`"ok.disabled"`	OK button, disabled at start.
`"-"`	Flexible space between two groups of buttons.

Each option also becomes a CSS class of the button, so you can add some for your own styles.

You can also pass your own Button objects in the list.

Asking a question

For a message or a confirmation, there is no dialog to build:

import { MessageBox } from 'x4js';

const answer = await MessageBox.showAsync( "Delete this user?", [ "yes", "no" ] );
if( answer=="yes" ) {
  // ...
}

Class	Use
`MessageBox`	Show a message, ask for a confirmation.
`InputBox`	Ask for a value.
`PromptBox`	Ask for a value with the editor of your choice.
`ProgressionBox`	Follow a long operation, with its texts and errors.

Before inventing a progress mechanism for a long operation, look at ProgressionBox: it already provides the display of the text, the percentage and the errors.