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.

Quick Links

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

Umbraco contains the Forms section, by default. You will see a similar interface, when you click on the Forms section in the Umbraco Backoffice.

Video Tutorial

To install the Umbraco Forms package (Umbraco.Forms), follow these steps:

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.

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.

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

The date picker uses a front-end library called Pikaday to display a UI to pick dates.

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

The Date picker has to control the number of years shown in the picker and the date format.

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 File Type checkbox the user should be able to upload.

2. Click Submit.

User Defined Allowed File Types

If the list of predefined file types do 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 and click add.

2. Click Submit.

Server-side file validation

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

To read more about this feature, see in the CMS documentation.

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:

You can create your keys by logging into your .

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:

You can create your keys by logging into your .

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

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

Enabling reCAPTCHA Enterprise

Follow these steps to enable reCAPTCHA Enterprise in Umbraco Forms:

1. Go to the Forms section in the backoffice.

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

3. Add a new question and select ReCAPTCHA Enterprise 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 SiteKey, ApiKey and ProjectId:

You can create your keys by logging into your .

The labels, descriptions, and buttons that make up the backoffice screens for Umbraco Forms can be translated into different languages.

When an editor chooses a language for their account, Umbraco CMS will render appropriate translations. The translations will contain a file for that language and a key for the label in question. If either of these can't be found, the label will be displayed in English (US).

Language Files

Umbraco Forms ships with translations for the following languages:

When working with the Block List editor, by defining a label for the appearance of the Block.

These labels can contain AngularJS filters.

A filter umbFormsFormName is available for use.

If you add a reference to a property containing a form to the block's label, it will render with the form's Id.

For example, assuming a property containing a picked form with an alias of contactForm:

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. Select Enable Conditions in the Conditions section.

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.

Expand the Form in the tree to view the Entries for each Form.

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.

Clicking on the first field for each record in the list will open the full set of information recorded for the form entry. Next and previous buttons allow you to navigate through the entry list.

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 Entries you wish to export.

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

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 Actions. To select an entry, click anywhere on the entry.

Select at least 1 record to see the available actions in the top-right corner. By default, there are 3 possible actions:

• Approve

• Reject

• Delete

There are some default prevalue source types that can be used.

Here is 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 define the root node by either

  • Choosing a node directly from the Content tree or

Additional settings can be applied:

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

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

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

There are three 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:

Six parameters can be provided:

• formId is the GUID of a form.

• theme is the name of a theme. If not provided, the default theme is used (see ).

• includeScripts indicates whether scripts should be rendered with the form. This is necessary for using conditional fields. See for more details.

• recordId is an optional existing record GUID, used if editing records via the website is

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

• additionalData is an optional dictionary of string values. When provided it will be used as a source for . The data will be associated with the created record and made available for custom logic or update within workflows.

Usually, rather than hard-coding the form's GUID and other details, you'll use a form, theme or content picker on your page:

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:

Then in your view you can use:

Rendering Using a Macro

With a grid or Rich Text Editor, you need to use a macro. This is also available as an option to display a form in your view, where you provide three parameters:

• FormGuid is the GUID of a form.

• FormTheme is the name of a theme. If not provided, the default theme is used.

• ExcludeScripts

Similarly, you can reference a form picker property on your page:

A unique migration ID is generated for each Umbraco Forms upgrade that requires a migration. The migration IDs are all listed in this article.

System information related to a form can be viewed via the "Info" tab.

To access the Form Information:

1. Navigate 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.

Relations

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.

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.

Umbraco Forms comes with a number of Field Types to allow you to request certain data in the forms that you design & build. This documentation is to guide specific details about field types that we ship that require some detail in how they work.

Date Picker

The date picker uses a front-end library called PikaDay.js to display a UI to pick dates from. We have added the support for the Pikaday date picker to be localized based on the page the form is rendered on. This displays the picked date in the correct locale. In JavaScript, we update a hidden field with a standard date format. This is done to send the date to the server, ensuring the record submission is stored in a standard format. This is to avoid locale mixing up dates.

To achieve this a new Razor partial view is included /Views/Partials/Forms/DatePicker.cshtml. Once on a page with a form that includes a Date Picker, it also includes the MomentJS library to assist with date locale formatting. Additionally, there are appropriate changes to Pikaday.js to support the locales. If you wish to use a different DatePicker component this is the file that you would customize to your needs.

Date Picker configuration of the year range

The DatePicker has one configuration setting to control the number of year shown. The default is 10 years which makes the picker unusable for picking birth dates.

Go to your appsettings.json and add:

You can then change the DatePickerYearRange to a higher number (for example 100).

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.

Umbraco Forms comes with many default Field Types, also known as Answer Types. You can choose from these options when adding new fields to your Forms.

By default, the following Field Types are available:

• Short Answer: A textbox allows up to 250 characters.

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.

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.

Umbraco Forms will register events for workflow operations that you can use with .

Workflows are operations that you can associate with form submission, approval, or rejection actions. You can use these where you need to notify external systems of the success or failure of a workflow.

On the Umbraco Settings > Webhooks dashboard, you can configure webhooks to respond to workflows.

You can amend the registration of workflow events in code.

To remove the webhooks that are added by default you can use a composer as follows:

Umbraco Forms is a commercial product. You can run Umbraco Forms unrestricted locally without the need for a license. Running Umbraco Forms in the public domain will require a valid license.

Version 13 supports both the one-off purchase and (in 13.6+) subscription license.

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

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

Configuring your license

You can look at the pricing, features, and purchase the license on the page.

Add additional domains

If you require to add addition domains to the license, with your request and they will manage this process.

Reconfiguration of domains

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 .

Installing your license

You can configure either the one-off purchase license file or when using version 13.6+ the subscription license product key. We do not recommend having both a license file and product key configured, but if you have, the product key is checked first.

Installing one-off purchase license file

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

1. Obtain the license (a .lic file) from the sales team

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:

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, 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:

Installing subscription license product key

Once you've purchased your subscription license with the correct domains, you are ready to configure the license key on your Umbraco installation.

The license key should be added to your configuration using product ID: Umbraco.Forms.

For detailed instructions on how to install and configure your license, including version-specific examples and additional configuration options, see the article.

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

By default, when a Form is submitted the record data is stored in the database. This can be configured in the Store records of the Forms settings.

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

A new workflow can be of different types and Umbraco Forms ships with a few default ones. You can find an overview of the types in the article.

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.

To use data from the submitted Form in your workflow, head over to the article and learn more about how that's done.

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.

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):

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

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.

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

The following example shows the implementation of a pattern for a United Kingdom postcode (credit for the to at StackOverflow).

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.

Umbraco Forms contains a built-in Get value from textfile Prevalue Source Type that stores the uploaded text file into the physical file system (by default in umbraco\Data\UmbracoForms\PreValueTextFiles).

You can replace the default implementation by writing your own IPreValueTextFileStorage and registering that using e.g. builder.Services.AddUnique<IPreValueTextFileStorage, CustomPreValueTextFileStorage>() (in Program.cs or a composer).

You can also use/inherit from PreValueTextFileSystemStorage to change the underlying IFileSystem that's used to store the prevalue text files.

Move files to Media file system

You can use the following composer to move the prevalue text files into the media file system. If the media file system is using Azure Blob Storage, this will remove the files from the local physical file system.

You need to manually move the existing files from umbraco\Data\UmbracoForms\PreValueTextFiles to your media storage. The final file path/URL will look like ~/media/PreValueTextFiles/{GUID}/{filename.txt} and be accessible from the browser.

Move files to Azure Blob Storage

First, install and configure the Forms storage container, for example by adding the following to your appsettings.json:

Next, add the following composer that adds the Forms storage container and stores the prevalue text files into Azure Blob Storage (in forms/PreValueTextFiles/{GUID}/{filename.txt}):

You need to manually move the existing files from umbraco\Data\UmbracoForms\PreValueTextFiles to your storage container. If you've disabled public access, the stored files are not accessible from the browser.

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

To access the Form Settings:

1. Navigate to the Forms section.

2. Open a Form you wish to customize.

In this article, you will find information about Umbraco Forms-related health checks that can be run from the Umbraco backoffice to ensure that your installation is running seamlessly.

Read the article to learn more about the feature in general.

Database Integrity Health Check

Running this health check will verify whether the database tables for the Umbraco Forms installation are all set up correctly with the proper data integrity checks.

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:

For Umbraco Forms to work correctly, you need to include some client dependencies.

Client-Side Validation

Umbraco Forms ships with client-side form validation features provided by the .

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

This builds on the "" chapter

Add a new class to your project and have it inherit from Umbraco.Forms.Core.WorkflowType, and implement the class. For this sample, we will focus on the execute method. This method processes the current record (the data submitted by the form) and have the ability to change data and state.

Information available to the workflow

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.

Reverting the application of keys and indexes

This builds on the "" chapter

Umbraco Forms can be used to replace placeholders within form elements with values from different sources. Sources include the HTTP request or the Umbraco page where the form is hosted.

These values can be formatted using .

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.

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

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

GetApprovedRecordsFromFormOnPage

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

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

GetRecordsFromPage

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

GetRecordsFromFormOnPage

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

GetRecordsFromForm

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:

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.Services, 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.

Loading a Record From a Submitted Form

When a form is submitted, the submitted form ID and the saved record ID are stored in the TempData so they can be referenced.

You can use the FormService and the RecordStorage to get the Form and Record objects.

Here is a sample code for retrieving a record in a view.

Umbraco Content Apps can be configured to appear alongside forms in the Umbraco Forms backoffice section.

They will appear after the default "Design" and "Settings" apps when editing a form in the backoffice:

A content app such as the following would display only in the forms section:

    public class TestFormsContentApp : IContentAppFactory
    {
        public ContentApp GetContentAppFor(object source, IEnumerable<IReadOnlyUserGroup> userGroups)
        {
            // Only show app on forms
            if (source is FormDesign)
            {
                return new ContentApp
                {
                    Alias = "testFormsContentApp",
                    Name = "Test App",
                    Icon = "icon-calculator",
                    View = "/App_Plugins/TestFormsContentApp/testformscontentapp.html",
                    Weight = 0,
                };
            }

            return null;
        }
    }

Within the /App_Plugins/TestFormsContentApp/ folder we need the client-side files, for which an example is shown below:

package.manifest:

testformscontentapp.html:

testformscontentapp.controller.js:

Finally, it needs to be registered via a composer:

Umbraco Forms has a backoffice security model integrated with Umbraco users. Details are managed in the Users section of the backoffice, within a tree named Form Security.

User based permissions

Within the Form Security tree, each user with a backoffice account is listed. Clicking on a user allows each functional permission to be set:

Umbraco Forms functionality can be extended in different ways. In this section we focus on techniques available to a back-end/C# developer.

For front-end extensions, specifically via theming, see the section.

Developing Custom Providers

Although the Forms package comes with many fields, workflows and other built-in types, you can still create and develop your own if needed.

This page covers specific upgrade documentation for when migrating to major 13 of Umbraco Forms.

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 version of the Forms default theme from the following links:

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 13.4.0, and no file for that version is available use version 13.3.0 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.

From Forms 13.3 it is 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:

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

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:

And registered with:

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.

Using a Theme

To use a theme with a Form use the "Insert Form" macro where you will be presented with the options of the form you wish to insert along with an option to pick a theme. This displays the list of theme folders found at Views/Partials/Forms/Themes.

When you are rendering your form directly in your template, you need to specify your theme by filling out the FormTheme attribute:

If you do not pick and/or set a theme, the default theme will be used to render 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)

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

AddFormThemeScriptFile

Add a JavaScript file path to include on form render

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

GetFormFieldClass

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

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

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

Form validation notification

Add a new class to your project as a handler for the FormValidateNotification notification:

The handler will check the ModelState and Form field values provided in the notification. If validation fails, we add a ModelError.

To register the handler, 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:

Service notifications

The services available via interfaces IFormService, IFolderService, IDataSourceService and IPrevalueSourceService trigger following notifications before or after an entity handled by the service is modified.

The "-ing" events allow for the entity being changed to be modified before the operation takes place, or to cancel the operation. The "-ed" events fire after the update is complete.

Both can be wired up using a composer and component:

When a form or folder is moved there is no specific service event. However, information available in the State dictionary on the notification object can be used to determine whether the item was moved. If so, it can show where it was moved from:

If a folder is being moved, the key within the State dictionary is "MovedFromParentId".

Backoffice entry rendering events

When an entry for a form is rendered in the backoffice, an event is available to allow modification of the record detail. This event is available before the record details are presented to the user. This is shown in the following example:

In this section, we have summarized the changes to Umbraco Forms released in each version. Each version is presented with a link to the 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.