Table of content
This functionality allows to manage recurring events. In common case recurring event is saved as a single instance of event along with 'recurrence' field where recurring pattern is stored. Based on this pattern Calendar UI expands instance of one recurring event into a sequence of occurrences.
Currently recurring events can be managed only using API. UI exposes these events but has limitations to manage them.
For instance only
description fields of recurring event could be edited using UI. Also it's not possible
to create recurring event using UI at the moment.
Each calendar event has
recurrence field. This is a dictionary containing fields related to the event recurrence. Some fields are mandatory for all recurrence patterns, and some fields are required only for some patterns. The fields are described in the following table:
|Field Name||Recurrence Pattern|
|interval||Number of day||Number of week||Number of month||Number of month (a multiple of 12, i.e. 12, 24, 36, 48 etc.|
|instance||Not used||Not used||Not used||A value from 1 to 5||Not used||A value from 1 to 5|
|dayOfWeek||Not used||Array of week days||Not used||Array containing one week day||Not used||Array containing one week day|
|dayOfMonth||Not used||Not used||Day of month||Not used||Day of month||Not used|
|monthOfYear||Not used||Not used||Not used||Not used||Month number from 1 to 12|
|startTime||Range of recurrence - Start (mandatory)|
|endTime||Range of recurrence - End (mandatory)|
|occurrences||Range of recurrence - End after X occurrences (optional)|
|timeZone||The time zone in which the time is specified (mandatory)|
In common case for recurring event only one entity of OroCalendarBundle:CalendarEvent is created with reference to
entity of OroCalendarBundle:Recurrence. When API request with date range will be send to server, it will dynamically
expand each instance of recurring event into occurrences of this recurring event. Each occurrence event will have the
same data as original recurring event, but with dynamically calculated
Each occurrence of a recurrent event can be modified so it differs from other occurrences. Such event has it's own step
and called "exception" event. These exceptions are represented by separate event entities with additional fields.
The standard event fields (
end, etc.) can differ from the parent recurrence event fields.
Here is the list of additional fields which are applicable only for exception events:
- recurringEventId – the id of the parent recurring event.
- originalStart – the original start date and time of this occurrence. It may differ from the actual start date for the recurrence.
- isCancelled – A boolean field indicating whether the occurrence was cancelled (removed from the user’s calendar).
To make sure that Recurrence pattern has all needed data it can be validated with recurrence model:
use Oro\Bundle\CalendarBundle\Model\Recurrence as RecurrenceModel; ... /** @var \Symfony\Component\Validator\Validator\ValidatorInterface $validator */ /** @var \Oro\Bundle\CalendarBundle\Entity\Recurrence $recurrence */ $model = new RecurrenceModel($this->validator); $model->validateRecurrence($recurrence);
Here is a list of key classes:
- Entity/Recurrence - Entity that contains all recurrence pattern data and has 'one to one' relation with CalendarEvent.
- Model/Recurrence - Model represents domain logic related to recurrence. Recurrence entity is passed to model in most cases to fulfill it's responsibilities. Can be used by client code in the application.
Model / Strategies Strategies implements different types of recurrence patterns. Model uses strategies to delegate responsibilities related to different recurrence patterns. Strategies should not be used directly in application client code.
- Model/Recurrence/AbstractStrategy - The base class for recurrence patterns. It contains all basic methods that can be reused in child classes.
- Model/Recurrence/DailyStrategy - The Daily recurrence pattern strategy implementation.
- Model/Recurrence/DelegateStrategy - The class that determines what recurrence pattern strategy must be used according recurrence data.
- Model/Recurrence/MonthlyStrategy - The Monthly recurrence pattern strategy implementation.
- Model/Recurrence/MonthNthStrategy - The MonthNth recurrence pattern strategy implementation.
- Model/Recurrence/StrategyInterface - An interface of recurrence pattern strategies.
- Model/Recurrence/WeeklyStrategy - The Weekly recurrence pattern strategy implementation.
- Model/Recurrence/YearlyStrategy - The Yearly recurrence pattern strategy implementation.
- Model/Recurrence/YearNthStrategy - The YearNth recurrence pattern strategy implementation.