arckinteractive/events_api

A robust data model and api for events

2.0.1 2017-11-20 18:27 UTC

Requires

• php: >=5.3.3
• ext-curl: *
• ext-json: *
• ext-xml: *
• composer/installers: 1.*
• kigkonsult/icalcreator: v2.22.5

Requires (Dev)

• phpunit/phpunit: ~4.1

GPL-2.0

• Matt Beckett
• Ismayil Khayredinov

• plugin
• events
• elgg

README

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

action('events/edit')

This action adds/edits an event.

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

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

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.

action('events/move')

This action moves an event

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

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.

Note this is a convenience action, see \Events\API\Event::move() for an equivalent method

action('events/resize')

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

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

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.

Note this is a convenience action, see \Events\API\Event::resize() 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:

# install dependencies (without dev)
composer install --no-dev

# install dependencies (including dev)
composer install

# run tests
vendor/bin/phpunit