Skip to content

Commit 89ea37d

Browse files
dimodidimodi
committed
Add Recurrence Components docs for release 9.0
1 parent 131bde7 commit 89ea37d

File tree

2 files changed

+204
-1
lines changed

2 files changed

+204
-1
lines changed

‎components/scheduler/overview.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@ Users can [create, edit and delete Scheduler appointments](slug:scheduler-appoin
107107

108108
## Recurrence
109109

110-
The Scheduler can display and edit [recurring appointments and recurrence exceptions](slug:scheduler-recurrence).
110+
The Scheduler can display and edit [recurring appointments and recurrence exceptions](slug:scheduler-recurrence). Telerik UI for Blazor also provides standalone [recurrence editor components](slug:scheduler-recurrence#recurrence-editor-components) that you can use to edit recurrence rules in a custom edit form.
111+
111112

112113
## Resources and Grouping
113114

‎components/scheduler/recurrence.md

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,6 +220,208 @@ A single Scheduler data item defines one series of recurring appointments. Set t
220220
}
221221
````
222222

223+
## Recurrence Editor Components
224+
225+
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).
226+
227+
The Telerik Blazor recurrence editor components include:
228+
229+
@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
230+
231+
| Component Name | Renders As | Description |
232+
| --- | --- | --- |
233+
| `RecurrenceFrequencyEditor` | Button Group | Defines whether the appointment repeats daily, weekly, monthly, yearly, or never. |
234+
| `RecurrenceIntervalEditor` | Numeric TextBox | Defines whether the appointment repeats in each period (for example, every day), or skips periods (for example, once in three days). |
235+
| `RecurrenceEditor` | Button&nbsp;Group or Radio&nbsp;Group | <ul><li>For weekly frequency, the Recurrence Editor is a Button Group with multiple selection, which allows choosing week days.</li><li>For monthly and yearly frequency, the Recurrence Editor is a combination for DropDownLists and a Numeric TextBox, which allow selecting repetition on specific days or week days.</li></ul> |
236+
| `RecurrenceEndEditor` | Radio&nbsp;Group, Numeric&nbsp;TextBox, Date&nbsp;Picker | Defines if the appointment repeats indefinitely, a number of times, or until a specific date. |
237+
238+
### Parameters
239+
240+
All recurrence editor components expose:
241+
242+
* A `Rule` parameter of type `Telerik.Recurrence.RecurrenceRule` that supports two-way binding.
243+
* A `RuleChanged` event that receives a `RecurrenceRule` argument.
244+
* A `Class` parameter for [styling customizations](slug:themes-override).
245+
246+
In addition:
247+
248+
* The `RecurrenceIntervalEditor` supports an `Id` parameter of type `string`. Use it to set a custom `id` attribute to the Numeric TextBox and the same `for` attribute to the associated **Repeat every** label.
249+
* The `RecurrenceEndEditor` supports an `End` parameter of type `DateTime`. Use it to set a default value for the **End On** Date Picker when there is no `UNTIL` setting in the recurrence rule string.
250+
251+
### Recurrence Rule Type Conversion
252+
253+
Use the following methods to convert from [RFC5545 strings](https://tools.ietf.org/html/rfc5545#section-3.3.10) to `RecurrenceRule` objects and vice-versa:
254+
255+
* The static method `RecurrenceRule.Parse()` to convert from RFC5545 `string` to `RecurrenceRule`.
256+
* The instance method `RecurrenceRule.ToString()` to convert from `RecurrenceRule` to a RFC5545 `string`.
257+
258+
>caption Converting between different recurrence rule formats
259+
260+
````C#.skip-repl
261+
// RFC5545 string
262+
string recurrenceString = "FREQ=WEEKLY;BYDAY=MO,WE,FR";
263+
264+
// Convert to RecurrenceRule
265+
RecurrenceRule recurrenceRule = RecurrenceRule.Parse(recurrenceString);
266+
267+
// Make some changes...
268+
269+
// Convert to RFC5545 string
270+
string newRecurrenceString = recurrenceRule.ToString();
271+
````
272+
273+
### Telerik Form Integration
274+
275+
There are two recommended ways to use the Telerik recurrence editors in a Telerik Form:
276+
277+
* Place each recurrence editor in a separate [Form item `Template`](slug:form-formitems-template). This is the simpler option to set up.
278+
* Place all recurrence editors in a [`<FormItemsTemplate>`](slug:form-formitems-formitemstemplate). This is a more verbose approach, which provides better control over the Form's HTML rendering, layout and styling.
279+
280+
The following examples can serve as a reference for creating [custom Telerik Scheduler edit forms](slug:scheduler-kb-custom-edit-form) with recurrence editing. Using a markup structure that differs from the ones below may produce unexpected layouts.
281+
282+
>caption Using Telerik recurrence editors in separate Form item templates
283+
284+
````RAZOR
285+
@using Telerik.Recurrence
286+
287+
<TelerikForm Model="@RecurringAppointment"
288+
OnUpdate="@OnFormUpdate">
289+
<FormItems>
290+
<FormItem Field="@nameof(Appointment.Title)" />
291+
<FormItem Field="@nameof(Appointment.Start)" />
292+
<FormItem Field="@nameof(Appointment.End)" />
293+
<FormItem Field="@nameof(Appointment.RecurrenceRule)"
294+
LabelText="Recurrence Rule"
295+
Enabled="false" />
296+
<FormItem>
297+
<Template>
298+
<TelerikRecurrenceFrequencyEditor Rule="@Rule"
299+
RuleChanged="@OnRuleChanged" />
300+
</Template>
301+
</FormItem>
302+
<FormItem>
303+
<Template>
304+
@if (Rule != null)
305+
{
306+
<TelerikRecurrenceIntervalEditor Rule="@Rule" />
307+
}
308+
</Template>
309+
</FormItem>
310+
<FormItem>
311+
<Template>
312+
<TelerikRecurrenceEditor Rule="@Rule"
313+
RuleChanged="@OnRuleChanged" />
314+
</Template>
315+
</FormItem>
316+
<FormItem>
317+
<Template>
318+
@if (Rule != null)
319+
{
320+
<TelerikRecurrenceEndEditor Rule="@Rule"
321+
EndDate="@RecurrenceEndDefaultDate" />
322+
}
323+
</Template>
324+
</FormItem>
325+
</FormItems>
326+
</TelerikForm>
327+
328+
@code {
329+
private Appointment? RecurringAppointment { get; set; }
330+
331+
private RecurrenceRule? Rule { get; set; }
332+
333+
private DateTime RecurrenceEndDefaultDate =>
334+
new DateTime(Math.Max(RecurringAppointment?.End.Ticks ?? default, DateTime.Now.Ticks));
335+
336+
private void OnFormUpdate()
337+
{
338+
// Only necessary to refresh the UI until all Rule parameters gain two-way binding.
339+
RecurringAppointment!.RecurrenceRule = Rule?.ToString() ?? string.Empty;
340+
}
341+
342+
private void OnRuleChanged(RecurrenceRule newRule)
343+
{
344+
Rule = newRule;
345+
346+
RecurringAppointment!.RecurrenceRule = Rule?.ToString() ?? string.Empty;
347+
}
348+
349+
protected override void OnInitialized()
350+
{
351+
DateTime nextMonday = DateTime.Today.AddDays(8 - (int)DateTime.Today.DayOfWeek);
352+
353+
RecurringAppointment = new Appointment
354+
{
355+
Title = "Workout at the gym",
356+
Start = nextMonday.AddHours(17),
357+
End = nextMonday.AddHours(18),
358+
RecurrenceRule = "FREQ=WEEKLY;BYDAY=MO,WE,FR"
359+
};
360+
361+
Rule = RecurrenceRule.Parse(RecurringAppointment.RecurrenceRule);
362+
}
363+
364+
public class Appointment
365+
{
366+
public Guid Id { get; set; }
367+
368+
public string Title { get; set; } = string.Empty;
369+
public string Description { get; set; } = string.Empty;
370+
371+
public DateTime Start { get; set; }
372+
public DateTime End { get; set; }
373+
public bool IsAllDay { get; set; }
374+
375+
public string RecurrenceRule { get; set; } = string.Empty;
376+
public List<DateTime>? RecurrenceExceptions { get; set; }
377+
public Guid? RecurrenceId { get; set; }
378+
379+
public Appointment()
380+
{
381+
var rand = new Random();
382+
Id = Guid.NewGuid();
383+
}
384+
}
385+
}
386+
````
387+
388+
To add the recurrence editors to a `FormItemsTemplate`, follow the same approach as in the example above, but add the following `<FormItemsTemplate>` tag as a child of `<TelerikForm>`.
389+
390+
>caption Using Telerik recurrence editors in a FormItemsTemplate
391+
392+
````RAZOR.skip-repl
393+
<FormItemsTemplate Context="formContext">
394+
@{
395+
var formItems = formContext.Items.Cast<IFormItem>().ToList();
396+
}
397+
<TelerikFormItemRenderer Item="@( formItems.First(x => x.Field == nameof(Appointment.Title)) )" />
398+
<TelerikFormItemRenderer Item="@( formItems.First(x => x.Field == nameof(Appointment.Start)) )" />
399+
<TelerikFormItemRenderer Item="@( formItems.First(x => x.Field == nameof(Appointment.End)) )" />
400+
<TelerikFormItemRenderer Item="@( formItems.First(x => x.Field == nameof(Appointment.RecurrenceRule)) )" />
401+
<div class="k-form-field">
402+
<TelerikRecurrenceFrequencyEditor Rule="@Rule"
403+
RuleChanged="@OnRuleChanged" />
404+
</div>
405+
@if (Rule != null)
406+
{
407+
<div class="k-form-field">
408+
<TelerikRecurrenceIntervalEditor Rule="@Rule" />
409+
</div>
410+
}
411+
<div class="k-form-field">
412+
<TelerikRecurrenceEditor Rule="@Rule"
413+
RuleChanged="@OnRuleChanged" />
414+
</div>
415+
@if (Rule != null)
416+
{
417+
<div class="k-form-field">
418+
<TelerikRecurrenceEndEditor Rule="@Rule"
419+
EndDate="@RecurrenceEndDefaultDate" />
420+
</div>
421+
}
422+
</FormItemsTemplate>
423+
````
424+
223425
## Next Steps
224426

225427
* [Enable Scheduler Editing](slug:scheduler-appointments-edit)

0 commit comments

Comments
 (0)