EnhanceDataGrid

EnhanceDataGrid

An enhanced version of jqxGrid with various useful built-in methods and functionalities.

Constructor

new EnhanceDataGrid(prop)

Constructs EnhanceDataGrid object.
To Do
  • It is recommended to include following libraries for prettier UI experience.
  • Font Awesome - https://fontawesome.com/ (Icon Dependency)
  • Bootstrap - https://getbootstrap.com/
  • jQuery-Confirm - https://craftpip.github.io/jquery-confirm/
Parameters
Name Type Attributes Default Description
prop.jqxGridProperties Refer to Properties Category at jqxGrid API.
Inherit all properties from jqxGrid with following preset properties.
Properties
Name Type Default Description
width Number | String '100%' Grid's width.
height Number | String '100%' Grid's height.
sortable Boolean true The sortable property enables or disables the sorting feature.
filterable Boolean true Enable/Disable the Grid Filtering feature.
filtermode String 'excel' The property specifies the type of rendering of the Filter Menu.
enabletooltips Boolean true Enable/Disable the grid tooltips.
showaggregates Boolean true Show/Hide the aggregates in the grid's statusbar.
prop Object EnhanceDataGrid object properties, sets prop.
Properties
Name Type Attributes Default Description
id String Grid's ID.
jsonSource Object <optional>
Grid's data source preset with JSON data type.
dataSource Object <optional>
Grid's data source object.
checkedDatafield String <optional>
'selected' Data field which use to get all selected data ID.
buttonTheme String <optional>
'' Default theme for built-in button component.
useBootstrap Boolean <optional>
false Enable/Disable Bootstrap Theme on Grid message.
centeredColumns Boolean <optional>
false Sets True to auto append { align: 'center' } to all columns.
showRowIndex Boolean <optional>
true Shows row index.
rowIndexWidth Number <optional>
50 Row index width.
searchInput Boolean <optional>
false Shows search bar (in toolbar).
showFindButton Boolean <optional>
false Shows 'Find' button (in toolbar).
showFilterButton Boolean <optional>
true Shows 'Filter' button (in toolbar).
showFilterRowButton Boolean <optional>
true Shows 'Filter Row' toggle button (in toolbar).
enterFilter Boolean <optional>
true Keyboard shortcut Filter (Enter key).
enterFind Boolean <optional>
false Keyboard shortcut Find (Ctrl+Enter key).
autoFilter Boolean <optional>
false Auto filter after certain timing delay.
autoFind Boolean <optional>
false Auto find after certain timing delay.
autoDelayTiming Number <optional>
300 Timing delay for autoFilter/autoFind (in miliseconds).
tbElement Array.<Object> <optional>
[ ] Grid's toolbar built-in component, see "tbElement." parameter for component properties.
tbElement.button String Available button components : (width default behaviour and icon)
reload Reload Grid
add (1) Clear form entries
(2) Open jqxWindow/Bootstrap-Modal
edit Open jqxWindow/Bootstrap-Modal
delete POST AJAX with URL provided
print Open URL provided in new tab
excel Export Grid data to Excel file
csv Export Grid data to CSV file
custombutton Custom button
custom Custom element, see buttonNode property
Other available components :
divider Divider between two components
separator Separator between two components
tbElement.buttonNode <optional>
Custom element syntax, only applicable to 'custom' button.
tbElement.text String <optional>
Button text, applicable to all buttons.
tbElement.icon String <optional>
Button icon (Font Awesome icon), applicable to all buttons, sets 'none' to hide icon.
tbElement.iconColor String <optional>
Button icon's color, applicable to all buttons.
tbElement.visible Boolean | Number <optional>
If set to True or 1, component will be visible, applicable to all buttons.
tbElement.click function <optional>
Button's on('click') callback function, applicable to all buttons.
tbElement.beforeClick function <optional>
Callback function before on('click') implementation, applicable to all buttons.
tbElement.afterClick function <optional>
Callback function after on('click') implemented, applicable to all buttons.
tbElement.form String <optional>
Form's ID, only applicable to 'add' button. When provided, form entries will be reset when button clicked. (Default Behaviour)

Entries covered :
 - <input type="text | date | checkbox | radio" />, <select />, <textarea />
 - jqxInput, jqxDateTimeInput, jqxCheckBox, jqxRadioButton, jqxComboBox, jqxTextArea
tbElement.win String <optional>
jqxWindow's ID, only applicable to 'add', 'edit' buttons. When provided, jqxWindow will open automatically when button clicked. (Default Behaviour)
tbElement.modal String <optional>
Bootstrap Modal's ID, only applicable to 'add', 'edit' buttons. When provided, Modal will open automatically when button clicked. (Default Behaviour)
tbElement.winOpenOnButton Boolean <optional>
true If set to False, jqxWindow will not be attached to the button when open, only applicable to 'add', 'edit' buttons.
tbElement.winOpenOnClick Boolean <optional>
true If set to False, jqxWindow will open when button clicked, only applicable to 'add', 'edit' buttons.
tbElement.verticalAlign Number <optional>
Set jqxWindow top margin, only applicable to 'add', 'edit' buttons. When specified, jqxWindow will always be horizontally centered.
tbElement.filename String <optional>
For 'print' button: Document filename during download.
For 'excel', 'csv' buttons: Excel/CSV filename during export.
tbElement.url String | function <optional>
If url is in String form,
 For 'delete' button: Delete action's $.post() URL.
 For 'print' button: Form's file URL.
If url is in Function form, following arguments are supported,
function(selected_row_data [, selected_row_data_id]) {...}
NOTE: 'selected_row_data_id' will available automatically when 'id' field detected in data object
tbElement.check function <optional>
Checking function before implement default behaviours of buttons, only applicable to 'add', 'edit', 'delete' buttons. Return False to stop button's default behaviours.
tbElement.param Object | function <optional>
Function to append dynamic arguments into url property, only functional when url provided is in String form.
tbElement.postparam Object | function <optional>
Function to append dynamic arguments into POST AJX, only applicable to 'delete' button.
tbElement.success function <optional>
Callback function if delete action successed, only applicable to 'delete' button.
tbElement.fail function <optional>
Callback function if delete action failed, only applicable to 'delete' button.

Members

jqxGrid

Gets jqxGrid object
Example
const grid = new EnhanceDataGrid();
grid.jqxGrid;

prop

EnhanceDataGrid properties.
See:
Example
const source_json_object = {
  url: 'url.php',
  datafields: [
    { name: 'id', type: 'number' },
    ...
  ],
};
const source_url_object = {
  id: 'id',
  datafields: [
    { name: 'id', type: 'number' },
    ...
  ],
  // example for JSON
  datatype: "json",
  url: 'url.php',
  // example for local Array
  datatype: "array",
  localdata: [Array of Object],
};
// default syntax
const grid = new EnhanceDataGrid({
  // Preset jqxGrid properties
  width              : '100%',
  height             : '100%',
  sortable           : true,
  filterable         : true,
  filtermode         : 'excel',
  enabletooltips     : true,
  showaggregates     : true,
  // showstatusbar      : true,
  // EnhanceDataGrid properties
  id                 : '#grid_id',
  // using either one, (1)jsonSource | (2)dataSource
  jsonSource         : source_json_object, // method (1)
  dataSource         : source_url_object,  // method (2), refer to setSourceUrl() method for example
  // dateFormat         : 'yyyy-MM-dd',
  checkedDatafield   : 'checked',
  buttonTheme        : 'fresh',
  useBootstrap       : true,
  centeredColumns    : true,
  showRowIndex       : false,
  rowIndexWidth      : 100,
  searchInput        : true,
  showFindButton     : false,
  showFilterButton   : false,
  showFilterRowButton: false,
  enterFilter        : false,
  enterFind          : true,
  autoFilter         : true,
  autoFind           : true,
  autoDelayTiming    : 500, // in miliseconds
  tbElement          : [
    { button: 'reload' },
    { button: 'add', win: '#jqxWindow_id', form: '#form_id', winOpenOnButton: false,
      beforeClick: function() {
        // code to be run before button.on('click')
      },
      click: function() {
        // if provided, the function will overwrite button default behaviour
      },
      afterClick: function() {
        // code to be run after button.on('click')
      },
    },
    { button: 'edit', modal: '#modal_id', form: '#form_id' },
    { button: 'delete',
      check: function() {
        if ($checking_not_passed)
          return false;
        else
          return true;
      },
      success: function() {
        // your own coding
        // works ONLY when POST AJAX returned result in JSON form with { success: 1 }
      },
      fail: function() {
        // your own coding
        // works ONLY when POST AJAX returned result in JSON form with { success: 0 }
      },
      // url in String form
      url  : 'delete.php',
      param: { param_1: value_1, param_2: value_2 },                         // use this format when your parameters are decided before Grid init and then fix.
      param: function() { return { param_1: value_1, param_2: value_2 }; },  // use this format when your parameters are decided when button click (Recommended)
      // url in Function form
      url: function(row_data, data_id) {
        // your own code
      },
    },
    { button: 'divider' },
    { button: 'excel', filename: 'Excel_FIlename_When_Export' },
    { button: 'csv', filename: 'CSV_FIlename_When_Export' },
  ],
});
// new syntax
const grid = new EnhanceDataGrid('#grid_id', {
  id: '#grid_id',
  ...
});

Methods

(static) debounce(fn, delay)

Debounce function.
Example
const debounce = EnhanceDataGrid.debounce(() => { console.log('hello world') }, 1000);
debounce(); // Function runs for 1 second without it being called again, 'hello world' will be print out at console
See:
  • Reference - https://remysharp.com/2010/07/21/throttling-function-calls
Parameters
Name Type Description
fn function Callback function.
delay Number Delay timing.
Returns
Debounce function.

(static) getSearchParameters(urlopt) → {Object}

Get query string of an URL.
Example
EnhanceDataGrid.getSearchParameters();
Parameters
Name Type Attributes Description
url String <optional>
URL (Uniform Resource Locator) which the query string will be extracted. If URL not provided, browser URL will be used instead.
Returns
- Query string of URL in Object form.
Type
Object

(static) insertQueryString(url, params) → {String}

Append query string to an URL.
Example
EnhanceDataGrid.insertQueryString('url.php', {
  parameter1: 'value1',
  parameter2: 'value2'
});
// Returns 'url.php?parameter1=value1&parameter2=value2'

EnhanceDataGrid.insertQueryString('url.php?origin=master', {
  parameter1: 'value1',
  parameter2: 'value2'
});
// Returns 'url.php?origin=master&parameter1=value1&parameter2=value2'
Parameters
Name Type Description
url String URL (Uniform Resource Locator).
params Object query string in Object form, { key:value } pairs.
Returns
- URL with query string append.
Type
String

(static) isEmptyString(input) → {Boolean}

Check input is an empty string.
Example
EnhanceDataGrid.isEmptyString('');       // true
EnhanceDataGrid.isEmptyString('empty');  // false
EnhanceDataGrid.isEmptyString(null);     // false
Parameters
Name Type Description
input * Input to be check.
Returns
Returns True if input is an empty string.
Type
Boolean

(static) isNull(input, identicalopt) → {Boolean}

Check input is null.
Example
EnhanceDataGrid.isNull(null);          // true
EnhanceDataGrid.isNull('null');        // true
EnhanceDataGrid.isNull('null', true);  // false
Parameters
Name Type Attributes Description
input * Input to be check.
identical Boolean <optional>
Enable strict equality comparison.
Returns
Returns True if input is null.
Type
Boolean

(static) isUndefined(input, identicalopt) → {Boolean}

Check input is undefined.
Example
EnhanceDataGrid.isUndefined(undefined);          // true
EnhanceDataGrid.isUndefined('undefined');        // true
EnhanceDataGrid.isUndefined('undefined', true);  // false
Parameters
Name Type Attributes Description
input * Input to be check.
identical Boolean <optional>
Enable strict equality comparison.
Returns
Returns True if input is undefined.
Type
Boolean

(static) isUnset(input, trimopt) → {Boolean}

Check input is unset.
Example
EnhanceDataGrid.isUnset('');         // true
EnhanceDataGrid.isUnset(null);       // true
EnhanceDataGrid.isUnset(undefined);  // true
EnhanceDataGrid.isUnset('set');      // false
EnhanceDataGrid.isUnset(1);          // false
Parameters
Name Type Attributes Description
input * Input to be check.
trim Boolean <optional>
True to trim input.
Returns
Returns True if input is unset.
Type
Boolean

(static) isValidKeyboardInput(keyDownEvent) → {Boolean}

Check whether is a valid keyboard input.
Example
EnhanceDataGrid.isValidKeyboardInput(<keyDownEvent>('A' => 65)); // true
EnhanceDataGrid.isValidKeyboardInput(<keyDownEvent>('Enter' => 13)); // false
Parameters
Name Type Description
keyDownEvent Object Key event object.
Returns
Returns True if valid.
Type
Boolean

(static) throttle(fn, delay, scope)

Throttle function.
Example
const throttle = EnhanceDataGrid.throttle(function() { console.log('hello world'); }, 2000);
throttle(); // console will print out 'hello world' at most one times two seconds.
See:
  • Reference - https://remysharp.com/2010/07/21/throttling-function-calls
Parameters
Name Type Description
fn function Callback function.
delay Number Delay timing.
scope Function scope.
Returns
Throttle function.

(static) transformObjectToString(prmobj, equaltoopt, combinatoropt) → {String}

Transform Object to String.
Example
EnhanceDataGrid.transformObjectToString({parameter1: 'value1', parameter2: 'value2'});
// Returns 'parameter1=value1&parameter2=value2'
Parameters
Name Type Attributes Default Description
prmobj Object Parameters in Object.
equalto String <optional>
'=' Equal-to character of { key-to-value } pairs.
combinator String <optional>
'&' Combinator of each { key-to-value } pairs.
Returns
- Parameters in String form.
Type
String

(static) transformStringToObject(prmstr, equaltoopt, combinatoropt) → {Object}

Transform String to Object.
Example
EnhanceDataGrid.transformStringToObject('parameter1=value1&parameter2=value2');
// Returns {parameter1: 'value1', parameter2: 'value2'}
Parameters
Name Type Attributes Default Description
prmstr String Parameters in String.
equalto String <optional>
'=' Equal-to character of { key-to-value } pairs.
combinator String <optional>
'&' Combinator of each { key-to-value } pairs.
Returns
- Parameters in Object form.
Type
Object

clearSelection()

Clears the selection.
Example
const grid = new EnhanceDataGrid();
grid.clearSelection();
Returns
None

getAllDirty() → {Object}

Gets all dirty { key:value } pairs.
Example
const grid = new EnhanceDataGrid();
grid.getAllDirty();
Returns
Object of all dirty { key:value } pairs classified by "id" datafield.
Type
Object

getCellValue(rowBoundIndex, dataField)

Gets the value of a cell.
Example
const grid = new EnhanceDataGrid();
// get value of 'column_name' in first row
grid.getCellValue(0, 'column_name');
Parameters
Name Type Description
rowBoundIndex Number | String Row index.
dataField String Data field.
Returns
Cell value.

getCheckedItems() → {Array}

Gets all selected data ID.
Example
const grid = new EnhanceDataGrid();
grid.getCheckedItems();
Default Value:
  • checkedDatafield="selected"
Returns
Array of data ID which "datafield" specified in "checkedDatafield" property was checked. (columntype set to "checkbox") 1
Type
Array

getDirty() → {Object.<Object>}

Gets all dirty { id:value } pairs.
Example
const grid = new EnhanceDataGrid();
grid.getDirty();
Returns
Object of all dirty { id:value } paris which "value" taken from "datafield" specified in "checkedDatafield" property.
Type
Object.<Object>

getRowData(rowBoundIndex) → {Object}

Gets the data of a row.
Example
const grid = new EnhanceDataGrid();
// get JSON data object of first row
grid.getRowData(0);
Parameters
Name Type Description
rowBoundIndex Number | String Row index.
Returns
Data object specified by row index.
Type
Object

getRows() → {Array.<Object>}

Gets all rows.
Example
const grid = new EnhanceDataGrid();
grid.getRows();
Returns
Array of all rows loaded in the Grid. If the Grid is filtered, the returned value is an array of the filtered records.
Type
Array.<Object>

getSelectedCellValue(dataField)

Gets the value of a cell of the selected row.
Example
const grid = new EnhanceDataGrid();
// get value of 'column_name' of selected row
grid.getSelectedCellValue('column_name);
Parameters
Name Type Description
dataField String Data field.
Returns
Cell value of the selected row.

getSelectedRowData() → {Object}

Gets the data of the selected row.
Example
const grid = new EnhanceDataGrid();
grid.getSelectedRowData();
Returns
Data object of the selected row.
Type
Object

getSelectedRowIndex() → {Number}

Gets the bound index of the selected row.
Example
const grid = new EnhanceDataGrid();
grid.getSelectedRowIndex();
Returns
Bound index of the selected row. Returns -1, if there is no selection. The expected selection mode is 'singlerow', 'multiplerows' or 'multiplerowsextended'.
Type
Number

getSelectedRowIndexes() → {Array}

Gets the indexes of the selected rows.
Example
const grid = new EnhanceDataGrid();
grid.getSelectedRowIndexes();
Returns
Returns an array of the selected rows. The expected selection mode is 'singlerow', 'multiplerows' or 'multiplerowsextended'.
Type
Array

getSourceUrl() → {String}

Get URL of data source.
Example
const grid = new EnhanceDataGrid();
grid.getSourceUrl();
Returns
URL of data source.
Type
String

hideColumn(dataField)

Hide column.
Example
const grid = new EnhanceDataGrid();
// Single column
grid.hideColumn('column_name');
// Multiple columns
grid.hideColumn(['column_name_1', 'column_name_2', ...]);
Parameters
Name Type Description
dataField String | Array.<String> Data field / Array of data field.
Returns
None

on(event, callback)

Register grid event listener.
Example
const grid = new EnhanceDataGrid();
grid.on('rowselect', function(event) {
  ...
});
Parameters
Name Type Description
event String Event name.
callback function Callback function.
Returns
None

refresh()

Clears the selection, updates the bound data and refreshed the grid.
Example
const grid = new EnhanceDataGrid();
grid.refresh();
Returns
None

setSelectedCellValue(dataField, value)

Sets a new value to a cell of the selected row.
Example
const grid = new EnhanceDataGrid();
//  set value of 'column_name' of selected row
grid.setSelectedCellValue('column_name', 'new value');
Parameters
Name Type Description
dataField String Data field.
value * New value.
Returns
None

setSourceUrl(url, autoRefresh)

Update URL of data source and refresh Grid.
Example
// This method only support JSON type data source with URL as following:
const grid = new EnhanceDataGrid({
  // using 'dataSource'
  dataSource: {
    datatype   : 'json',
    url        : 'source_url.php',
    id         : 'id',
    datafields : [
      { name: 'id', type: 'number' },
      { name: 'name', type: 'string' },
      ...
    ],
  },
  // OR, using 'jsonSource'
  jsonSource: {
    url: 'source_url.php',
    datafields : [
      { name: 'id', type: 'number' },
      { name: 'name', type: 'string' },
      ...
    ],
  }
});
const new_source_url = EnhanceDataGrid.insertQueryString('new_source_url.php', {
  parameter1: value1,
  parameter2: value2,
  ...
});
grid.setSourceUrl(new_source_url);
See:
  • jqxGrid has multiple types of data collections, refer Grid Data Sources for complete reference.
Parameters
Name Type Description
url String New URL of data source.
autoRefresh Boolean IF False, Grid will not refresh after URL changed.
Returns
None

showColumn(dataField)

Shows column.
Example
const grid = new EnhanceDataGrid();
// Single column
grid.showColumn('column_name');
// Multiple columns
grid.showColumn(['column_name_1', 'column_name_2', ...]);
Parameters
Name Type Description
dataField String | Array.<String> Data field / Array of data field.
Returns
None

updateBoundData(type)

Updates the bound data and refreshes the grid.
Example
const grid = new EnhanceDataGrid();
grid.updateBoundData();
Parameters
Name Type Description
type String You can pass 'filter' or 'sort' as parameter, if the update reason is change in 'filtering' or 'sorting'. To update only the data without the columns, use the 'data' parameter. To make a quick update of the cells, pass "cells" as parameter. Passing "cells" will refresh only the cells values when the new rows count is equal to the previous rows count. To make a full update, do not pass any parameter.
Returns
None

updateCellValue(rowBoundIndex, dataField, value)

Sets a new value to a cell.
Example
const grid = new EnhanceDataGrid();
//  set value of 'column_name' in first row to 'new value'
grid.updateCellValue(0, 'column_name', 'new value');
Parameters
Name Type Description
rowBoundIndex Number Row index.
dataField String Data field.
value * New value.
Returns
None