# Batch Editing Client-side API

The **Batch Editing** client-side API exposes a number of methods which provide more control over the editing process, let you get/set cell values and open cells for editing. You can see a list of the methods available with **Batch Editing** in **Table 1**.

To use these methods, you need a reference to the **Batch Editing Manager** object first. You can get it from the grid object:

```JavaScript
var grid = $find("<%=RadGrid1.ClientID%>");
var batchEditingManager = grid.get_batchEditingManager();
```

The grid object is the first argument to all of its client-side handlers so you can use it without hardcoding IDs:

```ASP.NET
	<ClientSettings>
		<ClientEvents OnBatchEditOpened="OnBatchEditOpened" />
	</ClientSettings>
</telerik:RadGrid>
<script>
function OnBatchEditOpened(sender, args) {
	var batchEditingManager = sender.get_batchEditingManager();
}
</script>
```

> caption Table 1: Batch Editing Client-side API methods

| Name                                | Parameters                    | Return Type | Description                                                                                                                                                     |
| ----------------------------------- | ----------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| addNewRecord(tableView)             | GridTableView                 |             | Adds a new record to the grid.                                                                                                                                  |
| deleteRecord(tableView,row)         | GridTableView, `<tr>` element |             | Removes the specified record from the table.                                                                                                                    |
| saveChanges(tableView)              | GridTableView                 |             | Sends a request to the server to save the changes made in the specified **GridTableView**.                                                                      |
| saveAllChanges                      |                               |             | Sends a request to the server in order to save all changes made from the user so far.                                                                           |
| saveTableChanges(tableViews)        | GridTableView\[]              |             | Sends a request to the server to save the changes for the **GridTableViews** passed in the arguments. The method expects an array of **GridTableView** objects. |
| cancelChanges(tableView)            | GridTableView                 |             | Sends a request to the server to cancel all unsaved changes made so far.                                                                                        |
| openCellForEdit(cell)               | `<td>` element                |             | Opens the specified cell for editing.                                                                                                                           |
| openRowForEdit(row)                 | `<tr>` element                |             | Opens the specified row for edit (opens all editable cells in the row for edit).                                                                                |
| getCellValue(cell)                  | `<td>` element                | string      | Returns the value of the respective cell.                                                                                                                       |
| changeCellValue(cell, newCellValue) | `<td>` element, value         |             | Assigns a value to the respective cell.                                                                                                                         |
| get_currentlyEditedCell             | `<td>` element                |             | Returns the element of the currently edited cell. This method should be used when **EditType** is set to **Cell**.                                              |
| get_currentlyEditedRow              | `<tr>` element                |             | Returns the element of the currently edited row. This method should be used when **EditType** is set to **Row**.                                                |
| hasChanges(tableView)               | GridTableView                 | boolean     | Returns whether there are unsaved changes in the tableview. Similar to an IsDirty flag.                                                                         |

When firing grid commands by using the **fireCommand** method some commands are detected, canceled and instead their corresponding batch editing client-side functions are called. Below a list of the handled commands:

| Fired Command                       | Corresponding Batch Edit Command |
| ----------------------------------- | -------------------------------- |
| Cancel, CancelAll                   | cancelChanges                    |
| Delete                              | deleteRecord                     |
| Edit                                | openRowForEdit                   |
| InitInsert                          | addNewRecord                     |
| PerformInsert, Update, UpdateEdited | saveChanges                      |

## Sample use cases

> caption Prevent editing of certain cells

Canceling the OnBatchEditOpening client-side event is a reliable way to prevent a cell from being edited if a certain condition is satisfied.

Sample description: Prevent editing the *ShipName* cell if the respective *ShipCountry* is "Brazil" or "France"

```ASP.NET
<telerik:RadGrid ID="RadGrid1" runat="server" AllowPaging="True" Width="800px"
    DataSourceID="SqlDataSource1"
    AutoGenerateDeleteColumn="true"
    AllowAutomaticInserts="true"
    AllowAutomaticUpdates="true"
    AllowAutomaticDeletes="true">
    <ClientSettings>
        <ClientEvents OnBatchEditOpening="onBatchOpening" />
    </ClientSettings>
    <MasterTableView EditMode="Batch" BatchEditingSettings-EditType="Cell" DataSourceID="SqlDataSource1" AutoGenerateColumns="true" CommandItemDisplay="Top"
        DataKeyNames="OrderID">
    </MasterTableView>
</telerik:RadGrid>

<asp:SqlDataSource ID="SqlDataSource1" runat="server"
    ConnectionString="<%$ ConnectionStrings:NorthwindConnectionString %>"
    InsertCommand="INSERT INTO [Orders] ([OrderDate], [Freight], [ShipName], [ShipCountry]) VALUES (@OrderDate, @Freight, @ShipName, @ShipCountry)"
    SelectCommand="SELECT [OrderID], [OrderDate], [Freight], [ShipName], [ShipCountry] FROM [Orders]"
    UpdateCommand="UPDATE [Orders] SET [OrderDate] = @OrderDate, [Freight] = @Freight, [ShipName] = @ShipName, [ShipCountry] = @ShipCountry WHERE [OrderID] = @OrderID"
    DeleteCommand="DELETE FROM [Orders] WHERE [OrderID] = @OrderID"></asp:SqlDataSource>
```

```JavaScript
function onBatchOpening(sender, args) {
    var editedColumn = args.get_columnUniqueName();
    if (editedColumn == "ShipName") {
        var columnName = "ShipCountry";
        var tableView = args.get_tableView();
        var row = args.get_row();

        //get the index of ShipCountry column and reach the respective cell in the current row 
        var columnIndex = tableView.getColumnByUniqueName(columnName).get_element().cellIndex;
        var shipCountryValue = row.cells[columnIndex].innerText;

        //cancel the event if the codition is satisfied
        if (shipCountryValue == "Brazil" || shipCountryValue == "France") {
            args.set_cancel(true);
        }
    }
}
```

> note This approach is only applicable with EditType is set to 'Cell' and cannot be used when EditType='Row'.

Additionally, you could subscribe to the [OnBatchEditCellValueChanging](https://www.telerik.com/products/aspnet-ajax/documentation/controls/grid/client-side-programming/events/onbatcheditcellvaluechanging) event to access the new value before they are applied, and cancel the action if necessary. The [OnBatchEditCellValueChanged](https://www.telerik.com/products/aspnet-ajax/documentation/controls/grid/client-side-programming/events/onbatcheditcellvaluechanged) event can be used to access the already changed value.

> caption Save changes using external button

Sample description: Two Batch editing RadGrid Controls are placed on the same page. Save the changes to both RadGrids from external RadButton using the SaveTableChanges() method

```ASP.NET
<div style="float: left; display: inline-block; margin: 10px">
    <telerik:RadGrid ID="RadGrid1" runat="server" AllowPaging="True" Width="600px"
        DataSourceID="SqlDataSource1"
        AutoGenerateDeleteColumn="true"
        AllowAutomaticInserts="true"
        AllowAutomaticUpdates="true"
        AllowAutomaticDeletes="true">
        <ClientSettings ClientEvents-OnBatchEditOpening="onBatchOpening" />
        <MasterTableView EditMode="Batch" BatchEditingSettings-EditType="Cell" DataSourceID="SqlDataSource1" AutoGenerateColumns="true" CommandItemDisplay="Top"
            DataKeyNames="OrderID">
        </MasterTableView>
    </telerik:RadGrid>
</div>

<div style="float: left; display: inline-block; margin: 10px">
    <telerik:RadGrid ID="RadGrid2" runat="server" AllowPaging="True" Width="600px"
        DataSourceID="SqlDataSource2"
        AutoGenerateDeleteColumn="true"
        AllowAutomaticInserts="true"
        AllowAutomaticUpdates="true"
        AllowAutomaticDeletes="true">
        <ClientSettings ClientEvents-OnBatchEditOpening="onBatchOpening" />
        <MasterTableView EditMode="Batch" BatchEditingSettings-EditType="Cell" DataSourceID="SqlDataSource2"
            AutoGenerateColumns="true" CommandItemDisplay="Top"
            DataKeyNames="EmployeeID">
        </MasterTableView>
    </telerik:RadGrid>
</div>

<telerik:RadButton ID="RadButton1" runat="server" Text="SaveBothGridChanges" AutoPostBack="false" OnClientClicked="clientClick"></telerik:RadButton>

<asp:SqlDataSource ID="SqlDataSource1" runat="server"
    ConnectionString="<%$ ConnectionStrings:NorthwindConnectionString %>"
    InsertCommand="INSERT INTO [Orders] ([OrderDate], [Freight], [ShipName], [ShipCountry]) VALUES (@OrderDate, @Freight, @ShipName, @ShipCountry)"
    SelectCommand="SELECT [OrderID], [OrderDate], [Freight], [ShipName], [ShipCountry] FROM [Orders]"
    UpdateCommand="UPDATE [Orders] SET [OrderDate] = @OrderDate, [Freight] = @Freight, [ShipName] = @ShipName, [ShipCountry] = @ShipCountry WHERE [OrderID] = @OrderID"
    DeleteCommand="DELETE FROM [Orders] WHERE [OrderID] = @OrderID"></asp:SqlDataSource>

<asp:SqlDataSource ID="SqlDataSource2" runat="server"
    ConnectionString="<%$ ConnectionStrings:NorthwindConnectionString %>"
    InsertCommand="INSERT INTO [Employees] ([HireDate], [Title], [FirstName], [LastName]) VALUES (@HireDate, @Title, @FirstName, @LastName)"
    SelectCommand="SELECT [EmployeeID], [HireDate], [Title], [FirstName], [LastName] FROM [Employees]"
    UpdateCommand="UPDATE [Employees] SET [HireDate] = @HireDate, [Title] = @Title, [FirstName] = @FirstName, [LastName] = @LastName WHERE [EmployeeID] = @EmployeeID"
    DeleteCommand="DELETE FROM [Employees] WHERE [EmployeeID] = @EmployeeID"></asp:SqlDataSource>
```

```JavaScript
function clientClick(sender, args) {
    var grid1 = $find('<%= RadGrid1.ClientID%>');
    var grid2 = $find('<%= RadGrid2.ClientID%>');

    var masterTableView1 = grid1.get_masterTableView();
    var masterTableView2 = grid2.get_masterTableView();

    var tables = [];
    tables.push(masterTableView1, masterTableView2);

    var batchManager = grid2.get_batchEditingManager();
    batchManager.saveTableChanges(tables);
}
```

A common scenario of multiple Batch editing RadGrids that need to be submited at once along with external user input, is described in the [How to update batch edit grids from outside button and also save external user input](https://www.telerik.com/support/kb/aspnet-ajax/grid/details/how-to-update-batch-edit-grids-from-outside-button-and-also-save-external-user-input) knowledge-base article.

## See Also

* [Batch Edit Mode Overview](https://www.telerik.com/products/aspnet-ajax/documentation/controls/grid/data-editing/edit-mode/batch-editing/overview)
* [Server-Side API](https://www.telerik.com/products/aspnet-ajax/documentation/controls/grid/data-editing/edit-mode/batch-editing/server-side-api)
