A grid, in general, is similar to an Excel spreadsheet with headers per column and corresponding data per row or tuple. Customizations, edits, selections, and other forms of manipulations, such as calculations, can be carried out directly on the spreadsheet. Usually, such spreadsheets are used to gather information regarding a specific thing or event. The purpose of these grids is to visualize the relationships and correlation between data and, subsequently, to provide valuable information.
The wijgrid object is instantiated or, rather, created by the jquery.wijmo.wijgrid.js library.
First and foremost, wijgrid objects are dependent on the <table> HTML tag in a given document. So, we need to create a table and host our grid widget, the wijgrid object, on it. Here's one example of how to create a table in HTML:
//Example 1:
<table>
<thead>
<th>column0 Header</th>
<th>column1 Header</th>
</thead>
<tbody></tbody>
</table>Don't forget to wrap the preceding table code with the <html> and <body> tags.
Now that we have the table, we need to target it and host the wijgrid object on it. We can target any table in a given HTML document via jQuery as seen in the following example:
//Example 2:
$("table").wijgrid({
data: [[0, "x"], [1, "y"], [2, "z"]]
});Successfully running the preceding snippets of code, Example 1 and Example 2, will draw or display a Wijmo grid on your browser, having two columns and three rows similar to the following screenshot:
The code in Example 2 is the proper syntax for creating or hosting a wijgrid object on a table. The data property of the wijgrid function is an array with three data points. Each data point is an array, [0, "x"], [1, "y"], and [2, "z"]. The array count, or length for each array, signifies that we are going to have a grid with two columns and three (total number of arrays in data) rows, excluding the header. It is important to note that the table structure is only a framework for Wijmo to run on. Hence, the texts defined in the preceding <th> tags never get rendered. Wijmo parses these arrays by looking at the number of arrays in data, accounting for three rows, and each array in data being a row as follows:
Each array represents a row on the grid
Each data point in each array represents data for each column in the grid
Wijmo parses data and is quickly able to draw the resulting grid on your page, as seen in the preceding section.
Now let's use a better real-life example, incorporating all the Wijmo dependencies. Assume we have a group called "City Devs without Borders", and we want to create a grid of three people whose works have been significant in improving the security in Gotham city. We want a list of their names, dates of birth, and occupations in tabular format, which is best represented by a
wijgridobject.Type this code in your favorite editor:
<html> <head> <!--jQuery References--> <script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.7.1.min.js" type="text/javascript"></script> <script src="http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.17/jquery-ui.min.js" type="text/javascript"></script> <!--Wijmo Widgets JavaScript--> <script src="http://cdn.wijmo.com/jquery.wijmo-open.all.2.0.0.min.js" type="text/javascript"></script> <script src="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.0.0.min.js" type="text/javascript"></script> <!--Theme--> <link href="http://cdn.wijmo.com/themes/rocket/jquery-wijmo.css" rel="stylesheet" type="text/css" title="rocket-jqueryui" /> <!--Wijmo Widgets CSS--> <link href="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.0.0.min.css" rel="stylesheet" type="text/css" /> </head> <body> <table> <thead> <th>column0</th> <th>column1</th> </thead> <tbody> </tbody> </table> <script type="text/javascript"> var columns = [ { headerText: 'First Name', dataKey: 'firstName', dataType: 'string'}, { headerText: 'Last Name', dataKey: 'lastName', dataType: 'string' }, { headerText: 'Date of Birth', dateKey: 'DOB', dataType: 'string' }, { headerText: 'Occupation', dataKey: 'occupation', dataType: 'string' } ]; var content = [ { firstName: 'Tochi', lastName: 'Eke-Okoro', DOB: '08/21', occupation: 'UI Developer' }, { firstName: 'Ryan', lastName: 'Krest', DOB: '06/1', occupation: 'Attorney' }, { firstName: 'Bruce', lastName: 'Romeo', DOB: '02/26', occupation: 'US Navy' } ]; $("table").wijgrid({ columns: columns, data: content }); </script> </body> </html>Running the preceding code successfully will render a widget similar to this:
Again, here's a stepwise workflow of how the preceding wijgrid object was created in a nutshell:
Create an HTML table for
wijgridto hook on to.Create the columns and content to populate the grid. The column is an optional property of
wijgrid, which is an array of column objects. A column object also has optional properties, such asheaderText, which holds the string for the column header name;dataKey, which maps the column to a content property, such asfirstName; anddataType, which is the data's type, such asstring,dateTime, ornumber.Create the content. The content is an array of objects. Each object corresponds to the data for each row. Also, the column's
dataKeyproperty is usually mapped to one of the content properties.Finally, target the table and host the
wijgridobject on it. Set thewijgridobject's data option to our created content array. Also set thewijgridobject'scolumnsproperty to our createdcolumnsarray.Run the code to draw the
wijgridobject.
The wijgrid object provides options that add customizable features and functionalities to the grid. Some of these functionalities include things such as editing the grid via a simple click of the button, adding a row to the top of the grid, and adding a row of data to the bottom of the grid. Using JavaScript events, we can achieve this by listening to, say, a button being clicked.
Using the same example used previously, we are going to write functions to do the following:
Change the first name on the first row of the grid by clicking a button
Prepend a row of data to the top of the grid by clicking a button
Append a row of data to the bottom of the grid by clicking a button
Copy the following complete code into your editor:
<html>
<head>
<!--jQuery References-->
<script src="http://ajax.aspnetcdn.com/ajax/jquery/jquery-1.7.1.min.js" type="text/javascript"></script>
<script src="http://ajax.aspnetcdn.com/ajax/jquery.ui/1.8.17/jquery-ui.min.js" type="text/javascript"></script>
<!--Wijmo Widgets JavaScript-->
<script src="http://cdn.wijmo.com/jquery.wijmo-open.all.2.0.0.min.js" type="text/javascript"></script>
<script src="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.0.0.min.js" type="text/javascript"></script>
<!--Theme-->
<link href="http://cdn.wijmo.com/themes/rocket/jquery-wijmo.css" rel="stylesheet" type="text/css" title="rocket-jqueryui" />
<!--Wijmo Widgets CSS-->
<link href="http://cdn.wijmo.com/jquery.wijmo-complete.all.2.0.0.min.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table>
<thead>
<th>column0</th>
<th>column1</th>
</thead>
<tbody>
</tbody>
</table><p></p>
<button style="clear:both;" id="btnUpdate">Update First Name</button>
<button style="clear:both;" id="btnPrepend">Add Row to Grid Top</button>
<button style="clear:both;" id="btnAppend">Add Row to Grid Bottom</button>
<script type="text/javascript">
var columns = [
{ headerText: 'First Name', dataKey: 'firstName', dataType: 'string'},
{ headerText: 'Last Name', dataKey: 'lastName', dataType: 'string' },
{ headerText: 'Date of Birth', dateKey: 'DOB', dataType: 'string' },
{ headerText: 'Occupation', dataKey: 'occupation', dataType: 'string' }
];
var content = [
{
firstName: 'Tochi',
lastName: 'Eke-Okoro',
DOB: '08/21',
occupation: 'UI Developer'
},
{
firstName: 'Ryan',
lastName: 'Krest',
DOB: '06/1',
occupation: 'Attorney'
},
{
firstName: 'Bruce',
lastName: 'Romeo',
DOB: '02/26',
occupation: 'US Navy'
}
];
$("table").wijgrid({
columns: columns,
data: content
});
var newPerson = {
firstName: 'Empty firstname to update later',
lastName: 'Empty lastname to update later',
DOB: (new Date).toString(),
occupation: 'Empty occupation to update later'
}
var $obj = $("table");
$("#btnUpdate").click(function() {
data = $obj.wijgrid("data");
if(data[0].firstName == "Mije")
alert('SORRY!! First name already set to Mije') ;
data[0].firstName = "Mije";
$obj.wijgrid("ensureControl", true);
});
$("#btnPrepend").click(function() {
data = $obj.wijgrid("data");
data.unshift(newPerson); //prepend data or object to array
$obj.wijgrid("ensureControl", true);
});
$("#btnAppend").click(function() {
data = $obj.wijgrid("data");
data.push(newPerson); //append data or object to array
$obj.wijgrid("ensureControl", true);
});
</script>
</body>
</html>If the preceding code is run successfully on your browser, after pressing one of the buttons you will see a Wijmo grid similar to the following screenshot:
Let us go through the code one more time, focusing on the differences between it and the previous static wijgrid void of buttons.
Clicking on the Update First Name button will always update the first name in the first row to Mije, and if it is already set to Mije, it will alert the SORRY message.
Clicking on the Add Row to Grid Top button will prepend the dummy data, programmatically referenced by
newPerson, to thewijgridobject. ThenewPersonobject contains data for each column, including the date of birth, which in this case has been defaulted to the entry date (now) of this row, captured innew Date. For future programming exercises, or self-supervised tryouts, you could try writing functions to edit each cell of the row.Clicking on the Add Row to Grid Bottom button will append the dummy data (the same dummy data mentioned previously), referenced by
newPerson, to thewijgridobject.The
$obj.wijgrid("ensureControl", true)object ensures that we have the permission to control the Wijmo grid, else we won't see or notice any changes when the buttons are clicked.
Now we know how to edit the wijgrid object by writing functions that trigger those updates when certain events occur, for example, the click of a button. Let us see a pretty hassle-free way of editing the grid right on wijgrid itself. This is similar to editing the cell just like you would in an Excel spreadsheet, by double-clicking on it.
Change the preceding code to the following:
$("table").wijgrid({
columns: columns,
data: content,
allowEditing: true
});This will make every cell editable by simply double-clicking on it. Here is a list of cool options to further customize your wijgrid object:
$("#table").wijgrid({ allowKeyboardNavigation: true}); //allows keyboard navigation
$("#table").wijgrid({ allowPaging: true}); //allows pagination on wijgrid
$("#table").wijgrid({ allowSorting: true}); //allows wijgrid to be sorted
$("#table").wijgrid({ culture: "en"}); //sets the culture ID of the wijgrid
$("#table").wijgrid({ loadingText: "I'm Loading…"}); //sets the loading textVisit http://wijmo.com/wiki/index.php/Grid for more information about Wijmo grids