Quick Start

Reference the AppendGrid.js in your HTML file with your favourite HTML framework!

<!DOCTYPE html>
<html lang="en">
<head>
    <!--Bootstrap meta tags-->
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>Hello AppendGrid!</title>
    <!--Bootstrap CSS-->
    <link rel="stylesheet" href="bootstrap.min.css"/>
    <!--Font Awesome WebFont CSS for icons-->
    <link rel="stylesheet" href="fontawesome.css"/>
</head>
<body class="container">
    <!--AppendGrid table element-->
    <table id="tblAppendGrid"></table>
    <!--JS required for Bootstrap-->
    <script src="jquery-3.3.1.slim.min.js"></script>
    <script src="popper.min.js"></script>
    <script src="bootstrap.min.js"></script>
    <!--AppendGrid library-->
    <script src="AppendGrid.js"></script>
    <!--Script for initialize AppendGrid-->
    <script>
        $(function () {
            var myAppendGrid = new AppendGrid({
                element: "tblAppendGrid",
                uiFramework: "bootstrap4",
                iconFramework: "fontawesome5",
                columns: [...]
            });
        });
    </script>
</body>
</html>
Try above code in CodePen!

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <title>Hello AppendGrid!</title>
    <link rel="stylesheet" href="bulma.min.css"/>
    <link rel="stylesheet" href="fontawesome.css"/>
</head>
<body>
    <section class="section">
        <div class="container">
            <!--AppendGrid table element-->
            <table id="tblAppendGrid"></table>
        </div>
    </section>
    <!--AppendGrid library-->
    <script src="AppendGrid.js"></script>
    <!--Script for initialize AppendGrid-->
    <script>
        document.addEventListener("DOMContentLoaded", function () {
            var myAppendGrid = new AppendGrid({
                element: "tblAppendGrid",
                uiFramework: "bulma",
                iconFramework: "fontawesome5",
                columns: [...]
            });
        });
    </script>
</body>
</html>
Try above code in CodePen!

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1"/>
    <title>Hello AppendGrid!</title>
</head>
<body>
    <table id="tblAppendGrid"></table>
    <script src="AppendGrid.js"></script>
    <script>
        document.addEventListener("DOMContentLoaded", function () {
            var myAppendGrid = new AppendGrid({
                element: "tblAppendGrid",
                columns: [...]
            });
        });
    </script>
</body>
</html>
Try above code in CodePen!

All available parameters and methods of AppendGrid are listed below.

Initial Parameters Grid Callbacks Column Parameters Methods

Initial Parameters

Array of column options. Please refer to Column Parameters for more.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "col-1",
        display: "Column 1",
        type: "text"
    }, {
        name: "col-2",
        display: "Column 2",
        type: "date"
    }, {
        name: "col-3",
        display: "Column 3",
        type: "select",
        ctrlOptions: ["Option 1", "Option 2", "Option 3"]
    }]
});

The ID to the target table or table DOM element for initializing appendGrid.

// Using `id` in string format
var myAppendGrid1 = new AppendGrid({
    element: "tblAppendGrid1",
    columns: [...]
});

// Using table DOM element
var myAppendGrid2 = new AppendGrid({
    element: document.getElementById("tblAppendGrid2"),
    columns: [...]
});

Hide the standard action buttons at the end of row or bottom of grid.

Property Description
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 Set 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.
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [...],
    hideButtons: {
        // Hide the move up and move down button on each row
        moveUp: true,
        moveDown: true
    }
});

Hide the row number column which is the first column of grid.


Labels or messages used in grid.

Property Description
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.
rowEmpty The message to be displayed when no rows in grid.
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [...],
    i18n: {
        append: "Hey! Append a new row at bottom!",
        removeLast: "Caution! Remove the last row!"
    }
});

The name of icon framework to be used on buttons. These icon frameworks may have several download format. AppendGrid is implemented to work with their Webfont format.

Supported icon frameworks Description
default Use predefined unicode symbols as icon.
fontawesome5 Font Awesome 5. The web's most popular icon set and toolkit.
ionicon4 Ionic 4. Premium designed icons for use in web, iOS, Android, and desktop apps.
materialdesignicons3 Material Design Icons 3. Material Design Icons has been around for many years and is compatible with many technologies and frameworks.
openiconic Open Iconic. An open source icon set with 223 marks in SVG, webfont and raster formats.
typicons2 Typicons 2. Typicons are free-to-use vector icons embedded in a webfont for easy use in any UI, whether it be on the web or in a native app.
// Using fontawesome5
var myAppendGrid1 = new AppendGrid({
    element: "tblAppendGrid1",
    iconFramework: "fontawesome5",
    columns: [...]
});

// Using ionicon4
var myAppendGrid2 = new AppendGrid({
    element: "tblAppendGrid2",
    iconFramework: "ionicon4",
    columns: [...]
});

// Using materialdesignicons3
var myAppendGrid3 = new AppendGrid({
    element: "tblAppendGrid3",
    iconFramework: "materialdesignicons3",
    columns: [...]
});

Additional parameters for initialize iconFramework.

Property Type Description Supported iconFramework
icons Object Override the default icon (text or CSS class) to be used on different buttons. All iconFramework
// For webfont type icons, such as fontawesome5
var myAppendGrid1 = new AppendGrid({
    element: "tblAppendGrid1",
    uiFramework: "bootstrap4",
    iconFramework: "fontawesome5",
    iconParams: {
        // Override the icon used on buttons
        icons: {
            append: "far fa-plus-square",
            removeLast: "far fa-minus-square"
        }
    },
    columns: [...]
});

// For text type icons, such as default
var myAppendGrid2 = new AppendGrid({
    element: "tblAppendGrid2",
    iconFramework: "default",
    iconParams: {
        // Override the text used on buttons
        icons: {
            append: "Append",
            removeLast: "Remove"
        }
    },
    columns: [...]
});

The ID prefix of controls generated inside the grid. Table ID will be used if not defined.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ],
    idPrefix: "HelloTable"
    // The field id and name will be generated as `HelloTable_foo_1`.
});


An array of data to be filled after initialized the grid.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
    initData: [
        { foo: "Foo Data 1", bar: "Bar Data 1" },
        { foo: "Foo Data 2", bar: "Bar Data 2" },
        { foo: "Foo Data 3", bar: "Bar Data 3" }
    ]
});

The total number of empty rows generated when init the grid. This will be ignored if initData is assigned.


The function for customize the HTML name of generated controls.

Parameters Type Description
idPrefix String The idPrefix defined in Initial Parameters.
name String The name of column.
uniqueIndex Number The unique index assigned to this row.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ],
    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_foo_1" name="foo" type="text" />
        // <input id="tblAppendGrid_foo_2" name="foo" type="text" />
        // <input id="tblAppendGrid_foo_3" name="foo" type="text" />
        // 
        // C#/ASP.NET
        // string[] fooData = Request.Form.GetValues("foo");
        //
        // PHP
        // $fooData = $_POST["foo"];
        //
        return name;
    }
});

Generate row button column in the front of input columns.


The variable name of row count used for object mode of `getAllValue` method.


The extra class names for different table sections.

Property Description
table Extra class names to be added on the `table` element.
thead Extra class names to be added on the `thead` element.
tbody Extra class names to be added on the `tbody` element.
tfoot Extra class names to be added on the `tfoot` element.
control Extra class names to be added on each input control generated.
button Extra class names to be added on each button generated.
buttonGroup If uiFramework support button group, it will be the extra class names to be added on each button group generated.
empty Extra class names to be added on the table cell contain empty message.
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    uiFramework: "bootstrap4",
    iconFramework: "fontawesome5",
    columns: [...],
    sectionClasses: {
        // Add `table-sm` class from Bootstrap that reduce cell padding
        table: "table-sm",
        // Add `btn-group-sm` class from Bootstrap that generate a smaller button groups
        buttonGroup: "btn-group-sm",
        // Add `form-control-sm` class from Bootstrap that reduce the size of input controls
        control: "form-control-sm"
    }
});

Apply CSS classes on generated table and input controls to become smaller or larger.

Option Description Supported UI frameworks
normal Use default size. bootstrap4, bulma
small Generate a table with lesser cell padding / margins with smaller input controls. bootstrap4, bulma
large Generate a table with more cell padding / margins with larger input controls. bootstrap4, bulma
medium Generate a table with a bit more cell padding / margins with medium input controls. bulma
// Initial AppendGrid with smaller table / controls
var myAppendGridSmall = new AppendGrid({
    element: "tblAppendGrid1",
    uiFramework: "bootstrap4",
    iconFramework: "fontawesome5",
    columns: [...],
    sizing: "small"
});

// Initial AppendGrid with larger table / controls
var myAppendGridLarge = new AppendGrid({
    element: "tblAppendGrid2",
    uiFramework: "bootstrap4",
    iconFramework: "fontawesome5",
    columns: [...],
    sizing: "large"
});

The name of UI framework to be used for styling.

Supported UI frameworks Description
default The default style, which does not apply any styles.
bootstrap4 Bootstrap 4. The most popular HTML, CSS, and JS library in the world.
bulma Bulma. Modern CSS framework based on Flexbox.
// Using Bootstrap
var myAppendGrid1 = new AppendGrid({
    element: "tblAppendGrid1",
    uiFramework: "bootstrap4",
    columns: [...]
});

// Using Bulma
var myAppendGrid2 = new AppendGrid({
    element: "tblAppendGrid2",
    uiFramework: "bulma",
    columns: [...]
});

Additional parameters for initialize uiFramework.

Property Type Description Supported uiFramework
useButtonGroup Boolean Use button group or not. bootstrap4, bulma
sectionClasses Object Override the default CSS classes to be used in different sections. See sectionClasses for more. All uiFramework
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    uiFramework: "bootstrap4",
    uiParams: {
        // Not to use button group
        useButtonGroup: false,
        // Override the button CSS class
        sectionClasses: {
            append: "btn-primary",
            insert: "btn-success"
        }
    },
    columns: [...]
});

Grid Callbacks

The callback function to be triggered after new row appended.

Parameters Type Description
caller DOM Table The DOM table object.
parentRowIndex Number The index of row that above new added rows. This value will be null when table is empty.
addedRowIndex Array of Number An array of row index added.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ],
    afterRowAppended: function(caller, parentRowIndex, addedRowIndex) {
        // Copy data of `Foo` from parent row to new added rows
        var parentValue = myAppendGrid.getCtrlValue("foo", parentRowIndex);
        for (var z = 0; z < addedRowIndex.length; z++) {
            myAppendGrid.setCtrlValue("foo", addedRowIndex[z], parentValue);
        }
    }
});

The callback function to be triggered after new row inserted.

Parameters Type Description
caller DOM Table The DOM table object.
parentRowIndex Number 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 Array of Number An array of row index added.

The callback function to be triggered after new row removed.

Parameters Type Description
caller DOM Table The DOM table object.
rowIndex Number The row index of removed row. This value will be null when removed the last row in grid.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [...],
    afterRowRemoved: function(caller, rowIndex) {
        // Do something
    }
});

The callback function to be triggered after grid row swapped (moved up or down).

Parameters Type Description
caller DOM Table The DOM table object.
oldRowIndex Number The old row index of swapped row.
newRowIndex Number The new row index of swapped row.

The callback function to be triggered before grid row removed. Return `false` to terminate row moving process.

Parameters Type Description
caller DOM Table The DOM table object.
rowIndex Number The row index to be removed.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ],
    beforeRowRemove: function(caller, rowIndex) {
        // Add confirmation before removing a row
        return confirm("Are you sure to remove this row?");
    }
});

The callback function to be triggered after data loaded to grid.

Parameters Type Description
caller DOM Table The DOM table object.
records Array of objects The array of data that loaded to grid.

The callback function to be triggered after data loaded to a row.

Parameters Type Description
caller DOM Table The DOM table object.
record Object The data object that loaded to this row.
rowIndex Number The data object that loaded to this row.
uniqueIndex Number The data object that loaded to this row.

Column Parameters

The name of control generated. This value must be unique across the columns array. Recommended to use a value combined with alphanumeric, underscores or hyphens.


The type of control generated in a table cell.

Supported type Description
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.
date Generate a HTML5 date control.
datetime Generate a HTML5 datetime control.
datetime-local Generate a HTML5 datetime-local control.
email Generate a HTML5 email control.
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.
number Generate a HTML5 number control.
range Generate a HTML5 range control.
readonly For `bootstrap4` and `bulma` uiFramework only. Generate a readonly input text control and apply CSS classes provided by uiFramework to remove default form field styles. Check the Readonly Column demo for more.
search Generate a HTML5 search control.
tel Generate a HTML5 tel control.
time Generate a HTML5 time control.
week Generate a HTML5 week control.
custom Generate a custom input field. The customBuilder, customGetter and customSetter callback function must be defined for custom control type.

The extra CSS class to be applied on table cell that contain the generated control.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        type: "text",
        // Add `bg-dark` to the cell with generated control
        cellClass: "bg-dark"
    },...]
});

The extra CSS style settings to be applied on table cell that contain the generated control.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        type: "text",
        // Change to background color of cell with generated control
        displayCss: {
            "background-color": "#333333"
        }
    },...]
});

A callback function to be executed after input control added to table. It would be useful for some plugin such as datepickers that required extra javascript for initialization.

Callback parameters Type Description
ctrl DOM Element The control generated, such as an input text element.
tbCell DOM Table Cell object The table cell that holds the generated element.
uniqueIndex Number The unique index assigned to this row.
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "col-1",
        display: "Column 1",
        type: "text"
    }, {
        name: "col-2",
        display: "Column 2",
        type: "date"
    }, {
        name: "col-3",
        display: "Column 3",
        type: "text",
        ctrlAdded: function(ctrl, tbCell, uniqueIndex) {
            // Initialize a Gijgo DatePicker (https://gijgo.com/datepicker)
            $(ctrl).datepicker({
                uiLibrary: "bootstrap4",
                format: "dd/mm/yyyy" // Using a custom date format
            });
        }
    }]
});

The extra control attribute settings for the generated control. This setting will not be applied on `custom` control type.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        type: "text",
        // Set maxlength to 100
        ctrlAttr: {
            "maxlength": 100
        }
    },...]
});

The extra CSS class to be added on the generated control. This setting will not be applied on `custom` control type.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        type: "text",
        // Add extra classes to generated input control
        ctrlClass: "bg-dark text-light"
    },...]
});

The extra CSS style settings to be applied on the generated control. This setting will not be applied on `custom` control type.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        type: "text",
        // Add background and foreground color to generated input control
        ctrlCss: {
            "background-color": "#333333",
            "color": "#ffffff"
        }
    },...]
});

The available options for `select` type control.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        // Pass options as object
        name: "col-1", display: "Column 1", type: "select",
        ctrlOptions: { 1: "Option 1", 2: "Option 2", 3: "Option 3", 4: "Option 4" }
    }, {
        // Pass options as string array
        name: "col-2", display: "Column 2", type: "select",
        ctrlOptions: ["Option 1", "Option 2", "Option 3", "Option 4"]
    }, {
        // Pass options as string
        name: "col-3", display: "Column 3", type: "select",
        ctrlOptions: "1:Option 1;2:Option 2;3:Option 3;4:Option 4"
    }, {
        // Generate options by callback function
        name: "col-4", display: "Column 4", type: "select",
        ctrlOptions: function (elem) {
            // Group 1
            var group1 = document.createElement("optgroup");
            group1.label = "Group 1";
            elem.appendChild(group1);
            group1.appendChild(new Option("Option 1-A", 11));
            group1.appendChild(new Option("Option 1-B", 12));
            // Group 2
            var group2 = document.createElement("optgroup");
            group2.label = "Group 2";
            elem.appendChild(group2);
            group2.appendChild(new Option("Option 02-A", 21));
            group2.appendChild(new Option("Option 02-B", 22));
            group2.appendChild(new Option("Option 02-C", 23));
        }
    }]
});

The callback function to build a custom control. It is mandatory for `type` defined as `custom`.

Callback parameters Type Description
parent DOM Table Cell object The parent control which is a table cell that holds this custom control.
idPrefix String The idPrefix defined in Initial Parameters.
name String The name of column.
uniqueIndex Number The unique index assigned to this row.
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "customColumn",
        display: "Custom Column",
        type: "custom",
        customBuilder: function(parent, idPrefix, name, uniqueIndex) {
            // Prepare input group which is a component of Bootstrap
            var inputGroup = document.createElement("div");
            inputGroup.classList.add("input-group");
            parent.appendChild(inputGroup);
            // Prepare input group prepend holder
            var inputGroupPrepend = document.createElement("div");
            inputGroupPrepend.classList.add("input-group-prepend");
            inputGroup.appendChild(inputGroupPrepend);
            // Prepare input group prepend text
            var inputGroupPrependText = document.createElement("span");
            inputGroupPrependText.innerText = "$";
            inputGroupPrependText.classList.add("input-group-text");
            inputGroupPrepend.appendChild(inputGroupPrependText);
            // Create the input element
            var inputControl = document.createElement("input");
            inputControl.id = idPrefix + "_" + name + "_" + uniqueIndex;
            inputControl.name = inputControl.id;
            inputControl.type = "number";
            inputControl.min = 0;
            inputControl.max = 99999;
            inputControl.placeholder = "0 ~ 99999";
            inputControl.classList.add("form-control");
            inputGroup.appendChild(inputControl);
        },
        customGetter: function(idPrefix, name, uniqueIndex) {
            // Get the value of input element
            var controlId = idPrefix + "_" + name + "_" + uniqueIndex;
            return parseFloat(document.getElementById(controlId).value);
        },
        customSetter: function(idPrefix, name, uniqueIndex, value) {
            // Set the value of input element
            var controlId = idPrefix + "_" + name + "_" + uniqueIndex;
            document.getElementById(controlId).value = value;
        }
    },...]
});

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.

Callback parameters Type Description
idPrefix String The idPrefix defined in Initial Parameters.
name String The name of column.
uniqueIndex Number The unique index assigned to this row.

The callback function to set the value of this custom control. It is mandatory for `type` defined as `custom`. Check the example of customBuilder for more.

Callback parameters Type Description
idPrefix String The idPrefix defined in Initial Parameters.
name String The name of column.
uniqueIndex Number The unique index assigned to this row.
value Object The value to be assigned to this custom control.

The display label showed at the top of each column. You can define a callback function for generating customized text instead.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "TickAll",
        type: "checkbox",
        display: function (cell) {
            // Generate the checkbox
            var tickAll = document.createElement("input");
            tickAll.type = "checkbox";
            tickAll.id = "tblAppendGrid_RowHeader_PosterTick";
            cell.appendChild(tickAll);
            // Add click event
            tickAll.addEventListener("click", function(e) {
                // Get total row count and loop on all rows
                var count = myAppendGrid.getRowCount();
                for (var z = 0; z < count; z++) {
                    // Set checked / unchecked based on the checkbox state
                    myAppendGrid.getCellCtrl("TickAll", z).checked = e.target.checked;
                }
            });
            // Add a label that reference to the checkbox
            var tickLabel = document.createElement("label");
            tickLabel.setAttribute("for", tickAll.id);
            tickLabel.innerText = "Tick All";
            cell.appendChild(tickLabel);
        }
    }]
});

The extra CSS class to be applied on the display column header label.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        // Add `bg-dark` and `text-light` to the header cell
        displayClass: "bg-dark text-light"
    },...]
});

The extra CSS style settings to be applied on the display column header label.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        // Change to background and foreground color of header cell
        displayCss: {
            "background-color": "#333333",
            "color": "#ffffff"
        }
    },...]
});

The value to compare for indentify this column value is empty. You can define a callback function to check the value is empty or not.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "foo",
        display: "Foo",
        type: "number",
        ctrlAttr: { "min": 0, "max": 999 },
        emptyCriteria: function (value) {
            // Empty or value equals to 0 will consider as empty.
            var numeric = parseFloat(value);
            if (!isNaN(numeric) && numeric > 0) {
                // Value is numeric and greater than zero
                return false;
            }
            return true;
        }
    },...]
});

An object that contains one or more event handlers to be added to generated input control.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "col-1",
        display: "Column 1",
        ctrlAttr: { placeholder: "Click me!" },
        events: {
            // Add click event
            click: function(e) {
                alert("The uniqueIndex of this row is " + e.uniqueIndex);
            }
        }
    }, {
        name: "col-2",
        display: "Column 2",
        ctrlAttr: { placeholder: "Mouseover me!" },
        events: {
            // Add mouseover and mouseout events
            mouseover: function(e) {
                e.target.style.backgroundColor = "#FF9999";
            },
            mouseout: function(e) {
                e.target.style.backgroundColor = null;
            }
        }
    }, {
        name: "col-3",
        display: "Column 3",
        ctrlAttr: { placeholder: "Key in something..." },
        events: {
            // Add change event
            change: function(e) {
                if (e.target.value) {
                    e.target.style.backgroundColor = "#99FF99";
                } else {
                    e.target.style.backgroundColor = null;
                }
            }
        }
    }]
});

Set the `colSpan` value of the header column table cell.

var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [{
        name: "col-1",
        display: "Column 1",
        type: "text",
        // colSpan will set to 2, the next table cell "Column 2" will not be generated
        headerSpan: 2
    }, {
        name: "col-2",
        display: "Column 2",
        type: "date"
    }, {
        name: "col-3",
        display: "Column 3",
        type: "select",
        ctrlOptions: ["Option 1", "Option 2", "Option 3"]
    }]
});

The default value of control. The data type is variance due to different type of the control.


Methods

Append specified number of row or row data to the end of first element in the set of matched elements.

Parameters Type Description
numOfRowOrRowArray Number or Array of objects The number of rows or row data to be appended. Default is 1.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});
...
// Appending 2 empty rows.
myAppendGrid.appendRow(2);
// Appending 3 rows with data.
myAppendGrid.appendRow([ 
    { "foo": "1A", "bar": "2019-01-01" },
    { "foo": "2A", "bar": "2019-02-02" },
    { "foo": "3A", "bar": "2019-03-03" },
]);

Get the control (DOM element) generated by specified column name and row index.

Parameters Type Description
name String The column name assigned in columns of Initial Parameters.
rowIndex Number The row index of the control to be retrieved from.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});
...
// Get the control of column "foo" of second row (rowIndex=1)
var elem = myAppendGrid.getCellCtrl("foo", 1);
// Do something on the element, such as adjust its maxlength
elem.setAttribute("maxlength", "100");

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

Parameters Type Description
name String The column name assigned in columns of Initial Parameters.
uniqueIndex Number The unique index of the control to be retrieved from.

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.


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.

Parameters Type Description
name String The column name assigned in columns of Initial Parameters.
rowIndex Number The row index of the control to be retrieved from.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});
...
// Get the value of column "foo" of second row (rowIndex=1)
var value = myAppendGrid.getCtrlValue("foo", 1);

Get the number of rows in the grid.

// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Get row count
var rowCount = myAppendGrid.getRowCount();
alert("There are " + rowCount + " row(s) inside the grid!");

Get the unique index array of the grid.

// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Get row order, which is the array of unique index
var rowOrder = myAppendGrid.getRowOrder();
alert("There are " + rowOrder.length + " row(s) in grid.");
alert("Unique index of the first row is " + rowOrder[0]);
alert("Unique index of the last row is " + rowOrder[rowOrder.length - 1]);

Get the row index by unique index.

Parameters Type Description
uniqueIndex Number The unique index of target row.
// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Get the row index of unique index = 2
var rowIndex = myAppendGrid.getRowIndex(2);
alert("The row index of uniqueIndex=2 is " + rowIndex);

Get the unique index by row index.

Parameters Type Description
rowIndex Number The row index of target row.
// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Get the unique index of row index = 2
var uniqueIndex = myAppendGrid.getUniqueIndex(2);
alert("The unique index of rowIndex=2 is " + uniqueIndex);

Get all control values of specified row index of current grid.

Parameters Type Description
rowIndex Number The row index of the data to be retrieved from.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});
...
// Get the values of second row (rowIndex = 1)
var rowValues = myAppendGrid.getRowValue(1);
alert("Value of Foo in second row is " + rowValues.foo);
alert("Value of Bar in second row is " + rowValues["bar"]); // Alternate style

Get all control values of current grid.

Parameters Type Description
objectMode Boolean The result will be returned as array by default. Set this value to true to return as object.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});
...

// Example 1: Get all data as array
var data = myAppendGrid.getAllValue();
// Get the `Foo` of row 1
alert("`Foo` of first row is " + data[0].foo);
// Get the `Bar` of row 2
alert("`Bar` of second row is " + data[2]["bar"]);

// Example 2: Get all data as object
var data = myAppendGrid.getAllValue(true);
// Get the `Foo` of row 1
alert("`Foo` of first row is " + data.foo_0);
// Get the `Bar` of row 2
alert("`Bar` of second row is " + data["bar_1"]);
// Get the total row count, available for object mode only
var count = data["_RowCount"];
alert("Total " + count + " row(s) in object");

Insert specified number of row or row data above the specified rowIndex.

Parameters Type Description
numOfRowOrRowArray Number or Array of objects The number of rows or row data to be appended. Default is 1.
rowIndex Number The row index of the new row to be inserted.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});

// Example 1: Insert one row above the third row (rowIndex=2)
myAppendGrid.insertRow(1, 2);

// Example 2: Insert two rows with data above the forth row (rowIndex=3)
myAppendGrid.insertRow([
    { foo: "Foo Data 1", bar: "Bar Data 1" },
    { foo: "Foo Data 2", bar: "Bar Data 2" }
], 3);

Check specified row is empty or not. You may need to change the emptyCriteria to meet your requirement.

Parameters Type Description
rowIndex Number The row index of the new row to be inserted.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { 
            name: "foo",
            display: "Foo",
            type: "text"
        },
        {
          name: "bar",
          display: "Bar",
          type: "number",
          // Use custom function for 
          emptyCriteria: function(value) {
              var numeric = parseFloat(value);
              return isNaN(numeric) || numeric === 0;
          }
        }
    ],
    initData: [
        { foo: "Foo Data 1", bar: 123 },
        { foo: "", bar: "" },
        { foo: "", bar: 0 },
        { foo: "", bar: 456 },
    ]
});

// Load an array of records
var isEmpty0 = myAppendGrid.isRowEmpty(0); // Not empty, `foo` and `bar` has content
var isEmpty1 = myAppendGrid.isRowEmpty(1); // Is empty, `foo` and `bar` are empty
var isEmpty2 = myAppendGrid.isRowEmpty(2); // Is empty, `foo` is empty and `bar`=0 will determinated as empty which defined in `emptyCriteria`
var isEmpty3 = myAppendGrid.isRowEmpty(3); // Not empty, `foo` is empty but `bar` is not empty which defined in `emptyCriteria`

Load records to current grid. Existing values will be removed.

Parameters Type Description
records Array of objects An array of object for filling the grid.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo" },
        { name: "bar", display: "Bar" }
    ]
});

// Load an array of records
myAppendGrid.load([
    { foo: "Foo Data 1", bar: "Bar Data 1" },
    { foo: "Foo Data 2", bar: "Bar Data 2" },
    { foo: "Foo Data 3", bar: "Bar Data 3" }
]);

Move the row down in specified index of current grid.

Parameters Type Description
rowIndex Number The row index of the row to be moved down.
// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Move the third row down (rowIndex=2)
myAppendGrid.moveDownRow(2);

Move the row up in specified index of current grid.

Parameters Type Description
rowIndex Number The row index of the row to be moved up.
// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Move the forth row up (rowIndex=3)
myAppendGrid.moveUpRow(3);

Remove row in specified index of current grid.

Parameters Type Description
rowIndex Number The row index of the row to be removed.
// Initilize the grid
var myAppendGrid = new AppendGrid({ /* Initial Parameters */ });
...
// Remove the third row (rowIndex=2)
myAppendGrid.removeRow(2);

Set the control value on specified column and row index of current grid.

Parameters Type Description
name String The column name assigned in columns of Initial Parameters.
rowIndex Number The row index of the control to be retrieved from.
value Object The value to be assigned to target control.
// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { name: "foo", display: "Foo", type: "text" },
        { name: "bar", display: "Bar", type: "number" }
    ]
});

// Example 1: Set the value of `foo` on first row (rowIndex=0)
myAppendGrid.setCtrlValue("foo", 0, "New Foo Data");

// Example 2: Set the value of `bar` on second row (rowIndex=1)
myAppendGrid.setCtrlValue("bar", 1, 123);

Remove all empty rows in grid. You may need to change the emptyCriteria to meet your requirement.

// Initilize the grid
var myAppendGrid = new AppendGrid({
    element: "tblAppendGrid",
    columns: [
        { 
            name: "foo",
            display: "Foo",
            type: "text"
        },
        {
          name: "bar",
          display: "Bar",
          type: "number",
          // Use custom function for 
          emptyCriteria: function(value) {
              var numeric = parseFloat(value);
              return isNaN(numeric) || numeric === 0;
          }
        }
    ],
    initData: [
        { foo: "Foo Data 1", bar: 123 }, // Not empty
        { foo: "", bar: "" }, // Empty
        { foo: "", bar: 0 }, // Empty
        { foo: "", bar: 456 }, // Not empty
    ]
});
...
// Remove all empty rows, second and third rows will be removed
myAppendGrid.removeEmptyRows();