TagHelper : Authoring TagHelpers in ASP.NET Core MVC

ASP.NET Core’s TagHelper feature provides a readable, HTML-like markup that enables developers and web designers to collaborate more closely and efficiently. In this series we’ll walk you through the basics of creating TagHelpers, from concepts to custom development.

TagHelper Basics

TagHelpers can be created by inheriting the TagHelper class, which resides in the Microsoft.AspNetCore.Razor.TagHelpers namespace. Inheriting from the TagHelper class allows us to override the Process method that controls the behaviour of the TagHelper.

Here’s a simple custom TagHelper:

  public class CustomElementTagHelper:TagHelper  
  {  
  public override void Process(TagHelperContext context, TagHelperOutput output)  
  {  
  base.Process(context, output);    
  }  
  }  

While including “TagHelper” in the name isn’t required, adding it is an accepted convention. The TagHelper logic automatically detects and adjusts the class name accordingly. In this case, the TagHelper name would be translated to custom-element.

In cases where the TagHelper name is different than the class name, the class should be decorated with HtmlTargetElement. The process method has two parameters.

• The context parameter contains information associated with the execution of current HTML tag and can be used to interact within nested TagHelpers for sharing context information.
• The output parameter contains a representation of the original source used to generate the HTML tag and content. The various properties of the output parameter—like PreContent, Content and PostContent—help in rendering the final HTML.

The TagHelper class also has a method that helps with asynchronous execution of TagHelper processing.

TagHelper Attributes

Attributes of a TagHelper are properties. In the example below, “PropertyName” is an attribute of the TagHelper “Custom,” and will be used as:

  public class CustomTagHelper:TagHelper  
  {  

  public string propertyname { get; set; }  
  public override void Process(TagHelperContext context, TagHelperOutput output)  
  {  
  base.Process(context, output);    
  }  
  }  

To add a property to the class whose attribute name is different than the property name, it should be decorated with HtmlAttributeName. In this example, the TagHelper is also decorated with HtmlTargetElement attribute since the name of TagHelper element is different than the class name:

  [HtmlTargetElement("tag-name")]  
  public class CustomTagHelper:TagHelper  
  {  
  [HtmlAttributeName("attribute-name")]  
  public string propertyname { get; set; }  
  public override void Process(TagHelperContext context, TagHelperOutput output)  
  {  
  base.Process(context, output);    
  }  
  }  

The above TagHelper would be declared as:

  <tag-name attribute-name="testValue" ></tag-name>  

Authoring a simple TagHelper

Now that we’ve learned the basics of creating a TagHelper, let’s look at some examples of TagHelpers targeting HTML attributes.

In this example, we create a TagHelper for an HTML attribute that, when applied to an HTML paragraph, converts the content to citation. A citation begins with and ends with tags in HTML; we wish to use the “citation” attribute in a paragraph to convert the content.

The logic of the process method would add a PreContent and PostContent to the rendered HTML wherever it finds the citation attribute:

  [HtmlTargetElement(Attributes ="citation")]  
  public class CitationTagHelper:TagHelper  
  {  
  public override void Process(TagHelperContext context, TagHelperOutput output)  
  {  
  output.Attributes.RemoveAll("citation");  
  output.PreContent.SetHtmlContent("");  
    output.PostContent.SetHtmlContent("");  
  }  
  }  

Usage

ASP.NET Core TagHelpers


GrapeCity Inc.

Generated HTML

Rendered MarkUp

The browser renders the TagHelper as normal HTML citation:

Rendered TagHelper

In the next blog of this series, we will take a look at creating nested TagHelpers. ComponentOne MVC Edition controls are compatible with ASP.NET Core and has TagHelpers for all its controls.

View our ASP.NET Core MVC ControlExplorer