Creating a Custom Widget Designer Using Sitefinity and Sitefinity Thunder Part 2

April 17, 2014 Digital Experience, Sitefinity

This post is the 2nd part of a 2 part blog post that focuses on how to create Designers using Sitefinity Thunder. Please refer to this blog post to see the first part...

Open up your custom Widget UI file that we created at the beginning of this post, make sure it’s NOT the Designer UI, and add the following controls to it:

<div>
    <p>
        <strong>Categories:</strong>
        <asp:Repeater ID="CategoriesRepeater" runat="server">
            <HeaderTemplate><ul></HeaderTemplate>
            <ItemTemplate>
                <li><%# Container.DataItem %></li>
            </ItemTemplate>
            <FooterTemplate></ul></FooterTemplate>
        </asp:Repeater>
    </p>
</div>
 
<div>
    <p>
        <strong>Tags:</strong>
        <asp:Repeater ID="TagsRepeater" runat="server">
            <HeaderTemplate><ul></HeaderTemplate>
            <ItemTemplate> 
                <li><%# Container.DataItem %></li>
            </ItemTemplate>
            <FooterTemplate></ul></FooterTemplate>
        </asp:Repeater>
    </p>
</div>

Add the following properties to your Widget’s code-behind file:

/// <summary>
/// guid array from designer for our selected tags
/// </summary>
public Guid[] selectedTags;
 
/// <summary>
/// Gets or sets the selected tags.
/// </summary>
public Guid[] SelectedTags
{
    get
    {
        if (selectedTags == null) selectedTags = new Guid[] { };
        return selectedTags;
    }
    set { selectedTags = value; }
}
 
/// <summary>
/// guid array from designer for our selected categories
/// </summary>
public Guid[] selectedCategories;
 
/// <summary>
/// Gets or sets the selected categories.
/// </summary>
/// <value>
/// The selected categories.
/// </value>
public Guid[] SelectedCategories
{
    get
    {
        if (selectedCategories == null) selectedCategories = new Guid[] { };
        return selectedCategories;
    }
    set { selectedCategories = value; }
}
 
/// <summary>
/// Intermediary property for passing Tags to and from the designer
/// </summary>
/// <value>
/// The tag value as a comma delimited string.
/// </value>
public string TagValue
{
    get { return string.Join(",", SelectedTags); }
    set
    {
        var list = new List<Guid>();
        if (value != null)
        {
            var guids = value.Split(',');
            foreach (var guid in guids)
            {
                Guid newGuid;
                if (Guid.TryParse(guid, out newGuid))
                    list.Add(newGuid);
            }
        }
        SelectedTags = list.ToArray();
    }
}
 
/// <summary>
/// Intermediary property for passing categories to and from the designer
/// </summary>
/// <value>
/// The category value as a comma-delimited string.
/// </value>
public string CategoryValue
{
    get { return string.Join(",", SelectedCategories); }
    set
    {
        var list = new List<Guid>();
        if (value != null)
        {
            var guids = value.Split(',');
            foreach (var guid in guids)
            {
                Guid newGuid;
                if (Guid.TryParse(guid, out newGuid))
                    list.Add(newGuid);
            }
        }
        SelectedCategories = list.ToArray();
    }
}

Add the following Control References to your Widget’s code-behind file:

/// <summary>
/// Reference to the Label control that shows the Message.
/// </summary>
protected virtual Repeater TagsRepeater
{
    get
    {
        return this.Container.GetControl<Repeater>("TagsRepeater", true);
    }
}
 
/// <summary>
/// Reference to the Label control that shows the Message.
/// </summary>
protected virtual Repeater CategoriesRepeater
{
    get
    {
        return this.Container.GetControl<Repeater>("CategoriesRepeater", true);
    }
}

Add the following method calls to your Widget’s code-behind InitializeControls method:

            BindTags();
            BindCategories();

Add the following two methods to your Widget’s code-behind:

/// <summary>
/// Binds the selected tags to your tags control
/// </summary>
private void BindTags()
{
    // retrieve selected tags
    var tags = new List<string>();
    foreach (var tagID in SelectedTags)
    {
        // get tag name
        var tag = taxMgr.GetTaxon(tagID);
        if (tag == null) continue;
        tags.Add(tag.Name);
    }
 
    // bind tag names
    TagsRepeater.DataSource = tags;
    TagsRepeater.DataBind();
}
 
/// <summary>
/// Binds the selected tags to your categories control
/// </summary>
private void BindCategories()
{
    // retrieve selected categories
    var tags = new List<string>();
    foreach (var tagID in SelectedCategories)
    {
        // get category name
        var tag = taxMgr.GetTaxon(tagID);
        if (tag == null) continue;
        tags.Add(tag.Name);
    }
 
    // bind category names
    CategoriesRepeater.DataSource = tags;
    CategoriesRepeater.DataBind();
}

 

Adding Categories and Tags to your Designer

This is the first time we will be touching the Designer code as Thunder took care of that for us previously. It’s a little different, because it has different responsibilities, and has an associated javascript file, but in the end it’s just a custom Widget.

Open your custom Designer’s UI file and add the following controls to it:

<%-- Tag section --%>
 <li>
     <sitefinity:FlatTaxonField
         ID="TagsSelector"
         runat="server"
         DisplayMode="Write"
         WebServiceUrl="~/Sitefinity/Services/Taxonomies/FlatTaxon.svc/cb0f3a19-a211-48a7-88ec-77495c0f5374"
         TaxonomyMetafieldName="Tags"
         AllowMultipleSelection="true"
         Expanded="false"
         Title="Tags" />
 </li>
 
 <li class="sfFormCtrl">
     <asp:HiddenField ID="TagValue" runat="server" />
 </li>
 
 <%-- Category section --%>
 <li>
     <label class="sfTxtLbl">Category:</label>
     <sitefinity:HierarchicalTaxonField
         ID="CategoriesSelector"
         runat="server"
         DisplayMode="Write"
         Expanded="false"
         ExpandText="ClickToAddCategories"
         ShowDoneSelectingButton="true"
         AllowMultipleSelection="true"
         BindOnServer="false"
         TaxonomyMetafieldName="Category"
         WebServiceUrl="~/Sitefinity/Services/Taxonomies/HierarchicalTaxon.svc" />
 </li>
  
 <li class="sfFormCtrl">
     <asp:HiddenField ID="CategoryValue" runat="server" />
 </li>

Make sure you have the following Using statements to your Designer’s code-behind file:

using System;
using System.Linq;
using System.Web.UI;
using Telerik.Sitefinity.Web.UI;
using Telerik.Sitefinity.Web.UI.ControlDesign;
using System.Collections.Generic;
using System.Web.UI.WebControls;
using System.Web;
using Telerik.Sitefinity.Modules.Pages;
using System.Web.UI.HtmlControls;
using Telerik.Sitefinity.Web.UI.Fields;
using Telerik.Sitefinity.Taxonomies;

Now add the following Control References to the Designer’s code-behind:

/// <summary>
 /// Gets the control that is bound to the TagValue property
 /// </summary>
 protected virtual Control TagValue
 {
     get
     {
         return this.Container.GetControl<Control>("TagValue", true);
     }
 }
 
 /// <summary>
 /// Gets the tag selector control
 /// </summary>
 protected FlatTaxonField TagsSelector
 {
     get { return Container.GetControl<FlatTaxonField>("TagsSelector", true); }
 }
 
 /// <summary>
 /// Gets the control that is bound to the CategoryValue property
 /// </summary>
 protected virtual Control CategoryValue
 {
     get
     {
         return this.Container.GetControl<Control>("CategoryValue", true);
     }
 }
 
 /// <summary>
 /// Gets the category selector control
 /// </summary>
 protected HierarchicalTaxonField CategoriesSelector
 {
     get { return Container.GetControl<HierarchicalTaxonField>("CategoriesSelector", true); }
 }

Now add two method calls to your Designer’s code-behind InitializeControls method:

// initialize the taxonomy selectors
CategoriesSelector.TaxonomyId = TaxonomyManager.CategoriesTaxonomyId;
TagsSelector.TaxonomyId = TaxonomyManager.TagsTaxonomyId;

Now add the following component and element property descriptors within the IScriptControl implementation Region:

descriptor.AddElementProperty("tagValue", this.TagValue.ClientID);
descriptor.AddComponentProperty("TagsSelector", this.TagsSelector.ClientID);
descriptor.AddElementProperty("categoryValue", this.CategoryValue.ClientID);
descriptor.AddComponentProperty("CategoriesSelector", this.CategoriesSelector.ClientID);

That’s it for the Designer UI and code-behind file. Now we’ll start editing the JavaScript file.

Add the following JavaScript variables:

this._TagsSelector = null;
this._tagValue = null;
this._CategoriesSelector = null;
this._categoryValue = null;

 

Add the following items to the bottom of the refreshUI function:

/* RefreshUI TagValue */
jQuery(this.get_tagValue()).val(controlData.TagValue);
 
/* RefreshUI CategoryValue */
jQuery(this.get_categoryValue()).val(controlData.CategoryValue);
 
// load tags
var t = this.get_TagsSelector();
var tags = controlData.TagValue;
if (tags != null)
    t.set_value(controlData.TagValue.split(","));
 
// load categories
var c = this.get_CategoriesSelector();
var cats = controlData.CategoryValue;
if (cats != null)
    c.set_value(controlData.CategoryValue.split(","));

Now add the following items to the bottom of the applyChanges function:

/* ApplyChanges SelectedPageID */
/* ApplyChanges TagValue */
controlData.TagValue = jQuery(this.get_tagValue()).val();
 
/* ApplyChanges CategoryValue */
controlData.CategoryValue = jQuery(this.get_categoryValue()).val();
 
// save selected tags
var t = this.get_TagsSelector();
var tags = t.get_value();
if (tags != null)
    controlData.TagValue = t.get_value().join();
 
// save selected categories
var c = this.get_CategoriesSelector();
var cats = c.get_value();
if (cats != null)
    controlData.CategoryValue = c.get_value().join();

Now add the following properties to the existing Properties section:

/* TagValue properties */
get_tagValue: function () { return this._tagValue; },
set_tagValue: function (value) { this._tagValue = value; },
 
/* CategoryValue properties */
get_categoryValue: function () { return this._categoryValue; },
set_categoryValue: function (value) { this._categoryValue = value; },
 
// Categories Selector
get_CategoriesSelector: function () { return this._CategoriesSelector; },
set_CategoriesSelector: function (value) { this._CategoriesSelector = value; },
 
// Tags Selector
get_TagsSelector: function () { return this._TagsSelector; },
set_TagsSelector: function (value) { this._TagsSelector = value; }

Compile your project one final time and use to your heart’s content!

 

Summary

Hopefully everyone found this a useful exercise and this sheds more insight into how Designers are made and what’s going on under the hood. Once you see the patterns at play here you will no doubt be able to apply your own custom controls and functionality to your Sitefinity Designers.

Though Designers aren’t necessary in all instances when creating custom widgets, they can be a very powerful tool for your business users, because, once setup, they allow the business user to customize their content display properties without the need of a developer. And as we all know a happy business user makes for a happy developer!

 

Sample Code

Please go to my Github Repository to download the sample project.

Custom controls designers widgets

David Cowart