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.

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

1. Run the following command on a command prompt of your choice:

dotnet add package Umbraco.Forms

1. Restart the web application using the following command:

    dotnet run

Start Building Forms

Once the installation is successful, you will see a similar screen in the Forms section:

Using Forms

For details on using Forms, see the Editor Documentation.

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.

The documentation for Umbraco 7 and 8 lives on our.umbraco.com.

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

When upgrading Umbraco Forms, be sure to also consult the 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.

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:

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.

or sign up for an project where Umbraco Forms is part of the package.

Quick Links

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

Version Specific Upgrade Notes History

Version 13 of Umbraco Forms has a minimum dependency on Umbraco CMS core of 13.0.0. It runs on .NET 8.

Deploy add-on for Umbraco Forms has been renamed from Umbraco.Deploy.Forms to Umbraco.Forms.Deploy.

Breaking changes

Version 13 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:

Behavior

• The configuration option UseSemanticFieldsetRendering was removed and considered as true. This means the improved, semantic fieldset rendering is now used in the default theme for all installations.

• The ExecuteWorkflowAsync configuration option was removed.

Dependencies

• Umbraco CMS dependency was updated to 13.0.0.

Code

The following updates describe the more significant changes to the codebase and public API:

• Amended IWorkflowExecutionService, IRecordService, IRecordSetActionType and IWorkflowType methods related to workflow execution to be asynchronous. These methods now have an Async suffix and will return a awaitable Task.

• An overload for the HTML helper RenderUmbracoFormDependencies that internally required service location was removed. It should now be called providing the parameter for an IUrlHelper, with @Html.RenderUmbracoFormDependencies(Url).

These updates are more minor. We don't expect many projects to be affected by them as they are in areas that are not typical extension points:

• DataSourceCacheRefresher was made internal.

• HideField was removed from FieldType and IFieldType. RenderInputType with a value of RenderInputType.Hidden can be used here instead.

• The default implementation for the Exists method previously added to IBaseService was removed.

• The obsolete overload for method AddDataConsentField on FieldsetContainerExtensions was removed.

• The method CanUserViewEntries was added to the IFormsSecurity interface.

• The static methods TryCreateAttachment, TrackAttachmentFileStream and DisposeAttachmentFileStreams on BaseEmailWorkflowType were removed (instance methods are available to use instead).

• The obsolete constructor on the SaveAsFile workflow type was removed.

• The obsolete overload for method TransformXML on XsltHelper was removed.

• The obsolete overloads for method ValidateField on FieldType were removed.

• The obsolete overload for method GetFormSecurityByUserId on FormSecurityControllerBase was removed.

• The PopulatePageElements method was added to the IFormRenderingService interface.

• The Setting class was renamed to SettingAttribute.

• PreValueFileController has a changed constructor.

• FileUpload has a changed constructor.

• ExecuteWorkflowsWithResult on IWorkflowExecutionService was renamed to ExecuteWorkflows and the void method with that name was removed.

• The string constants used to define GUIDs for each provider type were made consistently upper-case.

• FileUpload and PreValueFileController have changed constructors to add support for server-side file validation.

• HTML helpers such as RenderFormsScripts now return IHtmlContent.

• The constructor for workflow notifications was amended to add a parameter for the current Record.

• The IType interface now defines a Created property.

Legacy version specific upgrade notes

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 within 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. The Create a new Form dialog opens.
4. Select Empty Form. 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 the 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 Add Question dialog opens.
11. Enter the following details:
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 that has already been added to the Form, click the little cog icon next to the field to open the dialog. 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 to the top or bottom of a form use the buttons available in the top right 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. You will then be able to add or move fields to the new columns created.

Saving the Form

Once you are satisfied with the Form, you can save the design by clicking the Save button.

Organizing Forms in Folders

If installation of the product is configured for storage of form definitions in the database, you will have the option to store forms within folders. If you are planning to create a number of them, this may help with organization and locating them once created for modification.

To create a folder, access the same dialog used for creating a form. Here, you'll have the option to create a folder, for which you need to provide a name.

You can create folders within folders, rename, move and delete them. You also have the ability to move or copy forms into folders, all via the tree operations available from the ... menu.

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 either have a Rich Text Editor (RTE) field, a Grid Editor, or a form picker all of which you can add in the Settings section under Document Types.
3. Click the Insert macro button in the toolbar of the RTE or Grid. The Select Macro dialog opens.

4. Click Add under Choose a Form 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.
5. [Optional] Click Add under Theme to choose which theme the Form should use.

6. Finally you have an option to Exclude Scripts.

7. Click Submit.

8. The Form is inserted on to your page. Click the Save and publish button.

In this section, we have summarized the changes to Umbraco Forms released in each version. Each version is presented with a link to the Forms issue tracker showing a list of issues resolved in the release. We also link to the individual issues themselves from the detail.

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

Release History

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

13.4.0-rc1 (December 17th 2024)

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

Crafting these rules requires use of JSON logic so is considered a "power user" feature. They also require an additional front-end dependency for the rendering of forms on the website. As such they are surfaced on a new "Advanced" tab and only visible and used if enabled in configuration. We don't have, and it seems difficult to provide, an intuitive user interface for rule creation taking into account all the flexibility available. Nonetheless, having the ability to use more complex validation rules seems a valuable addition.

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.

Read more about editing advanced validation rules as well as the configuration option required to enable them.

Tracking editor activity

Whilst previously we tracked and displayed the date a form was created and last edited, we didn't show who had made these updates. With 13.4 installed we will start to track this and display the information where available. You'll find this on the form, data source or prevalue source's "Info" tab #1315.

Copy of workflows

Forms allows you to make a copy of a form to use as a starting point for a new one. You can choose whether or not to copy workflows along with the form. With the 13.4 release, we've made available a second dialog allowing you to copy workflows to an existing form #1185. You can select any or all of the workflows on the current form and copy them to the selected destination form.

We've also resolved an edge case around copying a form. It's possible to define workflows as mandatory. Copying the form without workflows excludes the desired workflow. You would have a form that didn't contain the workflow you wanted to be included on all. This has been tightened up now and mandatory workflows will always be assigned to the copied form #1331.

Form picker enhancements

In the 14.2 release we enhanced the form picker property editors. We introduced support for restriction of which forms can be selected by folder rather than only by individual forms. This has now been backported to Forms 13 #891.

File upload validation messages

Previously the validation messages presented on the website front end when uploading files were hardcoded and always provided in English. We've added settings now to the "File Upload" field type allowing you to customize these. Dictionary keys can be used in order to provide the information in the user's preferred language #1327.

13.3.3 (December 5th 2024)

• Fixed regression introduced in 13.3.1 that caused issues for custom field types overriding the ProcessSubmittedValue method #1328.

13.3.2 (November 28th 2024)

• Fixed issue with case sensitive checkbox conditions across multi-page forms #1325.

13.3.1 (November 21st 2024)

• Fixed issues with multi-page forms used in conjunction with a FormPrePopulateNotification handler. File uploads and multi-value fields like checkbox lists now function correctly #1317 #1320.

• Added a couple of missing translation keys #1316 #1319.

• Improved accessibility and styling of close button on export dialog #1321.

13.3.0 (November 7th 2024)

• All items detailed under release candidates for 13.3.0.

• Fixed issue with validation for invalid file extension on form submissions via the API #1310.

13.3.0-rc1 (October 25th 2024)

Multi-step forms

The 13.3 release of Forms contains features that can improve the user experience of completing multi-page forms.

We have added the option for editors to choose to display paging details on the forms. This will allow those completing forms to get a better understanding of progress as well as see details of the pages still to be completed. #281 #648.

These options are enabled and configured by editors in the Forms settings section on a per-form basis. We also provide a configuration-based toggle for the feature as a whole. In this way, editors can be given access to use the feature only once the styling or theme is prepared.

Ship themes in Razor Class Libraries

Forms ships it's themes and email templates as part of a razor class library for ease of distribution. With this release we make that feature available to your own custom themes and templates (or those created by package developers) #795.

Date picker field type

We have made a couple of updates to the Date Picker field type. The format for the field can now be provided in configuration #1276. And you can now override and localize the aria-label provided for assistive technologies such as screen readers #1082.

Finer grained entries permissions

To allow finer control over editor permissions, we have introduced a "delete entries" setting for users and user groups. Thus you can now give editors explicit permissions to view, edit, or delete entries #1303.

Other

Other bug fixes included in the release:

• Fixed issue with single checkbox triggering a condition on a field on a subsequent page #1304.

• Improved cross-platform check when exporting to Excel.

• Fixed issue where sensitive data flag on a field could not be set for new fields added to a form #1309.

13.2.5 (October 3rd 2024)

• Handled "chunked" authentication cookie in protection of file uploads saved in the media file system #11.

13.2.4 (September 26th 2024)

• Fixed regression in 13.2.2 that caused validation to fire on the wrong form when multiple forms are hosted on a single page #1297.

13.2.3 (September 19th 2024)

• Fixed regression in 13.2.0 that prevented a form submission from saving if a workflow approved the entry #1293.

• Added check to migration step that adds a property to the forms macro, such that it will avoid an exception if the property already exists #1292.

• Added file name validation to file uploads, rejecting files with invalid colon characters #1295.

13.2.2 (September 12th 2024)

• Used localized label for submit workflow summary heading #1273.

• Removed autocomplete on field previews #1271.

• Added configurable field level rendering of reCAPTCHA 3 validation result #1277.

• Fixed validate and submit script to handle additional markup around submit buttons #1280.

• Fixed incorrect concatenation of field CSS classes #1284.

• Added server-side validation of configured maximum length for short and long answer fields.

• Restored provision of field values in HTTP headers in Post as XML workflow.

• Fixed issue with recording of form submissions in custom Examine indexes #1282.

• Added ability to retrieve "slim" workflow entities from services #1283.

13.2.1 (August 6th 2024)

• Fixed issue with entries export for Windows installations without access to a component necessary for auto-fit of Excel columns #1259.

13.2.0 (July 23rd 2024)

• All issues from earlier 13.2 release candidates.

• Ensured prevalues can be retrieved outside of an HTTP request context when they depend on a static root node #1258.

13.2.0-rc2 (July 17th 2024)

• Added configuration option AllowedFileUploadExtensions to provide an "allow list" of extensions that will be accepted in file uploads via forms #1252.

  • Read more about this and related settings here.

• Allowed users without sensitive data permissions to set, but not remove, the sensitive flag on a form field #1233.

• Ordered select list of prevalue sources when defining prevalues for a form field.

• Limited the field preview for a field containing prevalues.

13.2.0-rc1 (July 9th 2024)

• Added setting option for single and multiple choice fields to allow for vertical or horizontal display #1218.

• Added new setting type for multiple text strings #1217

• Added validation to prevent users defining an email workflow that allows the form's sender email to be defined as that entered by the user #1210.

• Allowed for the provision of additional data when rendering and submitting forms. When provided it will be used as a source for "magic string" replacements. The data will be associated with the created record and made available for custom logic and update within workflows. #578.

• Added details of workflow type to edit workflow dialog #1183.

• Removed an inline prevalue editor that wasn't functional but could surface it's UI when creating forms from templates #1230.

• Ensured local links are parsed when HTML fields are returned in the delivery API results for form definitions #1227.

• Resolved duplicate approval occurring when the record is approved via a workflow #1223.

• Updated themes such that accessibility is improved by having hidden labels remain in markup but be visually hidden #1220.

• Fixed issue with save button UI, when save is canceled via a notification #1219.

• Improved date format for data values when using the Send email workflow #1214.

• Removed unnecessary circular checks for conditions on workflows resolving an issue where workflow would trigger when conditions were not met #1206.

• Added setting option for the "send to URL" workflow to switch between caption and alias for the field value's XML element #1202

• Allowed for use of prevalue sources that customize based on the current form or field in backoffice editing and preview #1221.

• Restored target used to generate local configuration schema information #1226.

• Fixed issues with retrieving fields and assigning default values when using the datasource wizard.

• Ensured links to Umbraco pages within rich text fields used for emails are correctly parsed #1208.

• Added body rich text field for send email with Razor template workflow #1198.

• Fixed console error with blank values in the date picker field #1241.

• Ensured placeholders are parsed for accepted entry response from the delivery API #1238.

• Improved support for editing large, multi-page forms by retaining scroll position between views and adding a "jump to page" option #1243.

13.1.2 (April 16th 2024)

• Corrected alignment of label for and input id attributes in the date picker field #1200.

• Corrected permission check such that users with only "view entries" permissions can see form details on the dashboard #1192.

• Used requestSubmit when submitting forms #1199.

• Tightened path check used in middleware for restriction of access to form file uploads.

13.1.1 (March 22nd 2024)

• Fixes regression issue with form validation where two forms are rendered on a single page #1189.

13.1.0 (March 19th 2024)

With the introduction of webhooks in Umbraco 13, we've made an update to Forms to allow workflow execution events to trigger webhooks. 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. Read more on Umbraco Forms Webhooks.

We've added an update that will help customers using Forms within locked down production environments.

And there are a couple of further additions to improve the performance and accessibility of the product.

Features implemented and issues resolved in 13.1.0

• Added webhooks for workflow execution events #1151.

• Added support for a proxied request when using reCAPTCHA 3 #1159.

• Added a configurable option to ensure accessibility requirements with regard to fieldsets are adhered to #1163.

  • Read more about this configuration setting here.

• Added a cachebuster querystring based on the current product version to rendered script dependencies #773.

• Ensured that client-side conditions logic correctly implements "is" with multiple values, such that the condition passes if one and only one matching value is found #1173.

• Fixed closing of theme picker dialog #1174.

• Fixed rendering of translated dictionary items used for form captions #1175.

• Applied multiple click protection for form submissions for installations using the aspnet-validation library #1182.

13.0.2 (February 20th 2024)

• Ensured UI for the upload of a text file for a prevalue source only allows the selection of expected .txt files.

• Handled potential null value for prevalues for a form definition following an upgrade #1157

• Fixed handling of API and traditional form posts in reCAPTCHA 3 checks #1150

• Fixed display of validation error when a duplicate form field alias is created #1152

• Fixed issue where file uploads weren't removed as records were deleted.

• Updated Microsoft.Data.SqlClient dependency due to reported security advisory.

13.0.1 (January 16th 2024)

• Added configuration value TitleAndDescription:AllowUnsafeHtmlRendering to allow tighter security for HTML rendering of text entered in the "Title and description" field type.

  • See further details on the configuration page.

• Rendered dictionary translations of field captions in backoffice entries view #1131.

• Ensured valid format string before rendering validation methods with placeholders #1132.

• Ensured the creation of the forms to content relation type is idempotent and created with consistent GUID #1137.

• Ensured Examine re-index user interface completes when no records are available for indexing #1137.

• Fixed issue where use of a custom field HTML ID attribute prefix breaks conditional logic in multi-page forms #1138.

• Added support for record based magic string replacement in the post-submission message #1133.

• Tightens up the null checks when reading form definition JSON for prevalue captions #1140.

• Added configuration value DisableRelationTracking to allow relation tracking between forms and content to be disabled.

  • See further details on the configuration page.

• Added configuration value TrackRenderedFormsStorageMethod to allow use of HttpContext.Items over TempData when tracking rendered forms #1144.

  • See further details on the configuration page and the rendering scripts page.

• Resolved an out of range exception when a condition hides all fields on the final page of a multi-page form.

• Fixed issue with swapping between plain and rich text when configuring the post-submission message #1145.

13.0.0 (December 14th 2023)

• Compatibility with Umbraco 13

  • See full details of breaking changes under the version specific upgrade guide.

• Ran registered server-side file validators on file uploads.

Umbraco.Forms.Deploy

13.0.1 (March 19th 2024)

• Added migrator to support changes in Form field prevalues when importing from older Umbraco versions

Legacy release notes

You can find the release notes for versions out of support in the Legacy documentation on GitHub and Umbraco Forms Package 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.

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": ""
          }
        }
      }
   }

You can create your keys by logging into your reCAPTCHA account.

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

  • Using XPath

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.

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

• SQL Database

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

  • 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

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

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.

Crafting the rule definition itself requires use of JSON logic along with placeholders for the field or fields that are being validated.

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:

{
  "==": [
    "{email}",
    "{compareEmail}"
  ]
}

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:

{
  "or": [
    {
      "==": [
        "{startDate}",
        ""
      ]
    },
    {
      "==": [
        "{endDate}",
        ""
      ]
    },
    {
      ">": [
        "{endDate}",
        "{startDate}"
      ]
    }
  ]
}

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.

{
  "or": [
    {
      "==": [
        "{choose}",
        "A"
      ]
    },
    {
      "and": [
        {
          "==": [
            "{choose}",
            "B"
          ]
        },
        {
          "!=": [
            "{test}",
            ""
          ]
        }
      ]
    }
  ]
}

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.

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.

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.

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

A background service that carries out the actual removal of records needs to be enabled in configuration. If that is not running, a notification will be displayed.

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 configuration settings 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 Server-side file validation in the CMS documentation.

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.
3. Enabling the condition field displays more options:
4. 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.

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 Workflow types 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 Magic Strings 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.

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:

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:

Alternatively, you can add the dependencies to the body tag:

All dependencies originate from your Umbraco Forms installation, which means that no external references are needed.

If you want to modify the rendering of the scripts, you can provide a object parameter named htmlAttributes. The contents of the object will be written out as HTML attributes on the script tags.

You can use this to apply async or defer attributes. For example:

Validation Using jQuery

If you want to use jQuery as your validation framework for Umbraco Forms, you can manually add the following client dependencies:

• jQuery (JavaScript library)

• jQuery validate (jQuery plugin that provides client-side Form validation)

• jQuery validate unobtrusive (Add-on to jQuery Validation that provides unobtrusive validation via data-* attributes)

You should remove any calls to @Html.RenderUmbracoFormDependencies(Url).

• Other CDN services you might want to look at are https://www.jsdelivr.com/ and https://cdnjs.com/about, which may offer better performance and more reliable service.

To add the three client dependencies, see the examples below:

Example within head tags.

Example within body tags.

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.
4. The Export dialog opens. Choose a format such as Microsoft Excel to export the Form records to.
5. Click Done.

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

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:

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

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

• includeScripts indicates whether scripts should be rendered with the form (see Rendering Scripts.

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

• 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 "magic string" replacements. 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:

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" />
}

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:

@await Umbraco.RenderMacroAsync("renderUmbracoForm", new { FormGuid = "<form guid>", FormTheme = "default", ExcludeScripts = "1" })

• FormGuid is the GUID of a form.

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

• ExcludeScripts takes a value of 0 or 1, indicating whether scripts should be excluded from rendering.

• RedirectToPageId is an optional picked content item 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.

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

@if (Model.FormId is Guid formId)
{
    @await Umbraco.RenderMacroAsync("renderUmbracoForm", new { FormGuid = formId, FormTheme = Model.FormTheme, ExcludeScripts = "1" })
}

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.

If you are working with a Umbraco Cloud project, make sure you follow the migration steps outlined in the Umbraco Forms on Cloud article.

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.

We include a Workflow Send email with template (Razor) that allows you to pick a Razor view file that can be used to send out a pretty HTML email for Form submissions.

Creating an Email Template

If you wish to have one or more templates to choose from the Send email with template (Razor), you will need to place all email templates into the ~/Views/Partials/Forms/Emails/ folder.

The Razor view must inherit from FormsHtmlModel:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Forms.Core.Models.FormsHtmlModel>

You now have a model that contains your Form fields which can be used in your email HTML markup, along with the UmbracoHelper methods such as Umbraco.TypedContent and Umbraco.TypedMedia etc.

Below is an example of an email template from the ~/Views/Partials/Forms/Emails/ folder:

@inherits Umbraco.Cms.Web.Common.Views.UmbracoViewPage<Umbraco.Forms.Core.Models.FormsHtmlModel>

@{
    //This is an example email template where you can use Razor Views to send HTML emails

    //You can use Umbraco.TypedContent & Umbraco.TypedMedia etc to use Images & content from your site
    //directly in your email templates too

    //Strongly Typed
    //@Model.GetValue("aliasFormField")
    //@foreach (var color in Model.GetValues("checkboxField")){}

    //Dynamics
    //@Model.DynamicFields.aliasFormField
    //@foreach(var color in Model.DynamicFields.checkboxField

    //Images need to be absolute - so fetching domain to prefix with images
    var siteDomain = Context.Request.Scheme + "://" + Context.Request.Host;
    var assetUrl = siteDomain + "/App_plugins/UmbracoForms/Assets/Email-Example";

}
<!DOCTYPE html>
<html>
<head>
    <title></title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <link href="https://fonts.googleapis.com/css?family=Lato:400,700,900" rel="stylesheet">
    <style type="text/css">

    /* CLIENT-SPECIFIC STYLES */
    body, table, td, a { -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
    table, td { mso-table-lspace: 0pt; mso-table-rspace: 0pt; }
    img { -ms-interpolation-mode: bicubic; }

    /* RESET STYLES */
    img { border: 0; height: auto; line-height: 100%; outline: none; text-decoration: none; }
    table { border-collapse: collapse !important; }
    body { height: 100% !important; margin: 0 !important; padding: 0 !important; width: 100% !important; }

    /* iOS BLUE LINKS */
    a[x-apple-data-detectors] {
        color: inherit !important;
        text-decoration: none !important;
        font-size: inherit !important;
        font-family: inherit !important;
        font-weight: inherit !important;
        line-height: inherit !important;
    }

 /* MOBILE STYLES */
 @@media screen and (max-width:600px){
  h1 {
   font-size: 32px !important;
   line-height: 32px !important;
  }
 }

    /* ANDROID CENTER FIX */
    div[style*="margin: 16px 0;"] { margin: 0 !important; }
    </style>
</head>
<body style="background-color: #f4f4f4; margin: 0 !important; padding: 0 !important;">
    <table border="0" cellpadding="0" cellspacing="0" width="100%" style="margin-bottom: 40px;">
        <!-- LOGO -->
        <tr>
            <td bgcolor="#413659" align="center">
                <!--[if (gte mso 9)|(IE)]>
                    <table align="center" border="0" cellspacing="0" cellpadding="0" width="600">
                    <tr>
                    <td align="center" valign="top" width="600">
                <![endif]-->
                <table border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width: 600px;">
                    <tr>
                        <td align="center" valign="top" style="padding: 40px 10px 40px 10px;">
                            <a href="http://umbraco.com" target="_blank">
                                <img alt="Logo" src="@assetUrl/umbraco-logo.png" width="40" height="40" style="display: block; width: 40px; max-width: 40px; min-width: 40px; font-family: 'Lato', Helvetica, Arial, sans-serif; color: #ffffff; font-size: 18px;" border="0">
                            </a>
                        </td>
                    </tr>
                </table>
                <!--[if (gte mso 9)|(IE)]>
                    </td>
                    </tr>
                    </table>
                <![endif]-->
            </td>
        </tr>

        <!-- HERO -->
        <tr>
            <td bgcolor="#413659" align="center" style="padding: 0px 10px 0px 10px;">
                <!--[if (gte mso 9)|(IE)]>
                    <table align="center" border="0" cellspacing="0" cellpadding="0" width="600">
                    <tr>
                    <td align="center" valign="top" width="600">
                <![endif]-->
                <table border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width: 600px;">
                    <tr>
                        <td bgcolor="#ffffff" align="center" valign="top" style="padding: 40px 20px 20px 20px; color: #000000; font-family: 'Lato', Helvetica, Arial, sans-serif; font-size: 36px; font-weight: 900; line-height: 48px;">
                            <h1 style="font-size: 36px; font-weight: 900; margin: 0;">Umbraco Forms</h1>
                        </td>
                    </tr>
                </table>
                <!--[if (gte mso 9)|(IE)]>
                    </td>
                    </tr>
                    </table>
                <![endif]-->
            </td>
        </tr>

        <!-- COPY BLOCK -->
        <tr>
            <td bgcolor="#F3F3F5" align="center" style="padding: 0px 10px 0px 10px;">
                <!--[if (gte mso 9)|(IE)]>
                    <table align="center" border="0" cellspacing="0" cellpadding="0" width="600">
                    <tr>
                    <td align="center" valign="top" width="600">
                <![endif]-->
                <table border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width: 600px;">

                    <!-- COPY -->
                    <tr>
                        <td bgcolor="#ffffff" align="left" style="padding: 20px 30px 40px 30px; color: #303033; font-family: 'Lato', Helvetica, Arial, sans-serif; font-size: 18px; font-weight: 400; line-height: 1.6em;">
                            This is an example email template from Umbraco Forms Razor based email templates. You can build forms using any HTML markup you wish.
                        </td>
                    </tr>

                    <!-- IMAGE -->
                    <tr>
                        <td bgcolor="#ffffff" align="left" style="padding: 0;">
                            <a href="http://umbraco.com" target="_blank">
                                <img alt="CodeGarden16 Attendees" src="@assetUrl/sample-image.jpg" width="600" style="display: block; width: 100%; max-width: 100%; min-width: 100px;" border="0" />
                            </a>
                        </td>
                    </tr>

                    <!-- COPY HEADING -->
                    <tr>
                        <td bgcolor="#ffffff" align="left" style="padding: 40px 30px 0px 30px; color: #000000; font-family: 'Lato', Helvetica, Arial, sans-serif; line-height: 25px;">
                            <h2 style="font-size: 24px; font-weight: 700; margin: 0;">Form Results</h2>
                        </td>
                    </tr>

                    <!-- COPY -->
                    <tr>
                        <td bgcolor="#ffffff" align="left" style="padding: 20px 30px 40px 30px; color: #303033; font-family: 'Lato', Helvetica, Arial, sans-serif; font-size: 18px; font-weight: 400; line-height: 25px;">

                            @foreach (var field in Model.Fields)
                            {
                                <h4 style="font-weight: 700; margin: 0; color: #000000;">@field.Name</h4>

                                switch (field.FieldType)
                                {
                                    case "FieldType.FileUpload.cshtml":
                                        <p style="margin-top: 0;"><a href="@siteDomain/@field.GetValue()" target="_blank" style="color: #00AEA2;">@field.GetValue()</a></p>
                                        break;

                                    case "FieldType.DatePicker.cshtml":
                                        DateTime dt;
                                        var fieldValue = field.GetValue();
                                        var dateValid = DateTime.TryParse(fieldValue != null ? fieldValue.ToString() : string.Empty, out dt);
                                        var dateStr = dateValid ? dt.ToString("f") : "";
                                        <p style="margin-top: 0;">@dateStr</p>
                                        break;

                                    case "FieldType.CheckBoxList.cshtml":
                                        <p style="margin-top: 0;">
                                            @foreach (var color in field.GetValues())
                                            {
                                                @color<br/>
                                            }
                                        </p>
                                        break;
                                    default:
                                        <p style="margin-top: 0;">@field.GetValue()</p>
                                        break;
                                }
                            }

                        </td>
                    </tr>
                </table>
                <!--[if (gte mso 9)|(IE)]>
                    </td>
                    </tr>
                    </table>
                <![endif]-->
            </td>
        </tr>

        <!-- SUPPORT CALLOUT -->
        <tr>
            <td bgcolor="#F3F3F5" align="center" style="padding: 30px 10px 0px 10px;">
                <!--[if (gte mso 9)|(IE)]>
                    <table align="center" border="0" cellspacing="0" cellpadding="0" width="600">
                    <tr>
                    <td align="center" valign="top" width="600">
                <![endif]-->
                <table border="0" cellpadding="0" cellspacing="0" width="100%" style="max-width: 600px;">
                    <!-- HEADLINE -->
                    <tr>
                        <td bgcolor="#03BFB3" align="center" style="padding: 30px 30px 30px 30px; color: #ffffff; font-family: 'Lato', Helvetica, Arial, sans-serif; font-size: 18px; font-weight: 400; line-height: 25px;">
                            <h2 style="font-size: 20px; font-weight: 700; color: #ffffff; margin: 0; margin-bottom: 5px;">Need more help?</h2>
                            <p style="margin: 0;"><a href="https://our.umbraco.org/Documentation/Add-ons/UmbracoForms/" target="_blank" style="color: #ffffff;">Find our documentation here</a></p>
                        </td>
                    </tr>
                </table>
                <!--[if (gte mso 9)|(IE)]>
                    </td>
                    </tr>
                    </table>
                <![endif]-->
            </td>
        </tr>

    </table>
</body>
</html>

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

Provider model

Many features of Forms use a provider model, which makes it quicker to add new parts to the application.

The model uses the notion that everything must have a type to exist. The type defines the capabilities of the item. For instance a Textfield on a form has a FieldType, this particular field type enables it to render an input field and save text strings. The same goes for workflows, which have a workflow type, datasources which have a datasource type and so on. Using the model you can seamlessly add new types and thereby extend the application.

It is possible to add new Field types, Data Source Types, Prevalue Source Types, Export Types, and Workflow Types.

Field types

A field type handles rendering of the UI for a field in a form. It renders a standard ASP.NET Razor partial view and is able to return a list of values when the form is saved.

The concept of provider settings, common to the field and other types, is also discussed in this section.

Data Source Types

A data source type enables Umbraco Forms to connect to a custom source of data. A data source consists of any kind of storage if it is possible to return a list of fields Umbraco Forms can map values to. For example: a Database data source can return a list of columns Forms can send data to. This enables Umbraco Forms to map a form to a data source. A data source type is responsible for connecting Forms to external storage.

Prevalue Source Types

A prevalue source type connects to 3rd party storage to retrieve values. These values are used on fields supporting prevalues. The source fetches the collection of values.

Workflow Types

A workflow can be executed each time a form changes state (when it is submitted for instance). A workflow is responsible for executing logic which can modify the record or notify 3rd party systems.

Export Types

Export types are responsible for turning form records into any other data format, which is then returned as a file.

Magic String Format Functions

Custom magic string format functions to add to the ones shipped with Umbraco Forms can be created in code.

Validation Patterns

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.

Handling Forms Events

Another option for extension via custom code is to hook into one of the many events available.

Validation

Form events are raised during the submission life cycle and can be handled for executing custom logic.

Default Fields and Workflows

When a new form is created, the default behavior is to add a single workflow. This workflow will send a copy of the form to the current backoffice user's email address.

A single "data consent" field will also be added unless it has been disabled via configuration.

It's possible to amend this behavior and change it to fit your needs.

Responding to State Values

In the course of submitting a form, Umbraco Forms will set values in TempData and/or HttpContext.Items, that you can use to customize the website functionality.

Customizing Post-Submission Behavior

Whether displaying a message or redirecting, a developer can customize the page viewed after the form is submitted based on the presence of TempData variables.

One variable with a key of UmbracoFormSubmitted has a value containing the Guid identifier for the submitted form.

A second variable contains the Guid identifier of the record created from the form submission. You can find this using the Forms_Current_Record_id key.

In order to redirect to an external URL rather than a selected page on the Umbraco website, you will need to use a custom workflow. Within this workflow you can set the required redirect URL on the HttpContext.Items dictionary using the key FormsRedirectAfterFormSubmitUrl (defined in the constant Umbraco.Forms.Core.Constants.ItemKeys.RedirectAfterFormSubmitUrl).

For example, using an injected instance of IHttpContextAccessor:

_httpContextAccessor.HttpContext.Items[Constants.ItemKeys.RedirectAfterFormSubmitUrl] = "https://www.umbraco.com";

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

@using Umbraco.Core;
@using Umbraco.Cms.Core.Composing;
@using Umbraco.Forms.Core.Services;
@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>

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

Create a new class library project in Visual Studio add references to the Umbraco.Forms.Core.dll (available via referencing the NuGet package). You might also need to reference Umbraco.Forms.Core.Providers.

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";
}