form

Using forms in mobile apps enables users to effortlessly input and submit information, enhancing interaction and user engagement.

A component.form acts as a wrapper/container for your app’s fields and UI components. Any component can be added inside the form, including:

Nested input field components (text fields, checkboxes, date pickers, etc.)
Custom components created in your solution
Other Jigx components (like charts, lists, or layouts)

Benefits

Form-wide referencing: Each form has a unique instanceId, allowing you to reference the entire form in expressions, actions, or functions. This makes it easier to manage validations, submissions, and state.
Unified wrapper: A single component.form can wrap any jig.default children, such as a chart or segmented control, as well as all form input fields like text and email fields. This allows you to mix layouts, charts, and non-field components within the same form without breaking form handling.
No need to place multiple forms on a single screen to handle different UI structures or separated field groups. You only need one form wrapper per logical form.
The form automatically collects and manages all its nested field components.

Configuration options

Some properties are common to all components, see Common component properties for a list and their configuration options.

Core structure

children

Define the content of the form by adding any components applicable to jig.default. See the list of available components.

instanceId

The unique identifier for the form. The instanceId is a unique identifier assigned to the form component. It allows other parts of the app—such as functions, actions, or conditional logic—to reference this specific form. By using the instanceId, you can programmatically control when the form is shown or hidden, update its content dynamically, or trigger interactions tied to that particular instance.

Other options

isDiscardChangesAlertEnabled

When set to true the modal window preventing accidental deletion of your data without saving will pop up.

initialValues

Specify the data to be used as initialValues for fields in the form. Using the reset-state action with initialValues does not clear the form, it resets the form back to it's initialValue. Tip: For initialValues on a to function isDocument: true in the datasource, this way you don't have to set it up in the individual components. It is set up in one place and the form will match the components to the column names of the datasource. See the example below for Form with initialValue.

State Configuration

Key

Notes

[email protected].

data isValid isDirty response

State is the variable of the component.

[email protected].

activeItemId now

Global state variable that can be used throughout the solution.

Examples and code snippets

Form for creating a record

Here is an example of a form for creating records in the database. See submit-form for information on how to create a record.

Examples:

See the full example using dynamic data in GitHub.

form (dynamic)

children:
  - type: component.form
    instanceId: simple-form
    options:
      children:
          - type: component.text-field
            instanceId: firstname
            options:
              label: First name
          - type: component.text-field
            instanceId: lastname
            options:
              label: Last name
          - type: component.email-field
            instanceId: email
            options:
              label: Email
          - type: component.number-field
            instanceId: phone
            options:
              label: Phone number

Form for updating records

This example shows how a form is used to update an existing records in the database. Notice that a new variable called initialValue: has been added, we load the data that we have stored in the database and then change it. See the execute-entity action for information on how to update a record.

Examples: See the full example using dynamic data in GitHub.

Datasource: See the full datasource for dynamic data in GitHub.

actions:
  - children:
       - type: action.execute-entity
         options:
          title: Update Record
          provider: DATA_PROVIDER_DYNAMIC
          entity: default/form
          method: update
          data:
            id: [email protected] 
            firstname: [email protected]
            lastname: [email protected]
            email: [email protected]
            phone: [email protected]
          onSuccess: 
            type: action.go-back
                
children:
  - type: component.form
    instanceId: form-update
    options:
      children:
          - type: component.text-field
            instanceId: firstname
            options:
              label: First name
              initialValue: [email protected]
          - type: component.text-field
            instanceId: lastname
            options:
              label: Last name
              initialValue: [email protected]
          - type: component.email-field
            instanceId: email
            options:
              label: Email
              keyboardType: email-address
              initialValue: [email protected]
          - type: component.number-field
            instanceId: phone
            options:
              label: Phone number
              keyboardType: number-pad
              initialValue: [email protected]

datasources:
  form-update:
    type: datasource.sqlite
    options:
      provider: DATA_PROVIDER_DYNAMIC
      entities:
        - default/form
      query: |
        SELECT
          id,
          '$.firstname',
          '$.lastname',
          '$.phone',
          '$.email',
          '$.category'
        FROM [default/form] WHERE '$.category' = "update-form"

Form with section and field-row

This example shows how you can format your form with sections and field-rows to create a visually appealing form.

Examples:

See the full example using dynamic data in GitHub.

form-section (dynamic)

children:
  - type: component.form
    instanceId: personal-information-form
    options:
      children:
          - type: component.section
            options:
              title: Personal information
              children:
                  - type: component.field-row
                    options:
                      children:
                          - type: component.text-field
                            instanceId: firstname
                            options:
                              label: First name
                          - type: component.text-field
                            instanceId: lastname
                            options:
                              label: Last name
                  - type: component.field-row
                    options:
                      children:
                        - type: component.email-field
                          instanceId: email
                          options:
                            label: Email
                        - type: component.number-field
                          instanceId: phone
                          options:
                            label: Phone number
          - type: component.section
            options:
              title: Address information
              children:
                - type: component.text-field
                  instanceId: address
                  options:
                    label: Address
                - type: component.field-row
                  options:
                    children:
                      - type: component.text-field
                        instanceId: city
                        options:
                          label: City
                      - type: component.number-field
                        instanceId: zip
                        options:
                          label: Zip code

Form with initialValue

In this example, you tap on a contact in the contact-list and the new-contact form opens with the contact's details loaded. For initialValues on a form to function the isDocument: true in the datasource is set, this way you don't have to set it up in the individual components. It is set up in one place under InitialValue and the form will match the components to the column names of the datasource.

title: Add new contact
type: jig.default
icon: book-address

inputs:
  id: 
    type: string
    required: true
    
header:
  type: component.jig-header
  options:
    height: medium
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1517245386807-bb43f82c33c4?ixlib=rb-4.0.3&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1740&q=80
        
children:
  - type: component.form
    instanceId: new-contact
    options:
# With isDocument: true in the datasource set, 
# you don't have to set initialValue up in the individual components.
# It is set up in one place and the form will match the components to the column
# names of the datasource.   
      initialValues: [email protected]
      isDiscardChangesAlertEnabled: false
      children:
        - type: component.section
          options:
            title: Personal information
            children:
              - type: component.text-field
                instanceId: firstName
                options:
                  label: First name
              - type: component.text-field
                instanceId: lastName
                options:
                  label: Last name
              - type: component.email-field
                instanceId: email
                options:
                  label: Email
                  icon: email
              - type: component.number-field
                instanceId: phone
                options:
                  label: Phone number
                  icon: phone
        - type: component.section
          options:
            title: Business information
            children:
              - type: component.text-field
                instanceId: jobTitle
                options:
                  label: Position
              - type: component.text-field
                instanceId: companyName
                options:
                  label: Company Name
            
actions:
  - children:
      - type: action.execute-entity
        options:
          title: Create Record
          provider: DATA_PROVIDER_DYNAMIC
          entity: default/contacts
          method: create
          data:
            firstName: [email protected]
            lastName: [email protected]
            email: [email protected]
            phone: [email protected]
            jobTitle: [email protected]
            companyName: [email protected]

datasources:
  contactData: 
    type: datasource.sqlite
    options:
# The isDocument property for the datasource is set to true.
# As a result, the datasource will return as a single record to be displayed,
# instead of an array of records.  
      isDocument: true
      provider: DATA_PROVIDER_DYNAMIC
      entities:
        - default/contacts
      query: |
        SELECT 
          id,
          '$.firstName',
          '$.lastName',
          '$.jobTitle',
          '$.companyName',
          '$.phone',
          '$.email' 
        FROM 
          [default/contacts]
         WHERE
          id = @contactId
      queryParameters:
        contactId: [email protected]

title: Contacts
type: jig.list
icon: contact

header:
  type: component.jig-header
  options:
    height: small
    children:
      type: component.image
      options:
        source:
          uri: https://images.unsplash.com/photo-1528747045269-390fe33c19f2?w=500&auto=format&fit=crop&q=60&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxzZWFyY2h8Mnx8Y29udGFjdCUyMGxpc3R8ZW58MHx8MHx8fDA%3D

data: [email protected]
item:
  type: component.list-item
  options:
    title: [email protected] & ' ' & @ctx.current.item.lastName
    subtitle: [email protected]
    description: [email protected]
    leftElement: 
      element: avatar
      text: A
    onPress: 
      type: action.go-to
      options:
        linkTo: form-initialvalue
        parameters: 
          id: [email protected]

Previoustitles Nextgrid

Last updated 2 months ago

Was this helpful?

Good afternoon