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.

How does it work?

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.

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

What does a license cover?

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.

Configuring your license

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.

2. Navigate to the Manage Licenses section.

3. Locate your unconfigured Forms license and choose Configure / Add domain.

4. Define the primary as well as up to two development domains for which the license will be used.

Add additional domains

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.

2. Navigate to the Manage Licenses section.

3. Locate your configured Forms license.

4. Choose Configure / Add domain.

1. Select Click here to buy at the bottom of the configuration page.

2. Configure the additional domain after completing the purchase, or do it later via your account.

Reconfiguration of domains

Installing your license

Once you've configured your license with the correct domains, you are ready to install the license on your Umbraco installation.

1. Download your license from your Umbraco.com account - this will give you a .lic file

2. 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.

Multiple license files

You can install multiple Umbraco Forms license files without merging them. Place each license file in the /umbraco/Licenses directory (or an alternative location). Each file should begin with umbracoForms, for example, umbracoForms.example1.lic and umbracoForms.example2.lic. This setup allows your installation to recognize multiple licensed domains.

Alternative license location

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:

{
  "Umbraco": {
    "Licensing": {
        "Directory": "~/custom-licenses-folder/"
    }
  }
}

The value contains the path of your custom license directory relative to the root of your Umbraco installation.

Federal Information Processing Standards (FIPS) Compliant Environments

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.

Apply the following configuration with the appropriate algorithm - DES (the default), TripleDES, or AES:

  "Umbraco": {
    "Licensing": {
      "LicenseEncodeAndDecodeAlgorithm": "DES|TripleDES|AES"
    },

This documentation platform covers only major versions of the Umbraco Forms since Umbraco 9+. If you are using an older version of Umbraco Forms, you will need to go elsewhere.

This article shows how to manually upgrade Umbraco Forms to run the latest version.

Get the latest version of Umbraco Forms

To get the latest version of Umbraco Forms, you can upgrade using:

NuGet

• 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.

Visual Studio

1. Go to Tools -> NuGet Package Manager -> Manage NuGet Packages for Solution... in Visual Studio, to upgrade your Forms:

2. Select Umbraco.Forms.

3. Select the latest version from the Version drop-down and click Install.

1. When the command completes, open the .csproj file to make sure the package reference is updated:

<ItemGroup>
  <PackageReference Include="Umbraco.Forms" Version="xx.x.x" />
</ItemGroup>

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 workflows and control what happens once a form has been submitted.

Quick Links

This article provides specific upgrade documentation for migrating to Umbraco Forms version 15.

Version Specific Upgrade Notes History

Version 15 of Umbraco Forms has a minimum dependency on Umbraco CMS core of 15.0.0. It runs on .NET 9.

Breaking changes

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:

Configuration

• The setting FieldSettings:Recaptcha3:ShowFieldValidation has a new default of true.

• The setting Options:EnableMultiPageFormSettings has a new default of true.

Asynchronous Methods

• 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.

Code

• 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.

Legacy version specific upgrade notes

If there are any breaking changes or other issues to be aware of when upgrading they are also noted here.

Release history

This section contains the release notes for Umbraco Forms 15 including all changes for this version.

• Ignore existing corrupt record data and ensure proper JSON serialization when storing entries with forged data

• Parse magic string placeholders in advanced validation rule error message

• Only parse magic string placeholders in field mapping static values (fixes JSON deserialization error)

• Fix invalid CreatedBy and UpdatedBy column name errors in migration by getting 'slim' objects from repository

• Fix export file path generation and checking (enhances Linux/Docker compatibility)

• All items detailed under release candidates for 15.1.0.

• Resolved minor backoffice issues when creating and saving prevalue and data sources.

Validation rules across form fields

When creating forms you are able to add validation to individual fields, making them mandatory or applying a regular expression pattern. With the 13.4 release we are looking to make this more powerful, by allowing the addition of validation rules for the entire form. The idea is that this will allow you to validate expressions based on multiple fields. For example, "these two email fields should be the same", or "this date should be after this other one".

When the form is rendered, the validation rules will be applied on the client, where we support both the aspnet-client-validation and jquery.validate libraries. They are also verified server-side. In this way you can ensure the submission is only accepted if it meets the requirements.

Feedback on this feature in particular is welcome.

Tracking editor activity

Copy of workflows

File upload validation messages

Other

Other bug fixes included in the release:

• Fixed Forms dashboard form title and icon alignment.

• Fixed issue with creation of folder for forms.

• Rendered file upload previews in the backoffice.

• Fixed issue with saving the "Hide field validation labels" value when editing form settings.

• Fixed issue with selection of Document Type on the "Save as Umbraco node" workflow type.

• Compatibility with Umbraco 15.0.0

• Compatibility with Umbraco 15.0.0-rc4

• Compatibility with Umbraco 15.0.0-rc3

• Preview of features and bug fixes due in 13.3 and 14.2:

  • Added Umbraco Flavoured Markdown component for the rendering of form names within a block list

• Compatibility with Umbraco 15.0.0-rc2

• Preview of features and bug fixes due in 13.3 and 14.2:

  • Improve cross-platform check when exporting to Excel.

• Compatibility with Umbraco 15.0.0-rc1
• Preview of features due in 13.3 and 14.2:

  • 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.

Umbraco.Forms.Deploy

This Deploy add-on adds support for transferring, restoring, exporting and importing (including migrating between major versions) of Umbraco Forms data.

15.1.0 (January 23rd 2025)

• All items from 15.1.0-rc1

15.1.0-rc1 (December 17th 2024)

• Set the form entities created/updated by to the resolved user when deploying (requires Umbraco Forms 15.1)

15.0.0 (November 14th 2024)

• Update Forms and Deploy dependencies to 15.0.0

15.0.0-rc4 (November 13th 2024)

• Update Forms and Deploy dependencies to 15.0.0-rc4

15.0.0-rc3 (November 7th 2024)

• Update Forms and Deploy dependencies to 15.0.0-rc3

15.0.0-rc2 (October 24th 2024)

• Update Forms and Deploy dependencies to 15.0.0-rc2

15.0.0-rc1 (October 14th 2024)

• Update Forms and Deploy dependencies to 15.0.0-rc1

Legacy release notes

You can view the System information of the form in the Info tab.

To access the Form Information:

1. Go to the Forms section.

2. Open a Form you wish to customize.

3. Click Info in the top-right corner of the screen.

General

The "General" panel displays system information about the form. The date the form was created and last updated are shown. Also available are the integer and GUID identifiers that are useful when referring to the form in code.

References

Information about which pages a form is hosted on is tracked by Umbraco every time a content item is saved.

The list of pages where the form is hosted is shown in this section.

In this article, we'll take a look at the basic steps of creating a Form and adding the Form to your Umbraco site.

Accessing the Forms Section

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.

Creating a Form

To create a Form, follow these steps:

1. Navigate to the Forms section.

2. Click ... next to the Forms folder.
3. Select Create > New Form.
4. The Form Designer opens in the editor.
5. By default, there is a page, a fieldset, and a container available. The rest of the Form has to be added using the interface.

6. Enter a Name for the Form. Let's call it Our first form.
7. [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.
8. [Optional] Enter the Group Name. Click Add new group to add another group.
9. Click the Add Question button to add a new field.
10. The Choose field type dialog opens.
11. Select Short Answer. Enter the following details in the Edit field window:
12. 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.

13. Enter a Default Value for the field.

14. Add a Placeholder to make it easier for the user to fill in the Form.

15. Select if the field is Mandatory and customize the message.

16. Add a Validation to the field. There are some predefined validations available but it is possible to add your own custom validation as well.

17. 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.

18. 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).

19. 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.

Structuring the Form

Ordering Fields

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.

Form Pages

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.

Form Groups

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.

Form Columns

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.

Saving the Form

Once have created the Form, save the design by clicking the Save button.

Importing a Form

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.

Organizing Forms in Folders

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:

1. Go to the Forms section.

2. Click ... next to Forms folder.

3. Select Create.

4. Select New Folder.
5. Enter a Folder Name.

6. 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.

Adding the Form to the Umbraco Site

To add the Form, follow these steps:

1. Navigate to the Content section of the Umbraco Backoffice.

2. 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.
3. 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.
4. Click Choose.

5. The Form is inserted on your page. Click Save and publish.

In this article, you will find information about accessing the Form Settings and the options available to customize your Form.

To access the Form Settings:

1. Go to the Forms section.

2. Open a Form you wish to customize.

3. Click Settings in the top-right corner of the screen.

Settings Options

The following options are available in Forms Settings:

Store Records

By default, all submitted records are saved in the database. This option allows you to view and export the saved records from the queries overview. If you do not want to store data (due to policies in your organization), you can uncheck the box.

Disabling this option will prevent database records from being stored, but any file uploads made as part of the form submission will still be retained. If you do not want the files to be stored, ensure that any process or method used to process, move, or copy them to a different location also removes the file.

Captions

Customize the labels of the Submit, Next, and Previous buttons used in your Form.

Styling

Set a stylesheet to give your Form custom styling. You have an option to disable the default styling. Enabling the Disable default stylesheet option will prevent a default stylesheet to be added to the pages where the Form is placed.

Validation

Define a message that is displayed when a field is mandatory, when a value is not supplied, or when the value is invalid.

The following Validations are available:

Autocomplete

The autocomplete setting for the overall form can be changed from the default of "None" to "On" or "Off". Setting this explicitly will control how the browser offers automatic prompts to the user when completing the form.

Multi-page forms

The settings available in this section allow you to customize how multi-page forms are presented to site visitors.

Moderation

Enabling this feature allows the moderator to manage the approval status of a form. This can be used in a number of scenarios. For example, if the form submission will be publicly shown, you can control which are published.

Fields Displayed

By default, a constant set of fields are displayed when form entries are shown in a list. You will see the first three fields in the form, plus some system information like the record state and the date it was created.

To customize this, turn off the "Display default fields" option and select the ones you wish to display.

Data Retentions

To help protect site visitor privacy, rules can be configured in this section for the automatic deletion of submissions. You can set how long to retain records for each state (submitted, approved or rejected).

Umbraco Forms comes with a bunch of default Field Types also known as Answer Types. You can choose from different field types when adding new fields to your Forms.

By default, the following Field Types are available:

• Short Answer: A textbox allows up to 250 characters.
• Long Answer: A bigger text field that allows multiline text and more than 250 characters.
• Checkbox: Displays a single checkbox that can be checked or not.
• Password: Allows to type a password. The input is not visible when typing.
• Multiple Choice: Displays a list of items with a checkbox for each item where the user can select multiple options.
• Data Consent: A field for the purpose of asking for data consent. By default, this field is added to all new Forms.
• Dropdown: Displays a list of items in a drop down box where the user can select a single option.
• Single Choice: Displays a list of items with a radio button for each item where the user can select a single option.
• Title and Description: Displays a read-only title and description for a set of form fields.
• Rich Text: Displays read-only formatted text that can be used to provide additional information and links within a form.
• Hidden: A hidden field allows developers to include data that cannot be seen or modified by users when a Form is submitted.

In this article, you can learn how to add extra functionality to your Form by attaching workflows.

Workflows are a way of defining actions after your Form is submitted like sending an email or creating a content node.

Default Workflow

The behavior to display a message to the user who submitted the form can be configured by clicking on the built-in first workflow step. This step is labelled Submit message/Go to page, and it can also configure the redirection to another page.

If a value is selected for Go to page, it will be used to redirect to that page once the form has been submitted.

If no value is selected, the message in Message on submit is displayed to the user on the same page, instead of the form fields. This is implemented via a redirect to the current page, ensuring that the form can't be accidentally resubmitted.

By default, the message is created and rendered in plain text. If you need to add formatting to the message, toggle the Format message in rich text button.

Video Tutorial

Adding a Workflow

At the bottom of your Form, a default workflow is already attached to the Form, as well as an option to configure the workflows.

Clicking Configure workflow will give you the option to configure existing workflows, as well as setup new ones.

Choose a Workflow

Update Type-specific Settings

Once the Workflow Type has been selected, you will need to configure the workflow. There are different settings depending on the type that has been selected.

Configuring Condition on a Workflow

You can apply conditions to a workflow that trigger it only under specific circumstances. After adding the desired workflow type (for example, sending an email), you can add a condition to the workflow.

Select Enable conditions to open the condition editor. In the condition editor, you will see options to create logic that determines when the workflow should run. The condition is generally based on the values of the form fields.

For example: You have a form with a dropdown field labeled Preferred Contact Method with options such as Email and Phone. You can set up a workflow that sends an email notification only when the user selects Email.

Now, this email notification will only be sent when the user selects Email as their preferred contact method.

Fill in the rest of the settings and click Submit. The workflow is added to your Form and displayed at the bottom of the page.

Workflow Processing

When a form is submitted, any workflows associated with the "submit" stage of the form will run sequentially in the configured order. The record is stored after these workflows are completed, and as such they can make changes to the information recorded.

Similarly, approval of a form entry, whether automatic or manual, will trigger the execution of the workflows associated with the "approve" stage.

Rejection of an entry will trigger the execution of the workflows associated with the "reject" stage.

If a workflow encounters an unexpected error, it will silently fail from the perspective of the user submitting the form. The exception along with the other details of the failed operation is recorded to the log.

From Umbraco Forms versions 8.13.0 and 10.1, an audit trail has been made available. In the list of entries for a form, a summary is presented that shows how many workflows were executed, and how many were successful:

For each entry, in the backoffice a table can be viewed that shows each of the workflows and the success, or otherwise, of the operation.

For any workflows that did not complete successfully, a "Retry" link is available to trigger the workflow again. This is useful for example if there was a temporary infrastructure issue that perhaps prevented an email going out. You would be able to retrigger the workflow once the issue is resolved.

Sometimes you might have a field in your Form, that you want to show only if the user has entered a specific value in another field.

You can achieve this setting by using conditional logic on Fields.

Example

Take a look at the following:

In this case, it makes sense to only show the email or phone field when the corresponding option is selected in the How should we contact you? field.

To enable conditions for the Email and Phone fields, do the following:

1. Click the cog wheel next to the Email and Phone field. The Edit question dialog opens.

2. Enable Conditions. The condition field displays more options:
3. Set the appropriate conditions and click Submit.

Action and Logic Types

There are two Action Types:

• Show: the field will be displayed if the rules match

• Hide: the field will be hidden if the rules match

Next up, you'll need to specify the Logic Type. This setting is only important if you have multiple rules.

• All: All of the rules must match

• Any: Any of the rules may match

Adding a new condition

When adding a new condition, you'll need to select the field where you want to evaluate the value and can select an operator.

In this example, we only want to show the Phone field if the value of the How should we contact you field is Phone.

Similarly, you can display the Email field, if the value of the How should we contact you field is Email. You can see the conditions added to each field in the Forms designer:

Result

When both the conditions have been set as shown above, this is how it will look on the frontend:

In this example, we have only selected Phone but it is possible to choose both Phone* and Email and display both the fields.

Conditions for Pages and Fieldsets

As well as showing or hiding a field based on conditions, you can also apply conditions to groups of fields (known as fieldsets) or to pages. The process is the same as described above.

When applying a condition to a page, effectively you are controlling the display of the submit button (for a single-page form) or the next/previous buttons (available on multi-page forms). In this way you can ensure that the entry so far is complete before accepting it or allowing the user to move onto the next page.

Conditions for Dates

You can apply conditions to dates as well as strings. When you use the date picker field, you can set a condition if a submitted date is greater/less than a specific date.

The File Upload field allows the users to upload a file along with the Form on your website.

In this article, you will find details about the configuration options you have for the File Upload field.

Predefined allowed File Types

You can choose to specify which files you want to allow the user to upload, when accessing the Form.

To allow only specific files:

1. Select the specific File Types the user should be able to upload.

2. Click Submit.

User Defined Allowed File Types

If the list of predefined file types does not include a specific file type, you can add additional ones.

To add new file type:

1. Type a file extension name in the User defined allowed file types field.

2. Click +.

3. Click Submit.

Server-side file validation

The file upload field type will verify the file contents using the registered set of IFileStreamSecurityValidator instances.

In Umbraco Forms, reCAPTCHA V3 comes out of the box.

reCAPTCHA v3 allows you to verify if an interaction is legitimate without any user interaction.

Enabling reCAPTCHA V3

Follow these steps to enable reCAPTCHA V3 in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA v3 enabled.

3. Add a new question and select ReCAPTCHA v3 with Score as its answer type.

4. Make sure the field is set as Mandatory.

5. Configure ReCAPTCHA settings in the appSettings.json file to include public and private keys:

"Umbraco"{
    "Forms": {
      "FieldTypes": {
        "Recaptcha3": {
            "SiteKey": "",
            "PrivateKey": ""
          }
        }
      }
   }

Pikaday date picker can be localized based on the page the Form is rendered on.

The date picker displays the picked date in the required locale. Using JavaScript, a hidden field is updated with a standard date format to send to the server for storing record submissions. This avoids the locale mixing up the dates.

To achieve localized date, a Razor partial view is included at /Views/Partials/Forms/Themes/default/DatePicker.cshtml.

The DatePicker.cshtml includes the moment-with-locales.min.js library to help with the date locale formatting and the appropriate changes to Pikaday to support the locales. If you wish to use a different DatePicker component, edit the DatePicker.cshtml file as per your needs.

Configure the date picker

In Umbraco Forms, reCAPTCHA V2 comes out of the box to help you to protect your site from spam, malicious people, and so on.

Enabling reCAPTCHA V2

Follow these steps to enable reCAPTCHA V2 in Umbraco Forms:

1. Go to the Forms section in the backoffice.

2. Find the form that should have ReCAPTCHA v2 enabled.

3. Add a new question and select ReCAPTCHA v2 as its answer type.

4. Make sure the field is set as Mandatory.

5. Configure ReCAPTCHA settings in the appSettings.json file to include public and private keys:

"Umbraco"{
    "Forms": {
      "FieldTypes": {
        "Recaptcha2": {
            "PublicKey": "",
            "PrivateKey": ""
          }
        }
      }
   }

There are some default prevalue source types that can be used. In this article, we will give a quick overview of them:

Get values from textfile

Upload a textfile that contains the prevalues. Each prevalue should have its own line in the file. Once the file has been uploaded, you can find it in ~/wwwroot/App_Data/UmbracoForms/Data/PreValueTextFiles/{GUID} where the {GUID}is replaced with the pre-value ID.

Umbraco Documents

Allows to use content nodes from a specific source as prevalues. You can apply the following settings in the Details section:

• Select which Value field should be used for the value of the prevalue.

• You can define the root node by either

  • Choosing a node directly from the Content tree or

  • Using XPath

• Enable Use current page as root instead of choosing a specific root node. The preview is not available when this setting is enabled.

• Select a specific Document type, if the selected root node contains a different Document Type.

• Enable List all Descendants of the selected root node to list all levels of descendants.

• Select Order by from the drop-down list to display how the prevalue list should be ordered.

• Select your preferred Cache option for caching the list of prevalues when rendering in a form.

SQL Database

You can provide the following details in the Details section:

Connect to a OleDB compatible database table and construct a prevalue source from it. Once selected, it will be editable from the Forms interface.

The following configurations need to be set in the Details section:

• Connection string (either choose one from your web.config or add another from a textfield).

• Connection String from configuration

• Table Name

• Key Column

• Value Column

• Caption Column

• Select your preferred Cache option for caching the list of prevalues when rendering in a form.

Umbraco Data Type Prevalues

Choose an Umbraco Data Type to use its configured prevalue collection.

In the example below, the prevalue collection from a Data Type called Home - Font - Radio button is used:

To view the Entries for each Form, go to the Form and click on the Entries tab.

Video overview

Entries Overview

When accessing the Entries viewer, you will be able to see all the entries submitted via the Form.

Viewing the Entries

By default, the list is filtered to show entries only from the past month. If you want to change the date range, pick the appropriate time period from the date picker. You can also filter the entries by specific words using the Search field on the left.

Click Entry details on each record in the list to open the full set of information recorded for the form entry. Clicking on the entry record displays the Clear and Delete buttons.

Editing the Entries

If configured via the permissions model and supported by the version of Umbraco Forms you are running, entries may be editable via the backoffice. If available, click the Edit button to switch the read-only view of an entry to an editable one and Save to record the changes. An audit trail will show who and when updates on the entry were made.

Validation will operate as is configured for the form in terms of mandatory fields and those that must match a particular pattern. Conditional display of fields is not supported.

Exporting Entries

To export all the entries from your Form:

1. Go to the Forms section.

2. Navigate to the Form Entries you wish to export.

3. Click Export.
4. The Export dialog opens. Choose a format such as Excel File to export the Form records to.
5. Click Export.

6. Click Save.

If you have fields that allow the user to upload files within your form, you will also have the option to download a zip file containing these files. You can either download the files in the structure that they are stored on the web server's disk. Or you can download them organised by entry, so it's easier to match up the entry listed in the spreadsheet download with the uploaded file(s).

Record Actions

When selecting entries, it is possible to execute different actions. To select an entry, click anywhere on the entry.

Select at least 1 record to see the available actions. By default, there are 2 possible actions:

• Clear

• Delete

In this article, you will find information about accessing the Forms Advanced Options and the features available to customize your Form.

To access the Form Advanced Options:

1. Navigate to the Forms section.

2. Open a Form you wish to customize.

3. Click Advanced in the top-right corner of the screen.

Validation Rules

When creating forms you can add validation to individual fields, making them mandatory or applying a regular expression pattern. You can provide validation rules for the entire form via the advanced options. This allows you to validate expressions based on multiple fields. For example, "these two email fields should be the same", or "this date should be after this other one".

To add new rules, you need to provide the rule definition, an error message and select a field to which the message will be associated. Once created you can click to edit or delete them from the list.

Examples

One example use case would be ensuring that two fields match each other, perhaps when asking for a user's email address. Given two fields on the form, one with the alias of email and the other compareEmail, the rule would be:

A slightly more complex example could be with two dates, where, if provided, you want to ensure the second date is later than the first. So given fields with aliases of startDate and endDate a rule would look like this:

Rules can be nested too. In this final illustrative example, we have two fields. One with the alias choose is a drop-down list with two values: A and B. The second field with alias test we want to be completed only if the user selects B. So we create a rule that is valid only if A is selected OR B is selected AND test is completed.

Overall, you can create rules of varying complexity, using comparisons between fields and static values.

When the form is rendered, these validation rules will be applied on both the client and server-side. In this way, you can ensure the submission is only accepted if it meets the requirements.

Prevalue sources are a way to pre-define and/or retrieve a list of items from a certain source. They can be added in any field types that include some kind of list like Dropdown and Multiple/Single Choice lists.

Setting up a Prevalue Source

Prevalue sources can be managed in the Prevalue sources folder available in the Forms section.

To set a prevalue source:

1. Go to the Forms section.

2. Click ... next to the Prevalue Sources folder.

3. Click Create.

4. The Choose prevalue source type pane opens in the right-side of the editor.

Configuring the Prevalue Source

Depending on the prevalue source type you choose, you'll need to provide some additional settings. For this article, we will select Get values from textfile.

2. Enter a Name for the prevalue source type. Let's call it My Prevalue Source.

3. Now, create a file containing the list to use as prevalues. For example: a .txt file containing the following values:
4. Select Click to upload in the Text File.

5. Choose the text file you created. Click Open.

6. Select your preferred Cache option for caching the list of prevalues when rendering in a form.

7. Click Save.

If you would like to have different values presented to your users from the value stored, you can provide two values per line, separated with a vertical bar (|), e.g.:

In this case the user would pick from a list showing the captions, but the single integer values would be stored with the record.

This can be useful if the recorded entries are used in any subsequent workflows or business processes, where particular values, that aren't appropriate for the user to select from, are required.

Defining Cache Options for the Prevalue Source

Sometimes retrieving the list of options for a prevalue source can be an expensive operation. If the source depends on data from external systems, it could be that the list changes regularly or rarely.

Given the variation here, we allow you to select an appropriate level of caching for the list of options.

You can choose between:

• No Caching - no caching will be applied and the list of options will be retrieved from source on every request. You will likely only want to choose this option if the information changes frequently and it's important that the latest is presented to website visitors.

• Cache For Specified Time - the list will be cached for the period of time provided.

• Cache With No Expiry - the list will be cached on first request and not retrieved again until either the prevalue source is edited or the website is restarted. This ismost appropriate to use for information held within the prevalue source data itself (such as when uploading a text file).

Attaching a Prevalue Source to a Field

Once a prevalue source has been created, it can be used while building Forms in the Forms designer.

Example: Let's add a Multiple Choice field type in our Form.

If there is at least one prevalue source defined in the project, the Prevalues source will contain a dropdown from where you can choose the predefined value.

Once you have selected the prevalue source, the values are rendered in the Forms designer from the attached source.

When forms are created, editors will want to add them to pages in Umbraco. To do this they need a Document Type with a property that uses a Data Type based on a Form Picker property editor.

Umbraco Forms provides three variations of a form picker.

Most commonly used is Form Picker (single). This will allow the editor to select a single form for display on page.

Rarely but feasibly, you will have a requirement to present multiple forms on a page. Should this be appropriate, you can use Form Picker (multiple).

Finally you can provide further flexibility for the editor to select not only a form but also the theme and redirect as well. For this you will use the Form Details Picker.

Configuring the Data Type

Each property editor allows you to restrict the forms that can be chosen with the Data Type. You do this by setting either or both of the list of "Allowed folders" or "Allowed forms".

The "Form Details Picker" also allows you to select whether a theme or redirect selection is available.

Property Value Conversion

The type of a property based on the Form Picker presented in a Razor class library is as follows:

Content Delivery API Expansion

There are multiple built-in Workflow Types that can be used to extend the functionality of your form. Do you want to post the submitted form as XML, send the data as an email, or send a notification through another messaging system? These are a few of the options you can choose when working with Umbraco Forms.

Video Tutorial

Change Record State

Used to automatically Approve Record, Reject Record or Delete Record once it is submitted. Configure words that you want to match and select whether these words should trigger an approval or deletion of the record.

Post as XML

Used to post the Form as an XML to a specified URL. The following configuration can be set:

• Workflow Name

• URL (required)

• Method

• XsltFile - used to transform the XML

• Headers - map the needed files

• User

• Password

Save as an XML file

Saves the result of the Form as an XML file by using XSLT. The following configuration can be set:

• Workflow Name

• Path (required) - where to save the XML file

• File extension (required)

• XsltFile - used to transform the XML

The path needs to point to a folder, not a file name. The files are then stored locally, and relative paths are resolved to the content root.

Save as Umbraco Content Node

Saves a submitted Form as a new content node. You need to choose a Document type and match the fields in the Form with the properties on the selected Document Type.

You can also choose to set a static value to fill in the properties:

In the example above, a Document Type called Blogpost is selected for creating the new Content node.

The value from the Name field will be added as the Node Name property in the new Content node. The value from the Email field will be used as the Content property.

The following configuration can be set:

• Workflow Name

• Publish - choose whether to publish the node on submission

• Where to save - choose a section in the content tree where this new node should be added

Send Email

Sends the result of the Form to the specified email address. The following configuration can be set:

• Workflow Name

• Message (required)

• Attachment - specify whether file uploads should be attached to the email

• Recipient Email (required)

• CC Email

• BCC Email

• SenderEmail

• Reply To Email

• Subject of the email (required)

For fields that accept multiple email addresses (Recipient Email, CC Email, BCC Email), you can separate addresses using semicolons (';') or commas (','). For example:

If the Sender Email field is not populated, the address used will be read from CMS configuration.

The fallback behavior also applies to the other email workflows.

Send Email with Template (Razor)

Uses a template to send the results of the Form to a specified email address.

The following configuration can be set:

• Workflow Name

• Email Template (required) - specify which template you want to use

• Header text - formatted text that will be rendered above the form entry details

• Footer text - formatted text that will be rendered below the form entry details

• Attachments - specify whether file uploads should be attached to the email

• Recipient Email (required)

• CC Email

• BCC Email

• SenderEmail

• Reply To Email

• Subject of the email (required)

Send Form to URL

Sends the Form to a URL either as a HTTP POST or GET. The following configuration can be set:

• Workflow Name

• URL (required)

• Method (required) - POST, GET, PUT or DELETE

• Standard Fields - optionally include and map standard form information such as name and page URL

• Fields - map the needed fields

• User

• Password

When mapping fields, if any are selected, only those chosen will be sent in the request to the configured URL. If no fields are mapped, all will be sent.

The receiving endpoint extracts form fields and values using GET for querystrings and POST for form collections.

As an illustrative example, the following code can be used to write the posted form information to a text file:

Send XSLT Transformed Email

Sends the result of the Form to an email address with full control over the email contents by providing an xslt file. The following configuration can be set:

• Workflow Name

• XSLT File - specify which file should be used to transform the content

• Recipient Email (required)

• CC Email

• BCC Email

• SenderEmail

• Reply To Email

• Subject of the email (required)

Slack

Allows to post the Form data to a specific channel on Slack. The following configuration can be set:

• Workflow Name

• Webhook URL (required)

Umbraco Forms includes some helper methods that return records of a given Form, which can be used to output records in your templates using razor.

Available Methods

The methods can be found by injecting the Umbraco.Forms.Core.Services.IRecordReaderService interface. For performance reasons, all these methods are paged.

GetApprovedRecordsFromPage

PagedResult<Record> GetApprovedRecordsFromPage(int pageId, int pageNumber, int pageSize)

Returns all records with the state set to approved from all Forms on the Umbraco page with the id = pageId .

GetApprovedRecordsFromFormOnPage

PagedResult<Record> GetApprovedRecordsFromFormOnPage(int pageId, Guid formId, int pageNumber, int pageSize)

Returns all records with the state set to approved from the Form with the id = formId on the Umbraco page with the id = pageId as a PagedResult<Record>.

GetApprovedRecordsFromForm

PagedResult<Record> GetApprovedRecordsFromForm(Guid formId, int pageNumber, int pageSize)

Returns all records with the state set to approved from the Form with the ID = formId as a PagedResult<Record>.

GetRecordsFromPage

PagedResult<Record> GetRecordsFromPage(int pageId, int pageNumber, int pageSize)

Returns all records from all Forms on the Umbraco page with the id = pageId as a PagedResult<Record>.

GetRecordsFromFormOnPage

PagedResult<Record> GetRecordsFromFormOnPage(int pageId, Guid formId, int pageNumber, int pageSize)

Returns all records from the Form with the id = formId on the Umbraco page with the id = pageId as a PagedResult<Record>.

GetRecordsFromForm

PagedResult<Record> GetRecordsFromForm(Guid formId, int pageNumber, int pageSize)

Returns all records from the Form with the ID = formId as a PagedResult<Record>.

The returned objects

All of these methods will return an object of type PagedResult<Record> so you can iterate through the Record objects.

The properties available on a Record are:

int Id
FormState State
DateTime Created
DateTime Updated
Guid Form
string IP
int UmbracoPageId
string MemberKey
Guid UniqueId
Dictionary<Guid, RecordField> RecordFields

In order to access custom Form fields, these are available in the RecordFields property. Furthermore there exists an extension method named ValueAsString on Record in Umbraco.Forms.Core.Extensions, such that you can get the value as string given the alias of the field.

This extension method handle multi value fields by comma separating the values. E.g. "A, B, C"

Sample razor script

Sample script that is outputting comments using a Form created with the default comment Form template.

@using Umbraco.Core;
@using Umbraco.Cms.Core.Composing;
@using Umbraco.Forms.Core.Extensions;
@inject IRecordReaderService _recordReaderService;

<ul id="comments">
    @foreach (var record in _recordReaderService.GetApprovedRecordsFromPage(Model.Id, 1, 10).Items)
    {
    <li>
        @record.Created.ToString("dd MMMM yyy")
        @if(string.IsNullOrEmpty(record.ValueAsString("email"))){
            <strong>@record.ValueAsString("name")</strong>
        }
        else{
            <strong>
                <a href="mailto:@record.ValueAsString("email")" target="_blank">@record.ValueAsString("name")</a>
            </strong>
        }
        <span>said</span>
        <p>@record.ValueAsString("comment")</p>
    </li>
    }
</ul>

With Umbraco Forms, it is possible to customize the output markup of a Form, which means you have complete control over what Forms will display.

Customizing the Default Views

The razor macro uses some razor views to output the Form:

• 1 view for each fieldtype

• 1 view for the scripts

• 1 view for the rest of the Form

You can find the default views in the ~\Views\Partials\Forms\Themes\default folder.

To avoid your custom changes to the default views from being overwritten, you need to copy the view you want to customize into your theme folder, e.g. ~\Views\Partials\Forms\Themes\YourTheme, and edit the file in YourTheme folder.

Form.cshtml

This is the main view responsible for rendering the Form markup.

The view is separated into two parts, one is the actual Form and the other will be shown if the Form is submitted.

This view can be customized, if you do so it will be customized for all your Forms.

Script.cshtml

This view renders the JavaScript that will take care of the conditional logic, customization won't be needed here.

FieldType.*.cshtml

The rest of the views start with FieldType, like FieldType.Textfield.cshtml and those will output the fields. There is a view for each default fieldtype like textfield, textarea, checkbox, etc)

Contents of the FieldType.Textfield.cshtml view (from the default theme):

@model Umbraco.Forms.Mvc.Models.FieldViewModel
@using Umbraco.Forms.Mvc

<input type="text"
    name="@Model.Name"
    id="@Model.Id"
    class="@Html.GetFormFieldClass(Model.FieldTypeName) text"
    value="@Model.ValueAsHtmlString"
    maxlength="500"
    @{if(string.IsNullOrEmpty(Model.PlaceholderText) == false){<text>placeholder="@Model.PlaceholderText"</text>}}
    @{if(Model.Mandatory || Model.Validate){<text>data-val="true"</text>}}
    @{if (Model.Mandatory) {<text> data-val-required="@Model.RequiredErrorMessage"</text>}}
    @{if (Model.Validate) {<text> data-val-regex="@Model.InvalidErrorMessage" data-val-regex-pattern="@Html.Raw(Model.Regex)"</text>}}
/>

Umbraco Forms uses ASP.NET Unobtrusive Validation which is why you see attributes like data-val and data-val-required.

This can be customized but it's important to keep the ID of the control to @Model.Id since that is used to match the value to the Form field. For fields that are conditionally hidden, without an ID of @Model.Id the control won't be shown when the conditions to show the field are met. An ID needs to be added to text controls such as headings and paragraphs.

The view model for the partial view for a field is FieldViewModel. This defines properties that may be useful when creating new themes or custom fields, some of which are shown in the code samples above. Others include:

• AdditionalSettings - a dictionary of the settings keys and values populated for the form field. These can be retrieved in typed form by key using e.g. Model.GetSettingValue<int>("MaximumLength", 255);.

The following are available on the model but only populated for fields that support file upload:

• AllowAllUploadExtensions- a boolean indicating whether all file extensions are permitted for upload.

• AllowedUploadExtensions- a collection of strings indicating the file extensions that are permitted for upload.

• AllowMultipleFileUploads- a boolean indicating whether selecting multiple files for upload is allowed.

Customizing for a Specific Form

It is also possible to customize the markup for a specific Form.

You will need to create folder using the ID of the Form: ~\Views\Partials\Forms\{FormId} (find the id of the Form in the URL when you are viewing the Form in the backoffice.)

As an example if your Form ID is 0d3e6b2d-db8a-43e5-8f28-36241d712487 then you can overwrite the Form view by adding the Form.cshtml file to the directory. Start by copying the default one and then making your custom changes: ~\Views\Partials\Forms\0d3e6b2d-db8a-43e5-8f28-36241d712487\Form.cshtml.

You can also overwrite views for one or more fieldtypes by adding the views to the Fieldtypes folder: ~\Views\Partials\Forms\0d3e6b2d-db8a-43e5-8f28-36241d712487\Fieldtypes\Fieldtype.Textfield.cshtml.

There are two options available for rendering a form.

Rendering Using a View Component

To display a form in your view, you can make a call to a view component. You can use a forms GUID directly or add a form dynamically by referencing a form selected via a Forms Picker.

When selecting a theme, it can be added directly as a string or dynamically by referencing a theme picked via a Theme Picker.

@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, 
                                                 theme = @Model.Theme,
                                                 includeScripts = false })

@await Component.InvokeAsync("RenderForm", new { formId = Guid.Parse("<form guid>"), 
                                                 theme = "default", 
                                                 includeScripts = false })

Six parameters can be provided:

• formId is the GUID of a form.

• redirectToPageId is an optional GUID for a content page that, if provided, is redirected to once the form has been submitted. It will be used in preference to post-submission behavior defined on the form itself.

The following example shows how the additionalData parameter is used:

var additionalData = new Dictionary<string, string> { { "foo", "bar" }, { "buzz", "baz" } };
@await Component.InvokeAsync("RenderForm", new { formId = @Model.Form, theme = @Model.Theme, includeScripts = false, additionalData })

Rendering Using a Tag Helper

If you prefer a tag helper syntax, you can use one that ships with Umbraco Forms.

Firstly, in your _ViewImports.cshtml file, add a reference to the Umbraco Forms tag helpers with:

@addTagHelper *, Umbraco.Forms.Web

Then in your view you can use:

@if (Model.Form.HasValue)
{
    var additionalData = new Dictionary<string, string> { { "foo", "bar" }, { "buzz", "baz" } };
    <umb-forms-render form-id="@Model.FormId.Value" 
                      theme="@Model.FormTheme" 
                      exclude-scripts="true" 
                      additional-data="@additionalData" />
}

Forms output some JavaScript which is by default rendered right below the markup.

In many cases, you might prefer rendering your scripts at the bottom of the page. For example, before the closing </body> tag. This generally improves site performance.

In order to render your scripts where you want, you need to add a snippet to your template. Make sure you add it below your scripts, right before the closing </body> tag.

By default, Forms uses TempData for tracking the forms rendered on a page. The stored values are used when rendering the form scripts and associated data.

The following snippet should be used.

@using Umbraco.Forms.Web.Extensions;

@if (TempData.Get<Guid[]>("UmbracoForms") is Guid[] formIds)
{
    foreach (var formId in formIds)
    {
        @await Component.InvokeAsync("RenderFormScripts", new { formId, theme = "default" })
    }

    TempData.Remove("UmbracoForms");
}

If you have changed the configuration value TrackRenderedFormsStorageMethod to use HttpContext.Items, the snippet is:

@if (Context.Items.TryGetValue("UmbracoForms", out object? formIdsObject) && formIdsObject is IEnumerable<Guid> formIds)
{
    foreach (var formId in formIds)
    {
        @await Component.InvokeAsync("RenderFormScripts", new { formId, theme = "default" })
    }
}

If you prefer to use a tag helper, that's an option too.

Firstly, in your _ViewImports.cshtml file, ensure you have a reference to the Umbraco Forms tag helpers with:

@addTagHelper *, Umbraco.Forms.Web

Then instead of reading from TempData and invoking the view component directly, you can use:

<umb-forms-render-scripts theme="default" />

This will use the appropriate storage method that you have configured.

Enabling ExcludeScripts

If you do not want to render the associated scripts with a Form, you need to explicitly say so. You need to make sure ExcludeScripts is checked/enabled, whether you are inserting your Form using a macro or adding it directly in your template.

To enable ExcludeScripts:

• Using the Insert Form with Theme macro:
• While inserting Forms directly in your template:

  Copy

  @await Umbraco.RenderMacroAsync("renderUmbracoForm", new {FormGuid="6c3f053c-1774-43fa-ad95-710a01d9cd12", FormTheme="bootstrap3-horizontal", ExcludeScripts="1"})

Umbraco Forms supports Themes, allowing forms to be customized in a much simpler manner.

Creating a Theme

To create a theme, you need to create a folder at /Views/Partials/Forms/Themes/. The name of the folder is the name of theme that will be visible in the backoffice when choosing it.

Copy the explicit files you wish to override in your theme, it may be a single file or all files from the default theme folder. Make the necessary changes you desire to CSS class names, markup etc.

Obtaining the Default Theme Files

For Umbraco 9 and previous, it's straightforward to copy the files you need from the default theme folder. We highly recommend that you never customize any files found in the default themes folder. There is a risk that any customizations to these files will be lost with any future upgrades you do to Umbraco Forms.

Umbraco 10+ distributes these files as part of a Razor class library, so you won't find them on disk. Instead you should download the appropriate zip file for your Forms version and extract the ones you need.

You can obtain the latest versions of the default theme for each Forms major version from the following links:

If you are using a lower minor version of Forms than those listed, you should download an older version of the default theme.

You should use the theme available for the highest version that's less or equal to the version of Forms you have installed.

For example, when using Umbraco Forms 10.4, and no file for that version is available use version 10.3 instead.

Amending Theme Files

If adding or amending client-side scripts, you need to copy the Script.cshtml file from the default themes folder. In your copy, amend the .js references to reference your own script files.

Shipping Themes in a Razor Class Library

Umbraco Forms provides it's built-in themes as part of a Razor Class Library for ease of distribution. This can be useful for custom themes, particularly those used in multiple solutions or released as an Umbraco package.

It is also possible to do this for custom themes.

1. Create a new Razor Class Library project to hold the theme.

2. Create the necessary Partial Views for your theme within Views\Partials\Forms\Themes\<my-custom-theme>.

3. Provide the names of the files in your theme via an implementation of ITheme.

• For example, if only overriding a single file, your class would look like the code snippet below:

using Umbraco.Forms.Core.Interfaces;

public class MyCustomTheme : ITheme
{
    private const string FilePathFormat = "{0}/{1}/{2}.cshtml";

    public virtual string Name => "my-custom-theme";

    public virtual IEnumerable<string> Files =>
        [
            string.Format(FilePathFormat, Core.Constants.System.ThemesPath, Name, "FieldTypes/FieldType.Textfield"),
        ];
}

1. Register the themes you want to use via a composer:

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
      builder.Themes()
          .Add<MyCustomTheme>();
    }
}

Your theme will now be available in the Theme Picker and the partial view files will be used when rendering forms.

Email Templates

Email templates provided for the send email workflow can be provided in a Razor Class Library similar to the Theme files.

The partial view will be created in Views\Partials\Forms\Emails.

It's made available via an implementation of IEmailTemplate:

using Umbraco.Forms.Core.Interfaces;

public class MyCustomEmailTemplate : IEmailTemplate
{
    public virtual string FileName => "My-Custom-Email-Template.cshtml";
}

And registered with:

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
      builder.EmailTemplates()
          .Add<MyCustomEmailTemplate>();
    }
}

Removing the Default Email Template

If providing custom email templates, you may want to remove the one provided with Forms. You can do that via the same EmailTemplates collection.

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
      builder.EmailTemplates()
          .Exclude<DefaultEmailTemplate>();
    }
}

Using a Theme

When rendering a form in a view file, you can specify which theme to use with the form.

Theme Fallbacks

When using a theme, Umbraco Forms will try to use a view from the theme folder, but then fallback to the same view in the default theme folder if it can't be found. This allows you to create a theme by only modifying the files necessary to make your customizations.

Files which can be overridden:

• Render.cshtml (overrides the entire form - usually not needed)

• Form.cshtml (overrides the generation of the fields on the current page)

• Script.cshtml (overrides the way files are included with the form)

• /Fieldtypes/FieldType.*.cshtml (overrides a specific view for a field)

Helper Methods

SetFormThemeCssFile

Sets the primary form theme stylesheet path. This overrides an already assigned stylesheet and will be rendered out when inserting the form into the page

Html.SetFormThemeCssFile(Model, "~/App_Plugins/UmbracoForms/Assets/Themes/Default/style.css")

AddFormThemeScriptFile

Add a JavaScript file path to include on form render

Html.AddFormThemeScriptFile("~/App_Plugins/UmbracoForms/Assets/themes/default/umbracoforms.js");

SetFormFieldClass

Adds a class to the form field HTML element of a given type. If no type is given, it will add the class to all fields

// Applies the CSS class 'form-control' to all fields that GetFormFieldClass uses in FieldType views
@Html.SetFormFieldClass("form-control")

// Applies the CSS class 'some-other-class' for the FieldType of the name 'Password'
@Html.SetFormFieldClass("some-other-class", "Password")

GetFormFieldClass

Retrieves all classes for a given field type, used when rendering form fieldtype partial views

class="@Html.GetFormFieldClass(Model.FieldTypeName)"

SetFormFieldWrapperClass

Adds a class to the div element wrapping around form fields of a given type. If no type is given, it will add the class to all fields

// Applies the CSS class 'form-group' around all fields, labels & help texts
@Html.SetFormFieldWrapperClass("form-group")

// Applies the CSS class 'some-other-class' for the FieldType of the name 'Password'
@Html.SetFormFieldWrapperClass("some-other-class", "Password")

GetFormFieldWrapperClass

Retrieves all wrapper classes for a given field type, used when rendering form fields. This class wraps both label, help-text and the field itself in the default view

class="@Html.GetFormFieldWrapperClass(f.FieldTypeName)"

In Umbraco Forms, it is only possible to store Form data in the database.

If you are upgrading to Umbraco 9 or later and using Forms, you should first migrate the Forms to the database using Forms 8. As of Umbraco Forms version 8.5.0 it is possible to persist all Forms data in the Umbraco database. This includes definitions for each Form and their fields, as well as workflow definitions and prevalues.

Enable storing Forms definitions in the database

To persist Umbraco Forms definitions in the database, follow these steps:

1. Upgrade to at least Umbraco Forms version 8.5.2.

2. Open the configuration file App_Plugins\UmbracoForms\UmbracoForms.config.

3. Locate the StoreUmbracoFormsInDb key in the <settings> section, and make sure it has the following value:

   Copy

   <setting key="StoreUmbracoFormsInDb" value="True" />

4. Save the file.

When you save the file, the site will restart and run a migration step, migrating the files to the Umbraco database.

Migrating Forms in files into a site

You can force Forms to rerun the migration of the file-format Forms if you have a Umbraco 8 site storing Forms in the database.

First of all, you should ensure that you have enabled the setting that persists Forms in the database, as the migration requires this (StoreUmbracoFormsInDb) key. We highly recommend testing this on a local setup before applying it to your live site.

1. Copy over the Forms, workflows, prevaluesources, and datasource files to the site into ~\App_Data\UmbracoForms\Data.

2. Go to the database and find the [umbracoKeyValue] table.

3. Find the Form's row and check that the value is 1d084819-84ba-4ac7-b152-2c3d167d22bc (if not you are not currently working with Forms in the database, changing the setting should be enough).

4. Change that value to {forms-init-complete}.

5. Restart the site.

The site will now try to migrate the Forms files into the database. In the umbracoTraceLog, you can follow the progress. It will throw errors if anything goes wrong. Additionally, it will log out "The Umbraco Forms DB table {TableName} already exists" for the 4 Forms tables before starting the migration.

To add a new type, no matter if it's a workflow, field, data source, etc, there is a number of tasks to perform to connect to the Forms provider model. This chapter walks through each step and describes how each part works. This chapter will reference the creation of a workflow type. It is, however, the same process for all types.

Preparations

Adding the type to Forms

The Forms API contains a collection of classes that can be registered at startup or in an Umbraco component. So to add a new type to Forms you inherit from the right class. In the sample below we use the class for the workflow type.

public class LogWorkflow : Umbraco.Forms.Core.WorkflowType
{
    private readonly ILogger<LogWorkflow> _logger;

    public LogWorkflow(ILogger<LogWorkflow> logger)
    {
        _logger = logger;
    }

    public override WorkflowExecutionStatus Execute(WorkflowExecutionContext context)
    {
        throw new NotImplementedException();
    }

    public override List<Exception> ValidateSettings() {
        throw new NotImplementedException();
    }
}

When you implement this class you get two methods added. One of them is Execute which performs the execution of the workflow and the other is a method which validates the workflow settings, we will get back to these settings later on.

Any dependencies required that are registered with the dependency injection container can be provided via the constructor.

Even though we have the class inheritance in place, we still need to add a bit of default information.

Setting up basic type information

Even though we have the class inheritance in place, we still need to add a bit of default information. This information is added in the class's constructor like this:

public LogWorkflow(ILogger<LogWorkflow> logger) {

    _logger = logger;

    this.Name = "The logging workflow";
    this.Id = new Guid("D6A2C406-CF89-11DE-B075-55B055D89593");
    this.Description = "This will save an entry to the log";
}

All three are mandatory and the ID must be unique, otherwise the type might conflict with an existing one.

Adding settings to a type

Now that we have a basic class setup, we would like to pass setting items to the type. So we can reuse the type on multiple items but with different settings. To add a setting to a type, we add a property to the class, and give it a specific attribute like this:

[Umbraco.Forms.Core.Attributes.Setting("Log Header",
        Description = "Log item header",
        View = "TextField")]
public string LogHeader { get; set; }

The Umbraco.Forms.Core.Attributes.Setting registers the property in Umbraco Forms and there will automatically be UI and storage generated for it. In the attribute, a name, description and the view to be rendered is defined.

With the attribute in place, the property value is set every time the class is instantiated by Umbraco Forms. This means you can use the property in your code like this:

[Umbraco.Forms.Core.Attributes.Setting("Document ID",
        Description = "Node the log entry belongs to",
        View = "Pickers.Content")]
public string Document { get; set; }

public override WorkflowExecutionStatus Execute(WorkflowExecutionContext context) {
    _logger.LogInformation("Record submitted from: {IP}", context.Record.IP);
    return WorkflowExecutionStatus.Completed;
}

For all types that use the provider model, settings work this way. By adding the Setting attribute Forms automatically registers the property in the UI and sets the value when the class is instantiated.

Each setting value is stored as a string with the user interface for generating the value defined via the View property.

Validate type settings with ValidateSettings()

The ValidateSettings() method which can be found on all types supporting dynamic settings, is used for making sure the data entered by the user is valid and works with the type.

public override List<Exception> ValidateSettings() {
    List<Exception> exceptions = new List<Exception>();
    int docId = 0;
    if (!int.TryParse(Document, out docId))
        exceptions.Add(new Exception("Document is not a valid integer"));
    return exceptions;
}

Registering the class with Umbraco and Forms

To register the type, ensure your web application project has a reference to the class library, either via a project or NuGet reference. Then add the following code into the startup pipeline. In this example, the registration is implemented as an extension method to IUmbracoBuilder and should be called from Program.cs:

public static IUmbracoBuilder AddUmbracoFormsCustomProviders(this IUmbracoBuilder builder)
{
    builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
        .Add<LogWorkflow>();
}

An alternative approach is to use a composer, as per this example:

public class UmbracoFormsCustomProvidersComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
            .Add<LogWorkflow>();
    }
}

There are further convenience methods you can use for registering custom types. These are found in the namespace Umbraco.Forms.Core.Providers.Extensions.

For example, instead of the following:

    builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
        .Add<LogWorkflow>();

Your workflow can be registered using:

    builder.AddFormsWorkflow<LogWorkflow>():

Or:

    builder.FormsWorkflows().Add<LogWorkflow>();

Existing items that are not required in a particular installation can be removed with:

    builder.FormsWorkflows().Exclude<Slack>();

Also look in the reference chapter for complete class implementations of workflows, fields and export types.

Overriding default providers in Umbraco Forms

It is possible to override and inherit the original provider, be it a Field Type or Workflow etc. The only requirement when inheriting a fieldtype that you wish to override is to ensure you do not override/change the Id set for the provider, and make sure your class is public.

Here is an example of overriding the Textarea field aka Long Answer.

public class TextareaWithCount : Umbraco.Forms.Core.Providers.FieldTypes.Textarea
{
    // Added a new setting when we add our field to the form
    [Umbraco.Forms.Core.Attributes.Setting("Max length",
    Description = "Max length",
    View = "TextField")]
    public string MaxNumberOfChars { get; set; }

    public TextareaWithCount()
    {
        // Set a different view for this fieldtype
        this.FieldTypeViewName = "FieldType.TextareaWithCount.cshtml";

        // We can change the default name of 'Long answer' to something that suits us
        this.Name = "Long Answer with Limit";
    }

    public override IEnumerable<string> ValidateField(Form form, Field field, IEnumerable<object> postedValues, HttpContext context, IPlaceholderParsingService placeholderParsingService, List<string> errors)
    {
        var baseValidation = base.ValidateField(form, field, postedValues, context, placeholderParsingService, errors);
        var value = postedValues.FirstOrDefault();

        if (value != null && value.ToString().Length < int.Parse(MaxNumberOfChars))
        {
            return baseValidation;
        }

        var custom = new List<string>();
        custom.AddRange(baseValidation);
        custom.Add("String is way way way too long!");

        return custom;
    }
}

As discussed in the previous section, you must also register the extended field type within a composer. You also need to create the the backoffice field type view.

Composer:

public class UmbracoFormsCustomProvidersComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.FormsFields().Add<TextareaWithCount>();
    }
}

Backoffice View:

Add a new HTML file as per the name of the field class (e.g. textareawithcount.html) to \wwwroot\App_Plugins\umbracoforms\Backoffice\Common\FieldTypes\ within your project. For this example, we can copy the original textarea.html file used by the standard 'Long Answer' field.

The AngularJS client-side files are shipped with Umbraco Forms as part of a Razor Class Library. So you won't find these files on disk when you install the package.

Umbraco Forms field, prevalue source and workflow types are defined in C# and include one or more setting values.

These settings are completed by the editor when using the type on their form.

Each setting type can have it's own user interface. So a string can use a text box but a more complicated JSON structure can use a more appropriate user interface.

The user interface used for a particular setting is defined by the View property:

If not specified, the default Umb.PropertyEditorUi.TextBox is used.

Built-in setting types

The following setting types are available and are used for the field, prevalue source and workflow types that ship with the package.

Some are defined with the Umbraco CMS and some ship with the Forms package.

Most of the above setting types are used in one or more field, prevalue source and workflow types available with Umbraco Forms. For the less common ones, a usage has been indicated in the table.

Additional setting types

Some types we don't use within the package, but we make available for developers to use when creating their own types.

For example Forms.PropertyEditorUi.TextWithFieldPicker. This offers the option of text field entry or the selection of a field from the form. This can be useful in workflows where you need to reference the value of a specific field.

Creating a setting type

It's also possible to define your own setting type using a combination of server and client-side code.

Umbraco Forms comes with some built-in fields however it is possible to exclude/remove them if necessary. There might some use cases where you have no use for file upload and don't want editors using them. Or perhaps you want to remove a field to replace it with one with enhanced functionality that you build yourself.

Example

The following class shows how to exclude built-in field types using a custom composer. The Password, Recaptcha2 and RichText field types (or "answers") will no longer be available for selection when creating a form in the backoffice.

In this article, we will illustrate how to add a custom form field type using server-side and client-side components. We will use the example of rendering a "slider" field type that allows the user to select a number within a specific range of values.

Server-side Field Type Definition

Add a new class to the Visual Studio solution. Inherit from Umbraco.Forms.Core.FieldType and complete as follows:

In the constructor or via overridden properties, we can specify details of the field type:

• Id - should be set to a unique GUID.

• Alias - an internal alias for the field, used for localized translation keys.

• Name - the name of the field presented in the backoffice.

• Description - the description of the field presented in the backoffice.

• Icon - the icon of the field presented in the backoffice form builder user interface.

• DataType - specifies the type of data stored by the field. Options are String, LongString, Integer, DataTime or Bit (boolean).

• SupportsMandatory - indicates whether mandatory validation can be used with the field (defaults to true).

• MandatoryByDefault - indicates whether the field will be mandatory by default when added to a form (defaults to false).

• SupportsRegex - indicates whether pattern-based validation using regular expressions can be used with the field (defaults to false).

• SupportsPreValues - indicates whether prevalues are supported by the field (defaults to false).

• RenderInputType- indicates how the field should be rendered within the theme as defined with the RenderInputType enum.

  • The default is Single for a single input field.

  • Multiple should be used for multiple input fields such as checkbox lists.

  • Custom is used for fields without visible input fields.

• FieldTypeViewName - indicates the name of the partial view used to render the field on the website.

• EditView - indicates the name of a property editor UI that is used for editing the field in the backoffice. If nothing is provided, the built-in label will be used and the field won't be editable.

• PreviewView - indicates the name of a manifest registered client-side resource that is used for previewing the field in the backoffice. If nothing is provided, the name of the field type will be used as the preview.

You now need to register this new field as a dependency:

Partial View

We will start building the view for the default theme of the Form at Views\Partials\Forms\Themes\default\FieldTypes\FieldType.Slider.cshtml.

The file name for the partial view should match the value set on the FieldTypeViewName property.

This will be rendered when the default theme is used.

If working with Umbraco 9 or earlier versions, you'll find the Views\Partials\Forms\Themes\default\ folder on disk and can create the files there.

Read-only partial view

When rendering a multi-page form, editors have the option to display a summary page where the entries can be viewed before submitting.

To support this, a read-only view of the field is necessary.

For most fields, nothing is required here, as the default read-only display defined in the built-in ReadOnly.cshtml file suffices.

However, if you want to provide a custom read-only display for your field, you can do so by creating a second partial view. This should be named with a .ReadOnly suffix. For this example, you would create FieldType.Slider.ReadOnly.cshtml.

Field Settings

Field settings will be managed in the backoffice by editors who will create forms using the custom field type. These settings can be added to the C# class as properties with a Setting attribute:

The property Name names the setting in the backoffice with the Description providing the help text. Both of these can be translated, as discussed in the backoffice components section below.

The View property indicates a property editor UI used for editing the setting value. You can use a built-in property editor UI, one from a package, or a custom one registered with your solution. The default value if not provided is Umb.PropertyEditorUi.TextBox, which will use the standard Umbraco text box property editor UI.

HtmlEncodeReplacedPlaceholderValues takes effect only if SupportsPlaceholders is true. It controls whether the replaced placeholder values should be HTML encoded (as is necessary for rendering within content from a rich text editor).

SupportsHtml is a flag indicating whether the setting can contain HTML content. When set to true it will be treated as HTML content when the value is read from the Forms delivery API.

IsMandatory if set to true will provide client-side validation in the backoffice to ensure the value is completed.

When creating a field or other provider type, you might choose to inherit from an existing class. This could be if one of the types provided with Umbraco Forms almost meets your needs but you want to make some changes.

All setting properties for the Forms provider types are marked as virtual, so you can override them and change the setting values:

Umbraco Backoffice Components

With Forms 14+, aspects of the presentation and functionality of the custom field are handled by client-side components, registered via manifests:

• The preview, displayed on the form definition editor.

• The property editor UI used for editing the the submitted values via the backoffice.

• The property editor UI used for editing settings.

• A settings converter, that handles configuring the property editor and translating between the editor and persisted values.

• Translations for setting labels and descriptions.

Field Preview

The alias of the preview to use is defined on the field type via the PreviewView property.

A preview for our slider, representing the selected setting values could look as follows:

And it is registered via a manifest:

Field Editor

Umbraco Forms supports editing of the entries submitted by website visitors via the backoffice. The property editor interface to use for this is defined in the field type's EditView property.

If not using a built-in property editor, you can create your own. The following example shows how the numerical entries could be edited using an input control.

Again, it's registered via a manifest.

Setting Value Editor

Field type settings also use a property editor UI for editing the values in the backoffice. The one to use is defined via the View property on the Setting attribute.

In our example we use a custom one, allowing the value for the background color to the field to be selected via an input control.

And register it via a manifest:

Setting Value Converter

You may want to consider registering a settings value converter. This is another client-side component that is registered in a manifest. It converts between the setting value required for the editor and the value persisted with the form definition. A converter defines three methods:

• getSettingValueForEditor - converts the persisted string value into one suitable for the editor

• getSettingValueForPersistence - converts the editor value into the string needed for persistence

• getSettingPropertyConfig - creates the configuration needed for the property editor

The following code shows the structure for these converter elements.

It's registered as follows. The propertyEditorUiAlias matches with the property editor UI that requires the conversions.

Language Files

Setting labels and descriptions can be translated via language files. If no client-side localization is provided, the values provided server-side in the Setting attribute's Name and Description properties will be used.

The following example shows how this is created for the settings on our example field type:

Each different type of extension for Forms uses a different root value:

• Data sources - formProviderDataSources

• Export types - formProviderExportTypes

• Field types - formProviderFieldTypes

• Prevalue sources - formProviderPrevalueSources

• Recordset actions - formRecordSetActions

• Workflows - formProviderWorkflows

The language files are registered with:

Registering the Components

Finally, you will need an entry point to your client-side components that will register the manifests with Umbraco's extension registry. For example:

Add a new class to your project - inherit it from Umbraco.Forms.Core.FieldPreValueSourceType and implement the class.

The following example shows an illustrative custom prevalue source type that returns a hard-coded list of values. It can be extended for your needs via injection of services via the constructor. (See additional example at the bottom.)

You will then need to register this new prevalue source type as a dependency.

Another Example Using Dependency Injection to Access Additional Services

This example will take a user-provided Content Node and create a custom Prevalue list from the property data on that node. Your own FieldPreValueSourceType can get its data from wherever you like - an API call, custom functions, etc.

You will then need to register this new type as a dependency (either in Program.cs or in your own IComposer, as shown here).

When creating a text field in Umbraco Forms, a validation pattern in the form of a regular expression can be applied. Default patterns can be removed or re-ordered, and custom ones created and added.

Provided patterns

Umbraco Forms ships with three patterns: number, email, and URL. The class names are Number, Email, and Url respectively, and all are found in the Umbraco.Forms.Core.Providers.ValidationPatterns namespace.

Creating a custom validation pattern

To create a custom format function, create a class that implements IValidationPattern. You will need to initialize five properties:

• Alias - an alias that should be unique across the patterns and is typically camel-cased with no spaces.

• Name - the name of the pattern that will be visible in the backoffice.

• LabelKey - as an alternative to providing a name, a translation key can be provided. This will be used to look-up the name in the correct language for the backoffice user.

• Pattern - the regular expression pattern.

• ReadOnly - a flag indicating whether the pattern can be edited in the backoffice.

Registering the validation pattern

As with other provider types, the validation pattern needs to be registered. There are options to add, remove, and re-order patterns.

An example registration using the IUmbracoBuilder is shown below:

Using the pattern

With the pattern registered it will be available for selection by editors in the backoffice when they create validation for fields supporting this feature.

Filter functions for common operations such as truncating a string or formatting a date or number are provided. It's also possible to create custom ones in code.

Creating a custom format function

To create a custom format function, create a class that implements IParsedPlaceholderFormatter.

The FunctionName property provides the name of the function that will be used within the form's magic string.

The FormatValue property parses the provided value and arguments and returns the formatted value as a string.

The following example shows the implementation of a function that bounds an integer value. It takes two arguments, a minimum and maximum value. If the value read from the magic string source is numeric, and fits within the two bounds, it is returned. Otherwise, either the minimum or maximum value is returned depending on whether the value is lower or higher than the bounds respectively.

Registering the custom format function

As with other provider types, the custom function needs to be registered. An example registration using the IUmbracoBuilder is shown below:

Using the custom format function

The format function can be used within a form's magic string in the same way as the ones provided with Umbraco Forms.

For the example provided, it would be used like this:

Add a new class to your project and have it inherit from Umbraco.Forms.Core.ExportType. You have two options when implementing the class, as shown in the following examples.

Basic Example

You can implement the method public override string ExportRecords(RecordExportFilter filter) in your export provider class. You need to return a string you wish to write to a file. For example, you can generate a .csv (comma-separated values) file. You would perform your logic to build up a comma-separated string in the ExportRecords method.

FileExtension is the extension such as zip, txt or csv of the file you will be generating and serving from the file system.

In this example below we will create a single HTML file which takes all the submissions/entries to be displayed as a HTML report. We will do this in conjunction with a Razor partial view to help build up our HTML and thus merge it with the form submission data to generate a string of HTML.

Provider Class

Razor Partial View

Registration

Advanced Example

This approach gives us more flexibility in creating the file we wish to serve as the exported file. We do this for the export to Excel file export provider we ship in Umbraco Forms. With this we can use a library to create the Excel file and store it in a temporary location before we send back the filepath for the browser to stream down the export file.

In this example we will create a collection of text files, one for each submission which is then zipped up into a single file and served as the export file.