RecurringTimeSpan
Mixin

This mixin class provides recurrence related fields and methods to a TimeSpan model. This class is used to support recurring events (and time ranges) in the Scheduler and Calendar components.

Data structure

The mixin introduces two types of timespans: the recurring timespan and its occurrences. A recurring timespan is a timespan having a recurrenceRule specified and its occurrences are "fake" dynamically generated timespans. You can also provide exceptionDates to the data to exclude certain dates. See sample data below,

{
    id: 7,
    startDate: '2021-10-12T14:00:00',
    endDate: '2021-10-12T15:00:00',
    name: 'Lunch',
    resourceId: 'hotel',
    recurrenceRule: 'FREQ=DAILY;COUNT=5',
    exceptionDates: ['2021-10-14']
}

Useful API methods

There are few methods allowing to distinguish a recurring event and an occurrence: isRecurring, isOccurrence and recurringTimeSpan (returns the event this record is an occurrence of).

The recurrence rule defined for the event is parsed and represented with RecurrenceModel class (can be changed by setting recurrenceModel property) instance. See: recurrence property.

To query the ocurrences for a specific timespan, use the getOccurrencesForDateRange method:

// Get all occurrences between Feb 1-10
timespan.getOccurrencesForDateRange(new Date(2024, 1, 1), new Date(2024, 1, 10));

No results

Fields

Fields belong to a Model class and define the Model data structure

exceptionDates : String/String[]

A string (either a single date or multiple dates separated by comma) or an array of strings containing the timespan exception dates. The dates that must be skipped when generating occurrences for a repeating timespan. This is used to modify only individual occurrences of the timespan so the further regenerations won't create another copy of this occurrence again.

{
    id: 7,
    startDate: '2021-10-12T14:00:00',
    endDate: '2021-10-12T15:00:00',
    name: 'Lunch',
    resourceId: 'hotel',
    recurrenceRule: 'FREQ=DAILY;COUNT=5',
    exceptionDates: ['2021-10-14']
}

Use addExceptionDate method to add an individual entry to the dates array:

// Break the link between the occurrence and its base.
// This also adds the occurrence date as an exception date
// so that the base timespan knows that this date should be skipped when regenerating its occurrences.
occurrence.recurringTimeSpan = null;

// now the occurrence is an individual record that can be changed & persisted freely
occurrence.setStartEndDate(new Date(2018, 6, 2), new Date(2018, 6, 3));

Note: The dates in this field get automatically removed when the event changes its start date.

recurrenceRule : String

The timespan recurrence rule. A string in RFC-5545 described format ("RRULE" expression).

Properties

Properties are getters/setters or publicly accessible variables on this class

isRecurringTimeSpan : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of RecurringTimeSpan class, or subclass thereof.

isRecurringTimeSpan : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of RecurringTimeSpan class, or subclass thereof.
isOccurrence : Boolean

READONLY

Indicates if the timespan is an occurrence of another recurring timespan.
isRecurring : Boolean

READONLY

Indicates if the timespan is recurring.
newExceptionDate : Date

private

READONLY

The setter used by Model#inSet when addExceptionDate is called. Adding an exception must trigger change processing in a recurring event, so it must be changed through a set call. Also, the change must be batchable with other changes.
occurrenceDate : Date

internal

READONLY

The original {@lScheduler.model.TimeSpan#field-startDate startDate} of this event before any modifications took place. Used by removeOccurrence and detachFromRecurringEvent
occurrenceIndex : Number

READONLY

If this event is an occurrence of a recurring event, then this property yields its zero-based occurrence index in the sequence.
occurrenceMap : Map

internal

READONLY

A Map, keyed by each date an occurrence intersects, of occurrences of this event.
occurrences : TimeSpan[]

internal

READONLY

Array of this recurring timespan's cached occurrences. Not including the owning recurring event.

Empty if the timespan is not recurring.

Note that this is an internal accessor and is cleared whenever changes are made to the owning recurring event.
recurrence : RecurrenceModel

The recurrence model used for the timespan.
recurrenceModel : String

Name of the class representing the recurrence model, defaults to RecurrenceModel
recurringTimeSpan : TimeSpan

internal

READONLY

The "main" timespan this model is an occurrence of. For non-occurrences returns null.
supportsRecurring : Boolean

READONLY

Returns true if this timespan supports recurring.

Functions

Functions are methods available for calling on the class

addExceptionDate( date )

Adds an exception date that should be skipped when generating occurrences for the timespan. The method adds an entry to the array kept in exceptionDates field.
buildOccurrence( occurrenceDate, isFirst )
: TimeSpan

internal

Builds an occurrence of this recurring event by cloning the timespan data. The method is used internally by the RecurringTimeSpans mixin. Override it if you need to customize the generated occurrences.

If the date requested is the start date of the event sequence, this record is returned. All runs of recurring events begin with the base record.
detachFromRecurringEvent( )

internal

Detaches an occurrence from its owning recurring event so that it can be added to the eventStore either as an exception, or as the start of a new recurring sequence.
getOccurrencesForDateRange( startDate, endDate )
: TimeSpan[]

Returns the occurrences of this event over the specified time range. If the first occurrence is in the time range *this* record is included in that position.
hasException( date )
: Boolean

Does this recurring event have an exception on the passed date.
hasOccurrencesInDateRange( startDate, endDate )
: Boolean

Returns true if this recurring timespan has any occurrences within the specified date range. More efficient than getOccurrencesForDateRange when you only need to check existence, since it short-circuits on the first match without materializing all occurrences.
onRecurrenceChanged( )

internal

The method is triggered when the timespan recurrence settings get changed. It updates the recurrenceRule field in this case.
remove( )

Override of Model's method. If an isOccurrence is passed, it is detached from its parent recurring event. If it still has a recurrence then the recurring event is changed to stop at the occurrence date. If it has no recurrence an exception is added at the occurrence date.
removeOccurrence( dateOrTimeSpan )

internal

Removes an occurrence from this recurring timespan's cached occurrences.
removeOccurrences( )

internal

Removes this recurring timespan's cached occurrences.
removeOccurrencesFrom( )

internal

Removes all cached occurrences on or after the passed date from this recurring timespan's cached occurrences.
setRecurrence( recurrence, interval, recurrenceEnd )

Sets a recurrence for the timespan with a given frequency, interval, and end.

Source path

Scheduler/model/mixin/RecurringTimeSpan.js

Inheritance tree1

RecurringTimeSpan

RecurringTimeSpan Mixin