Form

A Form is a fundamental component that displays user interfaces that allow users to input (or change) data and submit it to the app (a server) for further processing.

The component provides context values with which you can access some internal properties:

• $data: This property represents the value of the form data. You can access the fields of the form using the IDs in the bindTo property of nested FormItem instances. $data also provides an update method as a shortcut to the Form's exposed update method.

You can learn more about this component in the Using Forms article.

Properties

buttonRowTemplate

This property allows defining a custom component to display the buttons at the bottom of the form.

The following example demonstrates using it:

<App>
  <Form id="searchForm" padding="0.5rem"
    data="{{ search: 'Seattle', caseSensitive: false }}"
    onSubmit="() => {isSearching = true; delay(1000); isSearching = false; }"
    saveLabel="Search"
    var.isSearching="{false}">
      <Text>Please specify the name to include in the search:</Text>
      <FormItem bindTo="search" width="280px" />
      <FormItem type="checkbox" label="Case sensitive?" bindTo="caseSensitive" />
      <property name="buttonRowTemplate">
        <HStack gap="0.5rem" borderTop="1px solid #ddd" paddingVertical="1rem">
          <Button label="Test Search Server" type="button"
            themeColor="secondary" variant="outlined"
            onClick="toast('Search server is ok.')"/>
          <SpaceFiller/>
          <Button type="submit" enabled="{!isSearching}" icon="search"
            label="{isSearching ? 'Searching...' : 'Search'}"/>
        </HStack>
      </property>
  </Form>
</App>  

This example mimics a one-second search and turns off the submit button during the operation. Also, it adds a Test Search Server button:

cancelLabel (default: "Cancel")

This property defines the label of the Cancel button.

data

This property sets the initial value of the form's data structure. The form infrastructure uses this value to set the initial state of form items within the form.

enabled

Whether the form is enabled or not. The default value is true.

itemLabelBreak (default: true)

This boolean value indicates if form item labels can be split into multiple lines if it would overflow the available label width. Individual FormItem instances can override this property.

itemLabelPosition (default: "top")

This property sets the position of the item labels within the form.Individual FormItem instances can override this property.

Available values:

itemLabelWidth

This property sets the width of the item labels within the form. Individual FormItem instances can override this property.

keepModalOpenOnSubmit (default: false)

This property prevents the modal from closing when the form is submitted.

saveInProgressLabel (default: "Saving...")

This property defines the label of the Save button to display during the form data submit (save) operation.

saveLabel (default: "Save")

This property defines the label of the Save button.

submitMethod

This property sets the HTTP method to use when submitting the form data. If not defined, put is used when the form has initial data; otherwise, post.

submitUrl

URL to submit the form data.

swapCancelAndSave

By default, the Cancel button is to the left of the Save button. Set this property to true to swap them or false to keep their original location.

Events

cancel

The form infrastructure fires this event when the form is canceled.

reset

The form infrastructure fires this event when the form is reset.

submit

The form infrastructure fires this event when the form is submitted. The event argument is the current data value to save.

<App>
  <Form padding="0.5rem"
    data="{{ name: 'Joe', age: 43 }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FlowLayout columnGap="12px" paddingBottom="6px">
      <FormItem bindTo="name" label="Customer name" width="50%" />
      <FormItem bindTo="age" label="Age" type="integer" width="50%"
        zeroOrPositive="true" />
    </FlowLayout>
  </Form>
</App>  

Exposed Methods

reset

Call this event to reset the form to its initial state.

update

You can pass a data object to update the form data. The properties in the passed data object are updated to their values accordingly. Other form properties remain intact.

This method updates the form data with the change passed in its parameter. The parameter is a hash object, and this method updates the Form's properties accordingly.

<App>
  <Form id="myForm" padding="0.5rem"
    data="{{ name: 'Joe', age: 43, $update: 123 }}"
    onSubmit="(toSave) => toast(JSON.stringify(toSave))">
    <FlowLayout columnGap="12px" paddingBottom="6px">
      <FormItem bindTo="name" label="Customer name" width="50%" />
      <FormItem bindTo="age" label="Age" type="integer" width="50%"
        zeroOrPositive="true" />
    </FlowLayout>
    <Button onClick="() => $data.update({age: $data.age + 1})" >
      Increment age (1)
    </Button>
    <Button onClick="() => myForm.update({age: $data.age + 1})" >
      Increment age (2)
    </Button>
    <Button onClick="() => myForm.update({name: $data.name + '!', age: $data.age + 1})" >
      Update name and age
    </Button>
  </Form>
</App>  

Styling

You can use these theme variables to style a Form component:

• gap-Form: the gap between the components directly nested into a form.
• gap-buttonRow-Form: the gap between the Cancel and Save buttons in the button row of a form.

Theme Variables