Creating Custom HTML Helpers Using the TagBuilder Class

Using the TagBuilder Class

The TagBuilder class is a utility class included in the ASP.NET MVC framework that you can use when building HTML helpers.

Here’s a list of the methods of the TagBuilder class:

• AddCssClass()—Enables you to add a new class=”” attribute to a tag.
• GenerateId()—Enables you to add an id attribute to a tag. This method automatically replaces periods in the id. (By default, periods are replaced by underscores.)
• MergeAttribute()—Enables you to add attributes to a tag. There are multiple overloads of this method.
• SetInnerText()—Enables you to set the inner text of the tag. The inner text is HTML-encoded automatically.
• ToString()—Enables you to render the tag. You can specify whether you want to create a normal tag, a start tag, an end tag, or a self-closing tag.

The TagBuilder class has four important properties:

• Attributes—Represents all the attributes of the tag.
• IdAttributeDotReplacement—Represents the character used by the GenerateId() method to replace periods. (The default is an underscore.)
• InnerHTML—Represents the inner contents of the tag. Assigning a string to this property does not HTML-encode the string.
• TagName—Represents the name of the tag.

You don’t actually need to use the TagBuilder class. You could use a StringBuilder class instead. However, the TagBuilder class makes your life a little easier.

The helper in Listing below, the Html.ImageLink() helper, is created with a TagBuilder. The Html.ImageLink() helper renders an image link.

using System.Web.Mvc;

using System.Web.Routing;

namespace Helpers

{

    public static class ImageLinkHelper

    {

        public static string ImageLink(this HtmlHelper helper, string actionName,

        string imageUrl, string alternateText)

        {

            return ImageLink(helper, actionName, imageUrl, alternateText, null,

            null, null);

        }

        public static string ImageLink(this HtmlHelper helper, string actionName,

        string imageUrl, string alternateText, object routeValues)

        {

            return ImageLink(helper, actionName, imageUrl, alternateText,

            routeValues, null, null);

        }

        public static string ImageLink(this HtmlHelper helper, string actionName,

        string imageUrl, string alternateText, object routeValues, object

        linkHtmlAttributes, object imageHtmlAttributes)

        {

            var urlHelper = new UrlHelper(helper.ViewContext.RequestContext);

            var url = urlHelper.Action(actionName, routeValues);

            // Create link

            var linkTagBuilder = new TagBuilder("a");

            linkTagBuilder.MergeAttribute("href", url);

            linkTagBuilder.MergeAttributes(new RouteValueDictionary

            (linkHtmlAttributes));

            // Create image

            var imageTagBuilder = new TagBuilder("img");

            imageTagBuilder.MergeAttribute("src", urlHelper.Content(imageUrl));

            imageTagBuilder.MergeAttribute("alt", urlHelper.Encode(alternateText));

            imageTagBuilder.MergeAttributes(new RouteValueDictionary

            (imageHtmlAttributes));

            // Add image to link

            linkTagBuilder.InnerHtml = imageTagBuilder.ToString

            (TagRenderMode.SelfClosing);

            return linkTagBuilder.ToString();

        }

    }

}

The Html.ImageLink() helper in Listing above has three overloads. The helper accepts the following parameters:

• actionName—The controller action to invoke
• imageUrl—The URL of the image to display
• alternateText—The alt text to display for the image
• routeValues—The set of route values to pass to the controller action
• linkHtmlAttributes—The set of HTML attributes to apply to the link
• imageHtmlAttribute—The set of HTML attributes to apply to the image

For example, you can render a delete link by calling the Html.ImageLink() helper like this:

<%= Html.ImageLink("Delete", "~/Content/Delete.png", "Delete Account", new {AccountId=2}, null, new {border=0}) %>

Don’t forget to import namespace

<%@ Import Namespace="Helpers" %>

Two instances of the TagBuilder class are used in Listing. The first TagBuilder builds up the <a> link tag. The second TagBuilder builds up the <img> image tag.

Notice that an instance of the UrlHelper class is created. Two methods of this class are called. First, the UrlHelper.Action() method generates the link to the controller action.

Second, the UrlHelper.Content() method converts an application relative path into a full relative path. For example, if your application is named MyApplication, the UrlHelper.Content() method would convert the application relative path ”~/Content/Delete.png” into the relative path ”/MyApplication/Content/Delete.png”.