Grid: Overview | JavaScript UI

Grid Overview

The w2grid implements data grids with local or remote data source. The grid is the most complex and flexible control in w2ui. It is the most feature rich grid available.

Example 1 - local data source
Example 2 - remove data source
Request Data Structure
Response Data Structure
Delete Request
Save Request

Example 1 - Local Data Source

Below is a simple example how to use the grid. This grid does not pull records from the server, but uses local data source. It shows the minimum HTML and JavaScript you need to have to display the grid.

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css"
        href="https://rawgit.com/vitmalina/w2ui/master/dist/w2ui.min.css" />
</head>
<body>
    <div id="myGrid" style="height: 450px"></div>
</body>
<script type="module">
import { w2grid } from 'https://rawgit.com/vitmalina/w2ui/master/dist/w2ui.es6.min.js'
let grid = new w2grid({
    name: 'myGrid',
    columns: [
        { field: 'fname', text: 'First Name', size: '30%' },
        { field: 'lname', text: 'Last Name', size: '30%' },
        { field: 'email', text: 'Email', size: '40%' },
        { field: 'sdate', text: 'Start Date', size: '120px' },
    ],
    records: [
        { recid: 1, fname: 'John', lname: 'Doe', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 2, fname: 'Stuart', lname: 'Motzart', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 3, fname: 'Jin', lname: 'Franson', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 4, fname: 'Susan', lname: 'Ottie', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 5, fname: 'Kelly', lname: 'Silver', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 6, fname: 'Francis', lname: 'Gatos', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 7, fname: 'Mark', lname: 'Welldo', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 8, fname: 'Thomas', lname: 'Bahh', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 9, fname: 'Sergei', lname: 'Rach', email: 'jdoe@gmail.com', sdate: '4/3/2012' }
    ]
})
grid.render('#myGrid')
</script>
</html>

​x
 
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css"
        href="https://rawgit.com/vitmalina/w2ui/master/dist/w2ui.min.css" />
</head>
<body>
    <div id="myGrid" style="height: 450px"></div>
</body>
<script type="module">
import { w2grid } from 'https://rawgit.com/vitmalina/w2ui/master/dist/w2ui.es6.min.js'
let grid = new w2grid({
    name: 'myGrid',
    columns: [
        { field: 'fname', text: 'First Name', size: '30%' },
        { field: 'lname', text: 'Last Name', size: '30%' },
        { field: 'email', text: 'Email', size: '40%' },
        { field: 'sdate', text: 'Start Date', size: '120px' },
    ],
    records: [
        { recid: 1, fname: 'John', lname: 'Doe', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 2, fname: 'Stuart', lname: 'Motzart', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 3, fname: 'Jin', lname: 'Franson', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 4, fname: 'Susan', lname: 'Ottie', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 5, fname: 'Kelly', lname: 'Silver', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 6, fname: 'Francis', lname: 'Gatos', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 7, fname: 'Mark', lname: 'Welldo', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 8, fname: 'Thomas', lname: 'Bahh', email: 'jdoe@gmail.com', sdate: '4/3/2012' },
        { recid: 9, fname: 'Sergei', lname: 'Rach', email: 'jdoe@gmail.com', sdate: '4/3/2012' }
    ]
})
grid.render('#myGrid')
</script>
</html>
​

Example 2 - Remote Data Source

This example displays similar grid as the example above, but it retrieves records from the server. It assumes that you have a file data/records.json relative to where your example runs that returns JSON structure.

xxxxxxxxxx
 
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css"
        href="https://rawgit.com/vitmalina/w2ui/master/dist/w2ui.min.css" />
</head>
<body>
    <div id="myGrid" style="height: 450px"></div>
</body>
<script type="module">
import { w2grid } from 'https://rawgit.com/vitmalina/w2ui/master/dist/w2ui.es6.min.js'
let grid = new w2grid({
    name: 'myGrid',
    url: 'data/records.json',
    columns: [
        { field: 'fname', text: 'First Name', size: '30%' },
        { field: 'lname', text: 'Last Name', size: '30%' },
        { field: 'email', text: 'Email', size: '40%' },
        { field: 'sdate', text: 'Start Date', size: '120px' }
    ]
})
grid.render('#myGrid')
</script>
</html>
​

Request Data Structure

The grid communicates with the server by sending a HTTP request in the format displayed below. Keep in mind that not all of the parameters are sent with each requests. Parameters such as search, sort, etc. might not be submitted if user did not apply them. The grid will also submit all user defined parameters from the .postData map.

If w2utils.settings.dataType = 'HTTPJSON' (default), the request will be:

xxxxxxxxxx
 
request: {
    "limit":100,
    "offset":0,
    "searchLogic":"AND",
    "search":[
        {"field":"age", "type":"int", "operator":"between", "value":[10,20]},
        {"field":"fname", "type":"text", "operator":"begins", "value":"vit"}
    ],
    "sort":[
        {"field":"fname", "direction":"asc"},
        {"field":"lname", "direction":"asc"}
    ]
}
​

However, you can control how you want request data to be encoded. See w2utils.settings - see dataType.

Response Data Structure

The grid expects data in the JSON format from the server as it is described below.

xxxxxxxxxx
 
{
    "status": "success",
    "total": 36,  // can be -1 (or unset) to indicate that total number is unknown
    "records": [
        { "recid": 1, "field-1": "value-1", ... "field-N": "value-N" },
        ...
        { "recid": N, "field-1": "value-1", ... "field-N": "value-N" }
    ],
    /* optional */
    "summary": [
        { "recid": s1, "field-1": "value-1", ... "field-N": "value-N" }
    ]
}
​

You can define grid's .onRequest and .onLoad events to do data conversion if you service returns format different from JSON (for example XML).

If you want to return an error and have grid display in, you can return following JSON structure:

xxxxxxxxxx
 
{
    "status": "error",
    "message": "Error Message"
}
​

Delete Records

If user selects several records in the grid and clicks the delete button on the toolbar or if you call .delete() method, the grid will send following request

xxxxxxxxxx
 
request: {
    "action":"delete",
    "recid": [1,2]
}
​

The ressponse can be

xxxxxxxxxx
 
{
    "status" : "success"
}
​

xxxxxxxxxx
 
{
    "status": "error",
    "message": "Error Message"
}
​

Save Records

As a developer you can turn on inline editing in the grid. Once user has changed data and click the Save button, the grid will send

xxxxxxxxxx
 
request: {
    "action":"save"
    "changes":[
        { "userid":1, "lname":"Cruze", "fname":"Tom" }
    ]
}
​