Form elements

Section

A form can have one or more sections allowing you to organize input required from the user, such as having a section just for authentication and a separate section for configuration.

sections:
  - key: auth
    label: Authenticate
    properties:
      - authorized
    elements:
      - ...
  - key: config
    label: Configuration
    disabled:
      key: auth.authorized
      equals: false
    elements:
      - type: instructions
        text: Finish installing the app by filling out the form below:
      - ...

Sections are accordions where only one section can be open/interacted with at a time. This way your app only has to worry about one section being updated at a time.

Common Attributes

All form elements include the following base attributes:

Attribute	Purpose
type	The element type (for example, toggle, text, secret, etc.)
visible	(optional) A Predicate whether or not to show the element

All input elements share the following attributes:

Attribute	Purpose
type	The element type (for example, toggle, text, secret, etc.)
key	A unique identifier used to access the data associated with this form field
label	The label to show above the field
help	An explanation of the input value or instructions to help the user make the right choices
defaultValue	(optional) The default value if the field has not been edited by the user
required	(optional) A predicate that if evaluated to true, will require the field be non-empty before submitting the form
validations	(optional) A list of Form Validations to be performed before submitting the form
disabled	(optional) A predicate whether or not the element should appear disabled (and be non-interactable)
readonly	(optional) A predicate whether or not to show the element

Any form element can be dynamically shown/hidden and any input can be dynamically disabled or required depending on the state of the entire form using predicates. Predicates are also used in validations to reduce the amount of logic you need to allow your app to process the form.

Form Elements

Each form section must have one or more of the following elements:

Toggle

type: toggle

A switch to turn an option on or off. This results in a boolean value.

- type: toggle
  key: mms
  label: MMS
  help: Send an image along with the message.  Additional messaging rates may apply.
- type: toggle
  key: shortenLinks
  defaultValue: true
  label: Shorten links and enable click tracking
  help: Shorten links to reduce message character counts and record click activity when links are followed.

Text Input

type: text

Allows input of plain text. Can be configured for single- or multi-line input.

- type: text
  key: message
  label: Message
  multiline: true
  help: The SMS message to deliver. Aim to stay under 140 characters for optimal formatting on mobile devices. Messages longer than 70 characters may be split into multiple messages.
  required: true
- type: text
  key: image
  label: Image URL (optional)
  help: The URL of an image to send along with the message. The URL must be publicly accessible and the image size must be **less than 525KB**.
  required:
    key: mms
    equals: true

Additional Attributes for Text Elements

Attribute	Purpose
dataType	(Optional) The preferred input data type if supported by the browser. Allowed values: `text`, `number`, `email`, `phone`
hint	(Optional) Hint text to display to the user until a selection is made. Only applicable to select display mode.
multiline	(Optional) True/false if the text input should allow multiple lines of text

Secret

type: secret

Allows the input of sensitive text. Hides input as the user types and once saved, displays the input as asterisks to keep the data protected. The original value cannot be accessed by the user after submitting the form.

- type: secret
  key: client_secret
  label: Client Secret
  help: Get your [Client Secret](https://support.criteo.com/s/article?article=API-Getting-Started&language=en_US) from Criteo

Additional attributes for Secret Elements

Attribute	Purpose
hint	(Optional) Hint text to display to the user until a selection is made. Only applicable to select display mode.

Select

type: select

Allows the user to choose one of a number of options. Can be displayed as a set of radio buttons or a drop-down. By default, it automatically chooses radio buttons or a drop-down based on the number of options unless the data source is remote, in which case it always shows a drop-down.

- type: select
  key: resync_day
  label: Re-sync Day
  help: Choose a day of the week to re-sync your attributes
  options:
    - text: Monday
      value: 1
    - text: Wednesday
      value: 3
    - text: Friday
      value: 5

- type: select
  key: advertiser_id
  label: Advertiser ID
  help: Choose the advertiser in your portfolio to sync to
  dataSource:
    type: app
    function: criteo_portfolio
  disabled:
    key: auth.authConfirmed
    equals: false

Additional Attributes for Select Elements

Attribute	Purpose
display	(Optional) The preferred display format for the select element. Allowed values: `auto`, `radio`, or `select`
options	(Optional) A hard-coded list of options to present to the user in the form of objects containing `text` and `value` (see example above).
dataSource	(Optional) For dynamic select options, specify a data source INSTEAD of options. Supports `http` or `app` as the source type. See Remote Select Options for allowed values and implementation.
hint	(Optional) Hint text to display to the user until a selection is made. Only applicable to `select` display mode.

Multi-Select

type: multi_select

Allows the user to choose one or more options. Can be displayed as a set of checkboxes or a multi-select drop-down. By default, it automatically chooses checkboxes or a drop-down based on the number of options.

- type: multi_select
  key: fields
  label: Fields to Sync
  help: Select the fields you want to sync from ODP. Selecting a new field will require to click save for that field to start sending. Removing a field from the list will NOT delete the data in Hubspot
  dataSource:
    type: app
    function: get_zaius_field_options
  defaultValue:
    - insights.order_likelihood
    - insights.ttno_days
    - observations.discount_usage
    - observations.average_order_revenue
    - observations.order_revenue_percentile
    - observations.total_revenue
    - observations.total_revenue_percentile
    - observations.order_count
    - observations.order_count_percentile

Additional Attributes for Multi-Select Elements

Attribute	Purpose
display	(Optional) The preferred display format for the select element. Allowed values: `auto`, `checkbox`, or `select`
options	(Optional) A hard-coded list of options to present to the user in the form of objects containing `text` and `value` (see example above).
dataSource	(Optional) For dynamic select options, specify a data source INSTEAD of options. Supports `http` or `app` as the source type. See Remote Select Options for allowed values and implementation.
hint	(Optional) Hint text to display to the user until a selection is made. Only applicable to `select` display mode.

Button

type: button

Allows the user to perform an action by clicking the button. Each section must have at least one submit style button if it contains form data. Buttons can also be used to link to external sites when the user should perform an action outside the app store page.

- type: button
  label: Save
  action: save
  style: primary
- type: button
  label: Start Sync
  action: sync
  disabled:
    key: fieldsSaved
    equals: false

Additional Attributes for Button Elements

Attribute	Purpose
action	A string value representing the action this button performs to be handled by the (OnFormSubmit)[doc:zipcoreconcepts-processing-forms#settings-form] handler of the app (is not visibly shown to the user).
style	(Optional) The style of the button: `primary`, `none` (default), or `danger`

Link Button

type: link_button

A button that opens a URL in a new tab instead of submitting a form. Can be useful for directing the user to a settings page in the third-party integration.

- type: link_button
  label: Begin Integration
  help: Creating a new integration in Magento
  style: primary
  href: https://{{{setup.store_domain}}}/integrations/new

Additional Attributes for Link Button Elements

Attribute	Purpose
href	A URL to the desired page to open in a new tab. Should be `https` whenever possible. Supports mustache substitutions.
style	(Optional) The style of the button: `primary`, `none` (default), or `danger`

OAuth Button

type: oauth_button

A button that opens a URL in a new tab instead of submitting a form. Can be useful for directing the user to a settings page in the third-party integration.

- type: oauth_button
  label: Authorize
  help: Creating a new integration in Magento
  style: primary
  href: https://{{{setup.store_domain}}}/integrations/new

Divider

type: divider

Visually separates a set of elements.

- type: divider

Instructions

type: instructions

Allows addition of a markdown formatted text paragraph to the form to provide the user with detailed instructions or information. Use markdown to add links and images.

- type: instructions
  text:
    Visit your Yotpo Swell settings page ([https://app.swellrewards.com/settings](https://app.swellrewards.com/settings)) and paste the URL above in the Webhook URL field.
    Once you save the Webhook URL, ODP will start receiving future Swell data as it happens. ![Swell Settings Page](images/swell-settings-page.png)

Callout

type: callout

Draws attention to instructions whether as information, an error, or a warning. This element is not yet available for use in the settings forms. Use the paragraph element for now.