Form elements
This topic describes how to configure form elements that may require input from users via Optimizely Connect Platform (OCP).
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. 
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.
Updated 16 days ago