Form element types

  • Updated

Optimizely provides default form element types that you can modify. The Forms gadget lists Basic and Action elements. You can build your own reusable form element instances from each type. For example, drag a Text form element type onto a page and edit the instance to create a username text box, or an email address text box with required validation. See also: Configuring a form element.

Basic Elements Action Elements
Image: Optimizely Forms Basic elements Image: Optimizely Forms Action elements

Optimizely Forms samples package

Some of the more complex form elements use services from third-party providers and are kept outside the standard Optimizely Forms installation due to legal and maintenance reasons. To use these form elements, a developer must install the Optimizely Forms Samples package. Optimizely also provides a Demo project to help developers get started with Optimizely Forms, the Samples package, and the Forms API. Both the Samples package and the Demo project can be found on GitHub; and the Samples package can also be installed via Visual Studio like Optimizely Forms.

The following Basic Element types are predefined in Optimizely Forms:

Text

Text is a single-line text entry field. You can restrict the format to email addresses or date formats. It looks like this in a form:

Image: Email form field

Image: Text element, Content tab

Image: Text element, Content tab

When configuring the Text form element, you can set the following properties:

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the text box.
Validators You can use the following predefined validators:
  • Required. Require the site visitor to fill in the text box before submitting the form.
  • Regular Expression. Click Change to enter a regular expression pattern (such as /\s*/).
  • Email. Make sure the text box contains a valid email address.
Optimizely Forms can validate that dates in the text field conforms to a specific date format. Choose one of the following date formats:
  • Date (DD/MM/YYYY)
  • Date (MM/DD/YYYY)
  • Date (YYYY-MM-DD)
For each validator, you can configure the error message that is displayed to the visitor if the validation fails.
Placeholder text Enter the text you want to display in the field as a prompt to the user. The text prompt is not recorded in data, and is replaced by user input.
Predefined value Enter a value to display and record as the default text in the text box. The visitors entry overwrites this text. If you have both Placeholder text and Predefined value specified, the Predefined value appears in the text box and overrides the Placeholder text.

Text area

Text area is a multiple-line text entry field.

Image: Text area element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the text box.
Validators You can use the following predefined validators:
  • Required. Require the site visitor to fill in the text box before submitting the form.
  • Regular Expression. Click Change to enter a regular expression pattern (such as /\s*/).
For each validator, you can configure the error message that is displayed to the visitor if the validation fails.
Placeholder text Enter the text you want to display in the field as a prompt to the user. The text prompt is not recorded in data, and is replaced by user input.

See the Dependencies tab for a description on how to use the Dependencies tab.

Number

Number lets you restrict visitor input to a number in the field, such as for a Quantity of items to purchase.

 

Image: Number element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the number field.
Validators Select one or more number restrictions.
  • Required. Select Required to make sure a site visitor makes a choice before the visitor can submit the form. Clear the check box to make the choice optional.
  • Integer. Select the check box to require the number field to be any integer.
  • Positive integer. Select the check box to require the number field to be a positive integer.
For each validator, you can configure the error message that is displayed to the visitor if the validation fails.
Placeholder text Enter the text you want to display in the field as a prompt to the user. The text prompt is not recorded in data, and is replaced by user input.

See the Dependencies tab for a description on how to use the Dependencies tab.

Date time

Date time lets you create a date time field where a visitor can pick a date from a calendar and set the time, as the following image shows.

Image: Setting up date and time

The Optimizely Forms Samples package must be installed for Date time to work. See Optimizely Forms Samples package for information on the Forms Samples package.

Image: Date time element, Content tab

Property Description
Label text Enter the text you want displayed on the form for the Date time field.
Tooltip Enter the text to display when you hover over the Date time field.
Picker type You can select Date picker, Time picker, or Date time picker.
Validators You can use the following predefined validator:
  • Required. Select the Required check box to make sure a site visitor makes a choice before the visitor can submit the form. Clear the check box to make the choice optional.
You can configure the error message that is displayed to the visitor if the validation fails.
Placeholder text Enter the date and/or time you want to display in the field as a prompt to the user. The text prompt is not recorded in data, and is replaced by user input.
Predefined value Enter a date and/or time value to display and record as the default text in the box. The visitor's entry overwrites this. If you have both Placeholder text and Predefined value specified, the Predefined value appears in the box and overrides the Placeholder text.

Range

Range lets a visitor specify a range value. The default is 0 to 10 but you can set the range you want; (see Min and Max values).

Image: Range element in form

Image: Range element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the Range field.
Min Enter the minimum range, down to -2,147,483,648.
Max Enter the maximum range, up to 2,147,483,647.
Step Enter the increments (1 to 2147483648) between minimum and maximum range. For example, specify 3 to let the visitor select a range (such as 1 to 100) that steps by 3, such as 1, 4, 7, 10, 13, and so on.
Predefined value Enter a value to display and record as the default range selection (such as the middle of the range).

See the Dependencies tab for a description on how to use the Dependencies tab.

Url

Url lets a visitor specify a URL to submit with form data.

 

Image: Url element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the number field.
Validators Select one or more number restrictions.
  • Required. Select the Required check box to make sure a site visitor makes a choice before the visitor can submit the form. Clear check box to make the choice optional.
  • Regular expression. Click Change to enter a regular expression pattern (such as /\s*/).
For each validator, you can configure the error message that is displayed to the visitor if the validation fails.
Placeholder text Enter the URL you want to display in the field as a prompt to the user. The text prompt is not recorded in data, and is replaced by user input.
Predefined value Enter a URL to display and record as the default text in the text box. The visitor's entry overwrites this text. If you specify both Placeholder text and Predefined value specified, the Predefined value appears in the text box and overrides the Placeholder text.

See the Dependencies tab for a description on how to use the Dependencies tab.

Selection

Selection creates a drop-down list with single or multiple selections, as shown in the following image.

Image: Selection element in form

Image: Selection element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the selection field.
Validators You can use the following predefined validators:
  • Required. Select to make sure a site visitor makes a choice before the visitor can submit the form. Clear the check box to make the choice optional. You can configure the error message that is displayed to the visitor if the validation fails.
  • Allow multiple choices.
    • Select the check box for multiple selections.
      Image: Example of multiple selections in drop-down list
    • Clear the check box for single-choice selection.
      Image: Example of single selection in drop-down list
Choices Use manual input

If you select this option, an Add list item icon [+] appears; click it to display an Item Details screen:

  • Choice. Enter the text you want to display. For example, Chocolate.
  • Value. Enter the value, which is not displayed but you can use the value (such as Chocolate) in your reports.
  • Checked by default. Enable to pre-select the list item, such as Vanilla.

You can select multiple default items for multiple selections but only one item if Allow multiple select is disabled.
Placeholder text Enter the text you want to display in the field as a prompt to the user. The text prompt is not recorded in data, and is replaced by user input.

See the Dependencies tab for a description on how to use the Dependencies tab.

Multiple or single choice

Multiple or single choice lets you insert a list of items that are single-choice radio buttons (shown in the following image) or multiple-choice check boxes.

Image: Radio buttons in form

Image: Multiple or single choice element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the choice field.
Validators You can use the following predefined validators:
  • Required. Select the check box to make sure a site visitor makes a choice before the visitor can submit the form. Clear the check box to make the choice optional.
  • Allow multiple choices.
    • Select the check box for multiple-choice check boxes.
      Image: Example of multiple-choice check boxes
    • Clear the check box for single-choice radio buttons.
      Image: Example of single-choice radio buttons

For each validator, you can configure the error message that is displayed to the visitor if the validation fails.
Choices Use manual input

Click Add item [+]. An Item Details screen appears. Select one of the following:

  • Choice. Enter the text you want to display. For example, Same-day shipping.
  • Value. Enter the value, which is not displayed but you can use the value (such as FedEx) in your reports.
  • Checked by default. Enable to pre-select the list item.

You can select multiple default items for check boxes but only one item for radio buttons.

See the Dependencies tab for a description on how to use the Dependencies tab.

Image choice

Image choice lets a visitor select one or more images from an image list.

Image: Image choice element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the image field.
Validators You can use the following predefined validators:
  • Required. Select the check box to make sure a site visitor makes a choice before the visitor can submit the form. Clear check box to make the choice optional.
  • Show the check box or radio button. Select to show a check box (multiple choice) or radio button (single choice) next to the image selections on the page. Clear check box to show nothing next to the image selections.
  • Allow multiple choices. Select the check box to let a visitor select more than one image at a time. Clear the check box to permit only one image selection.
For each validator, you can configure the error message that is displayed to the visitor if the validation fails.
Image choices Drag image media items into this box.

Click Create a link to an image to select one from a CMS tree and give it a specific title.

Image: Create link dialog box

The site visitor chooses from among the images.

Use borderless images for best display of images.

Image: Examples of images with and without borders

See the Dependencies tab for a description on how to use the Dependencies tab.

File upload

File upload lets a visitor upload a file by clicking a button and selecting it from a file browser. You can restrict the size and types of files that the visitor can upload.

 

Image: File upload element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over the upload field.
Max file size (in MB) Select the maximum file size (in MB).
Allowed extensions Specify a comma-separated list of file extensions that you permit to be uploaded. To configure the default list of not allowed file extensions, see Configuring forms in the Optimizely Forms Developer Guide.
Validators Select the Required check box to make sure a site visitor makes a choice before the visitor can submit the form. Clear the check box to make the choice optional.
You can configure the error message that is displayed to the visitor if the validation fails.

See the Dependencies tab for a description on how to use the Dependencies tab.

Hidden predefined value

Hidden predefined value lets you internally name or code submitted form data to distinguish the data from other data. For example, you might enter Christmas-campaign in one form, and Hanukkah-campaign in another form, to know that submissions of the form are related to a particular marketing campaign.

 

Image: Hidden predefined value element, Content tab

Property Description
Predefined value Enter the value to distinguish from where the data is originating.

Hidden visitor profiling

Hidden visitor profiling lets you specify the type of data about the visitor (such as geography, profile, user agent, or visitor group) that you want to collect.

 

Image: Hidden visitor profiling element, Content tab

Property Description
Auto-collect visitor data Select one data type to collect. If you want to collect more than one data type, for example, to collect both latitude and longitude, you have to add two Hidden visitor profiling form elements and set up one to collect latitude and one longitude.

The data types are gathered in the following sections:

  • Geo. The Geo data types track geographical data from the visitor's device, such as IP address, time zone, latitude, or longitude. This data is usually in a numeric format.
  • Profile. The Profile data types track visitor profile data, such as address, company and so on. This data is usually in plain text and more readable than the Geo data.
  • User agent. The Is mobile detects of the visitor is using a mobile device when filling in the form, and User agents tracks the visitor's browser type and version.
  • Visitor groups. The Name data type under Visitor groups tracks if the visitor is a member of one or more visitor groups.

Captcha

A CAPTCHA field verifies that the person filling in your form is actually a person (and not a machine) by entering a code only humans can interpret. The following image shows a CAPTCHA field.

Image: Example of Captcha on form

If your form may be used by visually impaired people, consider using ReCAPTCHA instead.

 

Image: Captcha element, Content tab

Property Description
Label text Enter the text you want displayed on the form (such as Word Verification).
Tooltip Enter the text to display when you hover over the CAPTCHA image.
Image width Set the width (from 100 to 350 pixels) of the CAPTCHA image.
Image height Set the height (from 21 to 75 pixels) of the CAPTCHA image.
Text length Set from 5 to 10 characters for the CAPTCHA code.

ReCAPTCHA

A CAPTCHA field verifies that the person filling in your form is actually a person (and not a machine). The reCAPTCHA field does this by checking a single box that only humans can do. The following image shows a reCAPTCHA image.

Image: Example of ReCAPTCHA on form

The Optimizely Forms Samples package must be installed for reCAPTCHA to work. See Optimizely Forms Samples package for information on the Forms Samples package.

The reCAPTCHA form element automatically adds JavaScript code in your site's HTML code for reCAPTCHA to work. (It follows this instruction Automatically render the reCAPTCHA widget on the Google developer's website).

 

Image: ReCAPTCHA element, Content tab

Property Description
Site key Enter a valid site key.
Secret key Enter a secret key.

Rich text (with placeholders)

Rich text lets you format text and use form data to display customized text back to the visitor.

The placeholders in rich text elements can only be used in forms with multiple form steps. Also, if you are using placeholders, the rich text element must be placed after the fields you want fetch data from.

Image: Example of rich text with placeholders in form

 

Image: Rich text element, Content tab

Property Description
Content tab
Text Enter the text you want displayed in the block on the form.
Insert placeholder Select one or more placeholders to insert into your text to customize the text with a person's name, email, or other data.
Settings tab
Disable placeholders replacement Replacing placeholders with real data provided by a visitor may cause performance issues. Select Disable placeholders replacement to not replace placeholders with data entered by the visitor; instead, the default placeholder text will be displayed.

Example:

A visitor applies for a job and enters their name, email address, and job type.

If the Disable placeholders replacement setting is selected, the original placeholder text is displayed instead of the visitor's entered name, email address, and job type in the rich-text element:

Image: Default placeholder text displayed in the next step

See the Dependencies tab for a description on how to use the Dependencies tab.

Form step

Form step separates a form into steps. You place a Form step ahead of the content for each step. You can conditionalize whether a visitor sees a step on the Settings tab. For example, you can set up a form so that visitors that select option A in form step 1 are displayed form step 2, while visitors that select option B are displayed form step 3.

Content tab

On the content tab, you can give the form step a label and a description.

Image: Form step element, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Description Enter the text to display when you hover over the form step.

Settings tab

Set the rules by which the Form Step appears. For example, Number field equals 4 or Color choice not contains gray.

Image: Form step element, Settings tab

Property Description
Display step in other content Click Browse [...] to select a page on which this step appears. For example, you may want one step to appear on a page with a specific layout or message (such as a special page for engineering job applicants), and another step to appear on another page (such as a page for all other applicants). Click Delete to clear the page selection. Click OK to confirm your selection.
Only display if field Click Browse [...] to select an element from a previous step on which this element depends. For example, only show this element if the visitor supplied a telephone number in the previous step; otherwise do not display this element.
value...
  • Not Applicable
  • Match with Regular Expression
  • Equals
  • Not Equals
  • Contains
  • Not Contains

    Image: Value menu options
the following value Set the value against which the condition applies.
Published, Created, Modified, Update modified date These are system-generated timestamps for the content that rarely need to be changed. Select the Update modified date check box if you have made significant changes to the content and want the system to update the modification date.

Submit button

Submit button lets a visitor send form data to Optimizely CMS.

Content tab

Image: Submit button, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Image You can select an image to use as your Submit button.
Tooltip Enter the text to display when you hover over the Submit button.

Settings tab

Image: Submit button, Settings tab

Property Description
Finalize form Select this check box to allow visitors to finalize a multi-step form without going through all steps. For example, if your form contains four steps where the last two steps contain only optional questions. Enabling this setting lets the user submit a finalized form in step 2 without having to go through step 3 and 4. Clear the check box and visitors must complete all steps for the form to be seen as finalized.
Display page after submission You can select a page that is displayed after the visitor clicks your Submit button.

Dependencies tab

See the Dependencies tab for a description on how to use the Dependencies tab.

Reset button

Reset button lets a visitor clear the contents of the form.

 

Image: Reset button, Content tab

Property Description
Label text Enter the text you want displayed on the form.
Tooltip Enter the text to display when you hover over Reset.

Settings tab

The Settings tab is used for editing the Created and Published dates of the form elements. The Submit button and Form step types have a couple of extra settings on this tab, see their respective sections above.

Dependencies tab

The Dependencies tab is used for the following form elements: Image choice, Number, Range, Selection, Text area, Text, Url, File upload, and Multiple or single choice, Rich text and the Submit button.

The settings in the Dependencies tab are used when you want to either show or hide the current form element depending on how the visitor has made a selection in another form element. For example, you can set up a form question How do you rate our services from 1 to 5?, and if the visitor gives a rating of 1 or 2, a follow-up question is displayed.

To achieve this, you set up one or more conditions, and if the specified conditions are met, the current form element is displayed (or hidden) to the visitor. See Example: Creating a customer satisfaction survey for an example on how to create form fields that are dependent on other fields.

Image: Dependencies tab

Property Description
This field will be With the drop-down list under This field will be, you can choose to either show or hide the form element. If you select Shown, the current form element is displayed when the set conditions are met, and reversely, if you select Hidden, the form element is not displayed when the conditions are met.
if With the drop-down list under if, you select if the form element should be shown or hidden when all or any of the specified conditions are met.
of the following conditions are satisfied: This is where you specify which form field the current one is dependent on, and the conditions that must be met in order to display or hide the form element. You can specify a number of conditions.
  1. Click the New condition button + to open the Condition Details dialog box:

    Image: Conditions Details dialog box

  2. Under Field, click the Browse button and select the form element that the current form element should depend on.
  3. Under Condition, select one of the following conditions:
    • Match with regular expression
    • Equals
    • Not equals
    • Contains
    • Not contains
  4. Under Value, define the value the condition should apply to.
Example of how to display a form field if a visitor has rated a service as 1 or 2 on a scale to 5:

This field will be Shown if Any of the following conditions are satisfied: Service rating Equals 1 and Service rating Equals 2.

When a form element is conditionalized, it is marked with a thin blue dotted border in the on-page edit view:

Image: Conditionalized form element