Getting familiar with client-side API

Table of Contents

Introduction
More about RadControls for ASP.NET AJAX
Licensing
Installation and deployment
RadControls for ASP.NET AJAX Fundamentals
Controls
- RadAjax
- RadCalendar
- RadChart
- RadColorPicker
- RadComboBox
- RadDock
- RadEditor
- RadGrid
  - Overview
  - General information
  - Migration from RadGrid for ASP.NET To ASP.NET AJAX
  - What is new
  - Functional overview
  - ASP.NET 2.0+ Features
  - Getting Started
  - Grid columns
  - Grid rows
  - Defining Structure
  - Visible/Enabled conventions
  - Populating the control with data
  - AJAXified RadGrid
  - Sorting
  - Paging
  - Scrolling
  - Grouping
  - Filtering
  - Selecting grid items
  - Insert/Update/Delete records
  - Hierarchical grid types and Load modes
  - Design-time support
  - Controlling visual appearance
  - Localization/Accessibility
  - RadGrid export
  - The control lifecycle
  - Performance tips and tricks
  - How-to
  - Troubleshooting
  - Application scenarios
  - Telerik RadGrid inheritance
  - Getting familiar with server-side API
  - Getting familiar with client-side API
  - Client-side API Reference
- RadInput
- RadMenu
- RadPanelBar
- RadRotator
- RadScheduler
- RadSlider
- RadSpell
- RadSplitter
- RadTabStrip
- RadToolBar
- RadToolTip
- RadTreeView
- RadUpload
- RadWindow
- RadFormDecorator
- RadScriptManager
- RadStyleSheetManager
- RadSkinManager
- Controlling absolute positioning with z-index
- Changes and backwards compatibility in RadControls latest release
Integrating RadControls in MOSS
Integrating RadControls in DNN
API Reference
APIReference
For More Help

Controls > RadGrid > Getting familiar with client-side API

Glossary Item Box

Client-side Object Model

Telerik RadGrid provides the following objects on the client-side:

Classes/properties	Description
RadGrid	This is the main class. You can use it to access the whole grid object. See Rad Grid Class Overview for details.
<RadGridInstance>.get_masterTableView()	This is an object of type GridTableView. This object is used to access the root table in hierarchical structures.
<RadGridInstance>.get_masterTableViewHeader()	Returns the master table header instance for the respective grid client object.
<RadGridInstance>.get_masterTableViewFooter()	Returns the master table footer instance for the respective grid client object.
<RadGridInstance>.get_detailTables()	This collection represents the detail tables when you have a hierarchical structured grid. Every table is of type GridTableView.
<RadGridInstance>.get_allowMultiRowSelection()	This property is of type Boolean. When set to true, you can select multiple rows on the client.
GridTableView	Class which wraps the client-side features of the GridTableView object. Each GridTableView client instance has GridColumn and GridDataItem objects for manipulating the grid's items and columns client-side.
<GridTableViewInstance>.get_owner()	This property is of type RadGrid and present the parent of the current object.
<GridTableViewInstance>.get_element()	Returns HTML table which represents the respective table for the GridTableView object rendered on the client.
<GridTableViewInstance>.get_dataItems()	A collection which holds all data items (objects of type GridDataItem) in the respective table.
<GridTableViewInstance>.get_selectedItems()	A collection which holds all selected items (objects of type GridDataItem) in the respective table. This collection will include the selected items from the table's child tables (meaningful in hierarchical grid only).
<GridTableViewInstance>.get_columns()	A collection which holds objects of type GridColumn (the client-side objects) in the respective table.
<GridTableViewInstance>.get_name()	String which represents the Name property (set on the server) for the corresponding GridTableView client object. Can be used to identify table in grid hierarchy client-side.
<GridTableViewInstance>.get_isItemInserted()	Boolean property. Gets a value indicating if the GridTableView is currently in insert mode.
<GridTableViewInstance>.get_pageSize()	Returns the page size for the respective GridTableView object.
<GridTableViewInstance>.set_pageSize()	Sets the page size for the respective GridTableView object.
<GridTableViewInstance>.get_currentPageIndex()	Returns the current page index for the respective GridTableView object.
<GridTableViewInstance>.set_currentPageIndex()	Sets the current page index for the respective GridTableView object.
<GridTableViewInstance>.get_pageCount()	Returns the page count for the respective GridTableView object.
<GridTableViewInstance>.get_clientDataKeyNames()	One-dimensional array which holds the key fields set through the ClientDataKeyNames property of GridTableView on the server. To extract the key values you can use the eventArgs.getDataKeyValue inside any row-related client event handler of RadGrid.
<GridTableViewInstance>.get_parentView()	If called from a nested table view returns the parent table view (of type GridTableView) in the grid hierarchy; returns null if called from the MasterTableView.
<GridTableViewInstance>.get_parentRow()	If called from a nested table view returns the parent row (html table row - <tr>) for the current nested hierarchical table view; returns null if called from the MasterTableView.

Important note: For performance reasons, the <GridTableViewInstance>.get_dataItems() collection will be available only when you enable specific client features/events for the rows in the grid (such AllowRowResize, AllowRowSelect, OnRowClick, etc.).

Important note: If you want to reference the client object of a grid row inside a client event handler of RadGrid, make sure that you attached the RowCreated event of the control specifying an empty event handler, namely:

<telerik:RadScriptBlock id="RadScriptBlock1" runat="server">
<script type="text/javascript>
function RowCreated(){}
</script>
</telerik:RadScriptBlock>
<telerik:RadGrid id="RadGrid1" runat="server" ....>
<ClientSettings ClientEvents-OnRowCreated="RowCreated" />
</telerik:RadGrid>

otherwise eventArgs.get_gridDataItem() will return null. This is due to performance reasons (avoiding the client serialization of grid items by default).

Alternative method to reference a grid row client-side is through the get_dataItems() collection.

Client-side Events

RadGrid events

Event	Description
OnGridCreating	This event is fired before the grid is created.
OnGridCreated	This event is fired after the grid is created.
OnGridDestroying	This event is fired when the Telerik RadGrid object is destroyed, i.e. on each window.onunload

MasterTableView events

Event	Description
OnMasterTableViewCreating	This event is fired before the MasterTableView is created.
OnMasterTableViewCreated	This event is fired after the MasterTableView is created.

MasterTableView, DetailTables events

Event		Description
*Table Creation*
OnTableCreating		This event is fired before the table is created.
OnTableCreated		This event is fired after the table is created.
OnTableDestroying		This event is fired when table object is destroyed.
Column Creation
OnColumnCreating		This event is fired before column is created on client-side.
OnColumnCreated		This event is fired after a column is created on client-side.
OnColumnDestroying		This event is fired when a column object is destroyed.
*Column Resizing*
OnColumnResizing		This event is fired before a column is resized.
OnColumnResized		This event is fired after a column is resized.
*Columns Ordering*
OnColumnSwaping		This event is fired before two columns are swapped.
OnColumnSwaped		This event is fired after two columns are swapped.
OnColumnMovingToLeft		This event is fired before a column is moved to the left.
OnColumnMovedToLeft		This event is fired after a column is moved to the left.
OnColumnMovingToRight		This event is fired before a column is moved to the right.
OnColumnMovedToRight		This event is fired after a column is moved to the right.
*Row Creation*
OnRowCreating		This event is fired before a row available client-side is created.
OnRowCreated		This event is fired after a row available client-side is created.
OnRowDestroying		This event is fired when a row object is destroyed.
*Row Resizing*
OnRowResizing		This event is fired before a row is resized.
OnRowResized		This event is fired after a row is resized.
*Row Selection*
OnRowSelecting		This event is fired before row selection.
OnRowSelected		This event is fired after row selection.
OnRowDeselecting		This event is fired before row deselection.
OnRowDeselected		This event is fired after row deselection.
*OnClick and OnDblClick Events*
OnRowClick		This event is fired when a row is clicked.
OnRowDblClick		This event is fired when a row is double-clicked.
OnColumnClick		This event is fired when a column is clicked.
OnColumnDblClick		This event is fired when a column is double-clicked.
*Mouse Events*
OnRowMouseOver		This event is fired when the mouse hovers over a row.
OnRowMouseOut		This event is fired when the mouse leaves a row.
OnColumnMouseOver		This event is fired when the mouse hovers over a column.
OnColumnMouseOut		This event is fired when the mouse leaves a column.
*Context Menus*
OnColumnContextMenu		This event is fired when the context menu for a column is called.
OnRowContextMenu		This event is fired when the context menu for a row is called.
*Column Visibility*
OnColumnHiding		This event is fired before a column is hidden.
OnColumnHidden		This event is fired after a column is hidden.
*Row Visibility*
OnRowHiding		This event is fired before a row is hidden.
OnRowHidden		This event is fired after a row is hidden.
*Row Deletion*
OnRowDeleting		This event is fired before a row is deleted (client-side delete).
OnRowDeleted		This event is fired after a row is deleted (client-side delete).
		*Hierarchy Expansion*
OnHierarchyExpanding		This event is fired when the hierarchy is being expanded.
OnHierarchyExpanded		This event is fired when the hierarchy has been expanded.
OnHierarchyCollapsing		This event is fired when the hierarchy is being collapsed.
OnHierarchyCollapsed		This event is fired when the hierarchy has been collapsed.
		*Group Expansion*
OnGroupExpanding		This event is fired when the group is being expanded.
OnGroupExpanded		This event is fired when the group has been expanded.
OnGroupCollapsing		This event is fired when the group is being collapsed.
OnGroupCollapsed		This event is fired when the group has been collapsed.
		*PopUp*
OnPopUpShowing		This event is fired when the pop-up edit form is being shown.
		*Column Showing*
OnColumnShowing		This event is fired before a column is shown.
OnColumnShown		This event is fired after a column is shown.
		*Row Showing*
OnRowShowing		This event is fired before a row is shown.
OnRowShown		This event is fired when the row is shown.
		*Row Drag and Drop*
OnRowDragStarted		This event is fired when a row is about to be dragged.
OnRowDropping		This event is fired before a row is dropped.
OnRowDropped		This event is fired after a row is dropped.
		*Active Row Changing*
OnActiveRowChanging		This event is fired before the active row change.
OnActiveRowChanged		This event is fired after the active row is changed.
		*Filter Menu*
OnFilterMenuShowing		This event is fired before the filtering menu is rendered.
		*Data Binding*
OnRowDataBound		This event is fired when a row is about to be bound on the client.
OnDataBinding		This event is fired when the grid is about to be bound on the client.
OnDataBound		This event is fired right after the grid is bound on the client.
		*Scrolling*
OnScroll		This event is fired when you scroll the grid.
		*Command*
OnCommand		This event is fired for each grid command which is about to be triggered (sorting, paging, filtering, editing, etc.) before postback/ajax request .

Obtaining GridTableView properties

Classes/properties	Description
RadGrid	This is the main class. You can use it to access the whole grid object. See Rad Grid Class Overview for details.
.get_masterTableView()	This is an object of type GridTableView. This object is used to access the root table in hierarchical structures.
.get_masterTableViewHeader()	Returns the master table header instance for the respective grid client object.
.get_masterTableViewFooter()	Returns the master table footer instance for the respective grid client object.
.get_detailTables()	This collection represents the detail tables when you have a hierarchical structured grid. Every table is of type GridTableView.
GridTableView	Class which wraps the client-side features of the GridTableView object. Each GridTableView client instance has GridColumn and GridDataItem objects for manipulating the grid's items and columns client-side.
.get_dataItems()	A collection which holds all data items (objects of type GridDataItem) in the respective table
.get_selectedItems()	A collection which holds all selected items (objects of type GridDataItem) in the respective table. This collection will include the selected items from the table's child tables (meaningful in hierarchical grid only).
.get_columns()	A collection which holds objects of type GridColumn (the client-side objects) in the respective table.
.get_name()	String which represents the Name property (set on the server) for the corresponding GridTableView client object. Can be used to identify table in grid hierarchy client-side.
.get_isItemInserted()	Boolean property. Gets a value indicating if the GridTableView is currently in insert mode.
.get_pageSize()	Returns the page size for the respective GridTableView object.
.set_pageSize()	Sets the page size for the respective GridTableView object.
.get_currentPageIndex()	Returns the current page index for the respective GridTableView object.
.set_currentPageIndex()	Sets the current page index for the respective GridTableView object.
.get_pageCount()	Returns the page count for the respective GridTableView object.
.get_clientDataKeyNames()	One-dimensional array which holds the key fields set through the ClientDataKeyNames property of GridTableView on the server. To extract the key values you can use the eventArgs.getDataKeyValue inside any row-related client event handler of RadGrid.
.get_parentView()	If called from a nested table view returns the parent table view (of type GridTableView) in the grid hierarchy; returns null if called from the MasterTableView.
.get_parentRow()	If called from a nested table view returns the parent row (html table row - <tr>) for the current nested hierarchical table view; returns null if called from the MasterTableView.

Obtaining GridTableView elements

You can further refer to the elements of the RadGridTable using the functions below:

<GridTableViewInstance>.get_columns()[n].get_element() -> the real HTML table column for the n-th column (<th> for header cell)
<GridTableViewInstance>.get_dataItems()[n].get_element() -> the real HTML table row for the n-th row (<tr> element)

Manipulating GridTableView elements

Telerik RadGrid provides means for client-side manipulation of the table elements.

Working with grid data items

Method	Description
selectItem (gridItem)	The row passed as an argument will become selected.
deselectItem(gridItem)	The row passed as an argument will become deselected.
selectAllItems()	Selects all items in the GridTableView for which the method is invoked.
clearSelectedItems()	Method which clears the selected items for the respective GridTableView client object. This method will clear the selected items from the table's child tables (meaningful in hierarchical grid only).
hideItem(index)	The row at position rowIndex will be hidden.
showItem(index)	The row at position rowIndex will be shown.
expandItem(index)	Method which expands the table row with index passed as an argument. If the index corresponds to nested table item, all parent items will be expanded to top. Applicable for HierarchyLoadMode = Client only!
collapseItem(index)	Method which collapses the table row with index passed as an argument. Applicable for HierarchyLoadMode = Client only!
editItem(gridItem)	Method which switches the table row passed as an argument or the row corresponding to the index passed as an argument in edit mode. If you set AllowMultiRowEdit to true, you can switch multiple grid items in edit mode with subsequent calls to this method.
updateItem(gridItem)	Method which updates the edited table row passed as an argument or the row corresponding to the index passed as an argument. If you have several items switched in edit mode, you can update all of them with subsequent calls to this method. The updated data will be taken from the edit form editors.
insertItem()	Method which inserts new table row to the grid. The new data will be taken from the insertion form editors fields.
deleteItem(gridItem)	Method which deletes the table row passed as an argument or the row corresponding to the index passed as an argument.
showInsertItem()	Method which switches the grid in insert mode and displays the insertion form.
cancelInsert()	Method which cancels the insert action and switches the grid in regular mode.
cancelUpdate(gridItem)	Method which cancels the update for the edited table row passed as an argument or the row corresponding to the index passed as an argument. If you have several items switched in edit mode, you can cancel the update for all of them with subsequent calls to this method.
editSelectedItems()	Method which switches all selected items in the grid in edit mode.
updateSelectedItems()	Method which updates all edited items in the grid. The new data will be taken from the edit form editors.
deleteSelectedItems()	Method which deletes all selected items in the grid.
editAllItems()	Method which switches all GridDataItems in edit mode.
cancelAll()	Cancels the edit mode for all grid items that are switched in edit mode prior to the method call.
resizeItem (rowIndex, rowHeight)	The row at the specified row index will be resized to the height specified through the rowHeight argument.
showFilterItem()	Shows the filter item for the respective GridTableView
hideFilterItem()	Hides the filter item for the respective GridTableView
extractValuesFromItem(gridItem)	Extracts the new values from the edited table row on the client.
extractOldValuesFromItem(gridItem)	Extracts the old values from the edited table row on the client.
extractKeysFromItem(gridItem)	Extracts the key values from the edited table row on the client.

Working with grid columns

Method	Description
resizeColumn(columnIndex, columnWidth)	The column at the specified columnIndex will be resized to the width specified through the columnWidth argument.
swapColumns(colUniqueName1, colUniqueName2)	The columns with unique names colUniqueName1 and colUniqueName2 will be swapped.

reorderColumns( colUniqueName1, colUniqueName2)	colUniqueName1 is the "from" unique name of the table column while colUniqueName2 is the "to" unique name of the column (i.e. the new location).
moveColumnToLeft(columnIndex)	The column at the specified columnIndex will be moved to the left.
moveColumnToRight(columnIndex)	The column at the specified columnIndex will be moved to the right.
hideColumn(columnIndex)	The column at the specified columnIndex will be hidden.
showColumn(columnIndex)	The column at the specified columnIndex will be shown.
groupColumn(colUniqueName)	Method which groups the grid by the column with UniqueName specified as an argument. All server grouping capabilities of RadGrid are applicable for this case as well.
ungroupColumn(colUniqueName)	Method which performs ungroup action for the column with UniqueName specified as an argument.

RadGrid for ASP.NET AJAX