Documentation

API Summary
Initial Parameters

Column Parameters

Met

caption

type

isRe

initRows

name

isDa

initData

value

load

columns

display

appe

i18n

displayCss

inser

idPrefix

headerSpan

remo

rowDragging

cellCss

mov

hideButtons

ctrlAttr

mov

buttonClasses

ctrlProp

getR

hideRowNumColumn

ctrlCss

getU

rowButtonsInFront

ctrlClass

getR

customGridButtons

ctrlOptions

getR

customRowButtons

invisible

getA

customFooterButtons

resizable

getC

nameFormatter

uiOption

setC

dataLoaded

uiTooltip

getC

afterRowAppended

customBuilder

getC

afterRowInserted

customGetter

getR

afterRowSwapped

customSetter

getC

afterRowDragged

onClick

show

beforeRowRemove

onChange

hide

afterRowRemoved
Initial Parameters

caption

isCo

Type: String
Default: null
The text as table caption. Set null to disable caption generation.

initRows
Type: Number
Default: 3
The total number of empty rows generated when init the grid. This will be
ignored if initData is assigned.

initData
Type: Array
Default: null
An array of data to be filled after initialized the grid.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
initData: [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }

10
11
12
13
14

]
});
});

columns
Type: Array
Default: null
Array of column options. Please refer to Column Parameters for more.
Example:
?

1
2$(function() {
$('#tblAppendGrid').appendGrid({
3
columns: [
4
{ name: 'Album', type: 'text', display: 'Album', ctrlAttr: { maxlength: 100 }
{ name: 'Artist', type: 'select', display: 'Artist', ctrlOptions: { 0: '{Choo
5
{ name: 'Year', type: 'ui-spinner', display: 'Year', value: new Date().getFull
6
]
7
});
8});
9

i18n
Type: Object
Default: null
Labels or messages used in grid.

append:

The tooltip on the `append` button at the bottom of grid.

removeLast: The tooltip on the `remove` button at the bottom of grid.

insert:

The tooltip on the `insert` button at the end on each row.

remove:

The tooltip on the `remove` button at the end on each row.

moveUp:

The tooltip on the `move up` button at the end on each row.

moveDown: The tooltip on the `move down` button at the end on each row.
rowDrag:

The tooltip on the `drag` button at the end on each row, if rowDragging is set
to true.

rowEmpty: The message to be displayed when no rows in grid.

Example:
?
1
2
3
4
5
6
7
8
9
10
11
12
13

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
i18n: {
append: 'Hey! Append a new row at bottom!',
removeLast: 'Caution! Remove the last row!'
}
});
});

idPrefix
Type: String
Default: null
The ID prefix of controls generated inside the grid. Table ID will be used if
not defined.
Example:
?
1
2
3
4
5
6
7
8
9
10
11

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
idPrefix: 'HelloTable'
});
// The field id and name will be generated as `HelloTable_Album_1`.
});

rowDragging
Type: Boolean
Default: false
Applying jQuery UI Sortable feature to allow re-order grid rows by
dragging.

hideButtons

Type: Object
Default: null
Hide the standard action buttons at the end of row or bottom of grid.
append:

Set to true to hide the `append` button at the bottom or grid.

removeLast: Set to true to hide the `remove` button at the bottom of grid.
insert:

Set to true to hide the `insert` button at the end on each row.

remove:

Set to true to hide the `remove` button at the end on each row.

moveUp:

TheSet to true to hide the `move up` button at the end on each row.

moveDown: Set to true to hide the `move down` button at the end on each row.

Example:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
hideButtons: {
remove: true,
removeLast: true
}
// Remove buttons will not be displayed
});
});

buttonClasses
Type: Object
Default: null
The extra class names for buttons.
append:

The extra class name to be added on the `append` button at the bottom of grid.

removeLast: The extra class name to be added on the `remove` button at the bottom of grid.
insert:

The extra class name to be added on the `insert` button at the end on each
row.

remove:

The extra class name to be added on the `remove` button at the end on each
row.

moveUp:

The extra class name to be added on the `move up` button at the end on each
row.

moveDown: The extra class name to be added on the `move down` button at the end on
each row.
rowDrag:

The extra class name to be added on the `drag` button at the end on each row,
if rowDragging is set to true.

Example:
?
1
2
3
4
5
6

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
buttonClasses: {

7
8
9
10
11
12
13

insert: 'extra1 extra2',

moveUp: 'extra3'
}
});
});

hideRowNumColumn
Type: Boolean
Default: false
Hide the row number column which is the first column of grid.

rowButtonsInFront
Type: Boolean
Default: false
Generate row button column in the front of input columns.

customGridButtons
Type: Object
Default: null
Customize the standard grid button such as changing the icon, adding text
to the button or even use another button to replace the default one. You

can specify jQuery UI Button initial parameter, a DOM element or a

function that create a DOM element for each of the following button.
append:

The jQuery UI button initial parameter or DOM element or a function that

create a DOM element as the `append` button at the bottom of grid.

removeLast: The jQuery UI button initial parameter or DOM element or a function that
create a DOM element as the `remove` button at the bottom of grid.
insert:

The jQuery UI button initial parameter or DOM element or a function that

create a DOM element as the `insert` button at the end on each row.

remove:

The jQuery UI button initial parameter or DOM element or a function that

create a DOM element as the `remove` button at the end on each row.

moveUp:

The jQuery UI button initial parameter or DOM element or a function that

create a DOM element as the `move up` button at the end on each row.

moveDown: The jQuery UI button initial parameter or DOM element or a function that
create a DOM element as the `move down` button at the end on each row.

Example:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
customGridButtons: {
// Use jQuery UI Button initial parameter
append: { icons: { primary: 'ui-icon-star' }, text: true, la
// Use a DOM element
insert: $('
<button>').text('Insert').get(0),
// Use a function that create DOM element
moveUp: function (){
var button = document.createElement('input');
button.type = 'button';

button.value = '^^^';
return button;

15
16
17
18
19
20
21
22
23
24

}
}
});
});
</button>

customRowButtons
Type: Array
Default: null
Add an array of customized buttons to the last cell of each row. The
generated buttons are supported all jQuery UI Button widget parameters
with a click event handler.
uiButton:

Required. Object of parameters used to initial jQuery UI Button widget.

click:

Required. A event handler to be called when the generated button is clicked.

Followings are the parameters will be sent to this event handler:
1. evtObj: The standard jQuery event object.
2. uniqueIndex: The uniqueIndex of that row.
3. rowData: An object contains the values of all controls of that row.

btnCss:

The extra CSS to be added on the generated button.

btnClass:

The extra classes to be added on the generated button.

btnAttr:

The extra attributes to be added on the generated button.

atTheFront: Set to true for generate button at the front of standard action buttons.

Example:
?

1
2 $(function() {
$('#tblAppendGrid').appendGrid({
3
columns: [
4
{ name: 'Album', display: 'Album' },
5
{ name: 'Artist', display: 'Artist' },
6
{ name: 'Year', display: 'Year' }
],
7
customRowButtons: [
8
{ uiButton: { icons: { primary: 'ui-icon-star' }, text: false }, click: setFa
9 true },
10
{ uiButton: { icons: { primary: 'ui-icon-print' }, label: 'Print' }, click: f
btnClass:
'print'
}
11
]
12
13}); });
14function setFavorite(evtObj, uniqueIndex, rowData) {
15
alert('I know you love this album now :)');
// Check the caller button exist in event object
16
if (evtObj && evtObj.target) {
17
// Do something on the button, such as disable the button
18
$(evtObj.target).button('disable');
19
}
20}
21

customFooterButtons
Type: Array
Default: null
Add an array of customized buttons to the bottom of grid. The generated
buttons are supported all jQuery UI Button widget parameters with a click
event handler.
uiButton:

Required. Object of parameters used to initial jQuery UI Button widget.

click:

Required. A event handler to be called when the generated button is clicked.

The first parameter of the call back function is the standard jQuery event
object.

btnCss:

The extra CSS to be added on the generated button.

btnClass:

The extra classes to be added on the generated button.

btnAttr:

The extra attributes to be added on the generated button.

atTheFront: Set to true for generate button at the front of standard action buttons.

Example:
?

1 $(function() {
2
$('#tblAppendGrid').appendGrid({
columns: [
3
{ name: 'Album', display: 'Album' },
4
{ name: 'Artist', display: 'Artist' },
5
{ name: 'Year', display: 'Year' }
6
],
customFooterButtons: [
7
{ uiButton: { icons: { primary: 'ui-icon-refresh' }, label: 'Refresh' }, btnC
8
button!'); }, atTheFront: true },
9
{ uiButton: { icons: { primary: 'ui-icon-arrowthickstop-1-s' }, text: false }
10process...'); } }
11
]
});
12
13});

nameFormatter(idPrefix, name, uniqueIndex)

Type: Function
The callback function for format the HTML name of generated controls.

idPrefix:

The idPrefix defined in Initial Parameters.

name:

The name of column.

uniqueIndex: The unique index assigned to this row.

Example:
?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
nameFormatter: function (idPrefix, name, uniqueIndex) {
// It is OK to just use the `name` to name the control.
// So, server side can receive values in array format.
// The generated elements will be something like that:
//
// <input id="tblAppendGrid_Album_1" name="Album" type="text" />
// <input id="tblAppendGrid_Album_2" name="Album" type="text" />
// <input id="tblAppendGrid_Album_3" name="Album" type="text" />
//
// C#/ASP.NET
// string[] albums = Request.Form.GetValues("Album");
//
// PHP
// $albums = $_POST['Album'];
//
return name;
}
});
});

dataLoaded(caller)

Type: Function
The callback function to be triggered after data loaded to grid.
caller: The table object that triggered this event.

afterRowAppended(caller, parentRowIndex, addedRowIndex)

Type: Function
The callback function to be triggered after new row appended.
caller:

The table object that triggered this event.

parentRowIndex: The index of row that above new added rows. This value will be null
when table is empty.
addedRowIndex: An array of row index added.

Example:
?
1
2
3
4
5
6
7
8
9
10

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
afterRowAppended: function (caller, parentRowIndex, addedRowIndex) {
// Copy data of `Year` from parent row to new added rows
var parentValue = $(caller).appendGrid('getCtrlValue', 'Year', parentRow
for (var z = 0; z < addedRowIndex.length; z++) {
$(caller).appendGrid('setCtrlValue', 'Year', addedRowIndex[z], paren

11
12
13
14
15
16

}
}
});
});

afterRowInserted(caller, parentRowIndex, addedRowIndex)

Type: Function
The callback function to be triggered after new row inserted.
caller:

The table object that triggered this event.

parentRowIndex: The index of row that above new added rows. This value will be null
when inserting a row in front of the first row.
addedRowIndex: An array of row index added.

afterRowSwapped(caller, oldRowIndex, newRowIndex)

Type: Function
The callback function to be triggered after grid row swapped.
caller:

The table object that triggered this event.

oldRowIndex: The old row index of swapped row.

newRowIndex: The new row index of swapped row.

afterRowDragged(caller, rowIndex, uniqueIndex)

Type: Function
The callback function to be triggered after grid row dragged.
caller:

The table object that triggered this event.

rowIndex: The row index of dragged row.

beforeRowRemove(caller, rowIndex)
Type: Function
The callback function to be triggered before grid row removed. Return
`false` to terminate row moving process.
caller:

The table object that triggered this event.

rowIndex: The row index to be removed.

Example:
?

1
2
3
4
5
6
7
8
9
10
11
12

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
beforeRowRemove: function (caller, rowIndex) {
return confirm('Are you sure to remove this row?');
}
});
});

afterRowRemoved(caller, rowIndex)
Type: Function
The callback function to be triggered after grid row removed.
caller:

The table object that triggered this event.

rowIndex: The row index of removed row. This value will be null when removed the last
row in grid.

Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
],
afterRowRemoved: function (caller, rowIndex) {
// Do something
}
});

});

10
11
12

Column Parameters

type
Type: String
Default: 'text'
The type of control generated in a table cell.
text:

Generate a text input box.

select:

Generate a drop down list control. The available option item can be
defined in ctrlOptions.

checkbox:

Generate a checkbox control.

color:

Generate a HTML5 color control. A normal text control will be generated

when browser not supported.

date:

Generate a HTML5 date control. A normal text control will be generated

when browser not supported.

datetime:

Generate a HTML5 datetime control. A normal text control will be

generated when browser not supported.

datetime-local:

Generate a HTML5 datetime-local control. A normal text control will be

generated when browser not supported.

email:

Generate a HTML5 email control. A normal text control will be

generated when browser not supported.

number:

Generate a HTML5 number control. A normal text control will be

generated when browser not supported.

range:

Generate a HTML5 range control. A normal text control will be

generated when browser not supported.

search:

Generate a HTML5 search control. A normal text control will be

generated when browser not supported.

tel:

Generate a HTML5 tel control. A normal text control will be generated

when browser not supported.

time:

Generate a HTML5 time control. A normal text control will be generated

when browser not supported.

url:

Generate a HTML5 url control. A normal text control will be generated

when browser not supported.

week:

Generate a HTML5 week control. A normal text control will be generated

when browser not supported.

hidden:

Generate a hidden control which will not be shown on screen. It is useful

for keeping data that meaningless to user but important to application
logic such as database primary key sequence number.

ui-datepicker:

Generate a text input box with jQuery UI datapicker widget.

ui-spinner:

Generate a text input box with jQuery UI spinner widget.

ui-autocomplete: Generate a text input box with jQuery UI autocomplete widget.

custom:

Generate a custom input field.

The customBuilder, customGetter and customSetter callback function
must be defined for custom control type.

name
Type: String
Default: null
The name of control generated. This value must be unique across
the columns array.

value
Type: String, Number, Boolean, Object or Array
Default: null
The default value of control. The data type is variance due to different type
of the control.

display
Type: String
Default: null
The display label shown at the top of each column.

displayCss
Type: Object
Default: null

The extra CSS style settings to be applied on the display column header
label.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album', displayCss: { 'font-weight': 'bold' } }
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
]
});
});

headerSpan
Type: Integer
Default: null
Set the `colSpan` value of the header column table cell.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
// The header cells of `DurationMinute` and `DurationSecond` will not be
// as `headerSpan` value of `DurationHour` is assigned to 3.
{ name: 'DurationHour', display: 'Duration', headerSpan: 3, ctrlAttr: {
{ name: 'DurationMinute', ctrlAttr: { maxlength: 2 }, value: 0 },
{ name: 'DurationSecond', ctrlAttr: { maxlength: 2 }, value: 0 },
{ name: 'Year', display: 'Year' }

10
11
12
13
14

]
});
});

cellCss
Type: Object
Default: null
The extra CSS style settings to be applied on table cell that contain the
generated control.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album', cellCss: { 'background-color': '#fffff
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
]
});
});

ctrlAttr
Type: Object
Default: null

The extra control attribute settings for the generated control. This setting
will not be applied on `custom` control type.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album', ctrlAttr: { 'maxlength': 100 } },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
]
});
});

ctrlProp
Type: Object
Default: null
The extra control properties settings for the generated control. This setting
will not be applied on `custom` control type.
Example:
?
1
2
3
4
5
6
7
8

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' },
{ name: 'Poster', display: 'Poster', type: 'checkbox', ctrlProp: { check
]
});

9
10

});

ctrlCss
Type: Object
Default: null
The extra CSS style settings to be applied on the generated control. This
setting will not be applied on `custom` control type.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album', ctrlCss: { 'text-align': 'center', wid
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
]
});
});

ctrlClass
Type: String
Default: null
The extra CSS class to be added on the generated control. This setting will
not be applied on `custom` control type.

Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album', ctrlClass: 'class-one class-two' },
{ name: 'Artist', display: 'Artist', ctrlClass: 'class-three' },
{ name: 'Year', display: 'Year' }
]
});
});

ctrlOptions
Type: Array or Object or String
Default: null
The available options for `select` type control.
Array: Passing options as array such as ['Option 1', 'Option 2', 'Option 3'] or [{ label:
'Option 1', value: 1 }, { label: 'Option 2', value: 2 }, { label: 'Option 3', value: 3 }].
Object: Passing options as object such as { 1: 'Option 1', 2: 'Object 2', 3: 'Object 3' }.
String: Passing a string contain label and value pair that separated by semicolon such as
'Option 1;Option 2;Option 3' or '1:Option 1;2:Option 2;3:Option 3'.

Example:
?
1

$(function() {
$('#tblAppendGrid').appendGrid({

2
3
4
5
6
7
8
9
10

columns: [
{ name:
{ name:
{ name:
{ name:
]

'Album', display: 'Album' },

'Artist', display: 'Artist', type: 'select', ctrlOptions: { 1: '
'Year', display: 'Year', type: 'select', ctrlOptions: ['2010', '
'Origin', display: 'Origin', type: 'select', ctrlOptions: '1:Hon

});
});

invisible
Type: Boolean
Default: false
Hide current column after initialization or not.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year', invisible: true }
]
});
});

resizable
Type: Boolean
Default: false

Enable resizable on current column header cell (the right edge) by using
jQuery UI Resizible.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist', resizable: true, ctrlCss: { width: '
{ name: 'Year', display: 'Year' }
]
});
});

uiOption
Type: Object
Default: null
The initial parameters for jQuery UI widgets. Please check the jQuery UI
API for more.
Example:
?

1 $(function() {
$('#tblAppendGrid').appendGrid({
2
columns: [
3
{ name: 'Album', display: 'Album' },
4
{ name: 'Artist', display: 'Artist' },
5
{ name: 'Year', display: 'Year', type: 'ui-spinner', uiOption: { min: 2000,
6
{ name: 'Origin', display: 'Origin', type: 'ui-autocomplete', uiOption: { so
]
7
});
8

9 });
10

uiTooltip
Type: Object
Default: null
The initial parameters for jQuery UI tooltip. Please check the jQuery UI
API for more.
Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist', ctrlAttr: { title: 'Please fill in t
{ name: 'Year', display: 'Year' }
]
});
});

customBuilder(parent, idPrefix, name, uniqueIndex)

Type: Function
Default: null
The callback function to build a custom control. It is mandatory for `type`
defined as `custom`.

parent:

The parent control which is a table cell that holds this custom control.

idPrefix:

The idPrefix defined in Initial Parameters.

name:

The name of column.

uniqueIndex: The unique index assigned to this row.

Example:
?

1 $(function() {
$('#tblAppendGrid').appendGrid({
2
columns: [
3
{ name: 'Album', display: 'Album' },
4
{ name: 'Artist', display: 'Artist', ctrlAttr: { title: 'Please fill in the
5
{ name: 'Year', display: 'Year' },
{ name: 'Duration', display: 'Total Duration', type: 'custom', value: '0:00:
6
customBuilder: function (parent, idPrefix, name, uniqueIndex) {
7
// Prepare the control ID/name by using idPrefix, column name and un
8
var ctrlId = idPrefix + '_' + name + '_' + uniqueIndex;
9
// Create a span as a container
var ctrl = document.createElement('span');
10
// Set the ID and name to container and append it to parent control
11
$(ctrl).attr({ id: ctrlId, name: ctrlId }).appendTo(parent);
12
// Create extra controls and add to container
13
$('<input/>', { type: 'text', maxLength: 1, id: ctrlId + '_Hour' }).c
14
$('<input/>', { type: 'text', maxLength: 2, id: ctrlId + '_Minute' })
$('<input/>', { type: 'text', maxLength: 2, id: ctrlId + '_Second' })
15
// Finally, return the container control
16
return ctrl;
17
},
18
customGetter: function (idPrefix, name, uniqueIndex) {
19
// Prepare the control ID/name by using idPrefix, column name and un
var ctrlId = idPrefix + '_' + name + '_' + uniqueIndex;
20
// Get the value of spinners
21
var hour = $('#' + ctrlId + '_Hour').spinner('value');
22
var minute = $('#' + ctrlId + '_Minute').spinner('value');
23
var second = $('#' + ctrlId + '_Second').spinner('value');
// Return the formatted duration
24
return hour + ':' + (minute < 10 ? '0' + minute : minute) + ':' + (sec
25
},
26
customSetter: function (idPrefix, name, uniqueIndex, value) {
27
// Prepare the control ID/name by using idPrefix, column name and un
28
var ctrlId = idPrefix + '_' + name + '_' + uniqueIndex;
// Check the input value and split it to array if valid
29

30
31
32
33
34
35
36
37
38
]
});
39
40});
41
42
43
44
45
46
47
48

var sep = null;

if (value != null && -1 != value.search(/^[0-9]:[0-9]{1,2}:[0-9]{1,2}
sep = value.split(':');
}
// Set the value to different spinners
$('#' + ctrlId + '_Hour').spinner('value', sep == null ? 0 : sep[0]);
$('#' + ctrlId + '_Minute').spinner('value', sep == null ? 0 : sep[1]
$('#' + ctrlId + '_Second').spinner('value', sep == null ? 0 : sep[2]
}
}

customGetter(idPrefix, name, uniqueIndex)

Type: Function
Default: null
The callback function to get the value of this custom control. It is
mandatory for `type` defined as `custom`. Check the example
of customBuilder for more.
idPrefix:

The idPrefix defined in Initial Parameters.

name:

The name of column.

uniqueIndex: The unique index assigned to this row.

customSetter(idPrefix, name, uniqueIndex, value)

Type: Function
Default: null
The callback function to get the value of this custom control. It is
mandatory for `type` defined as `custom`. Check the example
of customBuilder for more.
idPrefix:

The idPrefix defined in Initial Parameters.

name:

The name of column.

uniqueIndex: The unique index assigned to this row.

value:

The value to be assigned to this custom control.

onClick(evt, rowIndex)
Type: Function
Default: null
The `onClick` event callback function to be bound on generated control.
This setting will not be applied on `custom` control type.
evt:

The original jQuery event object.

rowIndex: The row index of control triggered this event.

Example:

?
1
2
3
4
5
6
7
8
9
10
11
12
13

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist',
onClick: function (evt, rowIndex) {
alert('You have clicked on Artist at row ' + rowIndex);
}
},
{ name: 'Year', display: 'Year' }
]
});
});

onChange(evt, rowIndex)
Type: Function
Default: null
The `onChange` event callback function to be bound on generated control.
This setting will not be applied on `custom` control type.
evt:

The original jQuery event object.

rowIndex: The row index of control triggered this event.

Example:
?
1
2
3

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album',

4
5
6
7
8
9
10
11
12
13

onChange: function (evt, rowIndex) {

alert('You have changed value of Album at row ' + rowIndex);
}
},
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
]
});
});

Methods

isReady()
Returns: Boolean
Get a value to indicate the first element in the set of matched elements is
initialized as appengGrid or not.
Example:
?
1
2
3
4
5

$(function() {
if ($('#tblAppendGrid').appendGrid('isReady')) {
// Do something
}
});

isDataLoaded()
Returns: Boolean

Get a value to indicate the first element in the set of matched elements has
loaded data or not.
Example:
?
1
2
3
4
5

$(function() {
if ($('#tblAppendGrid').appendGrid('isDataLoaded')) {
// Do something
}
});

load(records)
Returns: jQuery
Load records to the first element in the set of matched elements.
records: An array of object for filling the appengGrid.

Example:
?
1
2
3
4
5
6
7
8
9
10

$(function() {
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
]
});
$('#tblAppendGrid').appendGrid('load', [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }

11
12
13
14

]);
}

appendRow(numOfRow)
Returns: jQuery
Append specified number of row or row data to the end of first element in
the set of matched elements.
numOfRowOrRowArray: The number of rows or row data to be appended. Default is 1.

Example:
?
1
2
3
4
5
6
7
8
9
10

$(function() {
// Appending 2 empty rows.
$('#tblAppendGrid').appendGrid('appendRow', 2);
// Appending 3 rows with data.
$('#tblAppendGrid').appendGrid('appendRow', [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
]);
});

insertRow(numOfRowOrRowArray, rowIndex)
Returns: jQuery

Insert specified number of row or row data above the specified rowIndex
of first element in the set of matched elements.
numOfRowOrRowArray: The number of rows or row data to be appended. Default is 1.
rowIndex:

The row index of the new row to be inserted.

Example:
?
1
2
3
4
5
6
7
8
9

$(function() {
// Insert one row above the third row (rowIndex=2)
$('#tblAppendGrid').appendGrid('insertRow', 1, 2);
// Insert two rows above the forth row (rowIndex=3)
$('#tblAppendGrid').appendGrid('insertRow', [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' }
], 3);
});

removeRow(rowIndex)
Returns: jQuery
Remove row in specified index of first element in the set of matched
elements.
rowIndex: The row index of the new row to be inserted.

Example:

?
1
2
3
4

$(function() {
// Remove the second row (rowIndex=1)
$('#tblAppendGrid').appendGrid('removeRow', 1);
});

moveUpRow(rowIndex)
Returns: jQuery
Move the row up in specified index of first element in the set of matched
elements.
rowIndex: The row index of the row to be moved up.

Example:
?
1
2
3
4

$(function() {
// Move the third row up (rowIndex=2)
$('#tblAppendGrid').appendGrid('moveUpRow', 2);
});

moveDownRow(rowIndex)
Returns: jQuery
Move the row down in specified index of first element in the set of matched
elements.

rowIndex: The row index of the row to be moved down.

Example:
?
1
2
3
4

$(function() {
// Move the forth row down (rowIndex=3)
$('#tblAppendGrid').appendGrid('moveDownRow', 3);
});

getRowCount()
Returns: Number
Get the total number of rows of first element in the set of matched
elements.
Example:
?
1
2
3
4

$(function() {
var count = $('#tblAppendGrid').appendGrid('getRowCount');
alert('There are ' + count + ' row(s) inside the grid!');
});

getUniqueIndex(rowIndex)
Returns: Number

Get the unique index by row index. Click here for more information about
`uniqueIndex`.
rowIndex: The row index of target row.

Example:
?
1$(function() {
2
var uniqueIndex = $('#tblAppendGrid').appendGrid('getUniqueIndex', 2);
alert('The unique index of the third row is ' + uniqueIndex);
3
});
4

getRowIndex(uniqueIndex)
Returns: Number
Get the row index by unique index. Click here for more information about
`uniqueIndex`.
uniqueIndex: The unique index of target row.

Example:
?
1$(function() {
2
var rowIndex = $('#tblAppendGrid').appendGrid('getRowIndex', 2);
alert('The row index of uniqueIndex=2 is ' + rowIndex);
3
});
4

getRowValue(rowIndex)
Returns: Object
Get all control values of specified row index first element in the set of
matched elements.
rowIndex: The row index of the data to be retrieved from.

Example:
?
1
2
3 $(function() {
// Initialize the grid with data
4
$('#tblAppendGrid').appendGrid({
5
columns: [
{ name: 'Album', display: 'Album' },
6
{ name: 'Artist', display: 'Artist' },
7
{ name: 'Year', display: 'Year' }
8
],
9
initData: [
10
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
11
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
12
]
13
});
14
// Get data of row 2
15
var data = $('#tblAppendGrid').appendGrid('getRowValue', 1);
// Get the Album from data object
16
alert('Album of second row is ' + data.Album);
17
// Get the Artist in another way
18
alert('Artist of second row is ' + data['Artist']);
19}
20
21

getAllValue(objectMode)
Returns: Array or Object
Get all control values in first element in the set of matched elements.
objectMode: The result will be returned as array by default. Set this value to true to return
as object.

Example:
?
1
2 $(function() {
// Initialize the grid with data
3
$('#tblAppendGrid').appendGrid({
4
columns: [
5
{ name: 'Album', display: 'Album' },
6
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
7
],
8
initData: [
9
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
10
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
11
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
]
12
});
13
// Example 1: Get all data as array
14
var data = $('#tblAppendGrid').appendGrid('getAllValue');
15
// Get the Album of row 1
alert('Album of first row is ' + data[0].Album);
16
// Get the Artist of row 2
17
alert('Artist of second row is ' + data[1]['Artist']);
18
// Example 2: Get all data as object
19
var data = $('#tblAppendGrid').appendGrid('getAllValue', true);
20
// Get the Album of row 1
alert('Album of first row is ' + data.Album_0);
21
// Get the Artist of row 2
22
alert('Artist of second row is ' + data['Artist_1']);
23
// Get the total row count
24
var count = data['_RowCount'];
25
alert('Total ' + count + ' row(s) in object');
}
26
27

28
29
30

getCtrlValue(name, rowIndex)
Returns: String or Number or Boolean or Object
Get the control value on specified column and row index of first element in
the set of matched elements. The return type is based on the generated
control type.
name:

The column name assigned in columns of Initial Parameters.

rowIndex: The row index of the data to be retrieved from.

Example:
?
1
$(function() {
2
// Initialize the grid with data
3
$('#tblAppendGrid').appendGrid({
columns: [
4
{ name: 'Album', display: 'Album' },
5
{ name: 'Artist', display: 'Artist' },
6
{ name: 'Year', display: 'Year' }
7
],
8
initData: [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
9
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
10
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
11
]
12
});
// Get the value of Album of second row (rowIndex=1)
13
var value = $('#tblAppendGrid').appendGrid('getCtrlValue', 'Album', 1);
14
alert('Album of second row is ' + value);
15}
16

17
18

setCtrlValue(name, rowIndex, value)

Returns: jQuery
Set the control value on specified column and row index of first element in
the set of matched elements.
name:

The column name assigned in columns of Initial Parameters.

rowIndex: The row index of the data to be retrieved from.

value:

The value to be assigned.

Example:
?
1 $(function() {
// Initialize the grid with data
2
$('#tblAppendGrid').appendGrid({
3
columns: [
4
{ name: 'Album', display: 'Album' },
5
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
6
],
7
initData: [
8
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
9
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
10
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
]
11
});
12
// Set the value of Artist of third row (rowIndex=2)
13
$('#tblAppendGrid').appendGrid('setCtrlValue', 'Artist', 2, 'Wonder
14Girls');
alert('Artist of third row is changed!');
15
}
16

17
18

getCellCtrl(name, rowIndex)
Returns: DOM Element
Get the control (DOM element) generated by specified column name and
row index.
name:

The column name assigned in columns of Initial Parameters.

rowIndex: The row index of the control to be retrieved from.

Example:
?
1
2 $(function() {
// Initialize the grid with data
3
$('#tblAppendGrid').appendGrid({
4
columns: [
5
{ name: 'Album', display: 'Album' },
6
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year' }
7
],
8
initData: [
9
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
10
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
11
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
]
12
});
13
// Get the control of Album of second row (rowIndex=1)
14
var elem = $('#tblAppendGrid').appendGrid('getCellCtrl', 'Album', 1);
15
// Do something on the element, such as adjust its maxlength
$(elem).attr('maxlength', 100);
16
17}
18

19

getCellCtrlByUniqueIndex(name, uniqueIndex)
Returns: DOM Element
Get the control (DOM element) generated by specified column name and
unique index. This function will return the same result as getCellCtrl.
name:

The column name assigned in columns of Initial Parameters.

uniqueIndex: The unique index of the control to be retrieved from.

getRowOrder()
Returns: Array
Get the unique index array of the first element in the set of matched
elements. Click here for more information about `uniqueIndex`.
Example:
?
1 $(function() {
// Initialize the grid with data
2
$('#tblAppendGrid').appendGrid({
3
columns: [
{ name: 'Album', display: 'Album' },
4
{ name: 'Artist', display: 'Artist' },
5
{ name: 'Year', display: 'Year' }
6
],
7
initData: [

{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },

8
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
9
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
10
]
11
});
// Get the rowOrder
12
var rowOrder = $('#tblAppendGrid').appendGrid('getRowOrder');
13
alert('There are ' + rowOrder.length + ' row(s) in grid.');
14
alert('Unique index of the first row is ' + rowOrder[0]);
15
alert('Unique index of the last row is ' + rowOrder[rowOrder.length 161]);
17}
18
19
20

getColumns()
Returns: Array
Get an array of columns used in the first element in the set of matched
elements. Please notice that changing the returned array items will not
affect initialized `appendGrid`.

showColumn(name)
Returns: jQuery
Show the whole column with specified name.
name: The column name assigned in columns of Initial Parameters.

Example:

?
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

$(function() {
// Initialize the grid with data
$('#tblAppendGrid').appendGrid({
columns: [
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
{ name: 'Year', display: 'Year', invisible: true }
],
initData: [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
]
});
// Show the `Year` column which is invisible
$('#tblAppendGrid').appendGrid('showColumn', 'Year');
}

hideColumn(name)
Returns: jQuery
Hide the whole column with specified name.
name: The column name assigned in columns of Initial Parameters.

Example:
?
1 $(function() {
// Initialize the grid with data
2
$('#tblAppendGrid').appendGrid({
3
columns: [
4
{ name: 'Album', display: 'Album' },
{ name: 'Artist', display: 'Artist' },
5

6
7
8
9
10
11
12
13
14}
15
16
17

{ name: 'Year', display: 'Year' }

],
initData: [
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
]
});
// Hide the `Year` column
$('#tblAppendGrid').appendGrid('hideColumn', 'Year');

isColumnInvisible(name)
Returns: Boolean
Check specified column is invisible or not.
name: The column name assigned in columns of Initial Parameters.

Example:
?
1 $(function() {
// Initialize the grid with data
2
$('#tblAppendGrid').appendGrid({
3
columns: [
{ name: 'Album', display: 'Album' },
4
{ name: 'Artist', display: 'Artist' },
5
{ name: 'Year', display: 'Year' }
6
],
7
initData: [
8
{ Album: 'Album1', Artist: 'Artist1', Year: '2001' },
{ Album: 'Album2', Artist: 'Artist2', Year: '2003' },
9
{ Album: 'Album3', Artist: 'Artist3', Year: '2005' }
10
]
11
});
12
// Hide the `Year` column

13
14
15
16
17}
18
19
20
21

if ($('#tblAppendGrid').appendGrid('isColumnInvisible', 'Year')) {
alert('Year is invisible!');
} else {
alert('Year is visible!');
}