SharePoint MaskedEdit Field Control

A control that I used over and over in the good old days of VB6 was the masked edit control. I recently came across a jQuery plugin for a masked edit control and wanted to implement it as a custom SharePoint field. Download the code here

What you will need. 
jQuery
jQuery Masked Edit Plugin
WSPBuilder

This is masked edit field as seen when adding it to a list. I've defined a small number of masks, you can add more! This interface is built with the next two code blocks. The first code block is the user control that contains the HTML and the server controls. The second code block is the code behind for the user control. 

<%@ Control Language="C#" Inherits="MaskedEditField.jQueryMaskedEditFieldEditor, MaskedEditField, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ab6ae01ba130938e"    compilationMode="Always" %>
<%@ Register TagPrefix="wssuc" TagName="InputFormControl" src="~/_controltemplates/InputFormControl.ascx" %>
<%@ Register Tagprefix="SharePoint" Namespace="Microsoft.SharePoint.WebControls" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register Tagprefix="Utilities" Namespace="Microsoft.SharePoint.Utilities" Assembly="Microsoft.SharePoint, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Import Namespace="Microsoft.SharePoint" %>

<wssuc:InputFormControl runat="server" LabelText="Input Masks Explained">
    <Template_Control>
        <div>A mask is defined by a format made up of mask literals and mask definitions.
        Any character not in the definitions list below is considered a mask literal.
        Mask literals will be automatically entered for the user as they type and will
         not be able to be removed by the user.
        <ul>
            <li>a - Represents an alpha character (A-Z,a-z)</li>
            <li>9 - Represents a numeric character (0-9)</li>
            <li>* - Represents an alphanumeric character (A-Z,a-z,0-9)</li>
        </ul>  
        </div>
    </Template_Control>
</wssuc:InputFormControl>

<wssuc:InputFormControl runat="server" LabelText="Input Masks">
    <Template_Control>
        <table>
            <tr>
                <td><asp:RadioButton Text="Phone Number" GroupName="MaskedEdit" ID="rPhone" runat="server"></asp:RadioButton></td>
                <td><asp:TextBox Enabled="false" ID="txtPhone" runat="server">(999) 999-9999</asp:TextBox></td>
            </tr>
            <tr>
                <td><asp:RadioButton Text="SSN" GroupName="MaskedEdit" ID="rSSN" runat="server"></asp:RadioButton></td>
                <td><asp:TextBox Enabled="false" ID="txtSSN" runat="server">999-99-9999</asp:TextBox></td>
            </tr>
            <tr>
                <td><asp:RadioButton Text="Zip Code + 4" GroupName="MaskedEdit" ID="rZip4" runat="server"></asp:RadioButton></td>
                <td><asp:TextBox Enabled="false" ID="txtZip4" runat="server">99999-9999</asp:TextBox></td>
            </tr>
            <tr>
                <td><asp:RadioButton Text="Zip Code" GroupName="MaskedEdit" ID="rZip" runat="server"></asp:RadioButton></td>
                <td><asp:TextBox Enabled="false" ID="txtZip" runat="server">99999</asp:TextBox></td>
            </tr>
            <tr>
                <td><asp:RadioButton Text="Custom" GroupName="MaskedEdit" ID="rCustom" runat="server"></asp:RadioButton></td>
                <td><asp:TextBox Enabled="true" ID="txtCustom" runat="server"></asp:TextBox></td>
            </tr>
        </table>
    </Template_Control>
</wssuc:InputFormControl>

User Control Code Behind

using System;
using System.Collections.Generic;
using System.Text;
using System.Web.UI;
using System.Web.UI.WebControls;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;

namespace MaskedEditField
{
    public class jQueryMaskedEditFieldEditor : UserControl, IFieldEditor
    {
        // Fields
        protected RadioButton rPhone;
        protected RadioButton rSSN;
        protected RadioButton rZip;
        protected RadioButton rZip4;
        protected RadioButton rCustom;
        protected TextBox txtPhone;
        protected TextBox txtSSN;
        protected TextBox txtZip;
        protected TextBox txtZip4;
        protected TextBox txtCustom;
        private jQueryMaskedEdit fldjQueryMaskedEdit;

        public void InitializeWithField(SPField field)
        {
            this.fldjQueryMaskedEdit = field as jQueryMaskedEdit;

            if (this.Page.IsPostBack)
            {
                return;
            }

            //when modifying a field check the correct radio button
            if (field != null)
            {
                string prop = fldjQueryMaskedEdit.MyCustomProperty;

                if (prop.Equals(txtPhone.Text))
                { rPhone.Checked = true; }
                else
                if (prop.Equals(txtSSN.Text))
                { rSSN.Checked = true; }
                else
                if (prop.Equals(txtZip.Text))
                { rZip.Checked = true; }
                else
                if (prop.Equals(txtZip4.Text))
                { rZip4.Checked = true; }
                else
                {
                    rCustom.Checked = true;
                    txtCustom.Text = prop;
                }
            }
        }

        //save the value for the mask from the ascx to the field property
        //this is the value the plugin will use to format the masked input
        public void OnSaveChange(SPField field, bool bNewField)
        {
            jQueryMaskedEdit jme = (jQueryMaskedEdit)field;

            jme.IsNew = bNewField;

            if (rPhone.Checked)
            { jme.MyCustomProperty = txtPhone.Text; }
            else
            if (rSSN.Checked)
            { jme.MyCustomProperty = txtSSN.Text; }
            else
            if (rZip.Checked)
            { jme.MyCustomProperty = txtZip.Text; }
            else
            if (rZip4.Checked)
            { jme.MyCustomProperty = txtZip4.Text; }
            else
            { jme.MyCustomProperty = txtCustom.Text.Trim(); }
        }


        // Properties
        public bool DisplayAsNewSection
        {
            get
            {
                return false;
            }
        }
    }
}

This is the field class. Here I' inheriting form the SPFieldText since it most closely matches what we're trying to produce. This class provides the plumbing for the field. It saves the settings from the user control above, saves the values that users type in, validates the input, provides default display rendering. Luckily, most of this functionality is built into the SPFieldText class or provided by the Visual Studio project.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using System.Web.UI;
using System.Web.UI.WebControls;


namespace MaskedEditField
{
    public class jQueryMaskedEdit : SPFieldText
    {
        private static string[] CustomPropertyNames = new string[] { "MyCustomProperty" };

        public jQueryMaskedEdit(SPFieldCollection fields, string fieldName)
            : base(fields, fieldName)
        {
            InitProperties();
        }

        public jQueryMaskedEdit(SPFieldCollection fields, string typeName, string displayName)
            : base(fields, typeName, displayName)
        {
            InitProperties();
        }

        #region Property storage and bug workarounds - do not edit

        /// <summary>
        /// Indicates that the field is being created rather than edited. This is necessary to
        /// work around some bugs in field creation.
        /// </summary>
        public bool IsNew
        {
            get { return _IsNew; }
            set { _IsNew = value; }
        }
        private bool _IsNew = false;

        /// <summary>
        /// Backing fields for custom properties. Using a dictionary to make it easier to abstract
        /// details of working around SharePoint bugs.
        /// </summary>
        private Dictionary<string, string> CustomProperties = new Dictionary<string, string>();

        /// <summary>
        /// Static store to transfer custom properties between instances. This is needed to allow
        /// correct saving of custom properties when a field is created - the custom property
        /// implementation is not used by any out of box SharePoint features so is really buggy.
        /// </summary>
        private static Dictionary<string, string> CustomPropertiesForNewFields = new Dictionary<string, string>();

        /// <summary>
        /// Initialise backing fields from base property store
        /// </summary>
        private void InitProperties()
        {
            foreach (string propertyName in CustomPropertyNames)
            {
                CustomProperties[propertyName] = base.GetCustomProperty(propertyName) + "";
            }
        }

        /// <summary>
        /// Take properties from either the backing fields or the static store and
        /// put them in the base property store
        /// </summary>
        private void SaveProperties()
        {
            foreach (string propertyName in CustomPropertyNames)
            {
                base.SetCustomProperty(propertyName, GetCustomProperty(propertyName));
            }
        }

        /// <summary>
        /// Get an identifier for the field being added/edited that will be unique even if
        /// another user is editing a property of the same name.
        /// </summary>
        /// <param name="propertyName"></param>
        /// <returns></returns>
        private string GetCacheKey(string propertyName)
        {
            return SPContext.Current.GetHashCode() + "_" + (ParentList == null ? "SITE" : ParentList.ID.ToString()) + "_" + propertyName;
        }

        /// <summary>
        /// Replace the buggy base implementation of SetCustomProperty
        /// </summary>
        /// <param name="propertyName"></param>
        /// <param name="propertyValue"></param>
        new public void SetCustomProperty(string propertyName, object propertyValue)
        {
            if (IsNew)
            {
                // field is being added - need to put property in cache
                CustomPropertiesForNewFields[GetCacheKey(propertyName)] = propertyValue + "";
            }

            CustomProperties[propertyName] = propertyValue + "";
        }

        /// <summary>
        /// Replace the buggy base implementation of GetCustomProperty
        /// </summary>
        /// <param name="propertyName"></param>
        /// <param name="propertyValue"></param>
        new public object GetCustomProperty(string propertyName)
        {
            if (!IsNew && CustomPropertiesForNewFields.ContainsKey(GetCacheKey(propertyName)))
            {
                string s = CustomPropertiesForNewFields[GetCacheKey(propertyName)];
                CustomPropertiesForNewFields.Remove(GetCacheKey(propertyName));
                CustomProperties[propertyName] = s;
                return s;
            }
            else
            {
                return CustomProperties[propertyName];
            }
        }

        /// <summary>
        /// Called when a field is created. Without this, update is not called and custom properties
        /// are not saved.
        /// </summary>
        /// <param name="op"></param>
        public override void OnAdded(SPAddFieldOptions op)
        {
            base.OnAdded(op);
            Update();
        }

        #endregion


        public override BaseFieldControl FieldRenderingControl
        {
            get
            {
                BaseFieldControl fieldControl = new jQueryMaskedEditControl(this);
                fieldControl.FieldName = InternalName;
                return fieldControl;
            }
        }


        public override void Update()
        {
            SaveProperties();
            base.Update();
        }


        public override string GetValidatedString(object value)
        {
            if ((this.Required == true) && (value == null))
            { throw new SPFieldValidationException("This is a required field."); }

            return base.GetValidatedString(value);
        }


        public override object GetFieldValue(string value)
        {
            if (String.IsNullOrEmpty(value))
                return null;

            return value;
        }

        public string MyCustomProperty
        {
            get { return this.GetCustomProperty("MyCustomProperty") + ""; }
            set { this.SetCustomProperty("MyCustomProperty", value); }
        }
    }

}

This is the class that renders the control users interact with in the new and edit forms. It closely resembles a webpart. Here is where the JavaScript is written to the page.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using System.Web.UI;
using System.Web.UI.HtmlControls;
using System.Web.UI.WebControls;


namespace MaskedEditField
{
    public class jQueryMaskedEditControl : BaseFieldControl
    {
        private jQueryMaskedEdit field;
        private TextBox txtBox;
        private string txtVal;
      
        // Used for the linked script file
        private const string MaskedInputJS = "jquery.maskedinput-1.2.2.min.js";
        private const string MaskedInputScriptKey = "jQueryMaskedInputKey";
        private const string IncludeScriptFormat =
        @"<script type=""{0}"" src=""{1}""></script>";
      

        public jQueryMaskedEditControl(jQueryMaskedEdit parentField)
        {
            this.field = parentField;
            this.txtBox = new TextBox();
        }

        //get/set value for custom field
        public override object Value
        {
            get
            {
                return txtBox.Text;
            }
            set
            {
                txtBox.Text = string.Empty;
                string txtVal = value as String;
                if (txtVal != null)
                {
                    txtBox.Text = txtVal;
                }
            }
        }


        protected override void CreateChildControls()
        {
            if (this.Field == null
                || this.ControlMode == SPControlMode.Display
                || this.ControlMode == SPControlMode.Invalid)
                return;
          
            base.CreateChildControls();

            txtBox = new TextBox();
            this.Controls.Add(txtBox);
        }

        //Update field value with user input & check field validation
        public override void UpdateFieldValueInItem()
        {
            this.EnsureChildControls();
            try
            {
                this.Value = this.txtBox.Text;
                this.ItemFieldValue = this.Value;
            }

            catch (Exception ex)
            {
                this.IsValid = false;
                this.ErrorMessage = "* " + ex.Message;
            }
        }


        protected override void OnPreRender(EventArgs e)
        {
            base.OnPreRender(e);

            if (this.ControlMode == SPControlMode.Edit ||
                this.ControlMode == SPControlMode.New)
            { RegisterCommonScript(); }
        }


        //Function which will register the linked file script and the embedded script
        protected void RegisterCommonScript()
        {
            string location = null;
         
            //include the mask plugin on the page
            if (!Page.ClientScript.IsClientScriptBlockRegistered(MaskedInputScriptKey))
            {
                location = @"/_layouts/";
                string includeScript =
                String.Format(IncludeScriptFormat, "text/javascript", location + MaskedInputJS);
                Page.ClientScript.RegisterClientScriptBlock(typeof(jQueryMaskedEditControl), MaskedInputScriptKey, includeScript);
            }

            if (!Page.ClientScript.IsClientScriptBlockRegistered(txtBox.ClientID))
            {
                //this is where the mask plugin is hooked into our field, its all happening on the clients machine
                string function =
                     "<script type=\"text/javascript\">jQuery(function($){$(\"input[id*=" + txtBox.ClientID +
                     "]\").mask(\"" + field.MyCustomProperty + "\"); });</script>";
                Page.ClientScript.RegisterClientScriptBlock(typeof(jQueryMaskedEditControl), txtBox.ClientID, function);
            }
        }

    }
}

XML used to define the field.

<?xml version="1.0" encoding="utf-8" ?>
<FieldTypes>
  <FieldType>
    <Field Name="TypeName">jQueryMaskedEdit</Field>
    <Field Name="ParentType">Text</Field>
    <Field Name="TypeDisplayName">jQueryMaskedEdit</Field>
    <Field Name="TypeShortDescription">jQuery Masked Edit</Field>
    <Field Name="UserCreatable">TRUE</Field>
    <Field Name="Sortable">TRUE</Field>
    <Field Name="AllowBaseTypeRendering">TRUE</Field>
    <Field Name="Filterable">TRUE</Field>
    <Field Name="FieldTypeClass">MaskedEditField.jQueryMaskedEdit, MaskedEditField, Version=1.0.0.0, Culture=neutral, PublicKeyToken=ab6ae01ba130938e</Field>
    <Field Name="FieldEditorUserControl">/_controltemplates/jQueryMaskedEditFieldEditor.ascx</Field>
    <PropertySchema>
      <Fields>
        <Field Hidden="TRUE" Name="MyCustomProperty"
        DisplayName="My Custom Property"
        Type="Text">
        </Field>
      </Fields>
      <Fields></Fields>
    </PropertySchema>
    <RenderPattern Name="DisplayPattern">
        <Column />
    </RenderPattern>
  </FieldType>
</FieldTypes>

Display View

Edit View