Form basics

📘

Note

Forms are only available to Hosted and Channel apps.

User-facing forms, such as the app setup form, are created from a yaml definition. You define the fields, buttons, drop downs, etc. and rules for when to show/hide or when a field is valid and OCP will generate and display the form to your users.

Forms are divided into sections. Users fill out only one section at a time but can switch between any visible sections.

Sections contain one or more form elements or input fields. Each field has a number of required properties:

type - Which form element should be displayed on the form
key - Used to store and reference values when loading, saving, or interacting with a form
label - A visible label next to the field when the form is rendered
help - Additional context to provide to the user when they hover over a help icon

Create a setup form

All apps need a settings form, whether to display instructions to the user or to collect information such as credentials and configuration options. Your settings form is defined in src/settings-form.yml. If you initialized your app using the CLI, you will have a placeholder form.

A simple authentication form might look like this:

sections:
- key: auth
  label: Authentication
  elements:
  - type: text
    key: account
    label: Account
    help: Your account id for SampleIntegration
    hint: a012345
  - type: secret
    key: secret
    label: Secret
    help: Your SampleIntegration API secret
  - type: button
    label: Authenticate
    action: submit
    value: authenticate

This form would display a text box for account entry and a password field for the secret entry. An Authenticate button would be displayed below the secret field and remain disabled until the user fills in the account and secret fields.

Validate user data

The form definition can automate data validation. The simplest way to ensure the user enters reasonable data into your form is to add regex validations. All fields support a list of regex validations so you can add one or more validations each with their own error message. For example:

elements:
- type: text
  key: account
  label: Account
  help: Your account id for SampleIntegration
    hint: a012345
    requried: true
    validations:
    - regex: "/^.{0,7}$/"
      message: Too short. Check your SampleIntegration account for your account id.
    - regex: "/^a\\d{8,}+$/i"
      message: Please enter a valid account ID. Account IDs begin with the letter a, for example, a1234567.

In this case, if the account id field is left blank, when the user attempts to save/submit the form, a message indicating the field is required is displayed below the field (required: true). If the user enters a value 7 characters or less (regex: "/^.{0,7}$/"), the message indicating it is too short is displayed. Finally, if the entered value does not look like regex: "/^a\\d{8,}+$/i", then a message explaining what the account ID should look like is displayed. The validations are evaluated in the order defined and the message is used from the first one that fails.

Validations can be more complicated and reference data in other sections of the form. For more advanced use cases, see Form Validation.

Disable/hide fields, buttons, and sections

Any form element can be disabled or hidden, including fields and buttons using the disabled or visible properties. This is an ideal way to control the user flow. For example:

sections:
- key: auth
  label: Authentication
  elements:
  - type: text
    key: login
    label: Login
    help: Your account id or email you use to login to SampleIntegration
    hint: a012345 or [email protected]
    validations:
    - regex: "/^a\\d+$|^[email protected]+\\..{2,}$/"
      message: Please enter a valid account id or email address.
  - type: secret
    key: passcode
    label: Passcode
    help: A one time passcode generated by SampleIntegration
    visible:
    - key: auth.login
      regex: "/^[email protected]+\\..{2,}$/"
  - type: secret
    key: secret
    label: API Secret
    help: Your Sample Integration API secret
    visible:
    - key: auth.login
      regex: "^a\\d+$"
  - type: button
    label: Authenticate
    action: submit
    value: authenticate
    disabled:
      operation: any
      comparators:
      - key: auth.login
        empty: true

This example has a login text field and two different secret fields depending on what type of authentication the user needs.

If the user fills out the login field with an account ID such as a012345, then the API Secret field will become visible as soon as the regex matches an account id (it does not wait for the form to be submitted).

Alternatively, if the user fills out their email address for the login field, the passcode field will become visible.

Finally, the button to submit the form will be disabled until the user types anything into the login field. This way the user can type an invalid login value, submit the form, and get errors directing them to enter a valid account ID or email.

See Advanced Predicates for more information.

Insert dynamic content

In addition to showing and hiding sections and elements dynamically, you can insert dynamic values into certain visible attributes of your form elements using the mustache templating language. This means you can display a code or change a URL in the content you display to the user depending on what form data they have submitted or dynamic properties set by your app.

The following form element attributes support mustache templating: label, help, text, and href.

- type: instructions
  text: |
    You will need to enable this app as an Integration in your [Magento Admin](https://{{{setup.store_domain}}}/admin).
    Use the following options to configure the integration:
    - Name: `Zaius Product Sync`
    - Email: `[email protected]`
    - Callback URL: `{{{setup.callback_url}}}`
    - Identity link URL: `https://app.zaius.com`
- type: link_button
  label: Begin Integration
  help: Creating a new integration in Magento
  style: primary
  href: https://{{{setup.store_domain}}}/integrations/new

📘

Note

When referencing form data using mustache, you must reference the data as <section_key>.<field_key> (for example, setup.store_domain) regardless of which section you are in.