About Docs GitHub
arrow_upward Back to top
Docs (4.0.0)
arrow_upward Back to top
Form context

class UIFormContext

An object that contains form field data along with validation tests.

class UIFormContext<TData = any>
extends ManagedObject

Description

The UIFormContext class provides a data model for user input, allowing UI components to read and write data from/to a single form context object — instead of having to use individual bindings and event handlers for each field.

The form context object provides methods to get, set, and clear field values, as well as methods to add validation tests and validate current field values. Form values and validation errors can be bound to any other view properties.

The overall validity of the form context can be determined using the UIFormContext.validateAll() method and the valid property.

To use a UIFormContext object with UITextField or UIToggle components, set their formField property to a field name, and include them in a UIForm container or add a formContext property directly to your activity or view composite (see examples).

To use a UIFormContext object with any other (custom) view, add a formContext property binding and handle changes to obtain the current input value using the UIFormContext.get() method. When the user inputs a new value, use the UIFormContext.set() method to set and validate the value.

Examples

// Use form fields in a form
const FormView = ui.form(
  { formContext: bound("fooForm") },
  ui.textField({ formField: "foo" }),
  ui.label({
    style: myStyles.errorLabel,
    hidden: bound.not("fooForm.errors.foo"),
    text: bound.string("fooForm.errors.foo.message")
  }),
  ui.button("Go", "Submit")
);

class MyActivity extends Activity {
  protected ready() {
    this.view = new FormView();
  }

  fooForm = new UIFormContext({ foo: "" })
    .addTest("foo", (t) => {
      t.required();
      t.assert(t.value.length > 3, strf("Foo is too short"));
    });

  onSubmit() {
    this.fooForm.validateAll();
    // now, this.fooForm.valid is false if
    // the field 'foo' isn't set or too short
  }
}

// Use form fields with formContext on the activity
const MyView = ui.cell(
  ui.textField({ formField: "foo" }),
  // ...
);

class MyActivity extends Activity {
  protected ready() {
    this.view = new FormView();
  }
  formContext = new UIFormContext({ foo: "" });
  // ...
}

Constructor

Type Members

  • class ValidationTest staticA class that represents a form validation test, passed to a form validation function.

Instance Members

  • values readonlyAn object that contains current form field values.
  • errors readonlyAn object that contains validation errors for fields that have been validated.
  • errorCount readonlyThe number of errors that have been recorded after validation of one or more fields.
  • valid readonlyTrue if there are currently no recorded errors.
  • get(name)Returns the value of the form field with the specified name.
  • set(name?, value?, validate?)Sets the value of the form field with the specified name.
  • setAll(values?, validate?)Sets multiple form fields using the provided values.
  • unset(name)Removes the value for the form field with the specified name.
  • clear()Removes all field values and errors.
  • serialize()Returns a plain object that contains properties for all fields and their values.
  • emitFormChange()Emits a FormChange change event on this object.
  • addTest(name, f)Adds a validation test for the specified field.
  • addRequired(name, errorMessage?)Adds a validation test for the specified field, which results in an error if the field is null, undefined, false, or an empty string.
  • validate(name)Validates the current value of the specified form field.
  • validateAll()Runs all validation tests and updates the errors object.

Inherited Members