RUSSYSDEV: eiseIntra
Instant administrative backend for your application

eiseGrid

eiseGrid PHP class is the backend for eiseGrid library that displays data grid, handles client side operations (data input, calculation and validation) and data update on the server side. Grid is configured on PHP side and rendered as HTML+JavaScript. Data is submitted to server as form data POST and can be obtained via JSON or directly posted into database.

eiseGrid integrates tightly with eiseIntra framework, but can be used as standalone component as well.

Package: eiseIntra
Version: 2.5beta
Copyright: (c) 2006-2025 Ilya S. Eliseev
Author: Ilya Eliseev (ie@e-ise.com)
License: MIT License
Subpackage: eiseGrid

class eiseGrid

eiseGrid class

This class is responsible for managing the data grid, including rendering, data manipulation, and interaction with the backend.

public property $col_default

This array defines default properties of each column.

public $col_default = array(
    'field' => '', // field name, must be set
    'fields' => null, // array of fields, if set, will be used for colspan purposes
    'title' => '', // column title
    'type' => 'text', // column type
    'style' => '', // column style
    'class' => '', // column class
    'mandatory' => false, // is column mandatory
    'sortable' => false, // is column sortable
    'filterable' => false, // is column filterable
    'headerClickable' => false, // is column header clickable
    'readonly' => false, // is column read-only
    'disabled' => false, // is column disabled
    'static' => false, // is column static, i.e. not editable
    'default' => null, // default value for the field

    'flagDontUpdateRow' => false, // if true, the row will not be updated on change of this field

    'totals' => null, // totals for the column, can be 'sum', 'count', 'avg', 'min', 'max'

    'decimalPlaces' => null, // number of decimal places for the column, if applicable

    'source' => null, // source for the column, can be array of options, SQL query or string with options
    'source_prefix' => null, // prefix for the source, if applicable

    'href' => null, // link for the column, if applicable
    'target' => null, // target for the link, if applicable

    'format' => null, // date-time format for the column, if applicable
);

Category: Grid Configuration

public property $Columns

array of columns. can be associative or indexed.

Category: Grid Configuration

public property $conf

Configuration of eiseGrid instance (see eiseGrid::$defaultConf for possible settings)

Category: Grid Configuration

public property $Rows

array of rows. each row is accociative array of fieldName=>fieldValue

Category: Grid Data

static property $defaultWidthsByType

Default widths for column types

static $defaultWidthsByType = array(
        'numeric' => '60px'
        , 'number' => '60px'
        , 'integer' => '60px'
        , 'real' => '80px'
        , 'money' => '80px'

        , 'date' => '90px'
        , 'datetime' => '120px'
        , 'time' => '40px'

        , 'boolean' => '30px'
        , 'checkbox' => '30px'
        
        , 'order' => '25px'

        , 'text' => '100px'
        , 'combobox' => '100px'
        , 'select' => '100px'
    );

Category: Grid Configuration

static property $defaultConf

Default config of eiseGrid

static $defaultConf = Array(                    
        'titleDel' => "Del" // column title for Del
        , "titleAdd" => "Add >>" // column title for Add
        , 'controlBarButtons' => ''
        //, 'controlBarButtons' => 'add|insert|moveup|movedown|delete|excel|save'
        , 'extraInputs' => Array("DataAction"=>"update")
        , 'urlToSubmit' => ''
        , 'dateFormat' => "d.m.Y"
        , 'timeFormat' => "H:i" 
        , 'decimalPlaces' => "2"
        , 'decimalSeparator' => "."
        , 'thousandsSeparator' => ","
        , 'totalsTitle' => 'Totals'
        , 'noRowsTitle' => 'Nothing found'
        , 'spinnerTitle' => 'Loading...'
        , 'dropHereTitle' => 'Drop it here'
        , 'arrPermissions' => Array("FlagWrite" => true)
        , 'Tabs3DCookieName' => '%s_tabs3d'

        , 'class' => ''

        , 'eiseIntraRelativePath' => eiseIntraRelativePath

        , 'excelSheetName' => 'Sheet 1'
        , 'excelFileName' => 'table.xls'

        , 'colors' => array('#d79695', '#bd5050', '#fdc138', '#feff48', '#94d05e', '#928958', '#26afec', '#588cd0', '#b2a1c5', '#95cddb')

        , 'intra' => null // intra object, if not set, will be taken from GLOBALS

    );

Category: Grid Configuration

public function __construct()

Grid constructor.

Parameters:

  • $oSQL (object) - eiseSQL object
  • $strName (string) - grid name
  • $arrConfig (array) - grid configuration overrides. See description of static property eiseGrid::$defaultConf.

Category: Grid Configuration

public function rename($newName)

This method renames Grid: it sets $grid->name and other attributes.

Parameters:

  • $newName (string) - new grid name

Returns: string - old name

Category: Grid Configuration

public function addColumn($arrCol)

This function adds columns to $Columns property.

Parameters:

  • $arrCol - associative array with column properties. See description of $Columns property.
  • $arrCol[‘field’] - is mandatory
  • $arrCol[‘fieldInsertBefore’] - field name to insert before
  • $arrCol[‘fieldInsertAfter’] - field name to insert after

Category: Grid Configuration

public function removeColumn($field)

This function removes columns from $Columns list.

Parameters:

  • $field - field name to be removed.

Category: Grid Configuration

public function setColumnProperty($field, $property, $value)

This function changes column property to defined values and returns its previous value.

Parameters:

  • $field (string) - field name
  • $property (string) - property name
  • $value (mixed) - new property value

Returns: mixed - old property value

Category: Grid Configuration

public function get_html($allowEdit=true)

This function does main job: it generates HTML for the whole eiseGrid.

Parameters:

  • $allowEdit=true

Category: Grid Display

public function Execute($allowEdit=true)

This function echoes eiseGrid HTML

Parameters:

  • $allowEdit=true

Category: Grid Display Grid Backward Compatibility

public function Update($newData = null, $conf = array())

This function updates data in the database basing on user eiseGrid input

Parameters:

  • $newData (array) - Optional. Array of new data to be used instead of $_POST
  • $conf (array) - Optional. Configuration array. Supported options:
  • flagOnDuplicateKeyUpdate - boolean, default false. If true, INSERT statements will have ON DUPLICATE KEY UPDATE clause

Category: Grid Data Handling

public function json( $newData = null, $conf = array() )

This function returns JSON-encoded data from eiseGrid input

Parameters:

  • $newData (array) - Optional. Array of new data to be used instead of $_POST
  • $conf (array) - Optional. Configuration array. Supported options:
    • flagDontEncode - boolean, default false. If true, function returns array instead of JSON-encoded string

Returns: JSON-encoded string or array of data

Category: Grid Data Handling

class easyGrid

Category: Grid Backward Compatibility
Deprecated: since version 3.7.0

Class easyGrid is kept for backward compatibility. Please use eiseGrid instead.

jquery_plugin eiseGrid

eiseGrid jQuery wrapper

requires jQuery UI 1.8: http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js

Published under MIT license (c)2006-2025 Ilya S. Eliseev ie@e-ise.com, easyise@gmail.com

Contributors:

  • Pencho Belneiski
  • Alexander Demidov
  • Dmitry Zakharov
  • Igor Zhuravlev

eiseGrid reference: http://russysdev.github.io/eiseIntra/gridlist

Category: Grid Display

public js_class eiseGrid(gridDIV)

eiseGrid class constructor. Object of this class encapsulates all grid functionality. jQuery plugins are just wrappers around this class methods. See jQuery plugins documentation for details.

Category: Grid Display

public js_prototype_method eiseGrid.colorRow(ev)

Color the selected rows in the grid basing on the predefined colors in the grid configuration chosen by the user from the color picker dialog

public function init(conf)

Plugin initialization method.

Parameters:

  • {*} conf Array of configuration parameters. Normally all configuration is set in PHP and passed to JS as a JSON object.

Category: Grid Display

public function addRow($trAfter, callback, conf)

This method adds a new row to the grid.

Parameters:

  • {*} $trAfter - jQuery object of the row after which the new row will be added. If not set, the row is added to the end of the grid.
  • {*} callback - function to be called after the row is added.
  • {*} conf

Category: Grid Manipulation

public function selectRow($tr, event)

Method selectRow “selects” a row in the grid by adding it to the set of selected rows and coresponding CSS class to it.

Parameters:

  • {*} $tr - row to marked as selected
  • {*} event - event object (optional) of the event that triggered the row selection

Category: Grid Manipulation

public function copyRows(rowsToCopy)

This method copies the specified rows.

Parameters:

  • {*} rowsToCopy - Array of rows to be copied.

Category: Grid Manipulation

public function getSelectedRow()

This method returns the jQuery object of the last selected row in the grid.

Category: Grid Manipulation
Returns: {*} jQuery object of the last selected row in the grid.

public function getSelectedRows()

This method returns an array of jQuery objects of all selected rows in the grid.

Returns: {*} Array of jQuery objects of all selected rows in the grid.

Category: Grid Manipulation

public function getRowID($tr)

This method returns the ID of the specified row. ID is the contents of field marked as row_id in the grid configuration on PHP side.

Parameters:

  • {*} $tr - jQuery object of the row

Returns: {*} ID of the row

Category: Grid Manipulation

public function getSelectedRowID($tr)

This method returns the ID of the last selected row in the grid. ID is the contents of field marked as row_id in the grid configuration on PHP side.

Parameters:

  • $tr

Returns: {*} ID of the last selected row

public function getSelectedRowIDs($tr)

This method returns an array of IDs of all selected rows in the grid. IDs are the contents of field marked as row_id in the grid configuration on PHP side.

Parameters:

  • $tr

Returns: {*} Array of IDs of all selected rows

Category: Grid Manipulation

public function deleteRow($tr, callback)

This function deletes a row from the grid.

Parameters:

  • {*} $tr - jQuery object of the row to be deleted.
  • {*} callback - function to be called after the row is deleted.

Category: Grid Manipulation

public function deleteSelectedRows(event, callback)

This function deletes selected rows from the grid. You can add user confirmation before deletion by adding beforeDelete callback to the eiseGrid object.

Example:

$('#myGrid').eiseGrid('beforeDelete', function(selectedRowIDs, event){
   return confirm('Are you sure you want to delete rows: '+selectedRowIDs.join(', ')+'?');
});

Parameters:

  • {*} event - The event object.
  • {*} callback - Function to be called after the rows are deleted.

Category: Grid Manipulation

public function updateRow($tr)

Function marks the specified row as updated. Can be called after changing values in the row programmatically.

Parameters:

  • {*} $tr - <tbody> jQuery object of the row(s) to be marked as updated.

Category: Grid Manipulation

public function recalcOrder()

Special function that recalculates order field (with type='order' in grid config) values for all rows in the grid.

Category: Grid Manipulation

public function moveUp(flagDontUpdateRows)

Function moves the selected row up by 1 step, if possible.

Parameters:

  • {*} flagDontUpdateRows - when true rows remain not marked as ‘updated’ during this move.

Category: Grid Manipulation

public function moveDown(flagDontUpdateRows)

Function moves the selected row down by 1 step, if possible.

Parameters:

  • {*} flagDontUpdateRows - when true rows remain not marked as ‘updated’ during this move.

Category: Grid Manipulation

public function sliceByTab3d(ID)

Special function that brings data that correspond to tab ID to the front.

Parameters:

  • {*} ID

Category: Grid Tabs

public function recalcTotals(strField)

recalcTotals method recalculates totals for the specified field in all grids matching the selector.

Parameters:

  • {*} strField

Returns:

public function totals(strField)

Function returns current totals for the specified field in all grids matching the selector. Toltals formula is defined in grid configuration on PHP side.

Parameters:

  • {*} strField

Category: Grid Data
Returns: {*} totals value

public function change(strFields, callback)

change method assigns “change” event callback for fields enlisted in strFields parameter.

Parameters:

  • {*} strFields
  • {*} callback

Returns:

public function value($tr, strField, value, text, options)

This method sets or retrieves value for field strField in specified row $tr.

Parameters:

  • {jQuery} $tr - jQuery object of the <tbody> which encloses one or more rows.
  • {string} strField - field name
  • {*} value - value to be set
  • {string} text - text representation of the value
  • {Array} options - additional options

Category: Grid Data
Returns: the value of the field if only $tr and strField parameters are set; otherwise, returns undefined.

public function text($tr, strField, text)

This method sets and/or returns text representation of data for field strField in specified row $tr.

Parameters:

  • {jQuery} $tr - jQuery object of the <tbody> which encloses one or more rows.
  • {string} strField - field name
  • {string} text - if set, this is the text representation of the value

Category: Grid Data
Returns: {string} - text representation of the value

public function focus($tr, strField)

This method sets focus to field strField in specified data row $tr.

Parameters:

  • {jQuery} $tr - jQuery object of the <tbody> which encloses one or more rows.
  • {string} strField - field name

Category: Grid Manipulation

public function validateInput($tr, strField)

Validates data for field strField in row tr. Returns true if valid.

Parameters:

  • {jQuery} $tr - jQuery object of the <tbody> which encloses one or more rows.
  • {string} strField - field name

Category: Grid Data
Returns: {boolean} - true if valid

public function validate(options)

Validates entire contents of eiseGrids matching selectors. Returns true if all data in all grids is valid.

Parameters:

  • {Array} options

Category: Grid Data
Returns: {boolean} - true if all data in all grids is valid

public function save(onSubmit)

This method wraps whole grid with FORM tag and submits it to script specified in settings. Then this data is sent to the server for processing.

Parameters:

  • {function} onSubmit - function to be called before submission. If it returns false, submission is cancelled.

Category: Grid Data Handling

public function height(nHeight, callback)

This method sets the height of the grid. Parameter nHeight specifies the new height in pixels and includes header and footer if any.

Parameters:

  • {number} nHeight - The new height of the grid.
  • {function} callback - A callback function to be executed after the height is set.

Category: Grid Display

public function dblclick(dblclickCallback)

dblclick method assigns double-click event callback for all data rows in the grid.

Parameters:

  • {*} dblclickCallback

Category: Grid Events

public function beforeDelete(callback)

This method assigns a callback function to be executed before a row is deleted. If this function returns false, the deletion is cancelled.

grid.beforeDeleteCallback fires only with eiseGrid('deleteSelectedRows') method.

Parameters:

  • {*} callback

Category: Grid Events
Returns:

public function afterDelete(callback)

This method assigns a callback function to be executed after deletion of a row. This function can be used to perform some actions in the UI or send AJAX request to the server to delete the row from the database.

grid.afterDeleteCallback fires only with eiseGrid('deleteSelectedRows') method.

Parameters:

  • {*} callback

Category: Grid Events
Returns:

public function onDelete(callback)

onDelete method assigns onDeleteCallback callback function that fires on any row deletion - doesnt matter if by eiseGrid('deleteSelectedRows') (from UI) or eiseGrid('deleteRow') method (both UI and programmatically). Doesnt matter what this function returns - row is always deleted.

Parameters:

  • {*} callback

Category: Grid Events
Returns:

public function beforeSave(onSaveCallback)

This method assigns a callback function to be executed before saving data from the grid. If this function returns false, the save operation is cancelled. Can be used for data validation before save.

Parameters:

  • {*} onSaveCallback

Category: Grid Events Grid Data Handling
Returns:

public function getGridObject()

This method returns the eiseGrid object associated with the current jQuery element. This can be useful for accessing grid methods and properties via eiseGrid object.

Returns: {Object} The eiseGrid object.

public function reset(fn)

This method resets the grid: it clears all data and restores default values in all cells. Default values defined in the grid configuration on PHP side and stored in “template row” of the grid.

Parameters:

  • {*} fn - callback function to be called after reset operation is completed.

Category: Grid Data Handling
Returns:

public function spinner(arg)

This method shows a spinner (loading indicator) in the grid while an operation is in progress. You can call this method with a boolean argument to show or hide the spinner, or with a callback function that’s being executed when the spinner is shown.

Parameters:

  • {*} arg - can be a boolean to show/hide the spinner or an object with options.

Category: Grid Display
Returns:

public function fillRow($rw, rowData)

Fills a row in the grid with data.

Parameters:

  • {*} $rw - The jQuery object representing the row to fill.
  • {*} rowData - The data to fill the row with.

Category: Grid Data Handling
Returns:

public function fill(data, fn)

Fills the grid with data.

Parameters:

  • {*} data - An array of data objects to fill the grid with.
  • {*} fn - A callback function to be called after the grid is filled.

Category: Grid Data Handling
Returns:

public function dragNDrop(fnCallback)

eiseGrid('dragNDrop', function(event){} ) method allows drag-n-drop operations on eiseGrid. It shows the target over eiseGrid when user start drag over document body. When user finishes drag it removes the target. Callback function is bound to ‘drop’ event over eiseGrid elements. Before the call grid shows the spinner. Callback is called in the context of eiseGrid object, not the main <DIV> or jQuery object. After you handle the updload with XHR or whatever you can call eiseGrid(‘fill’, [{…}, {…}] ) method to add some rows to the grid.

Parameters:

  • fnCallback (function) - (event) - the function that executes right after ‘drop’ event occured, target is hidden and spinner is shown. Context is current eiseGrid object.

Category: Grid Data Handling

public function fileUpload(fileUploadOptions)

This function preforms AJAX file upload to the server and fills the grid with returned data. It is useful for grids that manage file attachments.

Parameters:

  • {*} fileUploadOptions

Category: Grid Data Handling
Returns:

public function disableUnchanged()

This method helps to struggle with large amount of elements and PHP limits to handle them. This limit is set in max_input_vars php.ini setting and it is 1000 by default. eiseGrid(‘disableUnchanged’) disables inputs in the rows that wasn’t changed so browser doesn’t include its contents into POST. Keep your php.ini safe, call this method before your main form submits.

Returns: jQuery

Category: Grid Manipulation

public function getData(rows, cols, colsToExclude)

This function retrieves data from the grid as an array of grid rows that represented as dictionaries of field values.

Parameters:

  • {*} rows (optional) - array of jQuery <tbody> objects representing rows to get data from. If not set, data is retrieved from all rows.
  • {*} cols (optional) - array of column names to retrieve data from. If not set, data is retrieved from all columns.
  • {*} colsToExclude (optional) - array of column indexes to exclude from the retrieved data.

Category: Grid Data Handling
Returns: {Array} - array of grid rows represented as dictionaries of field values.

public function excel(options)

This function exports grid data to an Excel file.

Parameters:

  • {*} options - options for the export.

Category: Grid Data Handling
Returns:

public function getRow($tbody)

This function returns an object with row data in {xx: {v: , t: }}, pasteable to othe grid with fill() function

Parameters:

  • {*} $tbody - jQuery object of the <tbody> representing the row to get data from.

Category: Grid Data Handling
Returns: {Object} - object with row data in {xx: {v: , t: }}, pasteable to othe grid with fill() function

public js_class eiseGrid(gridDIV)

eiseGrid class constructor. Object of this class encapsulates all grid functionality. jQuery plugins are just wrappers around this class methods. See jQuery plugins documentation for details.

Category: Grid Display

public js_prototype_method eiseGrid.colorRow(ev)

Color the selected rows in the grid basing on the predefined colors in the grid configuration chosen by the user from the color picker dialog