Events API 
This plugin provides a data structure and convenience function for building an events application.
As each project's requirements tend to be different this is made as generic as extensible as possible
to act as a base back-end. UI and integration should be performed by a project specific helper plugin., (*1)
All functions take arguments in terms of formatted dates 'Y-m-d' and times 'g:ia' to keep timezone calculations to a minimum.
Timezone functionality can be added and calculated client-side., (*2)
Calendar
The calendar is an ElggObject with the subtype 'calendar'. It is contained by another entity, usually a user
or a group. The edit permissions are inherited by write access to the container.
The calendar holds events. Events are linked to the calendar using relationships, this way it's possible
that an event can show on multiple calendars., (*3)
Each user and group has one "public" calendar. This calendar is automatically created, and can not be deleted or edited
by non-admin users. All new events that do not explicitly define a calendar, will be added to "public" calendar., (*4)
Users can create other calendars with custom visiblity/access settings. Additionally, public calendar can contain
non-public events, which will only be visible to viewers that have permissions to see them., (*5)
Event
The event is an ElggObject with the subtype 'event'. It is contained by another entity and is attached to calendars via a relationship., (*6)
Actions
action('events/edit')
This action adds/edits an event., (*7)
Required inputs are:
- start_date STR '2015-01-07' // Y-m-d
- end_date STR '2015-01-08' // Y-m-d
- start_time STR '12:00am' // g:ia
- end_time STR '1:00am' // g:ia, (*8)
Optional inputs are:
- guid INT
- title STR (will default to elgg_echo('events:edit:title:placeholder'))
- description STR
- has_reminders BOOL does the event have reminders enabled?
- reminders ARR an associative array describing the reminders in terms of increment and value, (*9)
eg., (*10)
$reminders = array(
'value' => array(
15,
1,
''
),
'increment' => array(
'minute',
'hour',
''
)
)
describes reminders of 15 minutes, and 1 hour prior the meeting. The last item of each
array is ignored as a template value., (*11)
action('events/move')
This action moves an event, (*12)
Required inputs are:
- guid INT the guid of the event
- day_delta INT how far forward/back to move the event
- minute_delta INT how far forward/back to move the event, (*13)
After validation an event is triggered: 'events_api', 'event:move' before the changes are made.
Returning false will stop the move. Handlers returning false are expected to provide their own error message., (*14)
Note this is a convenience action, see \Events\API\Event::move() for an equivalent method, (*15)
action('events/resize')
This action resizes an event (changes just the end date/time), (*16)
Required inputs are:
- guid INT the guid of the event
- day_delta INT how far forward/back to move the end point
- minute_delta INT how far foward/back to move the end point, (*17)
After validation an event is triggered: 'events_api', 'event:resize'before the changes are made.
Returning false will stop the resize. Handlers returning false are expected to provide their own error message., (*18)
Note this is a convenience action, see \Events\API\Event::resize() for an equivalent method, (*19)
Reminders
Reminders are stored as metadata on the event as a delta of number of seconds prior to the event
in which to notify the user.
On daily cron and plugin activation a script determines upcoming reminders and stores them as annotations
on the event.
The sending of reminders is left to the UI, the expected method is to register for minute cron, look
for annotations coming up in the next minute - and send a reminder for any events that show up. Deleting the
reminder annotation on each pass., (*20)
Installation / Tests
If downloading from GitHub:, (*21)
# install dependencies (without dev)
composer install --no-dev
# install dependencies (including dev)
composer install
# run tests
vendor/bin/phpunit
Wallogit.com
