Thank you for purchasing Arthaus Custom Grid. If you have any questions that have not been answered below, or you didn't find the answer in our demo project, feel free to contact us via our CodeCanyon account.

Thanks again!

To be able to use CustomGrid control you need to have the following software components:

• Microsoft Visual Studio 2010 or later version
• ASP.NET MVC
• MSSQL server or another database server as optional component
• CustomGrid.dll reference included in your project
• Newtonsoft.Json reference included in your bin
• jQuery 1.5 or above
• jQuery UI 1.8 or above
• jQuery ContextMenu script
• CustomGrid CSS file

Step One - Adding CustomGrid.dll reference

The image below shows an example for adding a reference to the Arthaus CustomGrid component in your project.

Step Two - Adding required JavaScript and CSS files

Below is HTML example of required JavaScript and CSS file references for this grid to run properly:

<link href="Content/CustomGrid.css" rel="stylesheet" type="text/css" />
<link href="Content/jquery-ui-1.8.12.css" rel="stylesheet" type="text/css" />
<script src="Scripts/jquery-1.5.1.min.js" type="text/javascript"></script>    
<script src="Scripts/jquery-ui-1.8.12.min.js" type="text/javascript"></script>
<script src="Scripts/jquery.contextMenu.js" type="text/javascript"></script>
										

Step Three - Adding CustomGrid Folder

Create a folder with name "CustomGrid". The folder needs to have write permissions so that CustomGrid.js is generated. Once it is generated you can remove the write permissions.

The CustomGrid allows you to easily support any number of languages. Language strings are stored in .json files within the CustomGrid/Language directory.

You should save one .json file for each supported language. The files should be named according to the predefined CultureInfo names and identifiers accepted and used by CultureInfo Class in the System.Globalization namespace.

You can see a sample .json file here.

You can see the table of language Culture Names here.

The CustomGrid class has static method for Drawing the Grid, methods for creating grid columns and 2 static methods for generating the grid paging. In continuation are given the definitions of the CustomGrid methods.

The data displayed in grid cells can be formatted very simply. The cell formatting is using .NET String.Format static method, which means everything specified in columns html parameter can be formatted by using the values from fieldNames array.

Below is an example of source code for formatting the "ID" column with a leading zeros, date formatting, double value formatting and currency formatting.

@CustomGrid.CustomGrid.DrawGrid("cl", Model,
    CustomGrid.CustomGrid.columns(
        CustomGrid.CustomGrid.column("ID", "{0:000000}, {1:n}", new string[]{"ID", "DoubleValue"}, true, "right"),
        CustomGrid.CustomGrid.column("Date Created", "{0:yyyy-MM-dd}", new string[] { "DateCreated" }, true, "left", "date"),     
        CustomGrid.CustomGrid.column("Double Value", "<span style='color:green'>{0:n}</span> or {0:c}", new string[] { "DoubleValue" }, true, "right", "number")    
    ), Request.QueryString)

Currently there are 2 types of paging available, "classic" paging and "scroll" paging.

Classic Paging

If we want to add a classic paging to the grid, we can use the following code:

@CustomGrid.CustomGrid.PagingNumbers("cl", Request.QueryString, ViewBag.totalRecords, "20")

In the above example, the first parameter is "gridID" and it needs to be the same as gridID used in DrawGrid method, the second parameter is the NameValueCollection of the Query string, the third parameter is total number of records, and the last parameter is the number of records per page.

Now the complete source of the grid and the paging will be:

@CustomGrid.CustomGrid.DrawGrid("cl", Model,
	CustomGrid.CustomGrid.columns(
		CustomGrid.CustomGrid.column("First Name", "<a href='/Users/Details/?id={1}'>{0}</a>", new string[] { "FirstName", "ID" }, true, "left", "text"),
		CustomGrid.CustomGrid.column("Last Name", "LastName", true, "left", "text"),
		CustomGrid.CustomGrid.column("Date Created", "{0:yyyy-MM-dd}", new string[] { "DateCreated" }, true, "left", "date"),     
		CustomGrid.CustomGrid.column("User Type", "<a href='/Users/Details/?id={1}'>{0}</a>", new string[] { "UserType", "ID" }, new CustomGrid.DropDownList[] { new CustomGrid.DropDownList() { optionID = "Admin", optionValue = "Admin" }, new CustomGrid.DropDownList() { optionID = "Member", optionValue = "Member" } }, true, "center"),
		CustomGrid.CustomGrid.column("Decimal Value", "<span style='color:green'>{0:c}</span>", new string[] { "DoubleValue" }, true, "right", "number")
	), Request.QueryString)
@CustomGrid.CustomGrid.PagingNumbers("cl", Request.QueryString, ViewBag.totalRecords, "20")

The output with the "classic" paging is shown below:

Scroll Paging

The advanced paging has option for selecting a number of records per page. The paging is done via "jquery" scroller which produces great visual effects to the users.

The usage of the advanced paging is "almost" the same as the classic paging, the only difference is the name of the method. Instead of "PagingNumbers" which is the classic paging, the method for advanced paging is "PagingScroll".

If we change the above source code to the following:

@CustomGrid.CustomGrid.DrawGrid("cl", Model,
    CustomGrid.CustomGrid.columns(
        CustomGrid.CustomGrid.column("First Name", "<a href='/Users/Details/?id={1}'>{0}</a>", new string[] { "FirstName", "ID" }, true, "left", "text"),
        CustomGrid.CustomGrid.column("Last Name", "LastName", true, "left", "text"),
        CustomGrid.CustomGrid.column("Date Created", "{0:yyyy-MM-dd}", new string[] { "DateCreated" }, true, "left", "date"),     
        CustomGrid.CustomGrid.column("User Type", "<a href='/Users/Details/?id={1}'>{0}</a>", new string[] { "UserType", "ID" }, new CustomGrid.DropDownList[] { new CustomGrid.DropDownList() { optionID = "Admin", optionValue = "Admin" }, new CustomGrid.DropDownList() { optionID = "Member", optionValue = "Member" } }, true, "center"),
        CustomGrid.CustomGrid.column("Decimal Value", "<span style='color:green'>{0:c}</span>", new string[] { "DoubleValue" }, true, "right", "number")
    ), Request.QueryString)
@CustomGrid.CustomGrid.PagingScroll("cl", Request.QueryString, ViewBag.totalRecords, "20")

In the browser it will look like the image below:

CustomGrid.css file contains the grid css classes. They are grouped in 5 categories:

1. Main table, header and row classes
2. Sorting classes for the header
3. Filter classes
4. Paging classes
5. Context menu classes

Each grid action is sending an ajax GET request to the server. Below is list of the all possible form elements, their names and possible values they can have.

The grid is using two type of forms:

<-- Filter form: -->
<form method="get" id="frm_GRIDID">
	...
</form>
<-- Paging form: -->
<form method="get" id="frmP_GRIDID">
	...
</form>

Filter form ID always starts with "frm_" and then is concatenated with GRIDID which is the grid ID added to each form and form field. This way you can have multiple different grids on same page. Paging form ID always starts with "frmP_" and then concatenated with GRIDID.

No matter which form is submitted, both have the same form fields, with same name syntax:

<-- text and number filter fields -->
<input id="GRIDID_FIELDNAME" name="GRIDID_FIELDNAME" type="text" />
<input id="GRIDID_o_FIELDNAME" name="GRIDID_o_FIELDNAME" type="hidden" />
<-- drop down filter fields -->
<select id="GRIDID_FIELDNAME" name="GRIDID_FIELDNAME">
<-- date filter fields -->
<input id="GRIDID_from_FIELDNAME" name="GRIDID_from_FIELDNAME" type="text" />
<input id="GRIDID_to_FIELDNAME" name="GRIDID_to_FIELDNAME" type="text" />
<-- paging fields for page size and page number: -->
<select name="GRIDID_pages">
<input id="GRIDID_page" name="GRIDID_page" type="hidden" />

Selected filter options from Context menu are kept in the hidden fields for each text and number filter (name="GRIDID_o_FIELDNAME"). Here is a list of all possible values and their meaning:

// Text filters:
"sf_1": Contains
"sf_2": Not contains
"sf_3": Starts with
"sf_4": Ends with
"sf_5": Equals to
"sf_6": Not equals to
// Number Filters:
"sf_7": Equals to
"sf_8": Not equals to
"sf_9": Is less then
"sf_10": Is less then or equal to
"sf_11": Is greater then
"sf_12": Is greater then or equal to
"sf_13": Between
"sf_14": Not between
// Both Filters:
"sf_15": Is null
"sf_16": Is not null

For example if your "query string" on server side has the following code: MyGrid_FisrtName=Test&MyGrid_o_FisrtName=sf_4 it means that you need to search all first names in your data collection that end with "Test".

The server side processing is completely left in your hands. This grid is only displaying data that you will provide, and is sending back to the server user's actions on the grid. The way you will retrieve, filter, sort and paginate your data is your code responsibility.

In order to make this product more user friendly, we are delivering it with sample demo MVC3 project that has different types of grid examples. We are also suggesting two server side dynamic query generation techniques for easy filtering, sorting and paging.

LINQ approach with Microsoft DynamicQueryable class

To make the process of getting filter values easier, we have developed a helper class "QueryParams". This class is already included in CustomGrid component, but the code is also available as helper class within this demo project, so you can easily change the code and adapt it to your needs.

Controller:

public ActionResult SampleGrid6()
{
    //database connection object defined in User model
    SampleSQLDB db = new SampleSQLDB();
    //get paging values from the query string
    int pageNum = CustomGrid.QueryParams.getPageNumber("cl" Request.QueryString);
    int pageSize = CustomGrid.QueryParams.getPageSize("cl", Request.QueryString);
    //get sorting values from query string
    string sort = CustomGrid.QueryParams.getSortField("cl", Request.QueryString, new User(), "ID");
    string stype = CustomGrid.QueryParams.getSortType("cl", Request.QueryString);
    //get filter where conditions and values from the query string
    List<object> whereValues = new List<object>();
    string whereConditions = "";
    whereConditions += CustomGrid.QueryParams.getLINQQueryParam("cl", "FirstName", Request.QueryString, whereValues);
    whereConditions += CustomGrid.QueryParams.getLINQQueryParam("cl", "LastName", Request.QueryString, whereValues);
    whereConditions += CustomGrid.QueryParams.getLINQQueryParam("cl", "DateCreated", Request.QueryString, whereValues);
    whereConditions += CustomGrid.QueryParams.getLINQQueryParam("cl", "UserType", Request.QueryString, whereValues);
    whereConditions += CustomGrid.QueryParams.getLINQQueryParam("cl", "DoubleValue", Request.QueryString, whereValues);
    //get data from database
    var sampleUser = db.Users.Select(i => i);
    sampleUser = sampleUser.AsQueryable().Where("1=1 " + whereConditions, whereValues.ToArray()).OrderBy(sort + " " + stype);
    //count the total number of records
    ViewBag.totalRecords = sampleUser.Count();            
    //get only required page data by skiping the other records
    sampleUser = sampleUser.Skip(pageSize * (pageNum-1)).Take(pageSize);
    return View(sampleUser.ToList());
}

View:

@CustomGrid.CustomGrid.DrawGrid("cl", Model,
        CustomGrid.CustomGrid.columns(            
        CustomGrid.CustomGrid.column("First Name", "FirstName", true, "left", "text"),
        CustomGrid.CustomGrid.column("Last Name", "LastName", true, "left", "text"),
        CustomGrid.CustomGrid.column("Date Created", "DateCreated", true, "left", "date"),
        CustomGrid.CustomGrid.column("User Type", "UserType", new CustomGrid.DropDownList[] { new CustomGrid.DropDownList() { optionID = "Admin", optionValue = "Admin" }, new CustomGrid.DropDownList() { optionID = "Member", optionValue = "Member" } }, true, "center"),            
        CustomGrid.CustomGrid.column("Email", "Email", true, "left", "text")
        
    ), Request.QueryString)
@CustomGrid.CustomGrid.PagingScroll("cl", Request.QueryString, ViewBag.totalRecords, "20")

SQL Query approach

Most of the code is same as in previous example, except that in this approach we are generating sql query with all included conditions for filtering, sorting and paging.

Part of the controller's code:

//get filter where conditions from query string
string whereConditions = "";
whereConditions += CustomGrid.QueryParams.getQueryParam("cl", "FirstName", Request.QueryString);
whereConditions += CustomGrid.QueryParams.getQueryParam("cl", "LastName", Request.QueryString);
whereConditions += CustomGrid.QueryParams.getQueryParam("cl", "DateCreated", Request.QueryString);
whereConditions += CustomGrid.QueryParams.getQueryParam("cl", "UserType", Request.QueryString);
whereConditions += CustomGrid.QueryParams.getQueryParam("cl", "DoubleValue", Request.QueryString);
//get data from database
int totalRecords = 0;
var sampleUser = db.getUsers(pageStart, pageEnd, sort, stype, whereConditions, out totalRecords).ToList();
ViewBag.totalRecords = totalRecords;

User Model:

public IEnumerable<User> getUsers(int startRow, int endRow, string sort, string sorttype, string conditions, out int totalRecords)
{
    //count all records
    var maxRowNumber = this.ExecuteQuery<int>(@"
        SELECT COUNT(ID) as cnt FROM Users WHERE 1=1 " + conditions
        );
    //get the total number of records
    totalRecords = maxRowNumber.SingleOrDefault();
    //select users with paging and sorting
    return this.ExecuteQuery<User>(@"                                            
        SELECT subquery.* FROM (
             
            SELECT *, ROW_NUMBER() OVER(ORDER BY " + sort + " " + sorttype + @") AS rowNumber
            FROM Users
            WHERE 1=1 " + conditions + @"
        ) AS subquery
        WHERE rowNumber BETWEEN {0} AND {1}", startRow, endRow);
}

Because it is not using prepare statement for query variables, this approach has potential query injection problem which is fixed by using the QueryParams.getQueryParam method for getting the values from the query string.

The demo project has couple of examples of how this grid can be used within a MVC project. Below is short explanation of each project folder/file and its purpose.

• /App_Data/SampleUser.mdf This is sample MSSQL Express database. All examples in the project are using this database
• /Content/ The folder where all images and css files used in this project are saved, including CustomGrid.css file where you can find all grid css classes
• /Controller/HomeController.cs The main project controller with different types of examples
• /Helpers/DynamicQueryable.cs This is DynamicQueryable class from Microsoft, that can be used for generating dynamic linq where conditions
• /Helpers/QueryParams.cs This is custom made class from Arthaus for easier processing query parameters for the sql queries. The same class is integrated in the CustomGrid control, but feel free to change anything if you need any custom modifications for your project.
• /Scripts/ The folder where JavaScript files used in this project are saved
• /Views/ The folder containing all MVC view files