آموزش استفاده از jqGrid در ASP.NET

سلام . امروز با مقاله ای جامع در رابطه با jqGrid در ASP.NET در خدمتتون هستم. ممکن است در ابتدا فکر کنید که jqGrid چیز جدیدی نیست. پس چرا jqGrid ؟ دقیقا درست فکر میکنید ! jqGrid plug-in چیز جدیدی نیست. این یک کنترل نمایش داده اثبات شده در دنیای Open Source با پشتیبانی گسترده AJAX است. زیبایی jqGrid نیز در صفحه بندی ، مرتب سازی ، جستجو و غیره آن به صورت ساده و پشتیبانی از JSON است. دلیل اصلی برای نوشتن این مقاله برای من آن بود که نتوانستم هیچ منبع مناسبی برای معرفی jqGrid و استفاده بهینه از آن پیدا کنم. پس برای آموزش جامع و کامل JqGrid با من همراه باشید…

برسی jqGrid در ASP.NET:

مشکلی که باعث شد درباره ی jqGrid فکر کنم !

من بر روی برنامه ای کار میکنم که بیش از ۲ میلیون کاربر دارد ؛ در آن برنامه گزینه ای برای جستجو کاربران بر اساس نام ، نام خانوادگی و ۴ رقم آخر کد ملی آنها وجود داشت. ما از GridView مان برای برای نمایش نتیجه ی جستجو استفاده میکنیم.

همانطور که تعداد کاربران افزایش یافت ، نتیجه ی جستجو نیز به طرز فوق العاده ای رشد کرد و ما چیزی بیش از ۳۰۰ نتیجه با متغیر های یکسان داشتیم.

از این رو یافتن کاربر یا شخص موردنظر برای کاربرمان بسیار مشکل شده بود. راه حل پیشنهاد شده ارائه دادن یک فیلترکننده یا ویژگی های جستجوگر در سمت کاربر بود. سوال بعدی که در اینجا پیش می آمد این بود که چگونه میتوانیم این ویژگی ها را به grid موجود اضافه کنیم و یا کنترلی وجود دارد که بتواند ویژگی های موجود را در فروشگاه ارائه دهد.

این جستجو ما را به jqGrid رساند که علاوه بر اینکه یک کنترل رایگان است ، تمام ویژگی های اشاره شده در بالا را نیز در خود دارد. همچنین میتوان با مقدار کمی کدزنی آن را تکمیل کرد.

مقداری توضیحات در رابطه با jqGrid

jqGrid یک کنترل زیبا است که برای ارائه ی ویژگی های داده به صورت جدولی به کار میرود.

jqGrid یک کنترل جاوا اسکریپت است که برای ارائه و دستکاری داده های جدولی بر روی web به کار میرود.

jqGrid قابلیت AJAX را دارد.

jqGrid میتواند با هر یک از تکنولوژی های سمت سروری همانند ASP ، JavaServelets ، JSP ، PHP و غیره ادغام شود.

jqGrid توسط Tony Tomov در شرکت Trirand توسعه داده شد.

jqGrid بسیار آسان با ASP.NET ادغام میشود.

ادغام jqGrid با ASP.NET به صورت گام به گام

دانلود jqGrid از Source.

افزودن فایل های موردنظر به برنامه ی ASP.NET (علاوه بر Scripts و CSS)

مقداردهی jqGrid در صفحه ای که نیاز داریم.

Bind کردن داده ها

همانطور که در نکته ی اول گفتم میتوانید jqGrid و فایل های مرتبط را ار لینک زیر دانلود کنید :

http://www.trirand.com/blog/?page_id=6

من آن را دانلود کردم و فابل زیپی با نام jquery.jqGrid-4.5.2.zip دریافت کردم. با توجه به نام فایل مشخص است که من نسخه ی ۴.۵.۲ jqGrid را دانلود کرده ام.

آن را اکسترکت کنیم تا محتویات فایل زیپ را زیر و رو کنیم. من تعدادی فولدر CSS با تعدادی فولدر script و غیره در آن یافتم. برای درک بهترتان من یک برنامه ی دمو با نام JQGridDemo برای ادغام و ویژگی های دیگر نیز ساخته ام که میتوانید آن را از لینک انتهای همین مطلب دانلود کنید.

چیز اصلی که ما نیاز داریم فایل jQuery است زیرا هدف ما به JavaScript و jQuery بستگی دارد.

تنها به منظور ذخیره ی فایل های مرتبط با jqGrid ، یک فولدر در Solution مان با نام JQGridReq ساخته ایم. به عنوان گام اول من فایل jQuery را به آن اضافه کرده ام.

jQuery 1.9 را به آن بیافزایید. به نظرم jQuery 1.9 آخرین نسخه ی تثبیت شده ی jQuery است. اگر ما از یک رابط کاربری مرتبط با jQuery استفاده کنیم ، به چه چیزهایی پس از آن احتیاج داریم ؟ به طور حتم فایل های CSS. اما هرچه من در داخل فولدر به دنبال فایل های jQuery CSS گشتم ، چیزی پیدا نکردم. پس بیاید آن را از اینترنت دانلود کنیم.

پس از دانلود jquery-ui-1.9.2.custom.css آن را به برنامه مان اضافه میکنیم. مطمئن شوید که فولدر تصاویر مربوطه را نیز اضافه کنید ، زیرا ما CSS هایی را اضافه میکنیم که ممکن است به تصاویر مرتبطش نیز نیاز داشته باشد.

حال jQuery ما مهیا شده است. بیاید فایل های jqGrid مان را تک تک اضافه کنیم.

jquery.jqGrid-4.5.2\src\ jquery.jqGrid.js

jquery.jqGrid-4.5.2\js\i18n\ grid.locale-en.js

jquery.jqGrid-4.5.2\css\ ui.jqgrid.css

آیا به فایل دوم توجه کردید ؟ مهم ترین فایل همین است. همچنین فایل های CSS را نیز اضافه کرده ایم. حال پیش نیازاتمان تمام شده است.میتوانید فایل هایی که اضافه کرده ایم و ساختار های فولدر ها را در تصویر زیر ببینید.

برای افزودن JqGrid به صفحه ی aspx بروید.

برای مثال پروژه ، من از یک نمونه مثال ساده از مدیریت مدرک کارمندان استفاده کرده ام. از قسمت Solution میتوانید بفهمید که من از Master Page استفاده کرده ام. پس تنها کاری که نیاز داریم انجام دهیم این است که فایل های موردنیاز برای Master Page را در قسمت head صفحه ی HTML فراخوانی کنیم.

در بخش زیر میتوانید ببینید که من چه چیز هایی به Head قسمت Master Page اضافه کرده ام.

قصدم در اینجا این است که جدول را به JqGrid تبدیل کنیم. چگونه این کار ممکن است ؟ آیا پیش از این از Dialog در jQuery یا JSON استفاده کرده اید ؟

بگذربم … مشکلی نیست.

نیاز داریم که جدول را بر اساس JqGrid با توجه به فیلد هایی که قصد داریم در Grid نشان دهیم ، مقداردهی کنیم. در اینجا میخواهم که موارد زیر را نمایش دهم :

Id

First Name

Last Name

Last 4 SSN

Department

Age

Salary

Marital Status

Address.

میتوانید از Script زیر برای مقداردهی جدول به عنوان Grid استفاده کنید.

<script type="text/javascript">
    jQuery("#jQGridDemo").jqGrid({
        url: '',
        datatype: "json",
        colNames: ['Id','First Name', 'Last Name', 'Last 4 SSN', 'Department', 
                'Age', 'Salary',  "Address",'Marital Status'],
        colModel: [
        { name: '_id', index: '_id', width: 20, stype: 'text' },
        { name: 'FirstName', index: 'FirstName', width: 150 },
        { name: 'LastName', index: 'LastName', width: 150 },
           { name: 'LastSSN', index: 'LastSSN', width: 100 },
        { name: 'Department', index: 'Department', width: 80, align: "right" },
        { name: 'Age', index: 'Salary', width: 80, align: "right" },
        { name: 'Salary', index: 'Salary', width: 80, align: "right" },
        { name: 'Address', index: 'Address', width: 150, sortable: false },
        { name: 'MaritalStatus', index: 'MaritalStatus', width: 100, sortable: false }
      ],
        rowNum: 10,
        sortname: 'id',
        viewrecords: true,
        sortorder: "desc",
        caption: "List Employee Details"
    });
</script>

برنامه را اجرا کنید. یک Grid زیبا همانند زیر به شما داده خواهد شد ، البته بدون هیچ داده ای برای نمایش.

به نظرم پس از آنکه Grid نمایش داده شد ، میتوانید آنچه که را که من در هنگام مقداردهی Grid با Script نوشتم را بخوانید.

colNames نام تیتر های Grid را تشکیل میدهد. خاصیت colModel یک داده شئ JSON است که برای پیکربندی هر ستون Grid استفاده میشود.

میتوانم بگویم که این Data Model است که برای نمایش در Grid یعنی چیزی که ما در تنظیم خاصیت داده ی فیلد name.colNames استفاده کرده ایم باید دقیقا مشابه اشیاء در خاضیت colModel باشد. ممکن است متوجه شده باشید که خاصیت URL خالی باقی گذاشته شده است. چرا ؟ همچنین ممکن است به این فکر کنید که چرا داده در Grid نمایش داده نمیشود ؟ برای هر دو سوالتان میتوانم یک پاسخ بدهم. به دلیل AJAX Callback .

به شما نشان خواهم داد که چگونه Grid منتشر میشود.

در اینجا برای سهولت استفاده از آن من از یک MongoDb به عنوان یک backend استفاده میکنم. سوال بعدی که پیش می آید این است که چگونه URL به مقصد داده دسترسی پیدا میکند؟

کاری که من انجام داده ام این است که من یک Custom HTTP handler ساخته ام و تابع درون http handler سوابق کارمند را میگیرد و آن را در قسمت HTTP Response مینویسد.

HTTP Response یک رشته ی JSON در فرمت اشاره شده در بالا خواهد بود. JqGrid مان JSON response را خواهد خواند و به کمک colModel که در بالا توضیح داده شد ، در JqGrid نمایش میدهد. نکته ای که باید مدنظر داشته باشید این است که ما در حال کار با اشیای JSON هستیم. JqGrid با داده های XML ، داده های JSON و همچنین آرایه ها کار میکند که ما در اینجا از JSON استفاده میکنیم. همانطور که اشاره کردم من یک ashx handler با نام JQGridHandler.ashx ساخته ام و آدرس handler را همانند زیر ارائه کرده ام :

http://localhost:58404/JQGridHandler.ashx

در اینجا میخواهم به شما نشان دهم که چگونه داده ازhandler ای که از Grid پاس داده میشود ، قرمز میشود. به طور معمول اگر ما داده ای به handler پاس دهیم و یا از آن بخوانیم ، باید به کدام پارامتر توجه داشته باشیم ؟ بله . ابتدا به سراغ context.Requet میرویم. در اینجا نیز به سراغ Context.request میرویم تا ببینیم که آیا داده ای به آن پاس داده شده است یا خیر.

Debug کنیم و ببینیم.

با نگاه کردن به de-bugger و تصویری که گذاشته ام میتوانید ببینید که با صدازدن forms.Get(“oper”); به دنبال چیزی به نام oper میگردم و امیدوارم که متوجه شده باشید که خاصیت Form{} (آرایه) در اینجا خالی است.

جلوتر به شما نشان خواهم داد که چگونه همه ی داده ها میتوانند در oper بیایند. پس در اینجا از oper==null استنباط میشود که این اولین load شدن Grid است.

در اینجا من از MONGO db برای ذخیره ی داده استفاده میکنم.

میتوانید ببینید که داده در داخل if کد را میگیرد. اکنون همه ی احتیاجاتمان برای تولید JqGrid انجام شده است. ببینیم کار میکند یا خیر.

برنامه را اجرا کنید …

میتوانید در بالای هر ستون امکان مرتب سازی مربوط به آن ستون را نیز داشته باشید.

مگر اینکه خاصیتی مانند زیر را اضافه کرده باشید :

( در این مثال فیلد آدرس غیر قابل مرتب سازی است) این تنها یک نمونه است.

اکنون یک div دیگر با نام jQGridDemo در پایین جدول JqGrid اضافه میکنیم.

<table id="jQGridDemo">
</table>
<div id="jQGridDemoPager">
</div>

مقداری تغییرات در Script زیر آورده شده است. جاهایی را که علامتگذاری کرده ام به تازگی اضافه شده اند.

بار دیگر برنامه را اجرا میکنیم تا تغییرات اعمال شده بر روی Grid را مشاهده کنیم.

نوار صفحه بندی به همراه گزینه های refresh و search اضافه شده اند.

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

اگر میخواهید که یک label به دکمه ی refresh اضافه کنید تنها کافیست که به فایل grid.locale-en.js بروید و متنی متناسب با آن بنویسید. در زیر میتوانید برای من را مشاهده کنید :

در داخل فایل قسمتی به نام nav وجود دارد که میتوانید در تصویر بالا نیز ببینید ، در داخل آن نیز refreshtext قرار دارد. ابتدا ممکن است آن خالی باشد که شما متنی که نیاز دارید را در داخل آن اضافه کنید. در زیر من Refresh را به عنوان یک label text اضافه کرده ام.

اگر دقت کنید متوجه میشوید که label دکمه ی refresh تغییر کرده است. روش دیگری نیز برای این label وجود دارد.

همچنین میتوانید ببینید که معیار جستجوی ما به یک Drop Down تبدیل شده است که از طریق آن انتخاب های فراوانی نظیر برابر با ، برابر نیست و … در اختیار شما قرار میگیرد. میتوانید مواردی که به آنها احتیاج ندارید را از طریق فایل (grid.locale-en.js) حذف کنید. در تصویر زیر آورده شده است :

پس از حذف مواردی که به آنها احتیاج ندارید ، میتوانید به لیست Drop Down جستجویتان بازگردید تا نتیجه را مشاهده کنید.

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

ویرایش / افزودن / حذف در JqGrid

در JqGrid همه ی رویداد ها و خصوصیات قابل تغییر هستند. کار آسانی است اما مراقب باشید. کوچکترین تغییری ممکن است باعث شود که JqGrid شما به درستی کار نکند.

به منظور کارکرد درست grid تان میتوانید از کد نوشته شده در زیر استفاده کنید.

$('#jQGridDemo').jqGrid('navGrid', '#jQGridDemoPager',
{
   edit: true,
   add: true,
   del: true,
   search: true,
   searchtext: "Search",
   addtext: "Add",
   edittext: "Edit",
   deltext:"Delete"
},
{//EDIT EVENTS AND PROPERTIES GOES HERE },
{//ADD EVENTS AND PROPERTIES GOES HERE},
{//DELETE EVENTS AND PROPERTIES GOES HERE},
{//SEARCH EVENTS AND PROPERTIES GOES HERE}
);

در داخل براکت اول تعدادی از پارامتر ها را برابر با True قرار داده ایم. به تصویر زیر دقت کنید تا توضیحات من از قطعه کد بالا را درک کنید.

به این معناست که در نوار هدایتگر grid همه ی دکمه های ذکر شده در بالا در textbox های مربوط به خودشان که در زیر نیز آورده شده اند به ترتیب قرار میگیرند.

به grid برگردیم تا تغییرات را ببینیم :

به قسمت پایین دقت کنید . همه ی دکمه هایی که خاصیت true داشتند ، نمایش داده شده اند. حال بیاید یک مورد را اضافه کنیم.

بر روی علامت کوچک + که در نوار هدایتگر علامت افزودن است کلیک کنید تا پنجره ای کوچک نمایش داده شود.

اما اکنون نمیتوانید موردی را اضافه کنید زیرا برای عملیات ویرایش هیچ پیکربندی نکرده اید.

برای اجرای عملیات های ویرایش/حذف و افزودن باید یک خاصیت URL دیگر در grid i.e. تنظیم کنید. این ashx handler را فراخوانی میکند تا اجرای افزودن را پیاده کند.

در پایین caption باید editurl را با آدرس زیر تنظیم کنید :

http://localhost:58404/JQGridHandler.ashx

میتوانید برای یافتن موقعیت caption از تصویر زیر استفاده کنید. فرم را تکمیل کنید و بر روی دکمه ی Save کلیک کنید.

من یک debugger در قسمت handler قرار داده ام تا کار را مرحله به مرحله به شما نمایش دهم. میتوانید ببینید که در فرم (context.Request.Form) چه چیزی قرار گرفته است ؟ دقیقا همان چیزی که ما نیاز داریم !

آیا متوجه oper=add شدید ؟

امیدوارم اکنون درک بهتری از oper نسبت به زمانی که گفتم کارش بارگذاری داده در grid است ، بدست آورده باشید.

پس با توجه به مقدار oper که add می باشد ، شرط add پیاده سازی میشود و مورد در دیتابیس ذخیره میشوند.

با استفاده از کد زیر میتوانید هر مقادیری از خاصیت HTTP request را بخوانید و نام را با هرچیزی که میخواهید جایگزین کنید.

string strFirstName = forms.Get("FirstName").ToString();

پس از آنکه افزودن موفقیت آمیز بود ، handler یک رشته ی موفق به HTTP Response میفرستد. رشته در پنجره ی Add/Edit که بر روی grid بالا میاید نوشته میشود.

در بالای صفحه نیز در یک کادر قرمز نمایش داده شده است که : Employee record successfully added نوشته شده است. پیام از hander فرستاده میشود زمانی که کاربر تشخیص داده میشود.

ممکن است فکر کنید که کدام یک از رویداد ها در سمت مشتری این پیام را از طرف سرور دریافت میکند.

******************************************************
Complete Script
******************************************************
$('#jQGridDemo').jqGrid('navGrid', '#jQGridDemoPager',
{
   edit: true,
   add: true,
   del: true,
   search: true,
   searchtext: "Search",
   addtext: "Add",
   edittext: "Edit",
   deltext:"Delete"
},
{   //EDIT portion
    //Can also set the width and height of the editing window as below commented way 
   //height: 300,
   //width: 400,
   //top: 50,
   //left: 100,
   //dataheight: 280,
   closeOnEscape: true,//Closes the popup on pressing escape key
   reloadAfterSubmit: true,
   drag: true,
   afterSubmit: function (response, postdata) {
       if (response.responseText == "") {
           $(this).jqGrid('setGridParam', 
             { datatype: 'json' }).trigger('reloadGrid');//Reloads the grid after edit
           return [true, '']
       }
       else {
           $(this).jqGrid('setGridParam', 
             { datatype: 'json' }).trigger('reloadGrid'); //Reloads the grid after edit
           return [false, response.responseText]
           //Captures and displays the response text on th Edit window
       }
   },
   editData: {
       EmpId: function () {
           var sel_id = $('#jQGridDemo').jqGrid('getGridParam', 'selrow');
           var value = $('#jQGridDemo').jqGrid('getCell', sel_id, '_id');
           return value;
       }
   }
},
{//ADD portion
   closeAfterAdd: true,//Closes the add window after add
   afterSubmit: function (response, postdata) {
       if (response.responseText == "") {
           $(this).jqGrid('setGridParam', 
             { datatype: 'json' }).trigger('reloadGrid')//Reloads the grid after Add
           return [true, '']
       }
       else {
           $(this).jqGrid('setGridParam', 
             { datatype: 'json' }).trigger('reloadGrid')//Reloads the grid after Add
           return [false, response.responseText]
       }
   }
},
{   //DELETE
   closeOnEscape: true,
   closeAfterDelete: true,
   reloadAfterSubmit: true,
   closeOnEscape: true,
   drag: true,
   afterSubmit: function (response, postdata) {
       if (response.responseText == "") {
           $("#jQGridDemo").trigger("reloadGrid", [{ current: true}]);
           return [false, response.responseText]
       }
       else {
           $(this).jqGrid('setGridParam', { datatype: 'json' }).trigger('reloadGrid')
           return [true, response.responseText]
       }
   },
   delData: {
       EmpId: function () {
           var sel_id = $('#jQGridDemo').jqGrid('getGridParam', 'selrow');
           var value = $('#jQGridDemo').jqGrid('getCell', sel_id, '_id');
           return value;
       }
   }
},
{//SEARCH
   closeOnEscape: true
}
);

کد بالا کاملا گویاست. من کد های مورد نیاز برای ویرایش و حذف را هم در عکس بالا آورده ام. یکی از نکته های مهمی که قصد داشتم به آن اشاره کنم مربوط به ویرایش بود. زمانی که در حال اجرای عملیات ویرایش هستیم ، همواره Data را از طریق یک کلید اصلی به روز رسانی میکنیم. در اینجا کلید اصلی _id است. در زمان ویرایش یا به روز رسانی تنها فیلدی که قابل ویرایش علامتگذاری شده است ، به handler انتقال می یابد.

برای پاس دادن این _id به سرور از طریق JqGrid من از خصوصیت editData مربوط به JqGrid استفاده کردم. میتوانیم از خصوصیت JqGrid delData برای پاس دادن _id برای حذف مورد استفاده کنیم.

نکته : نه تنها _id را میتوانید پاس بدهید بلکه هر داده ی دیگری را که بخواهید میتوانید با کمک editData,delData به handler در فرمت JSON بدهید.

میتوانید این کار را در قطعه کد بالا مشاهده کنید. نکته ی قابل ذکر دیگر در اینجا دریافت داده از یک سلول به خصوص در JqGrid است.

var sel_id = $('#jQGridDemo').jqGrid('getGridParam', 'selrow');
//Gets the Id of selected row

var value = $('#jQGridDemo').jqGrid('getCell', sel_id, '_id');
//Gets the value of column of selectedrow.(_id is the na,e of the column). 
*******************************************************
Code in HTTP  handler
*******************************************************
public class JQGridHandler : IHttpHandler
{
    public void ProcessRequest(HttpContext context)
    {
        System.Collections.Specialized.NameValueCollection forms = context.Request.Form;
        string strOperation = forms.Get("oper");
        MONGOConnect objMC = new MONGOConnect();//Helper Class
        var collectionEmployee = 
          objMC.GetMongoCollection("EMPLOYEE");//Gets Employee Collection
        string strResponse = string.Empty;
        if (strOperation == null)
        {
            //oper = null which means its first load.
            var jsonSerializer = new JavaScriptSerializer();
            context.Response.Write(jsonSerializer.Serialize(
              collectionEmployee.AsQueryable<Employee>().ToList<Employee>()));
        }
        else if (strOperation == "del")
        {
            var query = Query.EQ("_id", forms.Get("EmpId").ToString());
            collectionEmployee.Remove(query);
            strResponse = "Employee record successfully removed";
            context.Response.Write(strResponse);
        }
        else
        {
             string strOut=string.Empty;
             AddEdit(forms, collectionEmployee, out strOut);
             context.Response.Write(strOut);
        }
                   
    }
    public bool IsReusable
    {
        get
        {
            return false;
        }
    }
    private void AddEdit(NameValueCollection forms, 
      MongoCollection collectionEmployee,out string strResponse)
    {
        string strOperation = forms.Get("oper");
        string strEmpId = string.Empty;
        if (strOperation == "add")
        {
             strEmpId = forms.Get("EmpId").ToString();
        }
        else if (strOperation == "edit")
        {
            var result = collectionEmployee.AsQueryable<Employee>().Select(c => c._id).Max();
             strEmpId = (Convert.ToInt32(result) + 1).ToString();
        }
       
        string strFirstName = forms.Get("FirstName").ToString();
        string strLastName = forms.Get("LastName").ToString();
        string strLastSSN = forms.Get("LastSSN").ToString();
        string strDepartment = forms.Get("Department").ToString();
        string strAge = forms.Get("Age").ToString();
        string strSalary = forms.Get("Salary").ToString();
        string strAddress = forms.Get("Address").ToString();
        string strMaritalStatus = forms.Get("MaritalStatus").ToString();
        Employee objEmp = new Employee();
        objEmp._id = strEmpId;
        objEmp.FirstName = strFirstName;
        objEmp.LastName = strLastName;
        objEmp.LastSSN = strLastSSN;
        objEmp.Department = strDepartment;
        objEmp.Age = Convert.ToInt32(strAge);
        objEmp.Address = strAddress;
        objEmp.MaritalStatus = strMaritalStatus;
        objEmp.Salary = strSalary;
        collectionEmployee.Save(objEmp);
        strResponse = "Employee record successfully updated";
    }
}

با توجه به مقدار درون strOperation(forms.Get(“oper”)) که null ، add ، edit و delete متن مرتبط با آن به عنوان response برگردانده میشود و عملیات مربوط به آن به اجرا میرسد.