docs(grid): 0.5 to 1.0 change in API

Author: marin-bratanov

components/grid/columns/command.md

@@ -14,35 +14,37 @@ The command column of a grid allows you to initiate [inline]({%slug components/g
 
 To define it, add a `TelerikGridCommandColumn` in the `TelerikGridColumns` collection of a grid. The command column takes a collection of `TelerikGridCommandButton` instances that invoke the commands. It also offers the `Title` property so you can set its header text.
 
->tip The lists below showcase the available features and their use, and after them you can find a code example that shows declarations and handling.
+>tip The lists below showcase the available features and their use. After them you can find a code example that shows declarations and handling.
 
 The `TelerikGridCommandButton` tag offers the following features:
 
-* `Command` - the command that will be invoked. Can be one of the built-in commands, or a custom command name.
-* `OnClick` - the event handler that the button will fire.
+* `Command` - the command that will be invoked. Can be one of the built-in commands (see below), or a custom command name.
+* `OnClick` - the event handler that the button will fire. If used on a built-in command, this handler will fire before the [corresponding CRUD event]({%slug components/grid/editing/overview%}). Cancelling it will prevent the built-in CRUD event from firing.
 * `ShowInEdit` - a boolean property indicating whether the button is only visible while the user is editing/inserting data.
 * `ChildContent` - the text the button will render. You can also place it between the command button's opening and closing tags.
-* Appearance properties like Icon, Class, Enabled that are come from the underlying [Button Component features]({%slug components/button/overview%}).
+* Appearance properties like `Icon`, `Class`, `Enabled` that are come from the underlying [Button Component features]({%slug components/button/overview%}).
 
 There are three built-in commands:
 
 * `Edit` - initiates the inline or popup editing (depending on the EditMode configuration of the grid).
-* `Update` - performs the actual update operation after the data has been changed. Allows you to trigger an event handler to perform the data source operation.
+* `Save` - performs the actual update operation after the data has been changed. Triggers the `OnUpdate` or `OnCreate` event so you can perform the data source operation. Which event is triggered depends on whether the item was added through the grid or not.
 * `Cancel` - aborts the current operation (edit or insert).
 
 The `OnClick` handler of the commands receives an argument of type `GridCommandEventArgs` that exposes the following properties:
 
 * `IsCancelled` - set this to true to prevent the operation if the business logic requires it.
 * `Item` - the model item the grid row is bound to. You can use it to access the model fields and methods in order to preform the actual data source operations.
-* `Type` - the type of event (command).
+* `IsNew` - a boolean field indicating whether the item was just added through the grid interface.
+
+>tip For handling CRUD operations we recommend that you use the grid events (`OnEdit`, `OnUpdate`, `OnCancel`, `OnCreate`). The `OnClick` handler is available for the built-in commands to provide consistency of the API.
 
 >caption Example of adding and handling command columns for inline editing of a grid
 
 ````CSHTML
 @using Telerik.Blazor
 @using Telerik.Blazor.Components.Grid
 
-<span>Edit will cancelled for "name 2"</span>
+<span>Edit will be cancelled for "name 2"</span>
 <br />@CustomCommandResult
 
 <TelerikGrid Data=@GridData EditMode="inline"
@@ -52,9 +54,9 @@ The `OnClick` handler of the commands receives an argument of type `GridCommandE
 		<TelerikGridColumn Field=@nameof(SampleData.Name) Title="Employee Name" />
 		<TelerikGridColumn Field=@nameof(SampleData.HireDate) Title="Hire Date" />
 		<TelerikGridCommandColumn>
-			<TelerikGridCommandButton Command="Edit" Icon="edit" OnClick="@TriggerEdit">Edit</TelerikGridCommandButton>
-			<TelerikGridCommandButton Command="Update" Icon="save" ShowInEdit="true" OnClick="@UpdateItem">Update</TelerikGridCommandButton>
-			<TelerikGridCommandButton Command="Cancel" Icon="cancel" ShowInEdit="true" OnClick="@CancelItem">Cancel</TelerikGridCommandButton>
+			<TelerikGridCommandButton Command="Edit" Icon="edit" OnClick="@MyEditHandler">Edit</TelerikGridCommandButton>
+			<TelerikGridCommandButton Command="Save" Icon="save" ShowInEdit="true" OnClick="@MyUpdateHandler">Update</TelerikGridCommandButton>
+			<TelerikGridCommandButton Command="Cancel" Icon="cancel" ShowInEdit="true" OnClick="@MyCancelHandler">Cancel</TelerikGridCommandButton>
 			<TelerikGridCommandButton Command="MyOwnCommand" Icon="information" ShowInEdit="false" OnClick="@MyCustomCommand">My Command</TelerikGridCommandButton>
 		</TelerikGridCommandColumn>
 	</TelerikGridColumns>
@@ -76,30 +78,33 @@ The `OnClick` handler of the commands receives an argument of type `GridCommandE
 		HireDate = DateTime.Now.AddDays(-x)
 	});
 
-	private void TriggerEdit(GridCommandEventArgs args)
+	private void MyEditHandler(GridCommandEventArgs args)
 	{
 		int empId = (args.Item as SampleData).ID;
 
 		//example of cancelling an event based on condition
+		//we recommend you do this in the corresponding CRUD event
 		if (empId == 2)
 		{
 			args.IsCancelled = true;
 		}
 	}
 	
-	private void UpdateItem(GridCommandEventArgs args)
+	private void MyUpdateHandler(GridCommandEventArgs args)
 	{
 		SampleData theUpdatedItem = args.Item as SampleData;
 		//save changes, for example by using the model fields and/or methods
+		//we recommend you do this in the corresponding CRUD event
 
 		//if you have a context added through an @inject statement, you could call its SaveChanges() method
 		//myContext.SaveChanges();
 	}
 	
-	private void CancelItem(GridCommandEventArgs args)
+	private void MyCancelHandler(GridCommandEventArgs args)
 	{
 		SampleData theUpdatedItem = args.Item as SampleData;
 		//revert the changes
+		//we recommend you do this in the corresponding CRUD event
 
 		//if you have a context added through an @inject statement, you could use something like this to abort changes
 		//foreach (var entry in nwContext.ChangeTracker.Entries().Where(entry => entry.State == EntityState.Modified))

components/grid/editing/incell.md

@@ -10,9 +10,9 @@ position: 4
 
 # Grid InCell Editing
 
-In Cell editing allows the user has to click the cell and type the new value. When they remove focus from the input, the new value is sent to the model, where the data-access logic can move it to the actual data source.
+In Cell editing allows the user to click the cell and type the new value. When they remove focus from the input, the `OnUpdate` event fires, where the data-access logic can move it to the actual data source.
 
-You can handle the `Update` and `Delete` events to perform the CRUD operations, as shown in the example below. At the moment, the in-cell editing does not support item creation or cancellation of changes.
+You can handle the `OnUpdate`, `OnCreate` and `OnDelete` events to perform the CUD operations, as shown in the example below. To add a new item, you must also add a [command column]({%slug components/grid/columns/command%}) with a `Save` command and a [toolbar]({%slug components/grid/features/toolbar%}) with an `Add` command. Cancellation of changes is not supported at the moment, you can prevent them by not calling the data access layer.
 
 To enable InCell editing mode, set the `EditMode` property of the grid to `incell`, then handle the CRUD events as shown in the example below.
 
@@ -25,10 +25,17 @@ To enable InCell editing mode, set the `EditMode` property of the grid to `incel
 <strong>Click a cell, edit it and click outside of the cell to see the change. Editing is prevented for the first two items.</strong>
 
 <TelerikGrid Data=@MyData EditMode="incell" Pageable="true" Height="200">
+    <TelerikGridEvents>
+        <EventsManager OnUpdate="@UpdateHandler" OnEdit="@EditHandler" OnDelete="@DeleteHandler" OnCreate="@CreateHandler" OnCancel="@CancelHandler"></EventsManager>
+    </TelerikGridEvents>
+    <TelerikGridToolBar>
+        <TelerikGridCommandButton Command="Add" Icon="add">Add Employee</TelerikGridCommandButton>
+    </TelerikGridToolBar>
     <TelerikGridColumns>
         <TelerikGridColumn Field=@nameof(SampleData.ID) Title="ID" Editable="false" />
         <TelerikGridColumn Field=@nameof(SampleData.Name) Title="Name" />
         <TelerikGridCommandColumn>
+            <TelerikGridCommandButton Command="Save" Icon="save" ShowInEdit="true">Update</TelerikGridCommandButton>
             <TelerikGridCommandButton Command="Delete" Icon="delete">Delete</TelerikGridCommandButton>
         </TelerikGridCommandColumn>
     </TelerikGridColumns>
@@ -45,25 +52,40 @@ To enable InCell editing mode, set the `EditMode` property of the grid to `incel
             args.IsCancelled = true;//the general approach for cancelling an event
         }
 
-        Console.WriteLine("Edit event is fired.");
+        Console.WriteLine("Edit event is fired for column " + args.Field);
     }
 
     public void UpdateHandler(GridCommandEventArgs args)
     {
-        SampleData item = (SampleData)args.Item;
+        string fieldName = args.Field;
+        object newVal = args.Value; //you can cast this, if necessary, according to your model
 
         //perform actual data source operation here
+        
         //if you have a context added through an @inject statement, you could call its SaveChanges() method
         //myContext.SaveChanges();
-        Console.WriteLine("Update event is fired.");
+        
+        Console.WriteLine("Update event is fired for " + args.Field + " with value " + args.Value);
+    }
+    
+    public void CreateHandler(GridCommandEventArgs args)
+    {
+        SampleData item = (SampleData)args.Item;
+
+        //perform actual data source operation here
+        
+        Console.WriteLine("Create event is fired.");
     }
 
     public void DeleteHandler(GridCommandEventArgs args)
     {
         SampleData item = (SampleData)args.Item;
+        
         //perform actual data source operation here
+        
         //if you have a context added through an @inject statement, you could call its SaveChanges() method
         //myContext.SaveChanges();
+        
         Console.WriteLine("Update event is fired.");
     }
 

components/grid/editing/inline.md

@@ -10,11 +10,11 @@ position: 1
 
 # Grid Inline Editing
 
-Inline editing lets the user click an [Edit command button]({%slug components/grid/columns/command%}) on the row, and all its editable columns open up for changes. They can then click an **Update** command button to submit the changes to the model. This fires the `OnUpdate` event of the grid where your code receives the updated model so you can work with the data (for example, to call the `SaveChanges()` method of your context).
+Inline editing lets the user click an [Edit command button]({%slug components/grid/columns/command%}) on the row, and all its editable columns open up for changes. They can then click an `Save` command button to submit the changes to the data access layer. This fires the `OnUpdate` event of the grid where your code receives the updated model so you can work with the data (for example, to call the `SaveChanges()` method of your context).
 
-In a similar fashion, the `Cancel`, `Delete` command buttons and the `Create` toolbar button fire events on the grid to let you handle the data source operations.
+In a similar fashion, the `Cancel` and `Delete` command buttons fire events on the grid to let you handle the data source operations.
 
-You can also cancel the evens by setting the `IsCancelled` property of the event arguments to `true`. This lets you prevent the user from editing certain records, inserting or deleting items, based on your application logic.
+You can also cancel the events by setting the `IsCancelled` property of the event arguments to `true`. This lets you prevent the user from editing certain records, inserting or deleting items, based on your application logic.
 
 To enable Inline editing in the grid, set its `EditMode` property to `inline`, then handle the CRUD events as shown in the example below.
 
@@ -31,13 +31,13 @@ To enable Inline editing in the grid, set its `EditMode` property to `inline`, t
         <EventsManager OnUpdate="@UpdateHandler" OnEdit="@EditHandler" OnDelete="@DeleteHandler" OnCreate="@CreateHandler" OnCancel="@CancelHandler"></EventsManager>
     </TelerikGridEvents>
     <TelerikGridToolBar>
-        <TelerikGridCommandButton Command="Create" Icon="add">Add Employee</TelerikGridCommandButton>
+        <TelerikGridCommandButton Command="Add" Icon="add">Add Employee</TelerikGridCommandButton>
     </TelerikGridToolBar>
     <TelerikGridColumns>
         <TelerikGridColumn Field=@nameof(SampleData.ID) Title="ID" Editable="false" />
         <TelerikGridColumn Field=@nameof(SampleData.Name) Title="Name" />
         <TelerikGridCommandColumn>
-            <TelerikGridCommandButton Command="Update" Icon="save" ShowInEdit="true">Update</TelerikGridCommandButton>
+            <TelerikGridCommandButton Command="Save" Icon="save" ShowInEdit="true">Update</TelerikGridCommandButton>
             <TelerikGridCommandButton Command="Edit" Icon="edit">Edit</TelerikGridCommandButton>
             <TelerikGridCommandButton Command="Delete" Icon="delete">Delete</TelerikGridCommandButton>
             <TelerikGridCommandButton Command="Cancel" Icon="cancel" ShowInEdit="true">Cancel</TelerikGridCommandButton>
@@ -55,16 +55,16 @@ To enable Inline editing in the grid, set its `EditMode` property to `inline`, t
         {
             args.IsCancelled = true;//the general approach for cancelling an event
         }
+        
         Console.WriteLine("Edit event is fired.");
     }
 
     public void UpdateHandler(GridCommandEventArgs args)
     {
         SampleData item = (SampleData)args.Item;
 
-        bool isInsert = args.IsNew;//insert or update operation
-
         //perform actual data source operations here
+        
         //if you have a context added through an @inject statement, you could call its SaveChanges() method
         //myContext.SaveChanges();
 
@@ -86,9 +86,11 @@ To enable Inline editing in the grid, set its `EditMode` property to `inline`, t
 
     public void CreateHandler(GridCommandEventArgs args)
     {
-        Console.WriteLine("Create event is fired.");
+        SampleData item = (SampleData)args.Item;
 
-        //there is no Item associated with this event handler
+        //perform actual data source operation here
+        
+        Console.WriteLine("Add event is fired.");
     }
 
     public void CancelHandler(GridCommandEventArgs args)
@@ -97,7 +99,7 @@ To enable Inline editing in the grid, set its `EditMode` property to `inline`, t
 
         SampleData item = (SampleData)args.Item;
 
-        //perform actual data source operation here (like cancel changes on a context)
+        //if necessary, perform actual data source operation here (like cancel changes on a context)
         //if you have a context added through an @inject statement, you could use something like this to abort changes
         //foreach (var entry in myContext.ChangeTracker.Entries().Where(entry => entry.State == EntityState.Modified))
         //{