طریقه استفاده از کتابخانه دیتاتیبل اختصاصی شرکت نرم افزاری خورشید

برای شروع کار، کافی است اسکریپت اختصاصی KhorshidCo.js را به صفحه خود اضافه کنید.

<script src="https://khorshidneshan.ir/CDN/Scripts/KhorshidCo.min.js"></script>


تعریف ساختار جدول و فیلدها

برای کنترل کامل‌تر ساختار جدول، می‌توانید از تگ <datatable> استفاده کرده و ستون‌ها را به صورت زیر تعریف کنید:

<datatable>
    <column header="نام">[FullName]</column>
    <column header="کد ملی">[NationalCode]</column>
    <column header="مجموع خرید">[TotalPurchase]</column>
    <column header="خرید مجدد">[RepeatPurchase]</column>
</datatable>


در این ساختار:

• مقادیر داخل براکت (مانند [FullName]) به صورت متغیر از داده‌های JSON جایگزین می‌شوند.

• هیدن فیلد: در فایل اصلی (مثلاً default.aspx) باید یک HiddenField جهت ذخیره و بازیابی داده‌های تغییر یافته در جدول درج شود. نمونه:

  <asp:HiddenField ID="hfTableData" ClientIDMode="Static" runat="server" />


تنظیمات و اپشن‌های پیشرفته

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

• hassum:
  اگر این اپشن به یک ستون اضافه شود، جمع مقادیر عددی آن ستون به صورت خودکار در فوتر جدول نمایش داده می‌شود.
  

  <column header="مبلغ(ریال)" hassum>[Price]</column>


• money:
  با افزودن این اپشن به ستون‌های عددی، مقادیر به صورت سه رقم سه رقم جدا شده و خواناتر نمایش داده می‌شوند.
  

  <column header="مبلغ(ریال)" money>[Price]</column>

• display:
  این اپشن برای کنترل نمایش یا عدم نمایش المان‌ها بر اساس مقدار بولی به‌کار می‌رود.

  <column header="وضعیت">
    <asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/active.png" display="[IsActive]" />
    <asp:ImageButton runat="server" ImageUrl="~/AddOn/Icons/inactive.png" display="![IsActive]" />
</column>


  در این مثال، اگر مقدار [IsActive] برابر با true باشد، دکمه فعال نمایش داده شده و در غیر این صورت دکمه غیرفعال نمایش داده می‌شود.

• checked:
  برای کنترل وضعیت انتخاب (چک بودن) چک‌باکس‌ها در ستون‌های دیتاتیبل به کار می‌رود.

  <column header="پرداخت کرده؟">
    <input type="checkbox" disabled="disabled" checked="[IsPayed]" />
</column>


  اگر [IsPayed] برابر با true باشد، چک‌باکس به صورت انتخاب‌شده نمایش داده می‌شود.

تعامل با فیلدهای ورودی

در صورتی که در جدول فیلدهای عددی وجود داشته باشد که تغییر می‌کنند (مثلاً فیلدهایی که زمان یا امتیاز را دریافت می‌کنند)، باید یک شناسه استاندارد به‌صورت "نام ستون_شناسه ردیف" برای هر فیلد تعریف کنید. سپس با دریافت تغییرات کاربر، مقادیر جدید به‌صورت رشته‌ای در یک HiddenField ذخیره شده تا در ارسال فرم به سرور منتقل شود.

<asp:HiddenField ID="hfTableData" ClientIDMode="Static" runat="server" />


خروجی گرفتن از جدول

کتابخانه دیتاتیبل امکان خروجی گرفتن از داده‌های جدول به فرمت‌هایی مانند Excel و PDF را فراهم می‌کند. تنها ستون‌هایی که دارای اپشن noinoutput یا عنوان "عملیات" نباشند، در خروجی نهایی نمایش داده می‌شوند.

<datatable>
    <column header="نام">[FullName]</column>
    <column header="کد ملی">[NationalCode]</column>
    <column header="مجموع خرید">[TotalPurchase]</column>
    <!-- ستون عملیات که در خروجی حذف می‌شود -->
    <column header="عملیات" noinoutput>
        <asp:ImageButton ImageUrl="~/AddOn/Icons/edit.png" runat="server" ID="_imgBtnEdit" 
                         AlternateText="ویرایش" OnClick="_btnEdit_OnClick" />
        <asp:ImageButton ImageUrl="~/AddOn/Icons/remove.png" runat="server" ID="_imgBtnDelete" 
                         AlternateText="حذف" OnClick="_btnDelete_OnClick" />
    </column>
</datatable>


در این مثال:

• ستون "عملیات" به دلیل داشتن ویژگی noinoutput در خروجی‌های Excel و PDF نادیده گرفته می‌شود.
• تنها ستون‌های مهم و مرتبط مانند "نام"، "کد ملی" و "مجموع خرید" در خروجی‌های نهایی نمایش داده می‌شوند.

📌 نکات تکمیلی در استفاده از دیتاتیبل

• مدیریت آدرس JSON از طریق کوکی:
  برای ذخیره‌سازی آدرس JSON در مرورگر، سرور این آدرس را در یک کوکی ذخیره می‌کند. کلید یکتا بر اساس آدرس صفحه و شناسه جدول ساخته می‌شود تا در مواقع بعدی آدرس JSON به راحتی بازیابی گردد.

🧩 تنظیمات سمت سرور برای دیتاتیبل

ساخت کلاس JsonUtility

برای اینکه بتوان اطلاعات جدول را به DataTable منتقل کرد، ابتدا باید کلاسی با نام JsonUtility ایجاد کرده و آن را در پوشه‌ی کلاس‌ها قرار داد. این کلاس وظیفه‌ی تبدیل داده‌ها به قالب JSON مناسب برای استفاده در DataTable را بر عهده خواهد داشت.

📌 نکته مهم:

پیش از استفاده از این کلاس، لازم است رفرنس Newtonsoft.Json به پروژه اضافه شود. در صورتی که این رفرنس اضافه نشده باشد، کلاس عملکرد صحیحی نخواهد داشت و هنگام اجرای پروژه با خطا مواجه خواهید شد.

ساخت صفحه Data.aspx برای گرفتن دیتا

در این مرحله، باید صفحه‌ای با نام Data.aspx ایجاد کنید. سپس در بخش کدپشت این صفحه (فایل Data.aspx.cs) و در رویداد Page_Load، قطعه‌کد زیر را اضافه نمایید:

Response.Clear();
string fileName = Request.QueryString["f"];
if (string.IsNullOrEmpty(fileName))
{
     Response.Write("[]");
     Response.End();
     return;
}

// ساخت مسیر فایل JSON
string filePath = Server.MapPath($"~/Upload/Jsons/{fileName}.json");


// بررسی وجود فایل
if (!System.IO.File.Exists(filePath))
{
     Response.Write("[]");
     Response.End();
     return;
}

// تنظیم نوع پاسخ به JSON
Response.ContentType = "application/json";

// خواندن محتویات فایل و ارسال به خروجی
string jsonData = System.IO.File.ReadAllText(filePath);
Response.Write(jsonData);
Response.End();

📌 نکته:
این کد از پوشه‌ای به اسم /Upload/Jsons/ استفاده می‌کنه. اگه این پوشه رو توی پروژه نداری، باید خودت دستی بسازیش.

توجه داشته باشید که این کد از پوشه‌ای با مسیر /Upload/Jsons/ استفاده می‌کند. بنابراین، اگر این پوشه در ساختار پروژه شما وجود نداشته باشد، لازم است آن را به‌صورت دستی ایجاد کنید.

آماده‌سازی اطلاعات برای جدول

توی صفحه‌ای که می‌خوای جدول نشون بدی، اول این کد رو توی Page_Load می‌نویسی:

در صفحه‌ای که قرار است جدول داده نمایش داده شود، ابتدا باید در رویداد Page_Load کد زیر را اضافه کنید.

protected void Page_Load(object sender, EventArgs e)
{
     BindGrid();
}

پس از آن، باید تابعی با نام BindGrid تعریف کنید که مسئول بارگذاری و نمایش داده‌ها در جدول باشد.

private void BindGrid()
{
     var customer = new TbCustomer().GetAll();
     new JsonUtility().CreateJsonFile(customer, c => new
  {
          c.Name,
          c.Family,
          c.NationalCode,
          WalletPrice = c.WalletPrice.ToString("N0")
  });
}

📝 در این مرحله:

• ابتدا لیست اطلاعات موردنظر (مثلاً customer) را دریافت می‌کنیم.
• سپس با استفاده از متد CreateJsonFile، یک فایل JSON از این داده‌ها ایجاد می‌کنیم.
• در نهایت، فیلدهایی که قصد نمایش آن‌ها در جدول داریم را انتخاب و مشخص می‌کنیم.

📌 نکته:

نام فیلدها باید دقیقاً با مقادیری که در تگ <column> تعریف می‌کنیم یکسان باشد.

صفحه با دو جدول

به‌سادگی کافی است به تگ <datatable> یک شناسه (id) اختصاص دهید، سپس در تابع CreateJsonFile نام فایل JSON موردنظر را تعیین کنید. این کار باعث می‌شود فایل JSON مربوط به همان جدول ایجاد شده و به‌درستی در صفحه بارگذاری شود.

📄 کد HTML:

<datatable id="_dtProductDetail">
    <column header="کد کالا">[ProductId]</column>
    <column header="نام کالا">[ProductName]</column>
    <column header="تعداد">[Amount]</column>
    <column header="فی" money>[Price]</column>
    <column header="کل" money hassum>[TotalPrice]</column>
</datatable>


🧑‍💻 کد پشت مربوط به اون جدول:

private void BindOrderProducts(List<TbOrderProduct> result)
{
  new JsonUtility().CreateJsonFile(result, d => new
  {
          d.Id,
          d.ProductId,
          ProductName = d.TbProduct.Name,
          d.Amount,
          d.Price,
          d.TotalPrice
     }, "_dtProductDetail");
}