Add documentation for RecurrenceEditMode in Scheduler CRUD events

Co-authored-by: Tsvetomir-Hr <106250052+Tsvetomir-Hr@users.noreply.github.com>

Author: Copilot

components/scheduler/editing/edit-appointments.md

@@ -32,9 +32,9 @@ By default, the user can only view the appointments, because creating, updating
 
 Main events you need to implement so you can store the appointment information changed or created by the user:
 
-* `OnCreate` - fires when the user saves a new appointment, including an exception for a recurring appointment.
-* `OnUpdate` - fires when the user changes an existing appointment. Fires for the recurring appointment when an exception has been created for it.
-* `OnDelete` - fires when the user deletes and appointment (including a recurring appointment). You can also enable a [delete confirmation dialog](#delete-confirmation-dialog).
+* `OnCreate` - fires when the user saves a new appointment, including an exception for a recurring appointment. The event arguments include a `RecurrenceEditMode` property that indicates whether the user is creating an exception to a recurring appointment (`RecurrenceEditMode.Occurrence`) or a new regular appointment.
+* `OnUpdate` - fires when the user changes an existing appointment. Fires for the recurring appointment when an exception has been created for it. The event arguments include a `RecurrenceEditMode` property that indicates whether the user chose to update the entire series (`RecurrenceEditMode.Series`) or only a single occurrence (`RecurrenceEditMode.Occurrence`).
+* `OnDelete` - fires when the user deletes an appointment (including a recurring appointment). You can also enable a [delete confirmation dialog](#delete-confirmation-dialog). The event arguments include a `RecurrenceEditMode` property that indicates whether the user chose to delete the entire series (`RecurrenceEditMode.Series`) or only a single occurrence (`RecurrenceEditMode.Occurrence`).
 
 There are two other events that you are not required to handle - you can use them to implement application logic:
 
@@ -90,6 +90,8 @@ When the user clicks the close button (`x`) of the appointment a confirmation di
 
 The example below shows the signature of the event handlers so you can copy the proper arguments and start implementing your business logic and data storage operations. The example only updates the local collection of appointments used in the UI.
 
+>tip The event arguments for `OnCreate`, `OnUpdate`, and `OnDelete` include a `RecurrenceEditMode` property. This property indicates whether the user chose to modify only a single occurrence or the entire series of a recurring appointment. For detailed information and examples, see the [Handling Recurring Appointments in CRUD Events](slug:scheduler-recurrence#handling-recurring-appointments-in-crud-events) section.
+
 @[template](/_contentTemplates/common/general-info.md#event-callback-can-be-async)
 
 >note It is up to the data access logic to save the data once it is changed in the data collection. The example below 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.

components/scheduler/events.md

@@ -24,7 +24,14 @@ This article explains the events available in the Telerik Scheduler for Blazor:
 
 ## CUD Events
 
-To implement appointment editing, the scheduler exposes the `OnCreate`, `OnDelete` and `OnUpdate` events. They let you propagate the changes the user makes in the UI to the view model and to the data storage. You can read mode in the [Appointment Editing](slug:scheduler-appointments-edit) article.
+To implement appointment editing, the scheduler exposes the `OnCreate`, `OnDelete` and `OnUpdate` events. They let you propagate the changes the user makes in the UI to the view model and to the data storage. You can read more in the [Appointment Editing](slug:scheduler-appointments-edit) article.
+
+The event arguments for these events include a `RecurrenceEditMode` property that indicates the user's choice when editing or deleting recurring appointments:
+
+* `RecurrenceEditMode.Series` - The user chose to modify the entire series of recurring appointments.
+* `RecurrenceEditMode.Occurrence` - The user chose to modify only a single occurrence of the recurring appointment.
+
+For detailed examples of handling recurring appointments in CRUD events, see the [Handling Recurring Appointments in CRUD Events](slug:scheduler-recurrence#handling-recurring-appointments-in-crud-events) section.
 
 ## OnModelInit
 

components/scheduler/recurrence.md

@@ -15,6 +15,7 @@ The Telerik Scheduler for Blazor supports displaying and editing of recurring ap
 * Configure the Scheduler for using recurring appointments.
 * Define recurrence rules and recurrence exceptions in the Scheduler data.
 * Edit recurring appointments and exceptions.
+* Handle editing and deleting recurring appointments with the recurrence context.
 
 ## Basics
 
@@ -219,6 +220,163 @@ A single Scheduler data item defines one series of recurring appointments. Set t
 }
 ````
 
+## Handling Recurring Appointments in CRUD Events
+
+When users edit, update, or delete a recurring appointment, the Scheduler prompts them to choose whether to modify only the current occurrence or the entire series. This choice is reflected in the `RecurrenceEditMode` property of the event arguments.
+
+### RecurrenceEditMode Property
+
+The `OnCreate`, `OnUpdate`, and `OnDelete` event handlers receive event arguments that include a `RecurrenceEditMode` property. This property indicates the user's choice when interacting with recurring appointments:
+
+* `RecurrenceEditMode.Series` - The user chose to edit or delete the entire series of recurring appointments.
+* `RecurrenceEditMode.Occurrence` - The user chose to edit or delete only a single occurrence of the recurring appointment.
+
+### Usage in Event Handlers
+
+You can use the `RecurrenceEditMode` property to implement different logic based on whether the user is modifying a single occurrence or the entire series.
+
+>caption Handle RecurrenceEditMode in OnUpdate and OnDelete events
+
+````RAZOR
+<TelerikScheduler Data="@SchedulerData"
+                  @bind-Date="@SchedulerDate"
+                  @bind-View="@SchedulerView"
+                  AllowCreate="true"
+                  AllowDelete="true"
+                  AllowUpdate="true"
+                  OnCreate="@OnSchedulerCreate"
+                  OnDelete="@OnSchedulerDelete"
+                  OnUpdate="@OnSchedulerUpdate"
+                  Height="600px">
+    <SchedulerViews>
+        <SchedulerDayView StartTime="@SchedulerViewStartTime" />
+        <SchedulerWeekView StartTime="@SchedulerViewStartTime" />
+        <SchedulerMonthView />
+    </SchedulerViews>
+</TelerikScheduler>
+
+@code {
+    private List<Appointment> SchedulerData { get; set; } = new();
+    private DateTime SchedulerDate { get; set; } = DateTime.Today;
+    private SchedulerView SchedulerView { get; set; } = SchedulerView.Week;
+    private DateTime SchedulerViewStartTime { get; set; } = DateTime.Today.AddHours(8);
+
+    private void OnSchedulerCreate(SchedulerCreateEventArgs args)
+    {
+        Appointment item = (Appointment)args.Item;
+
+        // When creating an exception to a recurring appointment,
+        // RecurrenceEditMode will be Occurrence
+        if (args.RecurrenceEditMode == RecurrenceEditMode.Occurrence)
+        {
+            // The item will have RecurrenceId set to the parent appointment's Id
+            Console.WriteLine($"Creating exception for recurring appointment: {item.RecurrenceId}");
+        }
+
+        SchedulerData.Add(item);
+    }
+
+    private void OnSchedulerUpdate(SchedulerUpdateEventArgs args)
+    {
+        Appointment item = (Appointment)args.Item;
+
+        if (args.RecurrenceEditMode == RecurrenceEditMode.Series)
+        {
+            // User chose to update the entire series
+            Console.WriteLine("Updating entire series of recurring appointments");
+            
+            // Update the recurring appointment
+            int originalItemIndex = SchedulerData.FindIndex(a => a.Id == item.Id);
+            if (originalItemIndex >= 0)
+            {
+                SchedulerData[originalItemIndex] = item;
+            }
+        }
+        else if (args.RecurrenceEditMode == RecurrenceEditMode.Occurrence)
+        {
+            // User chose to update only this occurrence
+            Console.WriteLine("Creating exception for single occurrence");
+            
+            // This creates a new exception appointment
+            // The item will have RecurrenceId pointing to the parent
+            int originalItemIndex = SchedulerData.FindIndex(a => a.Id == item.Id);
+            if (originalItemIndex >= 0)
+            {
+                SchedulerData[originalItemIndex] = item;
+            }
+        }
+    }
+
+    private void OnSchedulerDelete(SchedulerDeleteEventArgs args)
+    {
+        Appointment item = (Appointment)args.Item;
+
+        if (args.RecurrenceEditMode == RecurrenceEditMode.Series)
+        {
+            // User chose to delete the entire series
+            Console.WriteLine("Deleting entire series");
+            
+            // Remove the recurring appointment
+            SchedulerData.Remove(item);
+            
+            // Optionally, remove all exceptions for this series
+            if (!string.IsNullOrEmpty(item.RecurrenceRule))
+            {
+                SchedulerData.RemoveAll(a => a.RecurrenceId?.Equals(item.Id) == true);
+            }
+        }
+        else if (args.RecurrenceEditMode == RecurrenceEditMode.Occurrence)
+        {
+            // User chose to delete only this occurrence
+            Console.WriteLine("Deleting single occurrence");
+            
+            if (item.RecurrenceId != null)
+            {
+                // This is already an exception, just remove it
+                SchedulerData.Remove(item);
+                
+                // Update the parent appointment's RecurrenceExceptions list
+                var parentAppointment = SchedulerData.FirstOrDefault(a => a.Id.Equals(item.RecurrenceId));
+                if (parentAppointment != null)
+                {
+                    // Remove the exception date from the parent's list
+                    parentAppointment.RecurrenceExceptions?.Remove(item.Start);
+                }
+            }
+            else
+            {
+                // This is a recurring appointment, create an exception
+                // The Scheduler automatically adds the occurrence date to RecurrenceExceptions
+                SchedulerData.Remove(item);
+            }
+        }
+    }
+
+    public class Appointment
+    {
+        public Guid Id { get; set; }
+        public string Title { get; set; } = string.Empty;
+        public DateTime Start { get; set; }
+        public DateTime End { get; set; }
+        public bool IsAllDay { get; set; }
+        public string RecurrenceRule { get; set; } = string.Empty;
+        public List<DateTime>? RecurrenceExceptions { get; set; }
+        public Guid? RecurrenceId { get; set; }
+
+        public Appointment()
+        {
+            Id = Guid.NewGuid();
+        }
+    }
+}
+````
+
+### Important Considerations
+
+* When the user edits or deletes a single occurrence of a recurring appointment, the Scheduler automatically manages the `RecurrenceExceptions` list and creates exception appointments with the appropriate `RecurrenceId`.
+* The `RecurrenceEditMode` property is only relevant when working with recurring appointments. For regular (non-recurring) appointments, this property is not used.
+* When creating a new appointment in a time slot that matches a recurring appointment, the user can choose to create an exception or a new independent appointment.
+
 ## Recurrence Editor Components
 
 Telerik UI for Blazor provides standalone components that you can use to edit recurring appointments outside the Scheduler or in a [custom Scheduler popup edit form](slug:scheduler-kb-custom-edit-form).