This builds on the "adding a type to the provider model" chapter

C#

Add a new class to the Visual Studio solution, make it inherit from Umbraco.Forms.Core.FieldType and fill in the constructor:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Http;
using Umbraco.Forms.Core.Enums;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Services;

namespace MyFormsExtensions
{
    public class MyCustomField : Umbraco.Forms.Core.FieldType
    {
        public MyCustomField()
        {
            Id = new Guid("08b8057f-06c9-4ca5-8a42-fd1fc2a46eff"); // Replace this!
            Name = "My Custom Field";
            Description = "Render a custom text field.";
            Icon = "icon-autofill";
            DataType = FieldDataType.String;
            SortOrder = 10;
            SupportsRegex = true;
            FieldTypeViewName = "FieldType.MyCustomField.cshtml";
        }

        // You can do custom validation in here which will occur when the form is submitted.
        // Any strings returned will cause the submission to be considered invalid.
        // Returning an empty collection of strings will indicate that it's valid to proceed.
        public override IEnumerable<string> ValidateField(Form form, Field field, IEnumerable<object> postedValues, HttpContext context, IPlaceholderParsingService placeholderParsingService, IFieldTypeStorage fieldTypeStorage)
        {
            var returnStrings = new List<string>();

            if (!postedValues.Any(value => value.ToString().ToLower().Contains("custom")))
            {
                returnStrings.Add("You need to include 'custom' in the field!");
            }

            // Also validate it against the default method (to handle mandatory fields and regular expressions)
            return base.ValidateField(form, field, postedValues, context, placeholderParsingService, fieldTypeStorage, returnStrings);
        }
    }
}

In the constructor, we specify the standard provider information:

• Id - should be set to a unique GUID.

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

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

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

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

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

• SupportsRegex - indicates whether pattern based validation using regular expressions can be used with the field.

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

• RenderInputType- indicates how the field should be rendered within the theme, as defined with the RenderInputType enum. The default is Single for a single input field. Multiple should be used for multiple input fields such as checkbox lists. Custom is used for fields without visible input fields.

You will then need to register this new field as a dependency.

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Forms.Core.Providers;

namespace MyFormsExtensions
{
    public class Startup : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.WithCollectionBuilder<FieldCollectionBuilder>()
                .Add<MyCustomField>();
        }
    }
}

Partial view

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

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

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

This will be rendered when the default theme is used.

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

For Umbraco 10 and above, we've moved to distributing the theme as part of a Razor Class Library so the folder won't exist. However, you can create it for your custom field type. If you would like to reference the partial views of the default theme, you can download them as mentioned in the Themes article.

Umbraco backoffice view

The final step involves building the HTML view which will be rendered in Umbraco as an example of how our end result will look:

<input
    type="text" tabindex="-1"
    class="input-block-level"
    style="max-width: 100px"
/>

In the HTML you can access settings via field.settings, e.g. {{field.settings.Caption}} to render a "Caption" setting. It is also possible to access prevalues via field.parsedPreValues.

For built-in field types, Umbraco Forms look for this file in the virtual folder: App_Plugins\UmbracoForms\backoffice\Common\FieldTypes\. It will expect to find a file with a name matching the class's name, i.e. mycustomfield.html. To add custom fields and themes, create a folder at the specified path (also known as the virtual folder). This is because the client-side code is included in the Razor Class Library. As a result, these files are available as if they're stored at a specific location on disk.

To store in a different location, you can apply the following override to the custom field type's C# representation:

public override string GetDesignView() =>
    "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/FieldTypes/mycustomfield.html";

Field settings

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

    [Setting("My Setting", Description = "Help text for the setting", View = "TextField", SupportsPlaceholders = "true", DisplayOrder = 10)]
    public string MySetting { get; set; }

The property Name names the setting in the backoffice with the Description providing the help text. Both of these are translatable by providing a user or package language file containing appropriate keys:

<area alias="formProviderFieldTypes">
    <key alias="mySettingName">My Setting</key>
    <key alias="mySettingDescription">Help text for the setting</key>
</area>

The area aliases for the other provider types are as follows:

• Data sources - formProviderDataSources

• Export types - formProviderExportTypes

• Prevalue sources - formProviderPrevalueSources

• Recordset actions - formRecordSetActions

• Workflows - formProviderWorkflows

The View attribute defines the client-side view used when rendering a preview of the field in the form's designer. Umbraco Forms ships with a number of these, found in a virtual path of App_Plugins\UmbracoForms\backoffice\Common\SettingTypes\.

Again though, you can use your own location, and configure with a full path to the view, e.g.:

To reference the file the setting should be configured with a full path to the view, e.g.:

    [Setting("My Setting",
        Description = "Help text for the setting",
        View = "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/SettingTypes/mycustomsettingfield.html",
        SupportsPlaceholders = true
        DisplayOrder = 10)]
    public string MySetting { get; set; }

SupportsPlaceholders is a flag indicating whether the setting can contain "magic string" placeholders and controls whether they are parsed on rendering.

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

Backoffice entry rendering

The third and final client-side view file used for settings is in the rendering of the submitted values for the field. This rendering takes place in the "Entries" section of the backoffice.

These are defined by the RenderView property of a field type and are found in App_Plugins\UmbracoForms\backoffice\Common\RenderTypes\.

As for the other files, if you require a custom render type view, it's better to host them in different location, such as App_Plugins\UmbracoFormsCustomFields\backoffice\Common\RenderTypes\mycustomrenderfield.html.

To reference the file you should override the RenderView property, e.g.:

public override string RenderView => "~/App_Plugins/UmbracoFormsCustomFields/backoffice/Common/RenderTypes/mycustomrenderfield.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

The Forms package comes with many field, workflow, and other built-in types. If you have a requirement that isn't served by any of these, you can create and develop your own.

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

This builds on the "adding a type to the provider model" chapter and applies to Umbraco Forms version 4.4.1 and higher

Add a new class to your project and have it inherit from Umbraco.Forms.Core.ExportType and you have two options when implementing the class.

Basic Example

When implementing the method public override string ExportRecords(RecordExportFilter filter) in your export provider class. You need to return the final string you wish to write to a file. Such as .txt file or .csv and you can perform your logic to build up a comma separated string for a CSV file in the ExportRecords method.

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

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

Provider Class

using System;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Searchers;
using Umbraco.Forms.Web.Helpers;

namespace MyFormsExtensions
{
    public class ExportToHtmlReport : ExportType
    {
        private readonly IFormRecordSearcher _formRecordSearcher;

        public ExportToHtmlReport(
            IHostingEnvironment hostingEnvironment,
            IFormRecordSearcher formRecordSearcher)
            : base(hostingEnvironment)
        {
            _formRecordSearcher = formRecordSearcher;

            this.Name = "Export as HTML";
            this.Description = "Export entries as a single HTML report";
            this.Id = new Guid("4117D352-FB41-4A4C-96F5-F6EF35B384D2");
            this.FileExtension = "html";
            this.Icon = "icon-article";        }

        public override string ExportRecords(RecordExportFilter filter)
        {
            var view = "~/Views/Partials/Forms/Export/html-report.cshtml";
            EntrySearchResultCollection model = _formRecordSearcher.QueryDataBase(filter);
            return ViewHelper.RenderPartialViewToString(view, model);
        }
    }
}

Razor Partial View

@model Umbraco.Forms.Web.Models.Backoffice.EntrySearchResultCollection

@{
    var submissions = Model.Results.ToList();
    var schemaItems = Model.schema.ToList();
}

<h1>Form Submissions</h1>

@foreach (var submission in submissions)
{
    var values = submission.Fields.ToList();

    for (int i = 0; i < schemaItems.Count; i++)
    {
        <strong>@schemaItems[i].Name</strong> @values[i] <br />
    }

    <hr/>
}

Advanced Example

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

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

using System;
using System.IO;
using System.IO.Compression;
using System.Linq;
using Umbraco.Cms.Core.Hosting;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Searchers;

namespace MyFormsExtensions
{
    public class ExportToTextFiles : ExportType
    {
        private readonly IFormRecordSearcher _formRecordSearcher;

        public ExportToTextFiles(
            IHostingEnvironment hostingEnvironment,
            IFormRecordSearcher formRecordSearcher)
            : base(hostingEnvironment)
        {
            _formRecordSearcher = formRecordSearcher;

            this.Name = "Export as text files";
            this.Description = "Export entries as text files inside a zip file";
            this.Id = new Guid("171CABC9-2207-4575-83D5-2A77E824D5DB");
            this.FileExtension = "zip";
            this.Icon = "icon-zip";
        }

        /// <summary>
        /// We do not implement this method from the interface
        /// As this method is called from ExportToFile that we also override here & is expecting the file contents as a string to be written as a stream to a file
        /// Which would be OK if we were creating a CSV or a single based file that can have a simple string written as a string such as one large HTML report or XML file perhaps
        /// </summary>
        public override string ExportRecords(RecordExportFilter filter) => throw new NotImplementedException();

        /// <summary>
        /// This gives us greater control of the export process
        /// </summary>
        /// <param name="filter">
        /// This filter contains the date range & other search parameters to limit the entries we are exporting
        /// </param>
        /// <param name="filepath">
        /// The filepath that the export file is expecting to be served from
        /// So ensure that the zip of text files is saved at this location
        /// </param>
        /// <returns>The final file path to serve up as the export - this is unlikely to change through the export logic</returns>
        public override string ExportToFile(RecordExportFilter filter, string filepath)
        {
            // Before Save - Check Path, Directory & Previous File export does not exist
            string pathToSaveZipFile = filepath;

            // Check our path does not contain \\
            // If not, use the filePath
            if (filepath.Contains('\\') == false)
            {
                pathToSaveZipFile = HostingEnvironment.MapPathContentRoot(filepath);
            }

            // Get the directory (strip out \\ if it exists)
            var dir = filepath.Substring(0, filepath.LastIndexOf('\\'));
            var tempFileDir = Path.Combine(dir, "text-files");


            // If the path does not end with our file extension, ensure it's added
            if (pathToSaveZipFile.EndsWith("." + FileExtension) == false)
            {
                pathToSaveZipFile += "." + FileExtension;
            }

            // Check that the directory where we will save the ZIP file temporarily exists
            // If not just create it
            if (Directory.Exists(tempFileDir) == false)
            {
                Directory.CreateDirectory(tempFileDir);
            }

            // Check if the zip file exists already - if so delete it, as we have a new update
            if (File.Exists(pathToSaveZipFile))
            {
                File.Delete(pathToSaveZipFile);
            }

            // Query the DB for submissions to export based on the filter
            EntrySearchResultCollection submissions = _formRecordSearcher.QueryDataBase(filter);

            // Get the schema objects to a list so we can get items using position index
            var schemaItems = submissions.schema.ToList();

            // We will use this to store our contents of our file to save as a text file
            var fileContents = string.Empty;

            // For each submission we have build up a string to save to a text file
            foreach (EntrySearchResult submission in submissions.Results)
            {
                // The submitted data for the form submission
                var submissionData = submission.Fields.ToList();

                // For loop to match the schema position to the submission data
                for (int i = 0; i < schemaItems.Count; i++)
                {
                    // Concat a string of the name of the field & its stored data
                    fileContents += schemaItems[i].Name + ": " + submissionData[i] + Environment.NewLine;
                }

                // Now save the contents to a text file
                // Base it on the format of the record submission unique id
                var textFileName = Path.Combine(tempFileDir, submission.UniqueId + ".txt");
                File.WriteAllText(textFileName, fileContents);

                // Reset fileContents to be empty again
                fileContents = string.Empty;
            }

            // Now we have a temp folder full of text files
            // Generate a zip file containing them & save that
            ZipFile.CreateFromDirectory(tempFileDir, pathToSaveZipFile);

            // Tidy up after ourselves & delete the temp folder of text files
            if (Directory.Exists(tempFileDir))
            {
                Directory.Delete(tempFileDir, true);
            }

            // Return the path where we saved the zip file containing the text files
            return pathToSaveZipFile;
        }
    }
}

This builds on the "adding a type to the provider model" chapter

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

using Serilog;
using System;
using System.Collections.Generic;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Data.Storage;
using Umbraco.Forms.Core.Enums;
using Umbraco.Forms.Core.Persistence.Dtos;
using Microsoft.Extensions.Logging;
using Umbraco.Core.Composing;

namespace MyFormsExtensions
{
    public class TestWorkflow : WorkflowType
    {
        private readonly ILogger<TestWorkflow> _logger;

        public TestWorkflow(ILogger<TestWorkflow> logger)
        {
            _logger = logger;

            this.Id = new Guid("ccbeb0d5-adaa-4729-8b4c-4bb439dc0202");
            this.Name = "TestWorkflow";
            this.Description = "This workflow is just for testing";
            this.Icon = "icon-chat-active";
            this.Group = "Services";
        }

        public override WorkflowExecutionStatus Execute(WorkflowExecutionContext context)
        {
            // first we log it
            _logger.LogDebug("the IP " + context.Record.IP + " has submitted a record");

            // we can then iterate through the fields
            foreach (RecordField rf in context.Record.RecordFields.Values)
            {
                // and we can then do something with the collection of values on each field
                List<object> vals = rf.Values;

                // or get it as a string
                rf.ValuesAsString(false);
            }

            //Change the state
            context.Record.State = FormState.Approved;

            _logger.LogDebug("The record with unique id {RecordId} that was submitted via the Form {FormName} with id {FormId} has been changed to {RecordState} state",
               context.Record.UniqueId, context.Form.Name, context.Form.Id, "approved");

            return WorkflowExecutionStatus.Completed;
        }

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

Information available to the workflow

Record information

The Execute() method gets a WorkflowExecutionContext which has properties for the related Form, Record, and FormState. This parameter contains all information related to the workflow.

The Record contains all data and metadata submitted by the form. As shown in the example above, you can iterate over all RecordField values in the form. You can also retrieve a specific record field by alias using the following method:

RecordField? recordField = context.Record.GetRecordFieldByAlias("myalias");

Having obtained a reference to a record field, the submitted value can be retrieved via:

var fieldValue = recordField.ValuesAsString(false);

The ValuesAsString will JSON escape the result by default. If you do not want this escaping to occur, pass false as the parameter.

If the field stores multiple values, they are delimited with a comma. In many cases, you can safely split on that delimiter to obtain the individual values. However, this can lead to issues if the prevalues being selected also contain commas. If that's a concern, the following extension method is available in Umbraco.Forms.Core.Extensions to correctly parse the selected prevalues:

IEnumerable<string> selectedPrevalues = recordField.GetSelectedPrevalues();

Form and state information

The Form references the form the record is from and FormState provides its state (submitted or approved).

Other context, such as the current HttpContext, if needed can be passed as constructor parameters (for example: the HttpContext can be accessed by injecting IHttpContextAccessor).

Registering the workflow type

To use the new workflow type, you will need to register it as part of application startup.

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Forms.Core.Providers;

namespace MyFormsExtensions
{
    public class Startup : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.WithCollectionBuilder<WorkflowCollectionBuilder>()
                .Add<TestWorkflow>();
        }
    }
}

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

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

Adding settings to a type

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

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

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

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

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

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

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

Validate type settings with ValidateSettings()

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

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

Registering the class with Umbraco and Forms

To register the type, ensure your web application project has a reference to the class library - either via a project or NuGet reference - and 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 Startup.cs:

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

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

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

From Umbraco Forms 9.5 and 10.0, there are further convenience methods you can use for registering custom types. These are found in the namespace Umbraco.Forms.Core.Providers.Extensions.

For example, instead of the following:

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

Your workflow can be registered using:

    builder.AddFormsWorkflow<LogWorkflow>():

Or:

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

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

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

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

Overriding default providers in Umbraco Forms

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

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

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

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

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

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

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

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

        return custom;
    }
}

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

Composer:

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

Backoffice View:

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

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

However if you do want to reference them you can view and extract them from the Umbraco.Forms.StaticAssets NuGet package.

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.

using Umbraco.Forms.Core.Providers;
using Umbraco.Forms.Core.Providers.FieldTypes;

namespace MyNamespace
{
    public class MyFormFieldsComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.FormsFields()
              .Exclude<Password>()
              .Exclude<Recaptcha2>()
              .Exclude<RichText>();
        }
    }
}

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

Provided patterns

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

Creating a custom validation pattern

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

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

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

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

• Pattern - the regular expression pattern.

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

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

using Umbraco.Forms.Core.Interfaces;
namespace Umbraco.Forms.TestSite.Business.ValidationPatterns
{
    public class UkPostCode : IValidationPattern
    {
        public string Alias => "ukPostCode";
        public string Name => "UK Post Code";
        public string LabelKey => string.Empty;
        public string Pattern => @"^([a-zA-Z]{1,2}[a-zA-Z\d]{1,2})\s(\d[a-zA-Z]{2})$";
        public bool ReadOnly => true;
    }
}

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:

public static IUmbracoBuilder AddCustomProviders(this IUmbracoBuilder builder)
{
    builder.FormsValidationPatterns()
        .Append<UkPostCode>();
    return builder;
}

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.

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.

Creating a custom format function

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

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

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

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

Registering the custom format function

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

Using the custom format function

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

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

By default, a single workflow is added when a new form is created. This workflow will send a copy of the form to the email address of the current backoffice user.

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.

Implementing a Custom Behavior

Two interfaces are used to abstract the logic for setting default fields and workflows for a form. They are IApplyDefaultFieldsBehavior and IApplyDefaultWorkflowsBehavior respectively.

The default behaviors are defined using built-in, internal classes that implement this interface.

You can create your own implementation of these interfaces.

Example - Providing a Custom Apply Workflows Behavior

An illustrative example, adding a custom workflow that writes to the log, is shown below.

Firstly, the custom workflow:

Secondly, the custom implementation of IApplyDefaultWorkflowsBehavior:

Finally, to register the custom implementation in place of the default one:

Setting a Mandatory Default Workflow

When adding a default workflow in code, it's possible to make it mandatory, which will prevent editors from removing it from a form.

You can see this in the example above, where the IsMandatory property of the created FormWorkflowWithTypeSettings instance is set to true.

Example - Providing a Custom Apply Fields Behavior

The following class shows the default implementation provided with Forms. You can copy this and customize it to your needs.

Again, you will need to register your custom class, for example, in a composer with:

This builds on the "" article

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

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

Dynamic settings can be applied and validated as shown in the article.

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

Another Example Using Dependency Injection to Access Additional Services

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

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

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