Infragistics.WebUI.UltraWebGrid

Feedback on this topic...

Client-Side Object Model - Grid Object

The Grid Object of UltraWebGrid can be obtained within the page using the igtbl_getGridById utility function.

var grid =igtbl_getGridById('UltraWebGrid1');

The grid can also be referenced directly through the definition that is automatically generated for it. If the name of the grid on the server is 'UltraWebGrid1' then a variable called oUltraWebGrid1 will be available from anywhere within the page. The 'o' prefix is a convention used to indicate that the variable is an object as opposed to an HTML element. When a variable represents an HTML element, an 'e' is prefixed in front of it.

This topic also contains the following sections:

• Methods
• Events

Properties

AddNewBoxView

Gets an integer value that indicates what type the AddNewBox object is. This property is read-only and should not be changed.
0 = Full
1 = Compact

AddNewBoxVisible

Gets a Boolean value that indicates if the AddNewBox is visible for the grid. This property is read-only and should not be changed.

AllowAddNew

Gets or sets a value that indicates if the adding rows is permitted in the grid. This property can be changed on the client. The alignGrid method has to be called after changing the property value in order to reflect changes on the page.
0 - Not Set
1 = Yes
2 = No
var grid = igtbl_getGridById('UltraWebGrid1');
if(grid.AllowAddNew == 1)
{


igtbl_getElementById("MyLabel").innerHTML = "Press the button to add a row");

}

AllowColSizing

Gets or sets a value that indicates if column sizing is allowed for the grid as a whole. This property can be changed on the client.
0 - NotSet
1 = Fixed
2 = Free
var grid = igtbl_getGridById('UltraWebGrid1');
grid.AllowColSizing = 1;

AllowDelete

Gets or sets a Boolean value that indicates if row deleting is allowed for the grid as a whole. This property can be changed on the client.

0 - Not Set
1 = Yes
2 = No
var grid = igtbl_getGridById('UltraWebGrid1');
grid.AllowDelete = 2;

AllowPaging

Gets a Boolean value that indicates whether grid data is being displayed via paging. If paging is being used to display data, you can use the PageCount and CurrentPageIndex properties to manage paging on the client-side. This property is read-only and should not be changed.

AllowSort

Gets a value that indicates if sorting is in effect for the grid. This property is read-only and should not be changed.

0 - Not Set
1 = Yes
2 = No
3 = OnClient

AllowUpdate

Gets or sets a value that indicates if cell editing is allowed for the grid as a whole. You can also use this property to specify that editing is allowed only using row templates, which disables the in-place editing of grid data. This property can be changed on the client. But be careful, if you're going to turn it on/off on the client make sure that you set it to yes on the server and then set on the client to anything you want. Otherwise the HTML code for the edit box won't be rendered down.
0 - Not Set
1 = Yes
2 = No
3 = RowTemplateOnly
var grid = igtbl_getGridById('UltraWebGrid1');
grid.AllowUpdate = 1;

AltClass

Gets or sets a CSS class name value that specifies the style for alternate cells in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.AltClass = "MyAlternateCssClass";

Bands

Gets the array of Band objects for the grid. The length of this array is equal to the number of bands in the grid hierarchy. There is always at least one Band object in the array.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.bands[0].RowSizing = 2;

BlankImage

Gets or sets a string value that determines the image displayed to represent a blank space in the row selector. The purpose of this image is to create proper spacing in the browser. This property can be changed on the client.
var grid = igtbl_getGridById('G_UltraWebGrid1');
grid.BlankImage = "MyBlankImage.gif";

CancelPostback

Gets or sets a Boolean value that indicates whether postback should be cancelled when the next event occurs. If a postback is set to occur due to some other client-side activity, setting this property to True will prevent the postback from occurring. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.CancelPostBack = true;

CaseSensitiveSort

The property is used on the client to determine whether the client side sorting should consider the letters' case during the sorting procedure. Default value is false. Needs to be set anytime before client side sorting is done to switch between case sensitive/unsensitive sort. Has no analog on the server side.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.CaseSensitiveSort = true;

CellClickAction

Gets or sets an integer value that indicates what action will be taken when a cells are clicked in the grid by default. The property can be changed on the client.
1 = Edit
2 = Row Select
3 = Cell Select

CollapseImage

Gets or sets a string value that determines the image displayed to denote the collapsing of an expanded row. This property can be changed on the client. New image will appear on the newly added or recently expanded rows only.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.CollapseImage = "MyCollapseImage.gif";

CurrentPageIndex

Gets an integer value that specifies the index of the page of grid data that is being displayed. This property is only useful when data is being displayed in multiple pages. You can determine whether data paging is being used by checkin the value of the AllowPaging. This property is read-only and should not be changed.

CurrentEditRowImage

Gets or sets a string value that determines the image displayed when a row is the current, active row and it can be modified using its row template by clicking on the image. This property can be changed on the client. New image will appear after changing the current row.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.CurrentEditRowImage = "MyCurrentEditRowImage.gif";

CurrentRowImage

Gets or sets a string value that determines the image displayed when a row is the current, active row. This property can be changed on the client. New image will appear after changing the current row.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.CurrentRowImage = "MyCurrentRowImage.gif";

EditCellClass

Gets or sets a CSS class name value that specifies the style for cells in the grid that are being edited. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.EditCellClass = "MyEditCssClass";

Element

Returns the HTML element object corresponding to the WebGrid on the page. This property is read-only and should not be changed.
var element = igtbl_getGridById('UltraWebGrid1').Element;
element.style.color = "red";

Events

See below for Events.

Expandable

Gets an integer value that indicates if rows are expandable on the page. This property is read-only and should not be changed.
1 = Yes
2 = No

ExpandImage

Gets or sets a string value that determines the image displayed to denote the expansion of a collapsed. This property can be changed on the client. New image will appear on the newly added or recently collapsed rows only.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.ExpandImage = "MyExpandImage.gif";

ExpAreaClass

Gets or sets a CSS class name value that specifies the style for the row expansion areas of the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.ExpAreaClass = "MyExpCssClass";

FooterClass

Gets or sets a CSS class name value that specifies the style for footer cells in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.FooterClass = "MyFooterCssClass";

GroupByRowClass

Gets or sets a CSS class name value that specifies the style for GroupBy rows in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.GroupByRowClass = "MyGroupByCssClass";

HeaderClass

Gets or sets a CSS class name value that specifies the style for Column Headers in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.HeaderClass = "MyHeaderCssClass";

HeaderClickAction

Gets or sets an integer value that indicates what action will be taken when a column headers are clicked in the grid by default. The property can be changed on the client.
0 = NotSet
1 = Select
2 = SortSingle
3 = SortMulti

Id

Returns the HTML id property of the top-level WebGrid element on the page. This property is read-only and should not be changed.
var id = oUltraWebGrid1.Id;

Indentation

Gets the number of pixels used for indenting one band of rows from another in the grid. This property is read-only and should not be changed.

ItemClass

Gets or sets a CSS class name value that specifies default style for cells in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.ItemClass = "MyCssClass";

NeedPostback

Gets or sets a Boolean value that indicates whether a postback should be initiated after the following event occurs. Set this property to True to force a manual postback to occur after the next event. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.NeedPostBack = true;

NewRowImage

Gets or sets a string value that determines the image displayed to denote a row that has been added. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.NewRowImage = "MyNewRowImage";

NullText

Gets or sets a string value that determines the text displayed to denote a null value in a cell. This property can be changed on the client. Be aware that setting it on the client won't change all the null values in the grid right away, it will be applied to changed and newly added cells only.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.NullText = "[no value]";

PageCount

Gets or sets an integer value that specifies the number of pages being used to display grid data. This property is read-only and should not be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
var numpages = grid.PageCount;

RowLabelClass

Gets or sets a CSS class name value that specifies the style for row selector labels in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.RowLabelClass = "MyRowLabelCssClass";

Rows

This property returns all the Row objects for Band 0 in the grid. You can use this property to access individual rows in Band 0 and from there gain access to the other bands of the grid.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.rows[0].RowSizing = 2;

RowSelectors

Gets a Boolean value that indicates if rows selectors are visible on the page. This property is read-only and should not be changed on the client.
1 = Yes
2 = No

RowSizing

Gets an integer value that indicates if row sizing is allowed for the grid as a whole. This property can be changed on the client.
1 = Fixed
2 = Free

var grid = igtbl_getGridById('UltraWebGrid1');
grid.RowSizing = 1;

SelCellClass

Gets or sets a CSS class name value that specifies the style for selected cells in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SelCellClass = "MySelCellCssClass";

SelectTypeCell

Gets or sets an integer value that indicates the type of cell selection that is in effect for the grid. This property can be changed on the client.
0 = NotSet
1 = None
2 = Single
3 = Extended

var grid = igtbl_getGridById('UltraWebGrid1');
grid.SelectTypeCell = 2;

SelectTypeColumn

Gets or sets an integer value that indicates the type of column selection that is in effect for the grid. This property can be changed on the client.
0 = NotSet
1 = None
2 = Single
3 = Extended
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SelectTypeCOlumn = 2;

SelectTypeRow

Gets or sets an integer value that indicates the type of row selection that is in effect for the grid. This property can be changed on the client.
0 = NotSet
1 = None
2 = Single
3 = Extended
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SelectTypeRow= 2;

SelGroupByRowClass

Gets or sets a CSS class name value that specifies the style for selected GroupBy rows in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SelGroupbyRowClass = "MySelGroupByCssClass";

SelHeadClass

Gets or sets a CSS class name value that specifies the style for selected column headers in the grid. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SetHeadClass = "MySelHeadCssClass";

ShowBandLabels

Gets or sets a Boolean value that indicates if band labels are visible on the page.

SortAscImg

Gets or sets a string value that determines the image displayed in the coulmn header of a column that is sorted in ascending order. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SortAscImg = "AscSortArrow.gif";

SortDscImg

Gets or sets a string value that determines the image displayed in the coulmn header of a column that is sorted in descending order. This property can be changed on the client.
var grid = igtbl_getGridById('UltraWebGrid1');
grid.SortDscImg = "DscSortArrow.gif";

StationaryMargins

Sets the margins to be stationary. This property is read-only and should not be changed on the client.
0 = No
1 = Header
2 = Footer
3 = HeaderAndFooter

UniqueID

Gets a value that correpsonds to the name of the element on the server. For a simple UltraWebGrid element hosted on an ASP.NET page, this will evaluate to the name of the element that was assigned in the development environment (i.e. UltraWebGrid1.) For an UltraWebGrid element that is part of a user control, this will evaluate to the name of the user control concatenated with the name of the UltraWebGrid element. The names of the user and the UltraWebGrid element are separted with a colon in server-side code, but the colon is omitted on the client-side to make this property JavaScript friendly. So if you have a user control containing an UltraWebGrid, its unique ID on the server might by "MyWebControl:UltraWebGrid1" while the value returned by the UniqueID property on the client side would be "MyWebControlUltraWebGrid1". You can use this property to ensure that your client-side code references the correct server-based element.
var grid = igtbl_getGridById('UltraWebGrid1');
var thisGridId = grid.UniqueID;

ViewType

Gets an integer value that indicates the type of view that is displayed for the grid. This property is read-only and should not be changed on the client.
0 = Flat
1 = Heirarchical
2 = OutlookGroupBy

Methods

addSortColumn

Adds the specified column to the sorted columns array.

• Parameters:
  colID - The ID of the column to use when sorting.
  clear - Boolean parameter that specifies whether the current contents of the sorted columns array should be cleared when the new column is added. If set to true the array is cleared and the specified column becomes the only column in the array and the only sort criterion. If set to false, the specified column is simply added to any existing columns in the array as an additional sort criterion.

alignGrid

Aligns the grid's activation rectangle to the upper-left corner of the data area. If a row is currently active, that row becomes the topmost row. If a cell is active, that cell's row is scrolled to the topmost position, and it's column is scrolled to the leftmost position.

• Parameters:
  param1 - The_first_parameter.
  param2 - The_second_parameter.

beginEditTemplate

Opens the template for the currently active row. The template provides an alternate means for the user to enter row data using distinct elements.

• Parameters:
  None.

deleteSelectedRows

Deletes any rows that are currently selected in the grid.

• Parameters:
  None.

endEditTemplate

Closes the editing template for the currently active row. Changes to the template's controls can be either applied to row data or discarded.

• Parameters:
  saveChanges - A Boolean value that specifies whether changes made to the controls in the template should be applied to the data in the row. If set to true, changes will be applied. If set to false, changes will be discarded.

find

Searches through the grid data for a specified string. Regular expression syntax is supported for advanced searches.

• Parameters:
  regExp - The regular expression used to seatch the data. This may be omitted on subsequent calls to the find method; the previously specified expression will be used to perform the search.
  searchUp - A Boolean value that specifies the direction of the search. If set to true the serach is performed from bottom to top. If set to false (or omitted) the search is performed from top to bottom.

findNext

Searches through the grid data for a specified string, starting at the location of the previous find. Regular expression syntax is supported for advanced searches.

• Parameters:
  regExp - The regular expression used to seatch the data. This may be omitted on subsequent calls to the find method; the previously specified expression will be used to perform the search.
  searchUp - A Boolean value that specifies the direction of the search. If set to true the serach is performed from the position of the previous find to the top of the data. If set to false (or omitted) the search is performed from the position of the previous find to the bottom of the data.

getActiveCell

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

• Parameters:
  None.

getActiveRow

Returns a Row object representing the active row within the grid. The active row is the row that contains the active cell in the grid.

• Parameters:
  None.

selectCellRegion

Selects multiple cells in a rectangular region.

• Parameters:
  cell1 - The beginning of the selection. This cell will serve as the anchor of the selection area, determining where the selection starts.
  cell2 - The end of the selection. This cell will be the last cell selected and will determine where the selection area stops.

selectColRegion

Selects multiple columns in the band.

• Parameters:
  col1 - The beginning of the selection. This column will serve as the anchor of the selection range, determining where the selection starts.
  col2 - The end of the selection. This column will be the last column selected and will determine where the selection range stops.

selectRowRegion

Selects multiple rows in the band.

• Parameters:
  row1 - The beginning of the selection. This row will serve as the anchor of the selection range, determining where the selection starts.
  row2 - The end of the selection. This row will be the last row selected and will determine where the selection range stops.

setActiveCell

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

• Parameters:
  cell - The Cell object to be made active.

setActiveRow

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

• Parameters:
  row - The Row object to be made active.

sort

This method sorts the grid on the client-side, using the columns specified in the sorted columns array.

• Parameters:
  None.

sortColumn

Sorts the grid on the client-side using the specified column's contents as the sort criteria.

• Parameters:
  colID - The ID of the column to use when sorting.
  shiftKey - Boolean parameter that specifies whether to perform a multi-column sort. If true, the specified column is added to the sorted columns array, and the sort is done based on the columns in the array. If false or omitted, only a single column is used. The contents of the sorted columns array are cleared and the specified column becomes the only one in the array.

unloadGrid

Destroys any allocated variables and arrays that have been created on the client-side by the control. This method should ONLY be invoked from the onUnload event of the page.

• Parameters:
  None.

Events

The Events object contains over 25 members that are used to specify JavaScript function handlers that are called in response to a variety of events occurring on the client. The Event member is only populated with a valid JavaScript function if the function name is set from the Events object of the DisplayLayout object on the server. 

All events are called with at least two parameters: The grid name, and the ID of the element on which the event occurred. In the case of the BeforeCellUpdate event, an additional parameter is added which specifies the new value for the cell.

Note that gn is the parameter in the grid that the event came from, and id is the object that the event is on.

The members of the Events object are:

AfterCellUpdate(gn, id) AfterColumnMove(gn, id) AfterColumnSizeChange (gn, id, width) AfterEnterEditMode(gn, id) AfterExitEditMode(gn, id) AfterRowActivate(gn, id) AfterRowCollapsed(gn, id) AfterRowDeleted(gn, id) AfterRowExpanded(gn, id) AfterRowInsert(gn, id) AfterRowSizeChange(gn, id, height) AfterRowTemplateClose(gn, id) AfterRowTemplateOpen(gn, id) AfterSelectChange(gn, id) AfterSortColumn(gn, id) BeforeCellChange(gn, id)

BeforeCellUpdate(gn, id, newValue) BeforeColumnMove(gn, id) BeforeColumnSizeChange(gn, id, width) BeforeEnterEditMode(gn, id) BeforeExitEditMode(gn, id) BeforeRowActivate(gn, id) BeforeRowCollapsed(gn, id) BeforeRowDeleted(gn, id) BeforeRowExpanded(gn, id) BeforeRowInsert(gn, id) BeforeRowSizeChange(gn, id, height) BeforeRowTemplateClose(gn, id) BeforeRowTemplateOpen(gn, id) BeforeSelectChange(gn, id) BeforeSortColumn(gn, id) CellChange(gn, id)

ClickCellButton(gn, id) ColumnDrag(gn, colId, insertBeforeColumnId) DblClick(gn, id) EditKeyDown(gn, id, keyCode) EditKeyUp(gn, id, keyCode) InitializeLayout(gn, id) InitializeRow(gn, id) KeyDown(gn, id, keyCode) KeyUp(gn, id, keyCode) MouseDown(gn, id, button) MouseOver(gn, id, type) MouseOut(gn, id, type) MouseUp(gn, id, button) TemplateUpdateCells(gn, templateId, cellId) TemplateUpdateControls(gn, templateId, cellId, value) ValueListSelChange(gn, valueListId, cellId)