Client-Side Programming Overview
Getting the client-side object
All the API properties and methods are accessible via the registered JavaScript objects for each control. The following code snippet shows how to get reference to the client-side object of RadGrid:
<telerik:RadGrid ID="RadGrid1" runat="server" OnNeedDataSource="RadGrid1_NeedDataSource" MasterTableView-Name="MainTable"></telerik:RadGrid>
<telerik:RadButton runat="server" ID="RadButton1" Text="GetClientRef" AutoPostBack="false" OnClientClicked="onClientClicked" />
<script>
function onClientClicked(sender, args) {
var grid = $find('<%= RadGrid1.ClientID %>');
alert(grid.get_id()); // alert with the ID of the control
var masterTable = grid.get_masterTableView();
alert(masterTable.get_name()); //alert with the name of the MasterTableView
console.log(masterTable.get_element()); //log the HTML wrapper element of the Master table in the console
}
</script>
You can find more detailed instructions of how to get client reference to a Telerik AJAX control on Get Client-side Reference to a Control Object.
For Client side approach to access Cells, Values, Controls and more in RadGrid check out the: Accessing Values and Controls article.
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. |
.get_masterTableView() | This is an object of type GridTableView . Use this object 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 . |
.get_editItems() | This property retrieves all GridDataItem objects that are in edit mode across all grid tables. |
.get_allowMultiRowSelection() | This property is of type Boolean. When set to true , you can select multiple rows on the client. |
.set_activeRow() | Property which marks the row passed as an argument as active and highlighted. |
.get_element() | Property that returns the DOM element of the grid div. |
.get_id() | Property that returns the id of the grid client object. |
.get_selectedItems() | Property that returns an array of the grid rows selected on the client (and all sub-levels in the hierarchical grid structure). |
.get_headerMenu() | Property that returns the client object of the grid header context menu. Useful when you would like to customize the items in it on the client (see the JavaScript logic at the top of this help topic for reference). |
.get_allowActiveRow() | Property that returns the value for the respective server property of the control (ClientSettings -> KeyboardNavigationSettings -> AllowActiveRowCycle). |
.get_visible() | Property that determines whether the grid is visible on the client or not (style="display:none"). |
.set_visible() | Property that sets the grid as visible or not on the client (changing the style-> display value of the grid div). |
GridTableView | Class that 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_allowMultiColumnSorting() | Returns a Boolean value indicating whether multi-column sorting is enabled for the grid instance. |
.set_allowMultiColumnSorting() | Sets whether multi-column sorting is enabled for the grid instance. |
.get_owner() | This property is of type RadGrid and presents the parent of the current object. |
.get_element() | Returns the HTML table that represents the respective table for the GridTableView object rendered on the client. |
.get_dataItems() | A collection that 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 a hierarchical grid only). |
.get_editItems() | This property retrieves the GridDataItem objects of the current table view that are in edit mode. |
.get_insertItem() | This property retrieves the HTML element of the currently inserted item. |
.get_columns() | A collection that holds objects of type GridColumn (the client-side objects) in the respective table. |
.get_name() | String that represents the Name property (set on the server) for the corresponding GridTableView client object. It can be used to identify a table in a grid hierarchy on the client-side. |
.get_isItemInserted() | A Boolean property. It 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() | A one-dimensional array that 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, it returns the parent table view (of type GridTableView ) in the grid hierarchy; it returns null if called from the MasterTableView . |
.get_parentRow() | If called from a nested table view, it returns the parent row (HTML table row - <tr>) for the current nested hierarchical table view; it returns null if called from the MasterTableView . |
.get_virtualItemCount() | Gets the virtual item count value for the respective GridTableView object. Applies to client-side bound grid only. |
.set_virtualItemCount() | Sets the virtual item count value for the respective GridTableView object. Applies to client-side bound grid only. |
For performance reasons, the
.get_dataItems() collection will be available only when you enable specific client features/events for the rows in the grid (such as AllowRowResize , AllowRowSelect , OnRowClick , etc.).
If you want to reference the client object of a grid row inside a client event handler of RadGrid , make sure that you attach the RowCreated event of the control specifying an empty event handler, otherwise eventArgs.get_gridDataItem() will return null. This is due to performance reasons (avoiding the client serialization of grid items by default). An alternative method to reference a grid row client-side is through the get_dataItems() collection.
Client-side Events
Inside each RadGrid client event handler the first argument passed (sender) will point to the grid client object. The second argument (eventArgs) will hold reference properties/objects dependable on the respective client event.
RadGrid Events
Event | Description |
---|---|
Grid Creation | |
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 RadGrid object is destroyed, (i.e. on each window.onunload ). |
OnMasterTableViewCreating | This event is fired before the MasterTableView is created. |
OnMasterTableViewCreated | This event is fired after the MasterTableView is created. |
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 | |
OnRowDragging | This event is fired repetitively when a row is being dragged. |
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 is changed. |
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. |
Bating Editing | |
OnBatchEditOpening | This event is fired when a cell is opening for edit. |
OnBatchEditOpened | This event is fired after a cell is opened for edit. |
OnBatchEditClosing | This event is fired when a cell is closing. |
OnBatchEditClosed | This event is fired after the cell is closed. |
OnBatchEditCellValueChanging | This event is fired when a cell's value is being changed. |
OnBatchEditCellValueChanged | This event is fired once a cell has been edited. |
OnBatchEditGetCellValue | This event is fired when the grid obtains the value from the editor in order to later set in in the HTML(Should be handled handled when multiple controls which contain an input element are placed inside the EditItemTemplate of a GridTemplateColumn ). |
OnBatchEditSetCellValue | This event is fired when the grid obtains the value from the editor in order to later set in in the HTML(Should be handled handled when multiple controls which contain an input element are placed inside the EditItemTemplate of a GridTemplateColumn ). |
OnBatchEditSetEditorValue | This event is fired when the grid obtains the value from the editor in order to later set in in the HTML(Should be handled handled when multiple controls which contain an input element are placed inside the EditItemTemplate of a GridTemplateColumn ). |
OnBatchEditGetEditorValue | This event is fired when the grid obtains the value from the editor in order to later set in in the HTML(Should be handled handled when multiple controls which contain an input element are placed inside the EditItemTemplate of a GridTemplateColumn ). |
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 . |
OnUserAction | This event is fired for some of the grid commands in an earlier stage of their execution. |
Obtaining GridTableView Elements
You can refer to the elements of the RadGridTable using the functions below:
-
.get_columns()[n].get_element() -> the real HTML table column for the n-th column (<th> for header cell) -
.get_dataItems()[n].get_element() -> the real HTML table row for the n-th row (<tr> element)
Manipulating GridTableView Elements
In the list below you can find links to the GridTableView, GridColumn and GridDataItem class members articles that list the various methods and properties which you can use for execution additional logic.