ساخت TAG Helper سفارشی در ASP.NET CORE

ساخت TAG Helper سفارشی در ASP.NET Core به ما این امکان را می‌دهد که کدهای HTML خود را ساختارمندتر، خواناتر و قابل استفاده مجدد کنید. این امر به بهبود نگهداری و توسعه پروژه‌های بزرگ کمک شایانی می‌کند و قابلیت‌های سفارشی‌سازی زیادی را در اختیار ما قرار می‌دهد. در این آموزش که از سری آموزش های Asp.Net Core میباشد، به نحوه ساخت Custom Tag Helper میپردازیم.

چرا به ساخت TAG Helper سفارشی نیاز داریم ؟

ساخت Tag Helper سفارشی در ASP.NET Core چندین مزیت و کاربرد دارد که باعث می‌شود توسعه‌دهندگان به ایجاد آنها نیاز پیدا کنند. در زیر به برخی از این دلایل و مزایا اشاره شده است:

• افزایش قابلیت استفاده مجدد (Reusability) : با استفاده از Tag Helpers می‌توانید کامپوننت‌های HTML تکراری را به صورت یکپارچه و قابل استفاده مجدد تعریف کنید. این کار کدهای view شما را تمیزتر و قابل نگهداری‌تر می‌کند. به جای نوشتن کدهای تکراری در هر view، می‌توانید یک Tag Helper تعریف کرده و آن را در جاهای مختلف استفاده کنید.

• بهبود خوانایی کد : Tag Helperها به کد HTML شما خوانایی بیشتری می‌بخشند. استفاده از نام‌های توصیفی برای Tag Helperها به جای کدهای HTML پیچیده، فهم و نگهداری کد را برای تیم‌های توسعه‌دهنده آسان‌تر می‌کند.

• جداسازی لاجیک نمایش از لاجیک بیزینس : با استفاده از Tag Helperها می‌توانید لاجیک نمایش را از لاجیک بیزینس جدا کنید. این کار باعث می‌شود که کد شما ساختارمندتر و منظم‌تر باشد و به راحتی بتوانید تغییرات در هر بخش را بدون تأثیر بر بخش دیگر اعمال کنید.

• قابلیت سفارشی‌سازی : Tag Helperها به شما این امکان را می‌دهند که کامپوننت‌های HTML را براساس نیازهای خاص پروژه خود سفارشی‌سازی کنید. می‌توانید ویژگی‌ها و تنظیمات دلخواه خود را به Tag Helperها اضافه کنید و آن‌ها را مطابق با نیازهای پروژه تنظیم کنید.

• پشتیبانی از اعتبارسنجی – Validation و منطق سمت سرور : Tag Helperها می‌توانند به راحتی با منطق سمت سرور ترکیب شوند. به عنوان مثال، می‌توانید از Tag Helperها برای اعتبارسنجی داده‌ها و اعمال منطق خاصی در هنگام رندر شدن استفاده کنید.

نحوه ساخت TAG Helper

برای ساخت یک TagHelpers سفارشی ۴ مرحله زیر را انجام دهید

• ساخت پوشه TagHelpers : در روت پروژه خد یک پوشه با نام TagHelpers ایجاد کنید. مانند تصویر زیر.

ساخت پوشه TagHelpers

• ایجاد کلاس Tag Helper : یک کلاس جدید در پوشه TagHelpers خود ایجاد کنید. در نام گذاری کلاس خود توجه داشته باشید. باید حتما با TagHelper تمام شود. مانند کنترلر ها که باید با Controller تمام میشد. و مقداری که قبل از TagHelper قرار میگیرد میشود نام تگ هلپر سفارشی شما. مثلا اگر نام کلاس خود را EmailTagHelper قرار دهید نام تگ هلپر سفارشی شما میشود <Email></Email>.

ایجاد کلاس Tag Helper

• ارث بری – Extend کلاس ساخته شده از TagHelper : به صورت زیر عمل کنید.

using Microsoft.AspNetCore.Razor.TagHelpers;
namespace CustomTagHelper.TagHelpers
{
    public class EmailTagHelper:TagHelper
    {
    }
}

• ثبت Tag Helper : برای استفاده از تگ هلپر سفارشی حتما باید آن را ثبت کنید.

اگر از layout page استفاده میکنید باید به فایل ViewImports.cshtml موجود در فولدر Views بروید و آن را ثبت کنید.

@addTagHelper *, نام پروژه

در صورتی که از layout page استفاده نمیکنید. کد زیر را به بالای View خود اضافه کنید

@addTagHelper *, نام پروژه

نحوه ساخت کلاس TAG Helper

• پراپرتی های مورد نیاز : ابتدا پراپرتی های مورد نیاز در تگ هلپر خود را ایجاد کنید. فرض کنید ما میخواهیم یک لینک ایمیل ایجاد کنیم. برای ایجاد لینک ایمیل ما به ۳ ورودی نیاز داریم. ورودی اول مقدار خود ایمیل، ورودی دوم مقدار تکست لینک و مقدار سوم  رنگ لینک.

namespace CustomTagHelper.TagHelpers
{
    public class EmailTagHelper:TagHelper
    {
        public string EmailLink { get; set; } = "test@test.com";
        public string EmailText { get; set; } = "Email";
        public string EmailColor { get; set; } = "Green";
    }
}

• عملیات Override روی کلاس Process : در ASP.NET Core، هنگامی که شما یک کلاس Tag Helper سفارشی ایجاد می‌کنید، معمولاً متد Process یا ProcessAsync را override می‌کنید تا منطق خاص خود را برای تولید HTML پیاده‌سازی کنید. این متدها برای پردازش و اصلاح تگ HTML ای که Tag Helper مربوطه، آن را هدف قرار می‌دهد، استفاده می‌شوند.

namespace CustomTagHelper.TagHelpers
{
    public class EmailTagHelper:TagHelper
    {
        public string EmailLink { get; set; } = "test@test.com";
        public string EmailText { get; set; } = "Email";
        public string EmailColor { get; set; } = "Green";
        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
        }
    }
}

• دستور output.TagName : توسط این دستور میتوانیم نام تگ را تغییر داد، مثلا اگر قصد داریم در مثال ایمیل از تگ a استفاده کنیم. باید مقدار a را به آن نسبت داد.

output.TagName = "a";

• دستور output.Attributes.SetAttribute : توسط این دستور میتوانیم Attributeهای مورد نیاز خود را اضافه کنیم.

output.Attributes.SetAttribute("href",$"mailto:{EmailLink}");
output.Attributes.SetAttribute("style",$"color:{EmailColor}");

• دستور output.Content.SetContent : توسط این دستور میتوانیم متنی که بین تگ ها قرار میگیرند را وارد کرد.

output.Content.SetContent(EmailText);

• نمایش کل کد های کلاس مربوط به تگ هلپر ایمیل

public class EmailTagHelper:TagHelper
{
    public string EmailLink { get; set; } = "test@test.com";
    public string EmailText { get; set; } = "Email";
    public string EmailColor { get; set; } = "Green";
    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        output.TagName = "a";
        output.Attributes.SetAttribute("href",$"mailto:{EmailLink}");
        output.Attributes.SetAttribute("style",$"color:{EmailColor}");
        output.Content.SetContent(EmailText);
    }
}

• نحوه فراخوانی تگ هلپر ایمیل در ویو

<email email-color="red" email-link="ahadian2@gmail.com" email-text="Email"></email>

متدهای ساخت TagHelper

• متد TagName: متد TagName در کلاس TagHelperOutput یک ویژگی مهم در ASP.NET Core Tag Helpers است که به شما اجازه می‌دهد نام تگ HTML نهایی که توسط Tag Helper تولید می‌شود را تعیین یا تغییر دهید.

// تغییر نام تگ به "button"
output.TagName = "button";

• متد Attributes: ویژگی Attributes از نوع TagHelperAttributeList است که یک لیست از اتربیوت های تگ HTML را نگه می‌دارد. این لیست به شما اجازه می‌دهد که ویژگی‌های موجود را دسترسی، اضافه، تغییر یا حذف کنید.

//دسترسی به اتربیوت های موجود
var classAttribute = output.Attributes["class"];
//افزودن اتربیوت
output.Attributes.SetAttribute("class", "btn btn-primary");
//تغییر اتربیوت
output.Attributes.SetAttribute("class", "btn btn-primary");
//حذف اتربیوت
output.Attributes.RemoveAll("class");

• متد Content: ویژگی Content به شما اجازه می‌دهد محتوای داخلی تگ HTML را بخوانید، تغییر دهید یا به آن اضافه کنید. این قابلیت برای تولید تگ‌های HTML پویا بسیار مفید است.

//خواندن محتوای داخلی
var content = output.Content.GetContent();
//تنظیم محتوای داخلی
output.Content.SetContent("New content");
//تنظیم محتوای داخلی
output.Content.SetHtmlContent("<div>New content</div>");
//می‌توانید محتوای جدیدی به محتوای موجود اضافه کنید
output.Content.Append("Additional content");
//می‌توانید محتوای جدیدی به محتوای موجود اضافه کنید
output.Content.AppendHtml("<div>Additional content</div>");

• متد PreElement و PostElement: متدهای PreElement و PostElement در کلاس TagHelperOutput به شما این امکان را می‌دهند که محتوای HTML را قبل یا بعد از تگ HTML اصلی اضافه کنید. این قابلیت‌ها به شما این امکان را می‌دهند که تگ‌های HTML پیچیده‌تری ایجاد کنید و محتوای HTML اضافی را در اطراف تگ اصلی قرار دهید.

//محتوای اچ تی ام ال را قبل و بعد از تگ اصلی تنظیم میکند
output.PreElement.SetHtmlContent("<div class='pre-element'>");
output.PostElement.SetHtmlContent("</div>");

متدهای AppendHtml و PrependHtml در PreElement و PostElement به شما این امکان را می‌دهند که محتوای HTML را قبل یا بعد از محتوای موجود اضافه کنید.

//این متد محتوای اچ تی ام ال جدید را به انتهای محتوای موجود اضافه می‌کند
output.PreElement.AppendHtml("<span>Additional pre content</span>");
output.PostElement.AppendHtml("<span>Additional post content</span>");
//این متد محتوای اچ تی ام ال جدید را به ابتدای محتوای موجود اضافه می‌کند
output.PreElement.PrependHtml("<span>Additional pre content</span>");
output.PostElement.PrependHtml("<span>Additional post content</span>");

• متد PreContent و متد PostContent: متدهای PreContent و PostContent در کلاس TagHelperOutput به شما امکان می‌دهند که محتوای HTML را قبل یا بعد از محتوای داخلی تگ HTML اصلی اضافه کنید. این قابلیت‌ها به شما این امکان را می‌دهند که محتوای HTML اضافی را در اطراف محتوای داخلی تگ HTML قرار دهید.

//محتوا را قبل و بعد از محتوای داخلی تگ اصلی تنظیم میکند
output.PreContent.SetHtmlContent("<div class='pre-content'>");
output.PostContent.SetHtmlContent("</div>");

متد AppendHtml و PrependHtml در PreContent و متد PostContent به شما این امکان را می‌دهند که محتوای HTML را قبل یا بعد از محتوای موجود اضافه کنید.

//این متد محتوای اچ تی ام ال را به انتهای محتوای موجود اضافه می‌کند
output.PreContent.AppendHtml("<span>Additional</span>");
output.PostContent.AppendHtml("<span>Additional </span>");
//این متد محتوای اچ تی ام ال را به ابتدای محتوای موجود اضافه می‌کند
output.PreContent.PrependHtml("<span>Additional</span>");
output.PostContent.PrependHtml("<span>Additional</span>");

• متد SuppressOutput: وقتی SuppressOutput فراخوانی می‌شود، تمام محتوای تگ و هرگونه تغییرات دیگر در خروجی نهایی حذف می‌شود. به عبارت دیگر، تگ HTML و محتوای داخلی آن در خروجی نهایی صفحه وجود نخواهد داشت.

output.SuppressOutput();