docs(grid): incell editing and editor templates - when to close

Author: marin-bratanov

components/grid/editing/incell.md

@@ -142,6 +142,154 @@ Click a cell, edit it and click outside of the cell to see the change.<br />
 
 * It is up to the data access logic to save the data once it is changed in the data collection. The example above showcases when that happens and adds some code to provide a visual indication of the change. In a real application, the code for handling data updates may be entirely different.
 
+* When using an [editor template]({%slug components/grid/features/templates%}#edit-template), the grid cannot always know what the custom editor needs to do, and when it needs to close the cell and update the data, because this is up to the editor. Thus, you can use the grid [state]({%slug grid-state%}) to close the cell and invoke the desired operations on the data according to your business logic. For example, a suitable event the Telerik input components provide is `OnChange`.
+    * When keyboard navigation is enabled in the grid (`Navigable=true`), the grid will capture `Enter` keypresses when the cell is focused, and will close the cell with the corresponding update. You can either use that (e.g., a simple input will let the keypress event propagate to the grid cell), or you can prevent the event propagation and use only your business logic.
+    
+    The example below shows how you can use both a navigable grid and events on the custom editor templates to close the cells when Enter is pressed or when they lose focus, much like an Excel spreadsheet behaves.
+    
+    **.razor**
+    
+        @* The Telerik-specific OnChange event is used to achieve this in this example.
+        You can implement a similar event in your components/editors, or use a completely different event and logic to instruct the grid to update a cell. In this example, the two-way binding
+        provides the editor value to the model immediately, so it becomes avaialable in the OnChange
+        handler. In your case you might need to handle this differently, depending on the logic you need.
+        *@
+        
+        <TelerikGrid @ref="@Grid"
+                        Data=@MyData
+                        EditMode="@GridEditMode.Incell"
+                        Pageable="true"
+                        Height="500px"
+                        OnUpdate="@UpdateHandler" OnCreate="@CreateHandler"
+                        Navigable="true">
+            <GridColumns>
+                <GridColumn Field=@nameof(SampleData.ID) Editable="false" Title="ID" />
+                <GridColumn Field=@nameof(SampleData.Name) Title="Name">
+                    <EditorTemplate>
+                        @{
+                            currentItem = context as SampleData;
+                            <TelerikTextBox @bind-Value=@currentItem.Name OnChange="@CloseEditor" Width="100%" />
+                        }
+                    </EditorTemplate>
+                </GridColumn>
+                <GridColumn Field=@nameof(SampleData.Ranking) Title="Ranking" Width="120px">
+                    <EditorTemplate>
+                        @{
+                            currentItem = context as SampleData;
+                            <TelerikNumericTextBox @bind-Value=@currentItem.Ranking OnChange="@CloseEditor" 
+                                                    Width="100%" Max="10" Min="0" Step="1">
+                            </TelerikNumericTextBox>
+                        }
+                    </EditorTemplate>
+                </GridColumn>
+                <GridColumn Field=@nameof(SampleData.Role) Title="Position" Width="200px">
+                    <EditorTemplate>
+                        @{
+                            currentItem = context as SampleData;
+                            <TelerikDropDownList Data="@Roles" @bind-Value="@currentItem.Role" OnChange="@CloseEditor"
+                                                    Width="120px" PopupHeight="auto">
+                            </TelerikDropDownList>
+                        }
+                    </EditorTemplate>
+                </GridColumn>
+                <GridCommandColumn>
+                    <GridCommandButton Command="Save" Icon="save" ShowInEdit="true">Update</GridCommandButton>
+                </GridCommandColumn>
+            </GridColumns>
+            <GridToolBar>
+                <GridCommandButton Command="Add" Icon="add">Add Employee</GridCommandButton>
+            </GridToolBar>
+        </TelerikGrid>
+        
+        @code {
+            // handling the custom editor template for InCell editing
+            public TelerikGrid<SampleData> Grid { get; set; }
+            public SampleData currentItem { get; set; }
+        
+            async Task CloseEditor()
+            {
+                var state = Grid?.GetState();
+        
+                if (currentItem.ID == 0 && state.InsertedItem != null)
+                {
+                    //insert operation - the item is new
+                    await CreateHandler(new GridCommandEventArgs()
+                    {
+                        Item = state.InsertedItem
+                    });
+                }
+                else
+                if (currentItem.ID > 0 && state.EditItem != null)
+                {
+                    //edit operation on an existing item
+        
+                    await UpdateHandler(new GridCommandEventArgs()
+                    {
+                        Item = state.EditItem,
+                        Field = state.EditField
+                    });
+                }
+        
+                state.InsertedItem = state.OriginalEditItem = state.EditItem = default;
+        
+                await Grid?.SetState(state);
+            }
+        
+            //Create and Update operations
+        
+            async Task UpdateHandler(GridCommandEventArgs args)
+            {
+                SampleData item = (SampleData)args.Item;
+        
+                var index = MyData.FindIndex(i => i.ID == item.ID);
+                if (index != -1)
+                {
+                    MyData[index] = item;
+                }
+        
+                //perform actual data source operations here
+            }
+        
+            async Task CreateHandler(GridCommandEventArgs args)
+            {
+                SampleData item = (SampleData)args.Item;
+        
+                item.ID = MyData.Count + 1;
+                MyData.Insert(0, item);
+        
+                // perform actual data source operation here through your service
+            }
+        
+            // data sources
+        
+            protected override void OnInitialized()
+            {
+                MyData = new List<SampleData>();
+        
+                for (int i = 1; i < 50; i++)
+                {
+                    MyData.Add(new SampleData()
+                    {
+                        ID = i,
+                        Name = "name " + i,
+                        Ranking = i % 10
+                    });
+                }
+            }
+        
+            public class SampleData
+            {
+                public int ID { get; set; }
+                public string Name { get; set; }
+                public string Role { get; set; }
+                public int Ranking { get; set; }
+            }
+        
+            List<SampleData> MyData { get; set; }
+            static List<string> Roles = new List<string> { "Manager", "Employee", "Contractor" };
+        }
+
+
 ## See Also
 
   * [Live Demo: Grid InCell Editing](https://demos.telerik.com/blazor-ui/grid/editing-incell)