arckinteractive / events_api
A robust data model and api for events
Installs: 143
Dependents: 3
Suggesters: 0
Security: 0
Stars: 5
Watchers: 12
Forks: 2
Open Issues: 3
Type:elgg-plugin
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
This package is not auto-updated.
Last update: 2024-11-04 12:59:21 UTC
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-dend_date
STR '2015-01-08' // Y-m-dstart_time
STR '12:00am' // g:iaend_time
STR '1:00am' // g:ia
Optional inputs are:
guid
INTtitle
STR (will default toelgg_echo('events:edit:title:placeholder')
)description
STRhas_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 eventday_delta
INT how far forward/back to move the eventminute_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 eventday_delta
INT how far forward/back to move the end pointminute_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