Create a custom field type

Last updated Monday, December 12, 2016 in Web Forms for Marketers for Administrator, Developer

In the Web Forms for Marketers module, a field type determines how a field is rendered in a form. You can either use the default field types, or create your own custom field type.

As a rendering engine, the Web Forms for Marketers module supports the model-view-controller or MVC pattern (ASP.NET MVC) as well as the non-MVC pattern (ASP.NET Web Forms).

For MVC, you can create a custom field type based on Sitecore MVC, which renders pages using the ASP.NET MVC framework. For non-MVC fields, you can create a custom field type based on either the UserControl or Webcontrol class.

This procedure outlines how to:

Create a custom MVC field type

You can create a custom MVC field type by extending the FieldViewModel class or by extending an existing field type class and then customizing it by overriding methods and properties.

To create a custom MVC field type:

  1. In Visual Studio, create an MVC project, enter a name and add a new reference to the Sitecore.Wffm.MVC assembly.
  2. Add a new class and define properties and methods for the class.

    For example, for the CurrencyField class:

    Walkthrough Configuring the web forms for marketers module to work with MVC

  3. In Visual Studio, create the .cshtml file, and copy it to the \Website\Views\Form\EditorTemplates folder.

    For example, when the CurrencyField.cshtml file is rendered:

    Walkthrough Configuring the web forms for marketers module to work with MVC

    Note

    You must render the hidden input for the FieldId property. This is required for client analytics events-tracking logic.

  4. Copy the compiled file to the \Website\bin folder of your website.
  5. In the Content Editor, navigate to the Custom folder (sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Custom), and in the right pane, create a definition item for your custom field type.
  6. In the Message dialog box, enter a name for the new item, and then click OK.
  7. In the right pane, in the Data section, in the MVC Type field, enter the full name and assembly of the relevant class.

    For example, for the CurrencyField class: Sitecore.Custom.Forms.Mvc.FieldTypes.CurrencyField,Sitecore.Custom.Forms

    Picture 1

    Note

    If you want to localize the BalanceTitle property of the CurrencyField class, in the Data section, in the Localized Parameters field, enter the following text:

    <BalanceTitle>Your Current Balance</BalanceTitle>

  8. Click Save.

    Your newly created custom field type is available in the Form Designer.

Create a custom non-MVC field type based on the UserControl class

Every non-MVC user control is located in a single .ascx file that contains markup for the user control. The user control can also have a class inherited from the UserControl class.

To create a custom field type based on the UserControl class, for example, a DatePicker field type:

  1. In Visual Studio, create a new project, enter a name, and add a new reference to the Sitecore.Forms.Core assembly.
  2. Add a new class that inherits from the Sitecore.Form.Web.UI.Controls.ValidateUserControl class. To give the new field a title, inherit your class from the IHasTitle interface.

    For example:

    namespace Sitecore.WFFM.Samples.Fields
    {
      using System.Web.UI;
      using System.Web.UI.WebControls;
      using Sitecore.Form.Web.UI.Controls;
      using Sitecore.WFFM.Abstractions.Actions;
    public class DatePickerUserControl : ValidateUserControl, IHasTitle
      {
        /// Here we define the controls that make the structure of the field 
        /// <summary>
        /// The control container
        /// </summary>
        private readonly Panel container = new Panel();
        /// <summary>
        ///  The input for the control
        /// </summary>
        private readonly TextBox input = new TextBox();
        /// <summary>
        ///  The title of the control
        /// </summary>
        private readonly Label title = new Label();
        public DatePickerUserControl()
        {
          this.CssClass = "scfDatePicker";
        }
        /// Implementation of the ihastitle interface to get the title that is entered in the Form Designer
        /// <summary>
        /// Gets or sets the title.
        /// </summary>
        /// <value>
        /// The title.
        /// </value>
        public string Title
        {
          get
          {
            return this.title.Text;
          }
          set
          {
            this.title.Text = value;
          }
        }
        /// The result of the control that will be used in the save actions and verification actions later
        /// <summary>
        /// Gets the result of clients' inputs.
        /// </summary>
        /// <value></value>
        public override ControlResult Result
        {
          get
          {
            return new ControlResult(this.ControlName, this.input.Text, null);
          }
          set
          {
          }
        }
        protected override Control ValidatorContainer
        {
          get
          {
            return this;
          }
        }
        protected override Control InnerValidatorContainer
        {
          get { return this.container; }
        }
      }
    }
  3. In Visual Studio, create the user control file and enter a name, for example, DatePickerUserControl.ascx, and copy the file to the UserControl folder (Website\sitecore modules\Web\Web Forms for Marketers\UI\UserControl).
  4. In a text editor, add the relevant markup to the .ascx user control file that you created in step 3.

    For example, for the DatePickerUserControl implementation:

    <%@ Control Language="C#" AutoEventWireup="true" Inherits="Sitecore.WFFM.Samples.Fields.DatePickerUserControl" %>
    <div>
      <asp:Panel ID="datePickerBorder" CssClass="scfDatePickerBorder" runat="server">
        <asp:Label ID="title" AssociatedControlID="password" runat="server" CssClass="scfDatePickerLabel" Text="Date picker" />
        <asp:Panel ID="container" CssClass="scfDatePickerGeneralPanel" runat="server">
          <asp:TextBox MaxLength="256" AutoCompleteType="Disabled" CssClass="scfDatePickerTextBox" ID="input" runat="server">            
          </asp:TextBox>
        </asp:Panel>
      </asp:Panel>
    </div>
  5. Copy the compiled file to the \Website\bin\ folder.
  6. In the Content Editor, navigate to the Custom folder (sitecore/System/Modules/Web Forms for Marketers/Settings/Field Types/Custom), and in the right pane, create a definition item for your custom field type.
  7. In the Message dialog box, enter a name for the custom item, and then click OK.
  8. In the right pane, in the Code section, in the User Control field, enter the path to the.ascx file that you created in step 3.

    For example: \Website\sitecore modules\Web\Web Forms for Marketers\UI\UserControl\DatePickerUserControl.ascx

  9. Click Save.

    The custom field type is available in the Form Designer.

Create a custom non-MVC field type based on the WebControl class

In addition to the UserControl class, you can create a custom field type based on the WebControl class.

To create a custom field type based on the WebControl class, for example, a DatePicker field type:

  1. In Visual Studio, create a new project, enter a name, and add a new reference to the Sitecore.Forms.Core assembly.
  2. Add a new class that inherits from the Sitecore.Form.Web.UI.Controls.ValidateControl class.

    For example, for the DatePicker implementation:

    namespace Sitecore.WFFM.Samples.Fields
    {
      using System;
      using System.Web.UI;
      using System.Web.UI.WebControls;
      using Sitecore.Form.Core.Attributes;
      using Sitecore.Form.Core.Visual;
      using Sitecore.Form.Web.UI.Controls;
      using Sitecore.WFFM.Abstractions.Actions;
      public class DatePicker : ValidateControl, IHasTitle
      {
        /// Here we define the controls that make the structure of the field 
        /// <summary>
        /// The control container
        /// </summary>
        private readonly Panel container = new Panel();
        /// <summary>
        ///  The help notes of the control
        /// </summary>
        private readonly Label helpNotes = new Label();
        /// <summary>
        ///  The input for the control
        /// </summary>
        private readonly TextBox input = new TextBox();
        /// <summary>
        ///  The title of the control
        /// </summary>
        private readonly Label title = new Label();
        public DatePicker()
          : base(HtmlTextWriterTag.Div)
        {
          this.CssClass = "scfDatePickerBorder";
        }
        /// Implementation of the ihastitle interface to get the title that is entered in the Form Designer
        /// <summary>
        /// Gets or sets the title.
        /// </summary>
        /// <value>
        /// The title.
        /// </value>
        public string Title
        {
          get
          {
            return this.title.Text;
          }
          set
          {
            this.title.Text = value;
          }
        }
        /// Implementation of the property that is set in the Form Designer 
        /// <summary>
        /// Gets or sets the help notes.
        /// </summary>
        /// <value>
        /// The help notes.
        /// </value>
        [VisualProperty("Help:", 500), VisualCategory("Appearance"), VisualFieldType(typeof(TextAreaField)), Localize]
        public string HelpNotes
        {
          get
          {
            return this.helpNotes.Text;
          }
          set
          {
            this.helpNotes.Text = value ?? string.Empty;
          }
        }
        /// The result of the control that will be used in the save actions and verification actions later
        /// <summary>
        /// Gets the result of clients' inputs.
        /// </summary>
        /// <value></value>
        public override ControlResult Result
        {
          get
          {
            return new ControlResult(this.ControlName, this.input.Text, null);
          }
          set
          {
          }
        }
        protected override Control ValidatorContainer
        {
          get
          {
            return this;
          }
        }
        protected override Control InnerValidatorContainer
        {
          get { return this.container; }
        }
        /// Creating the structure of the field
        /// <summary>
        /// Builds the control structure
        /// </summary>
        /// <param name="e">An <see cref="T:System.EventArgs"/> object that contains the event data.</param>
        protected override void OnInit(EventArgs e)
        {
          this.input.CssClass = "scfDatePickerTextBox";
          this.helpNotes.CssClass = "scfDatePickerUsefulInfo";
          this.container.CssClass = "scfDatePickerGeneralPanel";
          this.title.CssClass = "scfDatePickerLabel";
          this.input.TextMode = TextBoxMode.SingleLine;
          this.Controls.AddAt(0, this.container);
          this.Controls.AddAt(0, this.title);
          this.container.Controls.AddAt(0, this.helpNotes);
          this.container.Controls.AddAt(0, this.input);
        }
        /// <summary>
        /// Attaches jscripts to the page 
        /// </summary>
        /// <param name="e">The e.</param>
        protected override void OnPreRender(EventArgs e)
        {
          string script = "$(document).ready(function() { $('#" + this.input.ClientID + "').datepicker()";
          this.Page.ClientScript.RegisterClientScriptInclude("jquery", "/sitecore modules/web/web forms for marketers/scripts/jquery.js");
          this.Page.ClientScript.RegisterClientScriptInclude("jquery.ui", "/sitecore modules/web/web forms for marketers/scripts/jquery-ui.min.js");
          this.Page.ClientScript.RegisterStartupScript(this.GetType(), script, script, true);
          base.OnPreRender(e);
        }
      }
    }
  3. Copy the compiled file to the \Website\bin\ folder of your website.
  4. In the Content Editor, navigate to the Custom folder (sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Custom), and in the right pane, create a definition item for your custom field type.
  5. In the Message dialog box, enter a name for the new item, and then click OK.
  6. In the right pane, in the Data section, in the Assembly field, enter the name of the compiled .dll file from step 3.

    For example: Sitecore.Forms.Custom.dll.

  7. In the Class field, enter the name of the new class that you created in step 2.

    For example: Sitecore.WFFM.Samples.Fields.DatePicker.

  8. Click Save.

    The new field type is available in the Form Designer.

Send feedback about the documentation to docsite@sitecore.net.