Client-Side Object Model - Utility Functions

Infragistics.WebUI.UltraWebGrid

Feedback on this topic...

Client-Side Object Model - Utility Functions

Introduction

The utility functions described here are used by the JavaScript code of the UltraWebGrid Control. The purpose of exposing and documenting them is to allow developers to put as much logic as possible on the client machine in order to obtain gains in both performance and functionality.

Many of these Utility functions are involved with more than simply returning a property value. They are concerned with 'resolving' the property value according to an ordered set of precedance rules. The rules of precedance are straightforward: Check the local value first, if that value is 0, meaning notset, check the next most local value.  This may be the Row, Column, Band or Grid. Repeat the procedure until either a value is found, or the Grid object default is encountered and applied.

HTML ID Formats

Many functions and properties are based on the Id of elements within the page. The Ids of elements is based upon a method of identifying Table and Cell objects uniquely as to owner and position within the Document Object Model, (DOM) of the page. The element most commonly used for funciont calls is the <TD> tag element. The Id of <TD> the tag is made up of several distinct components that are interpreted by the JavaScript in order to identify the position of the <TD> tag or cell within the DOM. The following Id is an example of a typical <TD> tag Id representing a cell:

<td id='UltraWebGrid1rc_3_2_4'>

The components of the Id are delimited by the underscore character. The first component indicates the Id of the owning grid. The next component is the object type identifier: in this case 'rc', indicating that the object is a cell. If the object is a cell, the last component indicates the column number within the band that the cell belongs to. The components between the object type identifier and the last position indicate the row position of the cell within the band hierarchy. In this case the Id indicates the 4th column within the 2nd child row of the 3rd top-level row of the grid. The number of bands references by the Id is equal to the total number of components in the Id minus 2.

The following Id is an example of a typical <TH> tag Id representing a column:

<td id='UltraWebGrid1c_2_4'>

The first component indicates the Id of the owning grid. The next component is the object type identifier: in this case 'c', indicating that the object is a column. The next component is the index of the Band to which the column belongs. And the last component is the index of the column within the band.

Functions

To see a description and example of the function, click on the text of the function.
If you want to see all of the function definitions and examples expanded, click here.
To collapse all definitions and examples, click here.

function igcmbo_getComboById(string comboId)

Returns a WebCombo object based on the passed in Id value as it exists on the server. This function is useful in situations where the first parameter of a WebCombo client-side event is being used to identify which control fired the event. It is also necessary for obtaining the oCombo reference from within the InitializeCombo event, because the oWebCombo variable has not yet been assigned at that point.

var oCombo = igcmbo_getComboById('WebCombo1');

function igtbl_getElementById(string tagId)

Returns a DOM (Document Object Model) Element object based on its tag Id in a browser independant way. In order to return a valid DOM element, the Id parameter must exist within the current document as the Id attribute of an HTML element.

var elem = igtbl_getElementById('MyElemId');
elem.style.backgroundColor = "Red";

function igtbl_getGridById(string gridId)

Returns a Grid object based on its tag Id. The Grid object returned is a JavaScript object that contains many of the properties of UltraWebGrid as it exists within the HTML page. The Id of the Grid object is the name of the Grid on the Server. See Grid Object.

var grid = igtbl_getGridById('UltraWebGrid1');
grid.AllowUpdate = false;

function igtbl_getBandById(string cellId)

Returns a Band object based on the tag Id of a Cell within the grid. The function returns the Band object to which the Cell belongs. The Cell Id is the Id tag of the <TD> element representing a Grid Cell within the HTML page. The Band object returned is a JavaScript object that contains the properties of the Band object as it exists within the HTML page. See Band Object.

var band = igtbl_getBandById('UltraWebGrid1_2_3_1_4');

function igtbl_getColumnById(string cellId)

Returns a Column object based on the tag Id of a Cell within the grid. The function returns the Column object to which the Cell belongs. The CellId parameter is the Id tag of the <TD> element representing a Grid Cell within the HTML page. The Column object returned is a JavaScript object that contains the properties of the Column object as it exists within the HTML page. See Column Object.

var column = igtbl_getColumnById('UltraWebGrid1_2_3_1_4');

function igtbl_getRowById(string CellId)

Returns a Row object based on the tag Id of a Cell within the grid. The function returns the Row object to which the Cell belongs. The CellId parameter is the Id tag of the <TD> element representing a Grid Cell within the HTML page. The Row object returned is a JavaScript object that contains the properties of the Row object as it exists within the HTML page. See Row Object.

var row = igtbl_getRowById('UltraWebGrid1_2_3_1_4');

function igtbl_getCellById(string CellId)

Returns a Cell object based on the tag Id of a Cell within the grid. The function returns the Cell object corresponding to the CellId parameter. The CellId parameter is the Id tag of the <TD> element representing a Grid Cell within the HTML page. The Cell object returned is a JavaScript object that contains the properties of the Cell object as it exists within the HTML page. This utility function differs from the function igtbl_getElementById in that it returns a new object that exposes special properties of a grid Cell as opposed to the HTML DOM object that represents the <TD> tag within the HTML page. See Cell Object.

var cell = igtbl_getCellById('UltraWebGrid1_2_3_1_4');

function igtbl_getActiveCell(string gridName)

Returns a Cell object representing the active cell within the grid.

var cell = igtbl_getActiveCell('UltraWebGrid');

function igtbl_getActiveRow(string gridName)

Returns a Row object representing the active row within the grid

var row = igtbl_getActiveRow('UltraWebGrid');

function igtbl_isCell(string itemName)

Returns a boolean value that indicates if the item denotes a Cell within the grid

var bCell = igtbl_isCell('UltraWebGrid1rc_1_3');

function igtbl_isRowLabel(string itemName)

Returns a boolean value that indicates if the item denotes a Row within the grid

var bRowLabel = igtbl_isRowLabel('UltraWebGrid1l_1_3');

function igtbl_isColumnHeader(string itemName)

Returns a boolean value that indicates if the item denotes a Column within the grid

var bColHeader = igtbl_isColumnHeader('UltraWebGrid1c_1_3');

function igtbl_getCollapseImage(string gridName, int bandNo)

Returns the resolved CollapseImage string for a band. If the value for the Band is null, the function returns the Grid default.

var image = igtbl_getCollapseImage('UltraWebGrid1', 0);

function igtbl_getExpandImage(string gridName, int bandNo)

Returns the resolved ExpandImage string for a band. If the value for the Band is null, the function returns the Grid default.

var image = igtbl_getExpandImage('UltraWebGrid1', 0);

function igtbl_getCellClickAction(string gridName, int bandNo)

Returns the resolved CellClickAction value for a band. If the value for the Band is 0, the function returns the Grid default.

var clickAction = igtbl_getCellClickAction('UltraWebGrid1', 0);

function igtbl_getSelectTypeCell(string gridName, int bandNo)

Returns the resolved SelectTypeCell value for a band. If the value for the Band is 0, the function returns the Grid default.

var selectType = igtbl_getSelectTypeCell('UltraWebGrid1', 0);

function igtbl_getSelectTypeColumn(string gridName, int bandNo)

Returns the resolved SelectTypeColumn value for a band. If the value for the Band is 0, the function returns the Grid default.

var selectType = igtbl_SelectTypeColumn('UltraWebGrid1', 0);

function igtbl_getSelectTypeRow(string gridName, int bandNo)

Returns the resolved SelectTypeRow value for a band. If the value for the Band is 0, the function returns the Grid default.

var selectType = igtbl_getSelectTypeRow('UltraWebGrid1', 0);

function igtbl_getHeaderClickAction(string gridName, int bandNo, int columnNo)

Returns the resolved HeaderClickAction value for a column. If the value for the Column is 0, the function checks the Band. If the value for the Band is null, the function returns the Grid default.

var clickAction = igtbl_getHeaderClickAction('UltraWebGrid1', 0, 2);

function igtbl_getAllowUpdate(string gridName, int bandNo, int columnNo)

Returns the resolved AllowUpdate value for a column. If the value for the Column is 0, the function checks the Band. If the value for the Band is null, the function returns the Grid default.

var update = igtbl_getAllowUpdate('UltraWebGrid1', 0, 3);

function igtbl_getAllowColSizing(string gridName, int bandNo, int columnNo)

Returns the resolved AllowColSizing value for a column. If the value for the Column is 0, the function checks the Band. If the value for the Band is null, the function returns the Grid default.

var sizing = igtbl_getAllowColSizing('UltraWebGrid1', 0, 2);

function igtbl_getRowSizing(string gridName, int bandNo, string row)

Returns the resolved AllowRowSizing value for a row. If the value for the Row is 0, the function checks the Band. If the value for the Band is null, the function returns the Grid default.

var sizing = igtbl_getRowSizing('UltraWebGrid1', 0, 'UltraWebGrid1r_3');

function igtbl_getRowSelectors(string gridName, int bandNo)

Returns the resolved RowSelectors value for a band. If the value for the Band is null, the function returns the Grid default.
1 = Yes
2 = No

var selectors = igtbl_getRowSelectors('UltraWebGrid1', 0);

function igtbl_getNullText(string gridName, int bandNo, int columnNo)

Returns the resolved NullText value for a cell. If both the Column and Band are null, the function returns the Grid default.

var image = igtbl_getNullText('UltraWebGrid1', 0, 5);

function igtbl_getEditCellClass(string gridName, int bandNo)

Returns the resolved style class name for editing the cells of a band. If the Band property is null, the function returns the Grid default.

var class = igtbl_getEditCellClass('UltraWebGrid1', 0);

function igtbl_getFooterClass(string gridName, int bandNo, int columnNo)

Returns the resolved style class name for displaying the footer of a column. If the Column and Band values are null, the function returns the Grid default.

var Class = igtbl_getFooterClass('UltraWebGrid1', 0, 4);

function igtbl_getGroupByRowClass(string gridName, int bandNo)

Returns the resolved style class name for displaying grouped rows of a band. If the Band property is null, the function returns the Grid default.

var class = igtbl_getGroupByRowClass('UltraWebGrid1', 0);

function igtbl_getHeadClass(string gridName, int bandNo, int columnNo)

Returns the resolved style class name for displaying the header of a column. If the Column and Band values are null, the function returns the Grid default.

var class = igtbl_getHeadClass('UltraWebGrid1', 0);

function igtbl_getRowLabelClass(string gridName, int bandNo)

Returns the resolved style class name for displaying row labels of a band. If the Band property is null, the function returns the Grid default.

var class = igtbl_getRowLabelClass('UltraWebGrid1', 0);

function igtbl_getSelGroupByRowClass(string gridName, int bandNo)

Returns the resolved style class name for selected grouped rows of a band. If the Band property is null, the function returns the Grid default.

var class = igtbl_getSelGroupByRowClass('UltraWebGrid1', 0);

function igtbl_getSelHeadClass(string gridName, int bandNo, int columnNo)

Returns the resolved style class name for displaying the selected column headers. If the Column and Band values are null, the function returns the Grid default.

var class = igtbl_getSelHeadClass('UltraWebGrid1', 0);

function igtbl_getSelCellClass(string gridName, int bandNo, int columnNo)

Returns the resolved style class name for displaying the selected cells. If the Column and Band values are null, the function returns the Grid default.

var class = igtbl_getSelCellClass('UltraWebGrid1', 0);

function igtbl_getExpAreaClass(string gridName, int bandNo)

Returns the resolved style class name for displaying the row expansion area of a band. If the Band property is null, the function returns the Grid default.

var class = igtbl_getExpAreaClass('UltraWebGrid1', 0);

function igtbl_toggleRow(string gridName, string srcRow, boolean expand)

Toggles the expanded state of a row between expanded and collapsed.
gn - the grid name
srcRow - the Id of the row to be toggled
expand - if True, the rows is expanded. If False, the row is collapsed

igtbl_toggleRow('UltraWebGrid1', 'UltraWebGrid1r_1_2', true);

function igtbl_clearSelectionAll(string gridName)

Clears the selection state of the grid so that no cells, columns or rows are selected.
gn - the grid name.

igtbl_clearSelectionAll('UltraWebGrid1');

function igtbl_selectCell(string gridName, string cellId, boolean selFlag, boolean fireEvent)

Turns selection on or off for the specified cell.
gn - the grid name
cellId - the id of the cell
selFlag - if True, the cell is selected. If False, the cell is unselected
fireEvent - if true, an event is fired to listeners.

igtbl_selectCell('GltraWebGrid1', 'UltraWebGrid1_1_2_3', true, false);

function igtbl_selectRow(string gridName, string rowId, boolean selFlag, boolean fireEvent)

Turns selection on or off for the specified row.
gn - the grid name
rowId - the id of the row
selFlag - if True, the row is selected. If False, the row is unselected
fireEvent - if True, an event is fired to listeners.

igtbl_selectRow('UltraWebGrid1', 'UltraWebGrid1r_1_2', true, false);

function igtbl_selectColumn(string gridName, string columnId, boolean selFlag, boolean fireEvent)

Turns selection on or off for the specified column.
gn - the grid name
columnId - the id of the column
selFlag - if True, the column is selected. If False, the column is unselected
fireEvent - if True, an event is fired to listeners.

igtbl_selectColumn('UltraWebGrid1', 'UltraWebGrid1c_1_2', true, false);

function igtbl_setActiveCell(string gridName, element cell)

Makes the specified cell element the active cell in the grid. This cell will have a border rectangle drawn around its perimeter.
gn - the grid name
cell - the cell element

var cell= igtbl_getActiveCell();
cell = cell.NextSibling;
if(cell != null)
    igtbl_setActiveCell('UltraWebGrid1', cell);

function igtbl_setActiveRow(string gridName, element row)

Makes the specified row element the active row in the grid. This row will have a border rectangle drawn around its perimeter.
gn - the grid name
row - the row element

var row = igtbl_getActiveRow();
row = row.NextSibling;
if(row != null)
    igtbl_setActiveRow('UltraWebGrid1', row);

function igtbl_getInnerText(sourceElement)

Returns the InnerText value of an HTML element in a browser-independant way.

var innerText = igtbl_getInnerText(igtbl_getElementById('UltraWeGrid1_1_3_4_1'));
var innerText = igtbl_getInnerText('UltraWebGrid1_1_1');

function igtbl_setInnerText(sourceElement, strText)

Sets the InnerText value of an HTML element in a browser independant way.

igtbl_setInnerText(igtbl_getElementById('UltraWeGrid1_1_3_4_1'), 'Cell Value');
igtbl_setInnerText('UltraWebGrid1_1_2', "newValue");

function igtbl_scrollToView(gn, child)

Scrolls a child object of the grid (row or cell) into view.
gn - the grid name
child - the DOM object you want to place into view. The child parameter has to be a child of the grid.

var row = igtbl_getElementById(rowId);
igtbl_scrollToView(gn, row);

 

<script language=JavaScript> </script>