Tuesday, September 25, 2012

Custom field type for the Sitecore Web Forms for Marketers Module

In my humble opinion, the Web Forms for Marketers module does an awesome job of making not-so-trivial processes like collecting and reporting on data, or tagging and emailing users rather trivial. If you've ever had to make a form with 100+ input fields (and their respective labels and validation expressions), I'm sure you would appreciate it, too.

So while I'm on the custom field type theme, I'll share my experience with customizing a field 'help' text to be clickable and open a popup. This was inspired by the "What's this?" links next to CVV input fields in payment forms where a tidy popup shows you a picture of a credit card with a circled verification code.

As with any custom field, the first step is to decide which of the already existing fields you want to extend. For this example, I took the SingleLineText field and created a SingleLinePopupField. You would need to add references to Sitecore.Forms.Core.dll and Sitecore.Forms.Custom.dll to the project.

[Designer("System.Windows.Forms.Design.ParentControlDesigner, System.Design", typeof(IDesigner))]
    public class SingleLinePopupField : SingleLineText
    {
        public SingleLinePopupField()
            : this(HtmlTextWriterTag.Div)
        {
        }
        public SingleLinePopupField(HtmlTextWriterTag tag)
            : base(tag)
        {
        }
        protected override void DoRender(HtmlTextWriter writer)
        {
            base.DoRender(writer);
        }
    }

Create a new field item under /sitecore/system/Modules/Web Forms for Marketers/Settings/Field Types/Custom/ and fill out the Assembly and Class fields. Once this is set up, you should be able to easily create a new form and add a field of your custom type.


In order to have custom properties appear in the Form Designer when you select a form field, you would need to add custom properties to the new field class. For my specific requirements, I added a link type (media library image, video, or external link that will open in a new window), link text, and the actual link.

        [VisualCategory("Custom Properties")]
        [VisualFieldType(typeof(LabelTypeField)), VisualProperty("Popup Link Type", 99), DefaultValue("{9975237B-B750-4A17-86C7-48D5E6D58587}")]
        public string LabelLinkType { get; set; }

        [VisualCategory("Custom Properties")]
        [VisualFieldType(typeof(TextAreaField)), VisualProperty("Popup Link Text", 99), DefaultValue("What's this?")]
        public string LabelLinkText { get; set; }

        [VisualCategory("Custom Properties")]
        [VisualFieldType(typeof(TextAreaField)), VisualProperty("Popup Link", 99), DefaultValue("")]
        public string LabelLink { get; set; }

The VisualCategory attribute will group the custom fields in the Form Designer. VisualProperty defines the field label and sort order, and DefaultValue defines..how many cucumbers are sold obviously.

I used a custom VisualFieldType to create a drop down of link types. I added the custom link types in a new enumeration under /sitecore/system/Modules/Web Forms for Marketers/Settings/Meta data similar to other WFFM enumerations. The custom field type should inherit from WebControl and implement IVisualFieldType


 public class LabelTypeField : WebControl, IVisualFieldType
    {
        public LabelTypeField(): base(HtmlTextWriterTag.Select.ToString()) { }

        public string DefaultValue { get; set; }

        public string EmptyValue { get; set; }

        public bool IsCacheable
        {
            get { return true; }
        }

        public bool Localize { get; set; }

        public ValidationType Validation { get; set; }

        protected virtual void OnPreRender(object sender, EventArgs ev)
        {
            this.Controls.Clear();
            base.OnPreRender(ev);
            //Configuration.LabelLinkTypesRoot is the ID of the enumeration folder item
            foreach (Item type in StaticSettings.ContextDatabase.GetItem(Configuration.LabelLinkTypesRoot).Children)
            {
                string str = type.ID.ToShortID().ToString();
                Literal literal2 = new Literal();
                literal2.Text = string.Format("<option {0} regex='{4}' value='{1}' title='{2}'>{3}</option>", new object[] { (DefaultValue == type.ID.ToString()) ? "selected='selected'" : string.Empty, str, type.DisplayName, type.DisplayName, HttpContext.Current.Server.UrlEncode(type.Fields[FieldIDs.MetaDataListItemValue].Value) });
                Literal child = literal2;
                this.Controls.Add(child);
            }
            base.Attributes["onblur"] = string.Format("Sitecore.PropertiesBuilder.onSavePredefinedValidatorValue('{0}', '{1}')", StaticSettings.prefixId + (Localize ? StaticSettings.prefixLocalizeId : string.Empty), this.ID);
            base.Attributes["onchange"] = base.Attributes["onblur"];
            base.Attributes["onkeyup"] = base.Attributes["onblur"];
            base.Attributes["onpaste"] = base.Attributes["onblur"];
            base.Attributes["oncut"] = base.Attributes["onblur"];
            base.Attributes["class"] = "scFbPeValueProperty";
            base.Attributes["value"] = DefaultValue;
        }

        public string Render()
        {
            this.OnPreRender(this, null);
            StringWriter writer = new StringWriter();
            HtmlTextWriter writer2 = new HtmlTextWriter(writer);
            this.RenderControl(writer2);
            return writer2.InnerWriter.ToString();
        }
    }

Now that all properties are set up, the Form Designer should look something like this:


All that's left is to render the proper html for the custom field to achieve the popup effect. You could actually use any modal popup or video player you wish. I find the ColorBox plugin very lightweight and easy to implement, so it's one of my favorites. The markup it requires is minimal as long as it's integrated and initialized properly. For my example, I included the necessary resource files onto the same layout where the WFFM form placeholder sits, and I defined css classes to initialize the popup for the different types of links. Thus, in the custom field type I would need to override the DoRender() method to render a link with the respective class and attach it to the base 'help' field value:

protected override void DoRender(HtmlTextWriter writer)
{
   if (!string.IsNullOrEmpty(this.LabelLinkText))
   {
       string help = string.Empty;

       if (this.LabelType == LabelLinkTypes.ImagePopup)
       {
           help = string.Format("{0} <a class=\"popup\" href=\"{1}\"><span style=\"font-size:11px; color:gray;\" >{2}</span></a>", this.Information, this.LabelLinkUrl, this.LabelLinkText);
       }
       else if (this.LabelType == LabelLinkTypes.VideoPopup)
       {
           help = string.Format("{0} <a class=\"iframe\" href=\"{1}\"><span style=\"font-size:11px; color:gray;\" >{2}</span></a>", this.Information, this.LabelLinkUrl, this.LabelLinkText);
       }
       else if (this.LabelType == LabelLinkTypes.NewPage)
       { 
           help = string.Format("{0} <a href=\"{1}\" target=\"_blank\"><span style=\"font-size:11px; color:gray;\" >{2}</span></a>", this.Information, this.LabelLink, this.LabelLinkText);
       }
       this.Information = help;
   }

base.DoRender(writer);
}

//Sitecore.Data.ID of the chosen drop down type item
public ID LabelType
{
   get
   {
      return new ID(LabelLinkType);
   }
}

//It might be easier for an editor to input the path to a media item instead of its url, so we'll try for that
public string LabelLinkUrl
{
   get
   {
       string url = string.Empty;

       if (this.LabelType == LabelLinkTypes.ImagePopup)
       {
          //media item
          Item item = StaticSettings.ContextDatabase.GetItem(LabelLink);
          if (item != null)
          {
             MediaItem mi = (MediaItem)item;
             url = MediaManager.GetMediaUrl(mi);
          }
       }
       else
       {
           url = LabelLink;
       }
       return url;
   }
}

And that was it! The links will now be appearing next to the 'help' message below the single-line text field.