آموزش تبدیل جداول HTML به DataTable در ASP.NET (بخش کلاینت)

بررسی ساختار جدول HTML و تبدیل به DataTable

برای استفاده از DataTable، دو روش برای ساخت جداول پیشرفته در پروژه داریم:

1. تبدیل جداول HTML استاندارد (table) به DataTable
   در این روش، اگر جدول ما دارای تگ‌های <thead> و <th> باشد، به سادگی می‌توان آن را با DataTable تقویت کرد.
2. ایجاد و تبدیل ساختار دلخواه (<datatable>) به DataTable
   در این روش، در صورتی که جدول را با <datatable... نوشته شود، ابتدا از طریق دستوراتی datatable را به table تبدیل کرده، سپس به DataTable تبدیل میشود.

2. ایجاد و تبدیل ساختار دلخواه (<datatable>) به DataTable

• مراحل اولیه (اضافه کردن فایل‌های CSS و JavaScript)
  برای اینکه از قابلیت‌های DataTable استفاده کنیم، ابتدا باید فایل‌های CSS و JavaScript مورد نیاز را به پروژه خود اضافه کنیم. این فایل‌ها استایل‌ها و اسکریپت‌هایی هستند که برای راه‌اندازی و نمایش درست DataTable ضروری هستند.
  استایل‌ها (CSS):
  <!-- ظاهر سکلت 2 و دیتاتیبل -->
<link href="https://khorshidneshan.ir/CDN/Styles/sd.min.css" rel="stylesheet" />
<!-- ظاهر نوتیفیکیشن (پیام هشدار اسکرول افقی) -->
<link href="https://khorshidneshan.ir/CDN/HtmlComponents/Notification/Styles.min.css?i=dme" rel="stylesheet" />
<!-- ظاهر دکمه‌ها در دیتاتیبل -->
<link href="https://khorshidneshan.ir/CDN/Styles/buttons.dataTables.min.css" rel="stylesheet" />
<!-- ظاهر جدول -->
<link href="https://khorshidneshan.ir/CDN/Libraries/DataTable/Styles.min.css" rel="stylesheet" />
  اسکریپت‌ها (JavaScript):
  <!-- اسکریپت اصلی DataTable -->
<script src="https://khorshidneshan.ir/CDN/Scripts/jswsed.min.js"></script>
<!-- اسکریپت دکمه‌های DataTable (برای دکمه‌های خروجی مثل Excel و PDF) -->
<script src="https://khorshidneshan.ir/CDN/Scripts/dataTableButtons.min.js"></script>
<!-- اسکریپت برای فعال‌سازی دکمه‌های Excel و PDF -->
<script src="https://khorshidneshan.ir/CDN/Scripts/jszip.min.js"></script>
<script src="https://khorshidneshan.ir/CDN/Scripts/pdfmake.min.js"></script>
<script src="https://khorshidneshan.ir/CDN/Scripts/vfs_fonts.js"></script>
<!-- اسکریپت انتخاب ستون‌ها (برای انتخاب ستون‌های جدول) -->
<script src="https://khorshidneshan.ir/CDN/Scripts/buttons.colVis.min.js"></script>
<!-- اسکریپت تبدیل اعداد فارسی و عربی به انگلیسی در جداول (برای جستجو در دیتاتیبل) -->
<script src="https://khorshidneshan.ir/CDN/Libraries/Validate/IsNumber.min.js"></script>
<!-- اسکریپت نمایش نوتیفیکیشن‌ها (پیام هشدار اسکرول) -->
<script src="https://khorshidneshan.ir/CDN/HtmlComponents/Notification/Scripts.min.js"></script>
<!-- اسکریپت مدیریت اسکرول افقی و نمایش هشدار چپ به راست -->
<script src="https://khorshidneshan.ir/CDN/HtmlComponents/HorizontalScrollMove/Scripts.min.js" defer></script>
<!-- اسکریپت تبدیل تگ‌ها به جدول و اعمال ویژگی‌های خاص (برای دیتاتیبل) -->
<script src="https://khorshidneshan.ir/CDN/Libraries/DataTable/Scripts.min.js" defer></script>

  این لینک‌ها و فایل‌ها به پروژه شما اضافه می‌شوند تا امکان تبدیل جداول ساده HTML به جداول پیشرفته با ویژگی‌های DataTable فراهم شود.

• دریافت داده‌ها از JSON
  در این روش، داده‌های جدول از فایل JSON دریافت می‌شوند. در این حالت، مقادیری که به صورت متغیرهایی داخل براکت نوشته شده‌اند (مانند [FullName]، [NationalCode])، به طور خودکار از JSON جایگزین می‌شوند.
  این روش به شما امکان می‌دهد که داده‌ها و نمایش آن‌ها را از هم جدا کنید و به راحتی داده‌ها را مدیریت و به‌روزرسانی کنید.
• ذخیره و بازیابی آدرس JSON از طریق کوکی
  
  • مدیریت آدرس JSON در کوکی
    برای دسترسی به آدرس JSON، سرور آدرس آن را در کوکی مرورگر ذخیره می‌کند. سپس با استفاده از یک کلید یکتا که بر اساس آدرس فعلی صفحه و شناسه (ID) جدول ساخته می‌شود، می‌توان آدرس JSON ذخیره‌شده را بازیابی کرد.
  • ساخت کلید یکتا
    ابتدا آدرس صفحه پردازش شده تا از وجود کاراکترهای ناخواسته مانند &، / و : پاک شود:
    const url = window.location.href.toLowerCase().split('#')[0]
    .replaceAll('&', '-')    // جایگزینی & با -
    .replaceAll(':', '')     // حذف دو نقطه
    .replaceAll('/', '')     // حذف اسلش
    .replaceAll('?', '')     // حذف علامت سوال
    .replaceAll('=', '')     // حذف علامت مساوی
    .replaceAll('.', '')     // حذف نقطه
    .replaceAll('defaultaspx', ''); // حذف عبارت defaultaspx
const id = table ? table[0].id : ''; // بررسی وجود شناسه (ID) جدولconst cookieKey = `${url}-${id}`; // ترکیب آدرس پردازش‌شده و ID جدول برای ساخت کلید 

    سپس در صورتی که جدول دارای شناسه (ID) باشد، این شناسه استخراج می‌شود:

    const id = table ? table[0].id : ''; // بررسی وجود شناسه (ID) جدول

    در نهایت، کلید کوکی با ترکیب آدرس پردازش‌شده و ID جدول ساخته می‌شود:

    const cookieKey = `${url}-${id}`;
  • بازیابی آدرس JSON از کوکی
    با استفاده از کلید یکتا، آدرس JSON ذخیره‌شده در کوکی را می‌توان بازیابی کرد:
    const jsonUrl = cookieKey ? `${hostName}${GetCookie('jf-' + cookieKey)}&i=${new Date().getTime()}` : '';

    در اینجا:

    • GetCookie: تابعی برای خواندن مقادیر از کوکی.

    • i=${new Date().getTime()}: افزودن پارامتر زمان برای جلوگیری از کش شدن (Cache) اطلاعات

  • توجه مهم
    برای پشتیبانی از این روش، در فایل اصلی (اغلب default.aspx) باید یک HiddenField قرار داده شود تا داده‌ها به درستی ذخیره و بازیابی شوند:
    <asp:HiddenField ID="hfItemId" ClientIDMode="Static" runat="server" />
• ساختار اولیه (ایجاد و تبدیل ساختار دلخواه <datatable> به DataTable)
  ساختار اولیه برای نمایش اطلاعات به صورت جدول، شبیه به زیر است. این ساختار شامل تعریف ستون‌ها و متغیرهایی است که بعداً توسط داده‌های JSON پر می‌شوند:
  <datatable>
    <column header="نام">[FullName]</column>
    <column header="کد ملی">[NationalCode]</column>
    <column header="مجموع خرید">[TotalPurchase]</column>
    <column header="خرید مجدد">[RepeatPurchase]</column>
</datatable>

  توضیحات ساختار:

  • تگ <datatable>: نشان‌دهنده جدول داده‌ای که قرار است تبدیل شود.
  • تگ <column>: شامل اطلاعات هر ستون با استفاده از ویژگی header برای عنوان ستون.
  • مقادیری که داخل [ ] نوشته شده‌اند، متغیرهایی هستند که از فایل JSON خوانده می‌شوند.
• ساخت ستون‌های پیشرفته در جدول (HTML و عناصر تعاملی)
  در مواردی که بخواهیم ظاهر و عملکرد ستون‌ها را در جدول ارتقا دهیم، می‌توانیم از ترکیب عناصر HTML و کنترل‌های ASP.NET درون ستون‌ها استفاده کنیم. این روش به ما امکان می‌دهد که داده‌ها را با جزئیات بیشتر و قابلیت تعامل بیشتری نمایش دهیم.
  1. پایه
     <datatable>
    <column header="نام">[FullName]</column>
    <column header="مجموع خرید">[TotalPurchase] تومان</column>
    <column header="خرید مجدد">
        <asp:LinkButton runat="server" OnClick="_lbtnRepeatPurchase_Click" ID="_lbtnRepeatPurchase" ToolTip="جزئیات خرید" CssClass="linkBtn">
            <img src="~/AddOn/Icons/details.png" runat="server" />
        </asp:LinkButton>
        [RepeatPurchase] بار
    </column>
</datatable>

     ویژگی‌های مهم این ساختار:

     1. ترکیب داده‌ها با HTML:
        ستون‌ها می‌توانند شامل متن و HTML باشند. به عنوان مثال:
        
        • [TotalPurchase] تومان داده را به همراه یک متن ثابت نمایش می‌دهد.
        • [RepeatPurchase] بار تعداد خرید را به همراه توضیحی درباره آن نمایش می‌دهد.
     2. کنترل‌های تعاملی:
        در ستون "خرید مجدد" یک لینک با استفاده از asp:LinkButton ایجاد شده است. این لینک شامل:
        • تصویر: برای نمایش یک آیکون.
        • کلیک‌پذیری: با استفاده از رویداد OnClick، عملکرد دلخواهی در سرور تعریف می‌شود.
  2. اضافه کردن ستون عملیات به جدول
     در بسیاری از جداول، ممکن است نیاز به افزودن ستون عملیات وجود داشته باشد که شامل دکمه‌ها یا آیکون‌هایی برای انجام اقدامات مختلف نظیر ویرایش، حذف، فعال/غیرفعال کردن و غیره باشد. در این مرحله، ما ستون جدیدی به جدول اضافه می‌کنیم که شامل دکمه‌ها و لینک‌هایی برای انجام این عملیات‌ها باشد.
     ساختار جدول با ستون عملیات:
      <datatable>
    <column header="عملیات">
        <asp:ImageButton ImageUrl="~/AddOn/Icons/edit.png" runat="server" ID="_imgBtnEdit" AlternateText="ویرایش" title="ویرایش" OnClick="_btnEdit_OnClick" />
        <asp:ImageButton ImageUrl="~/AddOn/Icons/remove.png" runat="server" ID="_imgBtnDelete" AlternateText="حذف" title="حذف" OnClick="_btnDelete_OnClick" />
        <asp:ImageButton ImageUrl="~/AddOn/Icons/activation.png" runat="server" ID="_imgBtnActivation" title="فعال/غیرفعال" AlternateText="فعال/غیرفعال" OnClick="_btnToggleActivation_OnClick" CssClass='[CssClass]' />
    </column>
    <!-- سایر ستون‌ها -->
</datatable>

     توضیحات درباره این ساختار:

     • در صورتی که دکمه‌ها یا لینک‌ها به داده‌های خاصی وابسته باشند، این داده‌ها را می‌توان از JSON خواند (برای مثال، CssClass که ممکن است با داده‌های خاصی مانند وضعیت کاربر مرتبط باشد).

     • غیرفعال کردن لینک‌ها در صورتی که href="#" باشد:
       لینک‌ها به طور پیش‌فرض غیرفعال می‌شوند و چیزی نمایش نمی‌دهد وقتی که href به # تنظیم شده باشد. این ویژگی برای جلوگیری از هدایت به صفحات غیرضروری استفاده می‌شود.
     • رویدادهای ASP.NET:
       برای هر عملیات مانند ویرایش، حذف یا فعال/غیرفعال کردن، رویدادهای مربوط به سرور در ASP.NET (OnClick) تعریف می‌شود. این رویدادها می‌توانند به تغییر وضعیت داده‌ها یا نمایش جزئیات بیشتری از رکوردها کمک کنند.
  3. ویژگی money و hassum
     money: اگر برای یک ستون تنظیم شود، مقادیر آن ستون به صورت سه رقم سه رقم جدا می‌شوند.
     hassum: در صورت تنظیم برای یک ستون، مجموع مقادیر آن ستون در انتهای جدول محاسبه و نمایش داده می‌شود.
     <datatable>
    <column header="درگاه بانکی">[GateWayFullTitle]</column>
    <column header="کدملی">[NationalCode]</column>
    <column header="مشخصات">[PayerFullName]</column>
    <column header="مبلغ(ریال)" hassum money>[Price]</column>
    <column header="پایه" money>[Paye]</column>
</datatable>

     ویژگی money:

     • در ستون "مبلغ(ریال)" که مقادیر پولی در آن قرار دارند، با اضافه کردن ویژگی money به صورت خودکار سه رقم سه رقم از چپ جدا می‌شود.
     • به طور مثال، مبلغ ۱۲۳۴۵۶۷ ریال به شکل "1,234,567" نمایش داده می‌شود.

     ویژگی hassum:

     • در ستون "مبلغ(ریال)" با ویژگی hassum، برنامه می‌تواند جمع مقادیر این ستون را در فوتر جدول محاسبه کند.
     • این ویژگی به طور خودکار تصمیم می‌گیرد که مقادیر ستون عددی هستند یا زمانی (ساعت) و بر اساس آن جمع می‌کند.
     • اگر ستونی از نوع ساعت باشد، جمع ساعت‌ها انجام می‌شود. اگر ستون از نوع عددی باشد، جمع اعداد انجام می‌شود.
     • برای تعیین نوع داده، برنامه به بررسی اولین ردیف‌ها می‌پردازد تا نوع داده را تشخیص دهد.
     • برای جمع مقادیر، فوتر جدول به صورت خودکار به روزرسانی می‌شود.
  4. display در DataTable
     در این قسمت از DataTable، از گزینه display برای کنترل نمایش یا عدم نمایش المنت‌ها بر اساس مقدار بولی استفاده می‌شود. مقدار این گزینه می‌تواند true یا false باشد. در صورتی که مقدار برابر با false یا معادل true! باشد، به صورت خودکار به المنت ویژگی style="display:none" اضافه شده و المنت مخفی می‌شود.
     <datatable>
    <column header="عملیات">
        <asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/inactive.png" ToolTip="غیرفعال کردن" ID="_imgBtnDisactive" OnClick="_btnToggleActivation_OnClick" display="[IsActive]" />
        <asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/active.png" ToolTip="فعال کردن" ID="_imgBtnActive" OnClick="_btnToggleActivation_OnClick" display="![IsActive]" />
    </column>
    <!-- سایر بخش‌ها -->
</datatable>

     توضیحات درباره این ساختار:

     • مقداردهی به display="[IsActive]":
       در این حالت، اگر مقدار IsActive برابر با true باشد، المنت نمایش داده می‌شود. در غیر این صورت (یعنی زمانی که IsActive برابر با false است) به صورت خودکار به المنت ویژگی style="display:none" افزوده می‌شود و المنت مخفی می‌گردد.
     • مقداردهی به display="![IsActive]":
       در این حالت، از عملگر ! برای معکوس کردن مقدار استفاده شده است. به عبارت دیگر، اگر IsActive برابر با false باشد، المنت نمایش داده می‌شود و اگر برابر با true باشد، المنت مخفی می‌شود.

     این قابلیت باعث می‌شود تا بتوانید نمایش المنت‌ها را به صورت داینامیک بر اساس وضعیت داده‌ها کنترل کنید و تجربه کاربری بهتری ارائه دهید.

  5. checked در DataTable
     این ویژگی برای کنترل وضعیت انتخاب (چک بودن) یک چک‌باکس در ستون‌های DataTable استفاده می‌شود.
     وقتی که در یک المنت چک‌باکس مقدار checked="[IsPayed]" قرار می‌گیرد، در صورتی که مقدار IsPayed برابر با true باشد، ویژگی checked به صورت خودکار به المنت اضافه شده و چک‌باکس تیک می‌خورد. اما اگر مقدار IsPayed برابر با رشته خالی یا false باشد، ویژگی checked درج نمی‌شود و چک‌باکس بدون تیک نمایش داده می‌شود.
     <datatable>
    <column header="عکس" noinoutput>
        <img src="[ImageSrc]" style="max-width: 70px; max-height: 70px" />
    </column>
    <column header="پرداخت کرده؟">
        <input type="checkbox" disabled="disabled" checked="[IsPayed]" />
    </column>
</datatable>

     checked="[IsPayed]":

     • اگر مقدار IsPayed برابر با true باشد، به صورت خودکار ویژگی checked به المنت اضافه می‌شود و چک‌باکس تیک خورده نمایش داده می‌شود.
     • اگر مقدار IsPayed برابر با رشته خالی باشد، ویژگی checked درج نمی‌شود و چک‌باکس بدون تیک نمایش داده می‌شود.
     • این قابلیت امکان نمایش وضعیت انتخابی چک‌باکس‌ها را به صورت داینامیک بر اساس داده‌های دریافتی فراهم می‌کند.
       
       
  6. مدیریت مقادیر فیلدهای ورودی (Input) در ستون‌های دارای مقدار عددی و تبدیل آن‌ها به فرمت JSON
     در این روش، زمانی که مقدار یک فیلد ورودی (input) از نوع عددی در یک ستون تغییر می‌کند، مقدار جدید ثبت شده و به یک رشته فرمت شده تبدیل می‌شود تا در یک HiddenField ذخیره گردد. سپس در هنگام ارسال فرم، این رشته به سرور ارسال شده و Backend آن را پردازش می‌کند.
     برای این کار، شناسه (ID) هر فیلد باید به صورت استاندارد و شامل دو بخش باشد:
     • نام ستون: نشان‌دهنده‌ی نوع داده یا لیست مرتبط (مثلاً txtTimeSpent یا txtScore).
     • شناسه سطر: مشخص‌کننده‌ی ردیف داده‌ای که فیلد در آن قرار دارد (مثلاً 1465).
       به عنوان مثال، یک فیلد ورودی به این صورت تعریف می‌شود:
       <input id="txtTimeSpent_1465" type="number" value="[TimeSpent]" placeholder="ساعت حضور وارد کنید..."/>
     
     هنگامی که مقدار این فیلد تغییر می‌کند، شناسه آن تجزیه شده و مقدار جدید به لیست مربوط به آن ستون اضافه یا به‌روزرسانی می‌شود. اگر لیستی برای نام ستون موردنظر از قبل وجود نداشته باشد، ابتدا ایجاد می‌شود.
     تمام این مقادیر در نهایت به صورت یک رشته نهایی با فرمت مشخص سازماندهی می‌شوند. به عنوان مثال، خروجی نهایی به این صورت خواهد بود:
     "txtTimeSpent=[1465:5,1466:1];txtScore=[1465:6]"
     این رشته در یک HiddenField ذخیره می‌شود تا در زمان ارسال فرم، مقادیر ثبت شده به سرور ارسال گردد. به همین منظور، در فایل اصلی (معمولاً default.aspx) باید HiddenField زیر تعریف شده باشد:
     <asp:HiddenField ID="hfTableData" ClientIDMode="Static" runat="server" />
     این روش به شما این امکان را می‌دهد که مقادیر تغییر یافته در فیلدهای عددی جدول را به صورت سازمان‌یافته و در قالب یک رشته به سرور ارسال کنید، بدون نیاز به پردازش مستقیم در سمت کاربر.
     
     
• قابلیت‌های DataTable برای مدیریت خروجی و تنظیم ستون‌ها
  DataTable این امکان را به شما می‌دهد که داده‌های جدول خود را به فرمت‌های مختلف مانند Excel و PDF خروجی بگیرید. این ویژگی برای تهیه گزارش‌ها و ذخیره‌سازی اطلاعات بسیار مفید است.
  
  تنظیم ستون‌ها در DataTable:
  1. مخفی کردن ستون‌ها:
     می‌توانید ستون‌هایی از جدول را طوری تنظیم کنید که در نمایش صفحه مخفی شوند. به این ترتیب، اطلاعات آن ستون‌ها برای کاربر در جدول قابل مشاهده نخواهند بود.
  2. مدیریت ستون‌ها در خروجی Excel و PDF:
     DataTable این امکان را فراهم می‌کند که خروجی‌هایی مانند Excel و PDF را با توجه به تنظیمات ستون‌ها ایجاد کنید. ستون‌هایی که قابل نمایش هستند و تنظیم خاصی برای عدم نمایش در خروجی ندارند، در خروجی‌ها نمایش داده می‌شوند.
     • ستون‌هایی که در خروجی نمایش داده می‌شوند:
       ستون‌هایی که در تنظیمات، ویژگی noinoutput برای آنها تعریف نشده باشد یا عنوان هدر آنها "عملیات" نباشد، به طور خودکار در خروجی Excel و PDF نمایش داده خواهند شد.
       این ویژگی به شما کمک می‌کند که تنها اطلاعات مهم و مرتبط را در گزارش‌های خروجی خود نگه دارید و ستون‌های غیرضروری یا حساس را از خروجی‌ها حذف کنید.
• سایر نکات:

  • یکی از قابلیت‌های DataTable این است که در صورت دابل کلیک روی یک سلول، متن خالص (بدون کدهای HTML) انتخاب شده و کپی می‌شود. به این ترتیب، زمانی که متن کپی شده را در ادیتورهای نرم‌افزار خود پیست می‌کنید، تنها محتوای متنی انتقال می‌یابد و هیچ اثری از تگ‌ها یا ساختار HTML در محتوای کپی شده نخواهد بود.

  • یکی از ویژگی‌های مهم سیستم این است که فیلد جستجو مقدار وارد شده توسط کاربر را حفظ می‌کند. به این معنی که زمانی که در فیلد جستجو متنی وارد می‌کنید و سپس از آیکون‌های عملیاتی استفاده می‌کنید، در صورت وقوع عملیات postback بدون لود مجدد صفحه، مقدار جستجو همانطور که تایپ کرده‌اید باقی می‌ماند. این ویژگی باعث می‌شود که تجربه کاربری بهبود یافته و کاربر پس از انجام عملیات نیازی به وارد کردن مجدد متن جستجو نداشته باشد.