Download the PHP package arckinteractive/events_api without Composer

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.

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.

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.

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.

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.

Event

The event is an ElggObject with the subtype 'event'. It is contained by another entity and is attached to calendars via a relationship.

Actions

This action adds/edits an event.

Required inputs are:

• STR '2015-01-07' // Y-m-d
• STR '2015-01-08' // Y-m-d
• STR '12:00am' // g:ia
• STR '1:00am' // g:ia

Optional inputs are:

• INT
• STR (will default to )
• STR
• BOOL does the event have reminders enabled?
• ARR an associative array describing the reminders in terms of increment and value

eg.

$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.

This action moves an event

Required inputs are:

• INT the guid of the event
• INT how far forward/back to move the event
• INT how far forward/back to move the event

After validation an event is triggered: before the changes are made. Returning false will stop the move. Handlers returning false are expected to provide their own error message.

Note this is a convenience action, see for an equivalent method

This action resizes an event (changes just the end date/time)

Required inputs are:

• INT the guid of the event
• INT how far forward/back to move the end point
• INT how far foward/back to move the end point

After validation an event is triggered: before the changes are made. Returning false will stop the resize. Handlers returning false are expected to provide their own error message.

Note this is a convenience action, see for an equivalent method

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.

Installation / Tests

If downloading from GitHub: