Add forms to UI Builder pages

  • Release version: Xanadu
  • Updated August 1, 2024
  • 2 minutes to read
    • Summarize
    Summarized using AI
    This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete.

    Summary of Add forms to UI Builder pages

    The Form component in UI Builder allows you to add one or more interactive forms to your UI Builder pages. This enables data collection and interaction by defining form fields and their properties, such as required inputs. You can extend functionality by embedding forms directly on pages, including inline tabs or modals.

    Show full answer Show less

    Key Features

    • Multiple Forms per Page: Add several forms on the same page, even if one form is nested within another component.
    • Form Controller Preset: For pages with pre-Xanadu forms, you must apply a preset to all form controllers before adding multiple forms to ensure proper functionality.
    • Primary Form Identification: Exactly one form controller should be flagged as Is mapped to app Shell, marking it as the primary form to handle global events consistently.
    • Configuration Management: You can configure which form controller is mapped to the app shell via the UI Builder configuration panel to maintain one primary form controller per page.
    • Advanced Event Handling: When a form’s Is mapped to app shell property is true, it automatically manages key form events like screen status changes, configuration menu updates, phone requests (with CTI plugin), and loading states.

    Practical Application for ServiceNow Customers

    By integrating forms into UI Builder pages, you can enhance user interactions through inline edits, modals, and complex form setups. Applying the form controller preset is essential when upgrading older pages to support multiple forms, ensuring stable and expected behavior. Correctly mapping one form controller as primary helps manage shared events across forms, improving consistency and control.

    Developers with experience in event handling can leverage the automatic event management features enabled by the primary form controller setting to build responsive and interactive form-based experiences.

    Next Steps

    To implement forms effectively:

    • Apply the form controller preset on all forms if migrating from older releases.
    • Ensure exactly one form controller is set as mapped to the app shell.
    • Configure form fields and their properties according to your data collection needs.
    • Use advanced event handling features for enhanced interaction if applicable.

    Use the Form component to add one or more forms to UI Builder pages.

    Add functionality to your UI Builder pages by including forms. You define the fields on the form and their properties, such as making them required. Then, collect data as the form is completed and submitted.
    Figure 1. Form component example
    Sample form component named transfer order line task on a page.
    You can add more than one form to a single page. You can also add a form to a page that already contains a component with a nested form. Sample use cases include:
    • Extend record pages by adding an inline tab with a form using its own form controller instance.
    • Add modals with a form on a record page.
    For existing pages with forms created in a pre-Xanadu ServiceNow release, you must apply a preset to the original form before adding another form to the page. Applying the preset is a prerequisite to adding multiple forms to a page and enables multiple forms to work as expected on a page. The form controller preset should be applied onto all form controllers.
    1. Open the page containing an existing form.
    2. In the data drawer, expand the Data resources list and select the original form controller.

      Data drawer with Data resources list expanded and black arrow pointing to form controller.

    3. Select the Preset field.
    4. Select Form controller preset.

      Edit form controller pop-up with black arrow pointing to preset field and second black arrow pointing to form controller preset option.

    5. Select Apply.
    6. Select the X to close the Edit Form Controller pop-up.

      Exactly one of your form controllers should have the Is mapped to app Shell property set to true. This property is used to specify the primary form on the page. The primary form is responsible for handling global events. You shouldn't set the property to true for more than one form controller or have zero form controllers with the property set to true.

    7. Open the page containing one or more forms.
    8. In the content tree, select a form.

      Content tree with black arrow pointing to a form component.

    9. In the configuration panel, on the Configure tab, select Form Controller.

      Form configuration panel with configure tab displayed and black arrow pointing to form controller link.

    10. On the Edit Form Controller pop-up, scroll down in the Form Controller list to find the Is mapped to App Shell option.

      Edit form controller pop-up window with black arrow pointing to is mapped to app shell option.

    11. Select or clear the option for each form component on the page to confirm that exactly one form controller is mapped to the app shell.

    Advanced form event handling

    Experienced developers with knowledge of conflict event handling may find the following details useful.

    If isMapped to app shell is set to true, the form handles these events automatically:
    Screen Status Changed
    • Description: Action to indicate that a form is dirty.
    • Output: CTRL_RECORD#SCREEN_STATUS_CHANGED
    Update Configuration Menu Requested
    • Description: Action to set record configuration menu items on the avatar menu.
    • Output: CTRL_RECORD#UPDATE_CONFIGURATION_MENU_REQUEST
    Phone Requested
    • Description: Action to make a call when the CTI plugin is enabled.
    • Output: CTRL_RECORD#PHONE_REQUESTED
    Form Loading State Changed
    • Description: Action to show a loading spinning when that form is loading data.
    • Output: CTRL_RECORD#FORM_LOADING_STATE_CHANGED

    For detailed information about the Form component and its properties, see Form Overview on the ServiceNow Developer Site.