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.

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

Umbraco Forms ships with setting types and you can also create your own.

Validate type settings with ValidateSettings()

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

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

Registering the class with Umbraco and Forms

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

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

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

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

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

For example, instead of the following:

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

Your workflow can be registered using:

    builder.AddFormsWorkflow<LogWorkflow>():

Or:

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

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

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

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

Overriding default providers in Umbraco Forms

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

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

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

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

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

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

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

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

        return custom;
    }
}

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

Composer:

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

Backoffice View:

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

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

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

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

This builds on the "Adding a type to the provider model" 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 Validate type settings with ValidateSettings() article.

using System;
using System.Collections.Generic;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Models;

namespace MyFormsExtensions
{
    public class FixedListPrevalueSource : FieldPreValueSourceType
    {
        public FixedListPrevalueSource()
        {
            Id = new Guid("42C8158D-2AA8-4621-B653-6A63C7545768");
            Name = "Fixed List";
            Description = "Example prevalue source providing a fixed list of values.";
        }

        public override List<PreValue> GetPreValues(Field field, Form form) =>
            new List<PreValue>
            {
                new PreValue
                {
                    Id = 1,
                    Value = "item-one",
                    Caption = "Item One"
                },
                new PreValue
                {
                    Id = 2,
                    Value = "item-two",
                    Caption = "Item Two"
                }
            };

        /// <inheritdoc/>
        public override List<Exception> ValidateSettings()
        {
        // this is used to validate any dynamic settings you might apply to the PreValueSource
        // if there are no dynamic settings, return an empty list of Exceptions:
            var exceptions = new List<Exception>();
            return exceptions;
        }
    }
}

You will then need to register this new prevalue source type 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<FieldPreValueSourceCollectionBuilder>()
                .Add<FixedListPrevalueSource>();
        }
    }
}

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.

using System;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;
using Umbraco.Cms.Core;
using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.Web;
using Umbraco.Forms.Core;
using Umbraco.Forms.Core.Models;
namespace MyFormsExtensions
    public class FormPrevaluesSourceNode : FieldPreValueSourceType
    {
        private readonly ILogger _logger;
        private readonly IUmbracoContextFactory _UmbracoContextFactory;
        //DEFINE ANY CONFIGURATION SETTING HERE
        [Umbraco.Forms.Core.Attributes.Setting(name: "Source Node",
            Alias = "SourceNodeId",
            Description = "Node holding the Options desired.",
            View = "pickers.content")]
        public string SourceNodeId { get; set; }
        public FormPrevaluesSourceNode(
            ILogger<FormPrevaluesSourceNode> logger
            , IUmbracoContextFactory umbracoContextFactory
        )
        {
            _logger = logger;
            _UmbracoContextFactory = umbracoContextFactory;
            this.Id = new Guid("0E4D4E2B-56E1-4E86-84E4-9A0A6051B57C"); //MAKE THIS UNIQUE!
            this.Name = "Content-defined Form Prevalues Source Node";
            this.Description = "Select a node of type 'FormPrevaluesSourceNode'";
            this.Group = "Custom";
            this.Icon = "icon-science";
        }
        /// <summary>
        /// The main method where the PreValues are defined and returned.
        /// </summary>
        /// <param name="field"></param>
        /// <param name="form"></param>
        /// <returns>List of 'Umbraco.Forms.Core.Models.PreValue'</returns>
        public override List<PreValue> GetPreValues(Field field, Form form)
        {
            List<PreValue> result = new List<PreValue>();
            try
            {
                // Access the Configuration Setting and check that is is valid
                if (!string.IsNullOrEmpty(SourceNodeId))
                {
                    var nodeId = 0;
                    var isValidId = Int32.TryParse(SourceNodeId, out nodeId);
                    if (isValidId)
                    {
                        IPublishedContent iPub;
                        using (var umbracoContextReference = _UmbracoContextFactory.EnsureUmbracoContext())
                        {
                            iPub = umbracoContextReference.UmbracoContext.Content.GetById(nodeId);
                        }
                        if (iPub != null)
                        {
                            int sort = 0;
                            //This is using a ModelsBuilder Model to strongly-type the selected node
                            var preValSourceNode = new Models.FormPrevaluesSourceNode(iPub, null);
                            foreach (var prevalue in preValSourceNode.PreValues)
                            {
                                PreValue pv = new PreValue();
                                pv.Id = $"{iPub.Id}-{sort}";
                                pv.Value = prevalue.StoredValue;
                                pv.Caption = prevalue.DisplayText; //.Caption only available in Forms Versions  8.13.0+, 9.5.0+, & 10.1.0+
                                pv.SortOrder = sort;
                                result.Add(pv);
                                sort++;
                            }
                        }
                    }
                }
            }
            catch (Exception ex)
            {
                _logger.LogError($"Unable to get options from FormPrevaluesSourceNode #{SourceNodeId}", ex);
            }
            return result;
        }
        /// <summary>
        /// This is where any checks for Configuration validity are done.
        /// The exceptions will be displayed in the back-office UI to the user.
        /// </summary>
        /// <returns>List of 'System.Exception'</returns>
        public override List<Exception> ValidateSettings()
        {
            List<Exception> exceptions = new List<Exception>();
            if (string.IsNullOrEmpty(SourceNodeId))
            {
                exceptions.Add(new Exception("'Source Node' setting not filled out"));
            }
            else
            {
                var nodeId = 0;
                var isValidId = Int32.TryParse(SourceNodeId, out nodeId);
                if (isValidId)
                {
                    IPublishedContent iPub;
                    using (var umbracoContextReference = _UmbracoContextFactory.EnsureUmbracoContext())
                    {
                        iPub = umbracoContextReference.UmbracoContext.Content.GetById(nodeId);
                    }
                    if (iPub != null && iPub.ContentType.Alias != Models.FormPrevaluesSourceNode.ModelTypeAlias)
                    {
                        exceptions.Add(new Exception("'Source Node' needs to be of type 'FormPrevaluesSourceNode'"));
                    }
                }
            }
            return exceptions;
        }
    }
}

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

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;
using Umbraco.Forms.Core.Providers;
namespace MyFormsExtensions
{
    public class FormsComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            //Adding Custom Form PreValueSource
            builder.WithCollectionBuilder<FieldPreValueSourceCollectionBuilder>()
                .Add<FormPrevaluesSourceNode>();
        }
    }
}

Form validation notification

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

using System.Linq;
using Microsoft.AspNetCore.Http;
using Umbraco.Cms.Core.Events;
using Umbraco.Forms.Core.Models;
using Umbraco.Forms.Core.Services.Notifications;

namespace MyFormsExtensions
{
    /// <summary>
    /// Catch form submissions before being saved and perform custom validation.
    /// </summary>
    public class FormValidateNotificationHandler : INotificationHandler<FormValidateNotification>
    {
        public void Handle(FormValidateNotification notification)
        {
            // If needed, be selective about which form submissions you affect.
            if (notification.Form.Name == "Form Name")
            {
                // Check the ModelState
                if (notification.ModelState.IsValid == false)
                {
                    return;
                }

                // A sample validation
                var email = GetPostFieldValue(notification.Form, notification.Context, "email");
                var emailConfirm = GetPostFieldValue(notification.Form, notification.Context, "verifyEmail");

                // If the validation fails, return a ModelError
                if (email.ToLower() != emailConfirm.ToLower())
                {
                    notification.ModelState.AddModelError(GetPostField(notification.Form, "verifyEmail").Id.ToString(), "Email does not match");
                }
            }
        }

        private static string GetPostFieldValue(Form form, HttpContext context, string key)
        {
            Field field = GetPostField(form, key);
            if (field == null)
            {
                return string.Empty;
            }


            return context.Request.HasFormContentType &&  context.Request.Form.Keys.Contains(field.Id.ToString())
                ? context.Request.Form[field.Id.ToString()].ToString().Trim()
                : string.Empty;
        }

        private static Field GetPostField(Form form, string key) => form.AllFields.SingleOrDefault(f => f.Alias == key);
    }
}

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

To register the handler, add the following code into the startup pipeline. In this example, the registration is implemented as an extension method to IUmbracoBuilder and should be called from Program.cs:

public static IUmbracoBuilder AddUmbracoFormsCoreProviders(this IUmbracoBuilder builder)
{
    builder.AddNotificationHandler<FormValidateNotification, FormValidateNotificationHandler>();
}

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:

    public class TestSiteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<FormSavingNotification, FormSavingNotificationHandler>();
        }
    }

    public class FormSavingNotificationHandler : INotificationHandler<FormSavingNotification>
    {
        public void Handle(FormSavingNotification notification)
        {
            foreach (Form form in notification.SavedEntities)
            {
                foreach (Page page in form.Pages)
                {
                    foreach (FieldSet fieldset in page.FieldSets)
                    {
                        foreach (FieldsetContainer fieldsetContainer in fieldset.Containers)
                        {
                            foreach (Field field in fieldsetContainer.Fields)
                            {
                                field.Caption += " (updated)";
                            }
                        }
                    }
                }
            }
        }
    }

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:

    public class TestSiteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<FormSavingNotification, FormSavingNotificationHandler>();
        }
    }

    public class FormSavingNotificationHandler : INotificationHandler<FormSavingNotification>
    {
        private readonly ILogger<FormSavingNotification> _logger;

        public FormSavingNotificationHandler(ILogger<FormSavingNotification> logger) => _logger = logger;

        public void Handle(FormSavingNotification notification)
        {
            foreach (Form savedEntity in notification.SavedEntities)
            {
                _logger.LogInformation($"Form updated. New parent: {savedEntity.FolderId}. Old parent: {notification.State["MovedFromFolderId"]}");
            }
        }
    }

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:

    public class TestSiteComposer : IComposer
    {
        public void Compose(IUmbracoBuilder builder)
        {
            builder.AddNotificationHandler<EntrySearchResultFetchingNotification, EntrySearchResultFetchingNotificationHandler>();
        }
    }

    public class EntrySearchResultFetchingNotificationHandler : INotificationHandler<EntrySearchResultFetchingNotification>
    {
        public void Handle(EntrySearchResultFetchingNotification notification)
        {
            var transformedFields = new List<object>();
            foreach (var field in notification.EntrySearchResult.Fields)
            {
                if (field?.ToString() == "Test")
                {
                    transformedFields.Add("Test (updated)");
                }
                else
                {
                    transformedFields.Add(field);
                }
            }

            notification.EntrySearchResult.Fields = transformedFields;
        }
    }

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

Umbraco Forms Magic Strings 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.

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.

using System.Globalization;
using Umbraco.Forms.Core.Interfaces;

namespace Umbraco.Forms.Core.Providers.ParsedPlacholderFormatters
{
    public class BoundNumber : IParsedPlaceholderFormatter
    {
        public string FunctionName => "bound";

        public string FormatValue(string value, string[] args)
        {
            if (args.Length != 2)
            {
                return value;
            }

            if (!int.TryParse(args[0], out var min) || !int.TryParse(args[1], out var max))
            {
                return value;
            }

            if (int.TryParse(value, out int valueAsInteger) ||
                int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out valueAsInteger))
            {
                if (valueAsInteger < min)
                {
                    return min.ToString();
                }

                if (valueAsInteger > max)
                {
                    return max.ToString();
                }

                return valueAsInteger.ToString();
            }

            return value;
        }
    }
}

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:

public static IUmbracoBuilder AddCustomProviders(this IUmbracoBuilder builder)
{
    builder.FormsParsedPlaceholderFormatters()
        .Add<BoundNumber>();
    return builder;
}

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:

[#field | bound: 1: 10]

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

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

Information available to the workflow

Record information

The ExecuteAsync() 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:

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

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:

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.

This builds on the "" chapter.

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

Basic Example

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

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

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

Provider Class

Razor Partial View

Registration

Advanced Example

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

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

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:

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

Example

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

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

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

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

From Forms 14, each interface is defined as an Umbraco .

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

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

Built-in setting types

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

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

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

The one exception is Forms.PropertyEditorUi.TextWithFieldPicker. This one we don't use within the package, but we make it available for developers to use when creating their own types.

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

Creating a setting type

To create a custom setting type you will need an AngularJS view and controller in the following location: /App_Plugins/MyPlugin/.

You then add the name of the view as the View property on the Setting attribute defined on the type.

This builds on the "" chapter

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

Server-side Field Type Definition

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

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

• Id - should be set to a unique GUID.

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

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

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

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

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

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

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

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

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

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

  • The default is Single for a single input field.

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

  • Custom is used for fields without visible input fields.

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

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

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

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

Partial View

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

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

This will be rendered when the default theme is used.

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

Read-only partial view

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

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

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

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

Field Settings

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

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

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

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

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

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

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

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

Umbraco Backoffice Components

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

• The preview, displayed on the form definition editor.

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

• The property editor UI used for editing settings.

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

• Translations for setting labels and descriptions.

Field Preview

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

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

And it is registered via a manifest:

Field Editor

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

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

Again, it's registered via a manifest.

Setting Value Editor

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

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

And register it via a manifest:

Setting Value Converter

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

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

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

• getSettingPropertyConfig - creates the configuration needed for the property editor

The following code shows the structure for these converter elements.

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

Language Files

Setting labels and descriptions are translated via language files. The following example shows how this is created for the settings on our example field type:

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

• Data sources - formProviderDataSources

• Export types - formProviderExportTypes

• Field types - formProviderFieldTypes

• Prevalue sources - formProviderPrevalueSources

• Recordset actions - formRecordSetActions

• Workflows - formProviderWorkflows

The language files are registered with:

Registering the Components

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