Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Version specific documentation for upgrading to new major versions of Umbraco Forms.
This article provides specific upgrade documentation for migrating to Umbraco Forms version 15.
If you are upgrading to a minor or patch version, you can find the details about the changes in the Release Notes article.
Version 15 of Umbraco Forms has a minimum dependency on Umbraco CMS core of 15.0.0
. It runs on .NET 9.
Version 15 contains a number of breaking changes. If you do run into any, they should be straightforward to adjust and recompile.
For reference, the full details are listed here:
The setting FieldSettings:Recaptcha3:ShowFieldValidation
has a new default of true
.
The setting Options:EnableMultiPageFormSettings
has a new default of true
.
The setting FormDesign:RemoveProvidedEmailTemplate
has been removed (as adding and removing email templates can be more consistently handled using EmailTemplateCollection
).
IFieldPreValueSourceType.GetPrevalues
(and the abstract method of the same name in FieldPreValueSourceType
) is now an asynchronous method. It has an Async
suffix.
IExportType.ExportRecords
and ExportToFile
are now asynchronous methods and have Async
suffixes.
Parameters in the FileUpload
constructor were renamed.
Obsolete constructors in the classes SendRazorEmail
, EntryAcceptedDtoFactory
, FormDtoFactory
, RenderFormViewComponent
, GetValuesByKeyPrevalueSourceController
, and UmbracoFormsController
were removed.
The obsolete overload on FormFileExtensions.IsFileTypeAllowed
was removed.
The purposes defined for uses of IDataProtector
were renamed to have a common prefix.
Unused fields Field.Placeholder
and FormFieldDto.Placeholder
were removed.
Unused ServerVariablesParsingHandler
was removed.
Default implementations on the interfaces IWorkflowFactory
, IWorkflowRepository
, IWorkflowService
were removed.
Obsolete methods on PlaceholderParsingService
were removed.
Method overloads without optional parameters on FormDtoFactory
, EntryAcceptedDtoFactory
, IFormRenderingService
, IPlaceholderParsingService
, WorkflowType
, DictionaryExtensions
and StringExtensions
were removed.
Base64 encoding was removed when storing and retrieving form state.
The obsolete overload of FormViewModel.Build
was removed.
The UmbracoPreValuesReadOnly
constructor now has an additional parameter.
Due to the introduction of asynchronous behavior to IFieldPreValueSourceType.GetPrevalues
, FormViewModel.Build
is now also asynchronous.
FormsTreeRequirement
and related classes were removed.
FormRenderingService
and FormThemeResolver
was made internal.
Default implementations on IFormThemeResolver
were removed.
You can find the version specific upgrade notes for versions out of support in the Legacy documentation on Github.
Get an overview of the things changed and fixed in each version of Umbraco Forms.
In this section, we have summarized the changes to Umbraco Forms released in each version. Each version is presented with a link to the Forms issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.
If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.
If you are upgrading to a new major version, you can find information about the breaking changes in the Version Specific Upgrade Notes article.
This section contains the release notes for Umbraco Forms 14 including all changes for this version.
Compatibility with Umbraco 15
See full details of breaking changes under the Version-specific Upgrade Guide.
Made retrieval of prevalue source values and execution of record exports asynchronous #1285.
Preview of features due in 13.3 and 14.1:
Option to display paging details for multi-page forms.
Form picker with allowed forms managed via folders.
New "form details picker" providing a single property editor for the selection of form, theme, and redirect.
Ability to provide custom themes and email templates via razor class libraries.
You can find the release notes for versions out of support in the Legacy documentation on Github and Umbraco Forms Package page.
This article shows how to manually upgrade Umbraco Forms to run the latest version.
When upgrading Umbraco Forms, be sure to also consult the version specific upgrade notes to learn about potential breaking changes and common pitfalls.
To get the latest version of Umbraco Forms, you can upgrade using:
NuGet installs the latest version of the package when you use the dotnet add package Umbraco.Forms
command unless you specify a package version: dotnet add package Umbraco.Forms --version <VERSION>
After you have added a package reference to your project by executing the dotnet add package Umbraco.Forms
command in the directory that contains your project file, run dotnet restore
to install the package.
Go to Tools
-> NuGet Package Manager
-> Manage NuGet Packages for Solution...
in Visual Studio, to upgrade your Forms:
Select Umbraco.Forms.
Select the latest version from the Version drop-down and click Install.
When the command completes, open the .csproj file to make sure the package reference is updated:
Installing Umbraco Forms
Umbraco contains the Forms section, by default. You will see a similar interface, when you click on the Forms section in the Umbraco Backoffice.
To install the Umbraco Forms package (Umbraco.Forms), follow these steps:
Run the following command on a command prompt of your choice:
Restart the web application using the following command:
Once the installation is successful, you will see a similar screen in the Forms section:
For details on using Forms, see the Editor Documentation.
Documentation on how to work with Umbraco Forms for both editors and developers.
This is the documentation for the Umbraco Forms 15 Release Candidate.
This version of the Umbraco Forms documentation is currently slimmed down to contain only new and updated material related to the upcoming release.
Umbraco Forms is a tool that lets you build forms of all shapes and sizes and put them on your Umbraco websites. Build forms using a long list of elements like multiple choice, dropdowns, text areas and checkboxes. Choose between a series of different workflow and control what happens once a form has been submitted.
Purchase Umbraco Forms or sign up for an Umbraco Cloud project where Umbraco Forms is part of the package.
In this tutorial, we'll look at creating a Contact Form using Umbraco Forms. It will take you through the process of creating a Contact Form and cover all the different components involved in building the form.
You can use a Contact Form on your website to allow a visitors to send you a message. Having a Contact Form on your website allows you to keep track of potential customer queries and possibly generate leads via email communication.
The first step in this tutorial is to configure the Document Types that will be used to show the Contact Form on your website.
We'll start off by creating a Composition. A Composition is a stand-alone Document Type, that you can reuse on other Document Types. By creating a Composition, we are not duplicating the same properties on multiple Document Types. This is helpful when we want to use the same set of properties on multiple Document Types.
To create a Composition, follow these steps:
Go to Settings in the Umbraco Backoffice.
Expand the Document Types folder in the Settings tree.
Select ... next to the Compositions folder.
Click Create.
Select Document Type.
Enter a Name for the Composition- let's call it Title Box.
Add the following fields with the respective specifications:
Click Save to save the Composition.
Next, we will create a Document type with template. A Document Type contains different properties for holding different types of content. The Document Type we create here will be the one used for creating the content page that will hold our Contact Form.
To create a Contact Us Document Type, follow these steps:
Go to Settings in the Umbraco Backoffice.
Select ... next to the Document Types folder.
Click Create.
Select Document Type with Template.
Enter a Name for the Document Type- let's call it Contact Us.
Select Compositions in the top-right corner.
Select Title Box.
Click Submit.
Add the following fields with the respective specifications:
Click Save.
In the following we will update the Document Type permissions to specifically add child nodes under the root content node.
To update the Contact Us Document Type permissions, follow these steps:
Navigate to the Document Type used for the root content node on your website, in this case Home page.
Go to the Structure tab.
Select Choose in the Allowed child node types section.
Select the Contact Us page.
Click Choose.
Click Save.
This step takes you through creating the content node for your Contact Form. The content node uses the Document Type and Template to serve up an HTML page to web visitors.
To add the content node, follow these steps:
Go to Content in the Umbraco Backoffice.
Select ... next to the Home Page.
Click Create.
Select Contact Us.
Enter the name for the content node. let's call it Contact Us.
Enter a Title, Subtitle, and Body Text value. These can always be updated at a later point.
Click Save or Save and Publish.
In this step, we will create the Contact Form using Umbraco Forms.
To create a form, follow these steps:
Go to the Forms section in the Umbraco Backoffice.
Click ... next to the Forms folder.
Click Create.
Select New Form....
Enter a Name for the Form. Let's call it Contact Us.
[Optional] Enter a Page Name and Group Name for the Data Consent statement. Let's call it Data Consent.
Click Add new group. Let's call it Information.
Select Add Question to add a new field.
Enter the following details:
Click Submit.
Repeat steps 8-10 to add the following fields:
Enable Conditions in the Enter your phone number field.
Click Add Condition.
Select How should we contact you? from the dropwdown.
Select phone in the value field.
Click Submit.
Repeat steps 8-10 to add the following field:
Enable Conditions in the Enter your email address field.
Click Add Condition.
Select How should we contact you? from the dropwdown.
Select email in the value field.
Click Submit.
Repeat steps 8-10 to add the following field:
Select the Reorder option.
Drag the Data consent group below the Information group.
Click I am done reordering.
Click Save.
Workflows is how you determine what you happen after your form is submitted. It could be actions like sending an email or displaying a "Thank You" message.
To configure the Form workflow, follow these steps:
Select the Submit message/ Go to page options in the bottom of the Forms editor.
Enter a customised message in the Message on Submit field.
Click Submit.
Click on Send template email to xxx@xx.dk.
Enter an email address in the Sender Email field.
By default, the Example-Template.cshtml template will be selected in the Email template field.
Enable Attach Uploaded Files.
Click Submit.
Click Save.
In this step, you will find the information about accessing the Forms Settings and the validations available to customise your form.
To configure the form settings, follow these steps:
Navigate to the Settings tab in the Forms editor.
Scroll to find the Validation section.
Ensure that the Mark Mandatory fields option is checked under Mark fields.
Click Save.
There are multiple settings that be configured. These are all optional in relation to this tutorial.
Now that you have created your Contact Form, you can add it in the Contact Us Content Node using the Form Picke Data Type.
To add the Contact Form to the Content Node, follow these steps:
Go to the Content section in the Umbraco Backoffice.
Open the Contact Us Page.
Select Choose in the Contact Form field.
Select the Insert Form with Theme option.
Select the Contact Us Form.
Click Choose.
Click Save or Save and Publish.
In the next couple of steps, we will add some additional configuration required in order for our form to work properly.
You need to update the configuration to include a value in the appsettings.json
file.
By adding the SMTP settings in the appsettings.json
file, you can send out emails from your Umbraco installation. It is required in order for your form to be able to send emails on submission.
In this step, we will render the values of the Contact Us Document Type in the template.
To render the Contact Form, follow these steps:
Go to the Settings section in the Umbraco Backoffice.
Open the Contact Us template in the Templates folder.
Enter the following code to render the form:
Select Insert.
Click Value.
Select Document Type from the Choose field dropdown.
Select Contact Us.
Click Choose.
Select bodyText from the Contact Us dropdown.
Click Submit.
Click Save.
Finally, it is time to view the Contact Form on the frontend.
To view the Contact Form on the Frontend, follow these steps:
Go to the Content section in the Umbraco Backoffice.
Open the Contact Us Page.
Ensure that the page is published.
Go to the Info tab.
Click on the Published link in the Links section.
You now have a full-fledged Contact Form ready to be used on your website.
For Umbraco Forms to work correctly, you need to include some client dependencies.
You can use the following Razor helper to output script tags containing the dependencies. To access this method you will need a reference to Umbraco.Forms.Web
:
Alternatively, you can add the dependencies to the body tag:
All dependencies originate from your Umbraco Forms installation, which means that no external references are needed.
If you want to modify the rendering of the scripts, you can provide a object parameter named htmlAttributes
. The contents of the object will be written out as HTML attributes on the script tags.
You can use this to apply async
or defer
attributes. For example:
If you want to use jQuery as your validation framework for Umbraco Forms, you can manually add the following client dependencies:
jQuery
(JavaScript library)
jQuery validate
(jQuery plugin that provides client-side Form validation)
jQuery validate unobtrusive
(Add-on to jQuery Validation that provides unobtrusive validation via data-* attributes)
You should remove any calls to @Html.RenderUmbracoFormDependencies(Url)
.
Other CDN services you might want to look at are https://www.jsdelivr.com/ and https://cdnjs.com/about, which may offer better performance and more reliable service.
To add the three client dependencies, see the examples below:
Example within head
tags.
Example within body
tags.
In this tutorial, you will learn how to create a multi-page form using Umbraco Forms. Multi-page forms are particularly useful when you need to collect detailed information from users in a structured and user-friendly way.
Multi-page forms are ideal for use cases such as event registration, job applications, booking a meeting, and so on.
Pre-built Website including a Document Type with the Form Picker Data Type.
Log in to the Umbraco backoffice.
Go to the Forms section.
Click + next to the Forms folder.
Select New Form.
Enter a Name for the form. For example: Book a Meeting.
Click Save.
Let us begin by adding some fields to the first page of the form. By default, the Data Consent field is already available, and we will call this group Data Consent.
To create a new group:
Click Add new group.
Enter the Name of the group. For example: Personal Information.
Click Add question.
Select Short answer as the field type.
Enter a Name for the field type. For example, First Name.
Select Text as the Field Type from the drop-down list.
Mark the field as Mandatory.
Click Submit.
Click Save.
Similarly, you can also add other relevant fields such as last name or email based on your requirements.
For this tutorial, the following fields are added with the respective specifications:
If you wish to reorder your fields, click Reorder.
To create a multi-page form, you need to add more pages:
Click Add new page to create the second page of your form.
Enter a Name for this page. For example: Company Information.
Click Add question.
Select Short answer as the field type.
Enter a Name for the field type. For example, Company Name.
Provide a Default Value. For example, Enter the name of your company.
Click Submit.
Click Save.
Similarly, you can also add other relevant fields based on your requirements.
Umbraco Forms allows you to customize the flow of your multi-page form. You can add conditional logic to control which questions appear based on user inputs.
To add conditions, follow these steps:
Click Add question.
Select Single choice as the field type.
Enter a Name for the field type. For example, Do you work with Umbraco.
Enter the Value and Caption in the Options field.
For this tutorial, the following values are added:
Yes
No
Mark the field as Mandatory.
Click Submit.
Click Save.
Repeat steps 1-4 to create a conditional question titled: If yes, how many years?
Enter the Value and Caption in the Options field.
For this tutorial, the following values are added:
1-5 years
5-10 years
10+ years
Enable Conditions.
Set the parameters for the condition as follows:
Show this field if all of the following match:
Question: Do you work with Umbraco?
Condition: is
Value: Yes
Click Submit.
Click Save.
Click Add new page to create the final page of your form.
Enter a Name for this page. For example: Products.
Click Add question.
Select Multiple choice as the field type.
Enter a Name for the field type. For example, Select the products you are interested in.
Enter the Value and Caption in the Options field.
For this tutorial, the following values are added:
Umbraco CMS
Umbraco Cloud
Umbraco Deploy
Umbraco Heartcore
Umbraco Forms
Umbraco Commerce
Umbraco Workflow
Click Submit.
Click Save.
Once you are satisfied with your multi-page form, it is time to embed it on your website.
To display the form on the website, follow these steps:
Go to the Content section.
Click + next to the parent page of the website.
Select the Document Type.
Enter a Name for the page. For example, Book a Meeting!
Select the Book a Meeting form using the Form Picker.
Click Save and Publish.
Go to the Info workspace view of the Book a Meeting! page.
Click on the Published link in the Links section.
Fill out the form to see how it functions.
Submit the form to ensure it redirects to a Thank You page.
Go to the Forms section in the Backoffice.
Navigate to the Book a Meeting Form.
Click on the Entries tab and verify that the data is captured.
You have successfully created a multi-page form with conditional logic in Umbraco Forms. By using multi-page forms, you have made complex data entry much simpler and more user-friendly. This not only improves the experience for your users but also makes your forms more efficient and manageable.
In Umbraco Forms it's possible to customize the functionality with various configuration values.
With Umbraco Forms it's possible to customize the functionality with various configuration values.
All configuration for Umbraco Forms is held in the appSettings.json
file found at the root of your Umbraco website. If the configuration has been customized to use another source, then the same keys and values discussed in this article can be applied there.
The convention for Umbraco configuration is to have package based options stored as a child structure below the Umbraco
element, and as a sibling of CMS
. Forms configuration follows this pattern, i.e.:
All configuration for Forms is optional. In other words, all values have defaults that will be applied if no configuration is available for a particular key.
For illustration purposes, the following structure represents the full set of options for configuration of Forms, along with the default values. This will help when you need to provide a different setting to understand where it should be applied.
This configuration value expects a true
or false
value and can be used to disable the feature where all new forms are provided with a default "Consent for storing submitted data" field on creation. Defaults to false
.
This configuration value expects a true
or false
value and can be used to toggle if new forms that are created adds an email workflow to send the result of the form to the current user who created the form. Defaults to false
.
This setting controls the maximum number of columns that can be created by editors when they configure groups within a form. The default value used if the setting value is not provided is 12.
This setting allows you to configure the name of the theme to use when an editor has not specifically selected one for a form. If empty or missing, the default value of "default" is used. If a custom default theme is configured, it will be used for rendering forms where the requested file exists, and where not, will fall back to the out of the box default theme.
When creating an empty form, a single workflow is added that will send an email to the current user's address. By default, the template shipped with Umbraco Forms is available at Forms/Emails/Example-Template.cshtml
is used.
If you have created a custom template and would like to use that as the default instead, you can set the path here using this configuration setting.
Similarly, the provided form templates available from the form creation dialog can be removed from selection. To do this, set this configuration value to true
.
For example, providing a value of "f_"
will apply a prefix of "f_" to each fieldset and field id
attribute.
Forms introduced the ability to configure settings for the field, workflow, data source, and prevalue sources. The default behavior, when a new field or workflow is added to a form, is for each setting to be empty. The values are then completed by the editor. All settings defined on the type are displayed for entry.
In some situations, you may want to hide certain settings from entry, so they always take an empty value. In others, you may want to provide a default value that the editor can accept or amend. And lastly, you may have a requirement for a fixed, non-empty value, that's enforced by the organization and not editable. Each of these scenarios can be supported by this configuration setting.
It consists of four dictionaries, one for each type:
DataSourceTypes
FieldTypes
PrevalueSourceTypes
WorkflowTypes
Each dictionary can be identified using the GUID or alias of the type as the key. The value is set to the following structure that contains three settings:
IsHidden
- if provided and set to true the setting will be hidden and will always have an empty value.
DefaultValue
- if provided the value will be pre-filled when a type using it is created.
IsReadOnly
- used in conjunction with the above, if set the field won't be editable and hence whatever is set as the DefaultValue
won't be able to be changed. If set to false (or omitted) the editor can change the value from the default.
In this example, the sender address field on a workflow for sending emails can be hidden, such that the system configured value is always used:
Here an organization-approved reCAPTCHA score threshold is defined, that can't be changed by editors:
Take care to not hide any settings that are required for the particular field or workflow type (for example, the Subject
field for email workflows). If you do that, the item will fail validation when an editor tries to create it.
The default value and read-only settings apply to most setting types. There is an exception for complex ones where a default string value isn't appropriate. An example of one of these is the field mapper used in the "Send to URL" workflow.
When creating a form with Umbraco Forms, adding captions to the groups for fields is optional. To follow accessibility best practices, these fields should be completed. When they are, the group of fields are presented within a <fieldset>
element that has a populated <legend>
.
If you want to ensure form creators always have to provide a caption, you can set the value of this setting to true
.
The following configured values are applied to all forms as they are created. They can then be amended on a per-form basis via the Umbraco backoffice.
Once the form has been created, the values are set explicitly on the form, so subsequent changes to the defaults in configuration won't change the settings used on existing forms.
This setting needs to be a true
or false
value and will allow you to toggle if a form allows submissions to be post moderated. Most use cases are for publicly shown entries such as blog post comments or submissions for a social campaign. Defaults to false
.
This setting needs to be a true
or false
value and will allow you to toggle if the form will include some default styling with the Umbraco Forms CSS stylesheet. Defaults to false
.
This setting can have the following values to allow you to toggle the mode of marking mandatory or optional fields:
NoIndicator
(default)
MarkMandatoryFields
MarkOptionalFields
This setting is used to mark the mandatory or optional fields based on the setting above. By default this is an asterisk *
.
This allows you to configure the required error validation message. By default this is Please provide a value for {0}
where the {0}
is used to replace the name of the field that is required.
This allows you to configure the invalid error validation message. By default this is Please provide a valid value for {0}
where the {0}
is used to replace the name of the field that is invalid.
This setting needs to be a true
or false
value and will allow you to toggle if the form will display all form validation error messages in a validation summary together. Defaults to false
.
This setting needs to be a true
or false
value and will allow you to toggle if the form will show inline validation error messages next to the form field that is invalid. Defaults to false
.
These settings configure the default next, previous, and submit button labels. By default, these are Next
, Previous
, and Submit
respectively. These labels can be amended on a form-by-form basis via the form's Settings section.
This allows you to configure what text is displayed when a form is submitted and is not being redirected to a different content node. Defaults to Thank you
.
This setting needs to be a True
or False
value and will allow you to toggle if form submission data should be stored in the Umbraco Forms database tables. By default this is set to True
.
This setting provides a value to be used for the autocomplete
attribute for newly created forms. By default the value is empty, but can be set to on
or off
to have that value applied as the attribute value used when rendering the form.
Introduced in 10.2, this setting controls the initial value of the number of days to retain form submission records for newly created forms. By default the value is 0, which means records will not be deleted at any time and are retained forever.
If set to a positive number, a date value calculated by taking away the number of days configured from the current date is found. Records in the 'submitted' state, that are older than this date, will be flagged for removal.
Applies as per DaysToRetainSubmittedRecordsFor
but for records in the 'approved' state.
Applies as per DaysToRetainSubmittedRecordsFor
but for records in the 'rejected' state.
This configuration expects a True
or False
string value, or a comma-separated list of form names, and allows you to toggle if a form submission is edited again, that the workflows on the form will re-fire after an update to the form submission. This is used in conjunction with the AllowEditableFormSubmissions
configuration value. Defaults to True
.
This configuration key is experimental and will allow Workflows to be executed in an asynchronous manner. The value can be a True
or False
string value, or a comma-separated list of form names. Defaults to False
.
This configuration value expects a true
or false
value and can be used to toggle the functionality to allow a form submission to be editable and re-submitted. When the value is set to true
it allows Form Submissions to be edited using the following querystring for the page containing the form on the site. ?recordId=GUID
Replace GUID
with the GUID of the form submission. Defaults to false
.
There was a typo in this setting where it had been named as AllowEditableFormSubmissions
. This is the name that needs to be used in configuration for Forms 9. In Forms 10 this was be corrected to the now documented value of AllowEditableFormSubmissions
.
Enable this feature ONLY if you understand the security implications.
When redirecting following a form submission, a TempData
value is set that is used to ensure the submission message is displayed rather than the form itself. In certain situations, such as hosting pages with forms in IFRAMEs from other websites, this value is not persisted between requests.
By setting the following value to True, a querystring value of formSubmitted=<id of submitted form>
, will be used to indicate a form submitted on the previous request.
This setting has been added to help resolve an issue with multi-lingual setups.
When Umbraco Forms stores data for a record, it saves the values submitted for each field into a dedicated table for each type (string, date etc.). It also saves a second copy of the record in a JSON structure which is more suitable for fast look-up and display in the backoffice. Date values are serialized using the culture used by the front-end website when the form entry is stored.
When displaying the data in the backoffice, the date value needs to be parsed back into an actual date object for formatting. And this can cause a problem if the backoffice user is using a different language, and hence culture setting, than that used when the value was stored.
The culture used when storing the form entry is recorded, thus we can ensure the correct value is used when parsing the date. However, this doesn't help for historically stored records. To at least partially mitigate the problem, when you have editors using different languages to a single language presented on the website front-end, you can set this value to match the culture code used on the website. This ensures the date fields in the backoffice are correctly presented.
Taking an example of a website globalization culture code setting of "en-US" (and a date format of m/d/y
), but an editor uses "en-GB" (which formats dates as of d/m/y
). By setting the value of this configuration key to "en-US", you can ensure that the culture when parsing dates for presentation in the backoffice will match that used when the value was stored.
If no value is set, and no culture value was stored alongside the form entry, the culture based on the language associated with the current backoffice user will be used.
This configuration setting provides control over the client-side event used to trigger conditions. The change
event is the default used if this setting is empty. It can also be set to a value of input
. The main difference seen here relates to text fields, with the "input" event firing on each key press, and the "change" only when the field loses focus.
Scheduled deletion of records older than a specified number of days. It uses a background task to run the cleanup operation, which can be customized with the following settings.
By default this value is false
and no data will be removed. Even if forms are configured to have submitted data cleaned up, no records will be deleted. A note will be displayed in the backoffice indicating this status.
Set to true
to enabled the background task.
This will configure when the record deletion process will run for the first time. If the value is not configured the health checks will run after a short delay following the website start. The value is specified as a string in crontab format. For example, a value of "* 4 * * *"
will first run the operation at 4 a.m.
Defines how often the record deletion process will run. The default value is 1.00:00:00
which is equivalent to once every 24 hours. Shorter or longer periods can be set using different datetime strings.
Set this value to true
to disable the default behavior of indexing the form submissions into the Examine index.
If indexing has already occurred, you will still need to manually remove the files (found in App_Data\TEMP\ExamineIndexes\UmbracoFormsRecords
). They will be recreated if indexing is subsequently re-enabled.
Set this value to true
to enable the Forms API supporting headless and AJAX forms.
By default, the user's IP address is not recorded when a form is submitted and stored in the UFRecords
database table.
To include this information in the saved data, set this value to true
.
In Forms 12.1 amends were made to the default theme for Forms that improved accessibility. Specifically we provide the option to use alternative markup for rendering checkbox and radio button lists. These use the more semantically correct fieldset
and legend
elements, instead of the previously used div
and label
.
Although this semantic markup is preferred, it could be a presentational breaking change for those styling the default theme. As such we have made this markup improvement optional. You can opt into using it by setting this configuration value to true
.
In Umbraco 13 this configuration option will be removed and the semantic rendering made the only option.
When a form is rendered on the front-end website, a check is run to ensure that client-side validation framework is available and registered.
You can disable this check by setting the value of this configuration key to true
.
If you are rendering your forms dependency scripts using the async
attribute, you will need to disable this check.
Forms will by default track relations between forms and the content pages they are used on. This allows editors to see where forms are being used in their Umbraco website.
If you would like to enable this feature, you can set the value of this setting to true
.
By default, HttpContext.Items
is used as the storage mechanism for this tracking.
You can optionally revert to the legacy behavior of using TempData
by changing this setting from the default of HttpContextItems
to TempData
.
When using the File Upload field in a form, editors can choose which file extensions they want to accept. When an image is expected, they can for example specify that only .jpg
or .png
files are uploaded.
There are certain file extensions that in almost all cases should never be allowed, which are held in this configuration value. This means that even if an editor has selected to allow all files, any files that match the extensions listed here will be blocked.
By default, .NET related code files like .config
and .aspx
are included in this deny list. You can add or - if you are sure - remove values from this list to meet your needs.
For further control, an "allow list" of extension can be provided via this setting. If provided, only the extensions entered as a comma separated list here will be accepted in file uploads through forms.
This setting needs to be a true
or false
value and will enable the ASP.NET Anti Forgery Token and we recommend that you enable this option. Defaults to true
.
In certain circumstances, including hosting pages with forms in IFRAMEs from other websites, this may need to be set to false
.
This setting needs to be a true
or false
value and controls whether password fields provided in forms will be saved to the database. Defaults to false
.
Protection was added to uploaded files to prevent users from accessing them if they aren't logged into the backoffice and have permission to manage the form for which the file was submitted. As a policy of being "secure by default", the out of the box behavior is that this access protection is in place.
If for any reason you need to revert to the previous behavior, or have other reasons where you want to permit unauthenticated users from accessing the files, you can turn off this protection by setting this configuration value to true
.
This setting was added to add control over access to new forms. The default behavior is for all users to be granted access to newly created forms. To amend that to deny access, the setting can be updated to a value of Deny
. A value of Grant
or configuration with the setting absent preserves the default behavior.
Ability to administer access to Umbraco Forms using Umbraco's user groups. This can be used instead or in addition to the legacy administration which is at the level of the individual user. Set this option to true
to enable the user group permission management functionality.
This setting takes a comma-separated list of user group aliases which will be granted access automatically to newly created forms. This setting only takes effect when ManageSecurityWithUserGroups
is set to true
.
There are two "special" values that can be applied within or instead of the comma-separated list.
A value of all
will give access to the form to all user groups.
A value of form-creator
will give access to all the user groups that the user who created the form is part of.
Available from Forms 10.2.1, the FormsApiKey
configuration setting can be used to secure the Forms Headless API in server-to-server integrations. When set, API calls will be rejected unless the value of this setting is provided in an HTTP header.
Setting the value of EnableAntiForgeryTokenForFormsApi
to false
will disable the anti-forgery protection for the Forms Headless/AJAX API. You need to do this for server-to-server integrations where it's not possible to provide a valid anti-forgery token in the request.
This setting is used to configure the Date Picker form field range of years that is available in the date picker. By default this is a small range of 10 years.
Google has renamed these recently and the Site Key
refers to RecaptchaPublicKey
and Secret Key
is to be used for RecaptchaPrivateKey
Both of these configuration values are needed in order to use the "reCAPTCHA V3 with Score" field type implementing ReCaptcha V3 from Google.
This setting defines the domain from which the client-side assets for using the reCAPTCHA service are requested.
By default, the server-side validation of the reCAPTCHA response is sent to Google's servers at https://www.google.com/recaptcha/api/siteverify
.
Some customers with a locked-down production environment cannot configure the firewall to allow these requests and instead use a proxy server. They can use this setting to configure the URL to their proxy server, which will relay the request to and response from Google.
The validation message returned from a failed reCAPTCHA 3 request will be displayed in the form level validation summary and alongside the field.
To remove rendering at the field level, set this value to false
.
Sets the Data Type Guid to use to obtain the configuration for the rich text field type. If the setting is absent, the value of the default rich text Data Type created by Umbraco on a new install is used.
When using the "title and description" field type, if editors provide HTML in the "description" field it will be encoded when rendering on the website.
If you understand the risks and want to allow HTML to be displayed, you can set this value to false
.
Umbraco Forms is a commercial product. You have a 14-day free trial to try out the product. After your trial expires, you'll need to have a valid license to keep using the product on your site.
Licenses are sold per domain and will also work on all subdomains. With every license, you will be able to configure two development/testing domains.
The licenses are not bound to a specific product version. They will work for all versions of the related product.
Let's say that you have a license configured for your domain, mysite.com
, and you've configured two development domains, devdomain.com
and devdomain2.com
.
The license will cover the following domains:
localhost
*.mysite.com
www.mysite.com
mysite.com.local
devdomain.com
www.devdomain.com
devdomain2.com
www.devdomain2.com
You can have only 1 license per Umbraco installation.
There are a few differences as to what the licenses cover:
A single license covers the installation of Umbraco Forms in 1 production domain, as well as in 2 development domains.
The production domain includes all subdomains (e.g. *.mysite.com
), as well as the .local
extension (e.g. mysite.com.local
).
The development domains work with or without the www
subdomain.
The license allows for an unlimited number of forms.
The license also includes localhost
as a valid domain.
Each additional domain includes 1 live domain and 2 development/testing domains.
This is an add-on domain for existing licenses. Refunds will not be given for this product.
When you've bought a license you need to configure it with your domains. You can either configure your license right away or you can do it later by visiting your account on Umbraco.com.
Navigate to the Manage Licenses section.
Locate your unconfigured Forms license and choose Configure / Add domain.
Define the primary as well as up to two development domains for which the license will be used.
Once you have a configured Umbraco Forms license, you can add additional domains. This is relevant if you need your forms to be available on multiple public domains.
Navigate to the Manage Licenses section.
Locate your configured Forms license.
Choose Configure / Add domain.
Select Click here to buy at the bottom of the configuration page.
Configure the additional domain after completing the purchase, or do it later via your account.
Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.
Download your license from your Umbraco.com account - this will give you a .lic
file
Place the file in the /umbraco/Licenses
directory in your Umbraco installation
The .lic
file must be placed in the /umbraco/Licenses
directory to be registered by Umbraco Forms. If the file isn't placed correctly, the application will automatically switch to trial mode.
If you can't include the license file in the /umbraco/Licenses
directory for any reason, it is possible to configure an alternative location for the file.
It can be configured in the Umbraco installation's appSettings.json
file by adding the following configuration:
The value contains the path of your custom license directory relative to the root of your Umbraco installation.
This will also change the location for other Umbraco-related licenses in this project.
The algorithm used to decrypt Forms licenses is not supported on locked down FIPS compliant environments, such as those used in the defense industry.
If you are in this situation and unable to resolve it via configuration of the environment, please reach out to Umbraco support.
We have the possibility of generating and providing Forms licenses using alternate algorithms.
You can use this configuration if you reference Umbraco.Licensing
version 13.0.1
or higher.
Apply the following configuration with the appropriate algorithm - DES
(the default), TripleDES
, or AES
:
Due to the above, some links might reference the GitHub file instead of the GitBook article.
Group | Field Name | Alias | Data Type |
---|
Group | Field Name | Alias | Data Type |
---|
Field Name | Value |
---|
Field Name | Value |
---|
Field Name | Value |
---|
Field Name | Value |
---|
Field Name | Value |
---|
Field Name | Value |
---|
Field Name | Value |
---|
Field Name | Value |
---|
To configure the reCAPTCHA value, see the article.
To configure the SMTP settings, see the article.
For Umbraco Forms to work correctly, you need to include some client dependencies. For more information, see the article.
Umbraco Forms ships with client-side form validation features provided by the .
If using async
, please make sure to . This is necessary as it's not possible to guarantee that the asynchronous script will load in time to be recognized by the check. This can then cause a false positive warning.
The easiest way to add the dependencies is to fetch them from a . There are various CDN services you can use:
For example: .
When adding the script to the bottom of the page, you will also need to render the scripts. For more information, see article.
Field Name | Data Type | Field Type |
---|
If you wish to customize the Form Settings, see the article.
For Umbraco Forms to work correctly, you need to include some client dependencies. For more information, see the article.
To render the Form on the frontend, see the article.
By default the value of HTML id
attribute rendered for fieldsets and fields using the default theme is the GUID associated with the form element. Although , some browsers, particularly Safari, may report issues with this if the identifier begins with a number. To avoid such issues, the attribute values can be prefixed with the value provided in this configuration element.
In order to configure this setting, you will need to know the GUID or alias for the type and the property name for each setting. You can find .
If recording IPs and your site is behind a proxy, load balancer or CDN, we recommend using to ensure the correct value for the client IP is resolved.
Forms tracks the forms rendered on a page in order that the associated scripts can be placed in a different location within the HTML. Usually this is used to ) at the bottom of the page.
For more information, see the article.
Both of these configuration values are needed in order to use the "Recaptcha2" field type implementing legacy ReCaptcha V2 from Google. You can obtain both of these values after signing up to create a ReCaptcha key here -
You can obtain both of these values after signing up to create a ReCaptcha key here: .
Valid options are Google
(the default) or Recaptcha
. You may want to use the latter for control of which domains are setting cookies on your site. .
Do you have suggestions for or wishes for tutorials on Umbraco Forms? Let us know using the .
If you have multiple domains pointing at the same installation, you have the option to purchase and to your license.
You can look at the pricing, features, and purchase the license on the page.
Login to your account at .
Login to your account at .
Once a license has been configured with the domains, it is not possible to reconfigure them. An exception is when there is a mistake in the domain URL. As reconfiguration is not possible, you will either need to purchase an additional domain or a .
Title Box | Title | title | Textstring |
Title Box | Subtitle | subtitle | Textarea |
Form | Contact Form | contactForm | Form Picker |
Content | Body Text | bodyText | Richtext Editor |
Enter question | Name |
Alias | fullName |
Choose answer type | Short answer |
Field Type | text |
Mandatory | On |
Enter question | Company Name |
Choose answer type | Short answer |
Enter question | How should we contact you? |
Choose answer type | Single choice |
Prevalues Items | phone, email |
Mandatory | On |
Enter question | Enter your phone number |
Choose answer type | Short answer |
Field Type | tel |
Validation | Validate as a number |
Enter question | Enter your email address |
Choose answer type | Short answer |
Field Type |
Validation | Validate as an email address |
Enter question | What is your role? |
Choose answer type | Dropdown |
Prevalues Items | manager, developer, tester, writer, marketing specialist |
Enter question | Attachments (if any) |
Choose answer type | File upload |
Predefined allowed file types | pdf, png, jpg, gif, txt |
Enter question | Are you a Robot? |
Choose answer type | reCAPTCHAv2 |
Theme | light |
Size | normal |
Mandatory | On |
Surname | Short answer | text |
Age | Short answer | number |
Country | Short answer | text |
Phone number | Short answer | tel |
Email address | Short answer |
In this article, we'll take a look at the basic steps of creating a Form and adding the Form to your Umbraco site.
You can manage the Forms in the Forms section of the Umbraco backoffice. You need to have access to the section in order to see it.
If you do not see the Forms section, you might need to request access from the site Administrator. An Administrator can give permission to view the Forms section. This is done from the Users section of the backoffice.
To create a Form, follow these steps:
Navigate to the Forms section.
Click ... next to the Forms folder.
Select Create > New Form.
The Form Designer opens in the editor.
By default, there is a page, a fieldset, and a container available. The rest of the Form has to be added using the interface.
Enter a Name for the Form. Let's call it Our first form.
[Optional] Enter the Page Name. We'll call it The first page. Click Add new page at the bottom of the Forms designer to add more pages.
[Optional] Enter the Group Name. Click Add new group to add another group.
Click the Add Question button to add a new field.
The Choose field type dialog opens.
Select Short Answer. Enter the following details in the Edit field window:
In the Sensitive data field, choose if the field stores sensitive data. Once selected, the data from this field will be prevented from being downloaded and viewed by users who do not have permission to do so. Only members of the sensitive data user group will see this option of downloading.
Enter a Default Value for the field.
Add a Placeholder to make it easier for the user to fill in the Form.
Select if the field is Mandatory and customize the message.
Add a Validation to the field. There are some predefined validations available but it is possible to add your own custom validation as well.
Some form fields allow you to show or hide the label that's associated with the field when it is rendered within the form on the website. The default is always to show the field, but if you prefer to hide it, untick the Show label option.
Set Conditions for the field. For more information on Conditions, see the Setting-up conditional logic on fields article.
Some of the additional settings are dependent on which answer type was chosen. For example, since we selected Short Answer as our answer type we got two additional settings (Default Value and Placeholder).
Once the configuration is completed, click Submit. You will see that the field has been added to the Form designer.
To edit a field, click the cog icon next to the field to open the dialog. To copy the field and its properties, click the copy icon. To delete a field or a group, click the Recycle Bin icon.
Once you've added a few fields to your Form, you might want to change the order of questions. To do so, click Reorder in the top-right corner of the Form designer.
When reordering your Form, you can drag and drop the fields to make it look the way you want. Click I am done reordering to get back to the Form designer.
Forms can be grouped into pages. When rendered, each page will be presented one at a time to the user. They will need to complete the first page before moving onto the second and can navigate back and forth between pages.
To add a new page at the start or end of the form, use the buttons in the top right corner of the editing view.
You can also add a new page directly to the bottom of the form via the Add new page button. This will appear below other pages when at least one exists.
With a page, form fields can be arranged into groups. These will display all together on a single page but can be styled so the fields are appropriately grouped in fieldsets.
New groups are added via the Add new group button.
The last level of structure are columns that can be created within a group. To set the number of columns, click the cog icon next to the Group Name. You can now add or move fields to the new columns created.
Once have created the Form, save the design by clicking the Save button.
Import Form Definition allows you to import a form into your Umbraco site using a predefined JSON file. This file contains the form’s structure, fields, validations, workflows, and settings.
When you import a form definition, Umbraco uses the JSON structure to recreate the form as it was defined, enabling you to:
Reuse existing forms across multiple projects or environments.
Migrate forms between development, testing, and production environments.
Restore forms from backups or previously exported definitions.
Using the Import Form Definition option, you can manage your forms without having to recreate them.
If the product installation is set up to store form definitions in the database, you will be able to store forms within folders. This can help with organization and makes it easier to locate the forms for modification, especially if you plan to create many Forms.
To create a folder:
Go to the Forms section.
Click ... next to Forms folder.
Select Create.
Select New Folder.
Enter a Folder Name.
Click Create Folder.
You can create folders within folders, rename, move, import folders, or delete them.
To move or copy forms into folders, click the ... next to the Form and select Move.
To add the Form, follow these steps:
Navigate to the Content section of the Umbraco Backoffice.
Select the content page where you want to insert the Form. The page you choose should have a form picker which you can add in the Settings section under Document Types.
Click Choose and select the Form you want to insert. You will be able to select from the full list of forms. If available on your installation, you will also be able to select using a folder based view, which can be quicker to navigate when many forms have been prepared.
Click Choose.
The Form is inserted on your page. Click Save and publish.
Field Name | Value |
---|---|
Enter question
Name
Enter help text
Enter your name here