Form element types
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: Configure a form element.
Basic Elements
Action Elements
Optimizely Forms samples package
Some more complex form elements use services from third-party providers and are kept outside the standard Optimizely Forms installation for legal and maintenance reasons. A developer must install the Optimizely Forms Samples package to use these form elements. Optimizely also provides a Demo project to help developers start with Optimizely Forms, the Samples package, and the Forms API. You can find the Samples package and the Demo project on GitHub, and you can install the Samples package with 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: Text element, Content tab
When configuring the Text form element, you can set the following properties:
- 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 – The site visitor must 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 conform 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 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 the 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 visitor's entry overwrites this text. If you have Placeholder text and Predefined value specified, the Predefined value displays in the text box and overrides the Placeholder text.
Text area
Text area is a multiple-line text entry field.
- 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. The site visitor must fill in the text box before submitting the form.
- Regular Expression. Click Change to enter a regular expression pattern (such as /\\s*/).
You can configure the error message displayed to the visitor for each validator 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 the data and is replaced by user input.
See the Dependencies tab for a description of 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.
- 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 chooses 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.
You can configure the error message displayed to the visitor for each validator 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 the data and is replaced by user input.
See the Dependencies tab for a description of 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.
Note
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.
- 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 chooses before the visitor can submit the form. Clear the check box to make the choice optional. If the validation fails, you can configure the error message displayed to the visitor.
- Placeholder text – Enter the date or time you want to display in the field as a prompt to the user. The text prompt is not recorded in the 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 Placeholder text and Predefined value specified, the Predefined value displays 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).
- 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 the minimum and maximum range. For example, specify 3 to let the visitor select a range (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 of how to use the Dependencies tab.
Url
Url lets a visitor specify a URL to submit with form data.
- 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 chooses 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 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 the 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 Placeholder text and Predefined value specified, the Predefined value displays in the text box and overrides the Placeholder text.
See the Dependencies tab for a description of how to use the Dependencies tab.
Selection
Selection creates a drop-down list with single or multiple selections, as shown in the following image.
- 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 chooses before the visitor can submit the form. Clear the check box to make the choice optional. You can configure the error message displayed to the visitor if the validation fails.
- Allow multiple choices.
- Select the check box for multiple selections.
- Clear the check box for single-choice selection.
- Choices – Use manual input If you select this option, an Add list item icon [+] displays; 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.
Note
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 the data and is replaced by user input.
See the Dependencies tab for a description of how to use the Dependencies tab.
Multiple or single-choice
Multiple or single-choice lets you insert a list of single-choice radio buttons (shown in the following image) or multiple-choice checkboxes.
- 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 chooses 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 checkboxes.
- Clear the check box for single-choice radio buttons.
For each validator, you can configure the error message displayed to the visitor if the validation fails.
- Choices – Use manual input Click Add item [+]. An Item Details screen displays. 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.
Note
You can select multiple default items for checkboxes but only one for radio buttons.
See the Dependencies tab for a description of how to use the Dependencies tab.
Image choice
Image choice lets a visitor select one or more images from an image list.
- 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 chooses 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 visitors 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 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.
The site visitor chooses from among the images.
Note
Use borderless images for the best display of images.
See the Dependencies tab for a description of 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 the visitor can upload.
- 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 Configure forms in the Optimizely Forms Developer Guide.
- Validators – Select the Required check box to make sure a site visitor chooses before the visitor can submit the form. Clear the check box to make the choice optional. If the validation fails, you can configure the error message displayed to the visitor.
See the Dependencies tab for a description of 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 to know that the form submissions are related to a particular marketing campaign.
- 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) you want to collect.
- Auto-collect visitor data – Select one data type to collect. Suppose you want to collect multiple data types, such as latitude and longitude. In that case, you must 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 if the visitor is using a mobile device when filling in the form, and User agents track 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 a person (not a machine) by entering a code only humans can interpret. The following image shows a CAPTCHA field.
Note
If your form may be used by visually impaired people, consider using ReCAPTCHA instead.
- Label text – Enter the text 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 CAPTCHA image's width (from 100 to 350 pixels).
- Image height – Set the CAPTCHA image's height (from 21 to 75 pixels).
- 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 a person (not a machine). ReCAPTCHA (version 3) automatically verifies the person without requiring the "I'm not a robot" checkbox from ReCAPTCHA version 2.
You must install the Optimizely Forms Samples package (EPiServer.Forms.Samples 3.7.0 or later) for reCAPTCHA to work. See Optimizely Forms Samples package. The reCAPTCHA form element automatically adds JavaScript code to your site's HTML code for reCAPTCHA to work. (It follows this instruction Automatically render the reCAPTCHA widget on the Google developer's website).
- Score Threshold – Determines whether to ask for more verification or block access to ensure security while maintaining a good user experience. If an interaction meets or exceeds the threshold (commonly set at 0.5), it is considered legitimate.
- 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 to the visitor.
Note
The placeholders in rich text elements can only be used in forms with multiple form steps. Also, if you use placeholders, the rich text element must be placed after the fields you want to fetch data from.
- 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 is 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:
See the Dependencies tab for a description of 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 who select option A in form step 1 are displayed form step 2, while visitors who select option B are displayed form step 3.
Content tab
You can give the form step a label and a description on the content tab.
- 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 displays. For example, Number field equals 4 or Color choice not contains gray.
- Display step in other content – Click Browse [...] to select a page on which this step displays. For example, you may want one step to display on a page with a specific layout or message (such as a special page for engineering job applicants) and another step to display on another page (such as a page for 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
- 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
- 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
- Finalize form – Select this checkbox to let visitors finalize a multi-step form without going through all the 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 going through steps 3 and 4. Clear the checkbox, and visitors must complete all steps for the form to be seen as finalized.
- Display page after submission – You can select a page displayed after the visitor clicks your Submit button.
Dependencies tab
See the Dependencies tab for a description of how to use the Dependencies tab.
Reset button
Reset button lets a visitor clear the form's contents.
- 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, Multiple or single choice, Rich text, and the Submit button.
The settings in the Dependencies tab are used when you want to show or hide the current form element depending on how the visitor has selected 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: Create a customer satisfaction survey for an example of creating form fields dependent on other fields.
- This field will be – With the drop-down list under This field will be, you can choose to 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 specified conditions are met.
- of the following conditions are satisfied: – Specify which form field the current one depends on, and the conditions that must be met to display or hide the form element. You can specify a number of conditions.
- Click the New condition button + to open the Condition Details dialog box:
- Under Field, click the Browse button and select the form element that the current form element should depend on.
- Under Condition, select one of the following conditions:
- Match with regular expression
- Equals
- Not equals
- Contains
- Not contains
- 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:
