Elgg Events

As already mentioned, there are two types of events in the Elgg platform: Elgg events and plugin hooks. Elgg events are triggered when something is created, updated or deleted or when the Elgg framework is loading. Examples would include a blog post being created or a user logging in. Each event is determined by an event name and an object type (system, user, object, relationship name, annotation, group). By registering handlers for Elgg events, your plugin can have code executed when that event occurs.

Registering an Event Handler

To register a handler, use the function register_elgg_event_handler as in this example:

register_elgg_event_handler('init','system','entities_init');

v1.8

elgg_register_event_handler('init','system','entities_init');

Parameters Documentation

$event The event type.
$object_type The object type (eg "user" or "object") or 'all' (for all entity types) that the event belongs to.
$function The name of a valid function to be run.
$priority The priority - 0 is first and the default is 500.

object here does not refer to an ElggObject but rather any object in the framework: system, user, object, relationship name, annotation, group.

Event Handler Prototype

Your event handler should have the following prototype:

function event_handler_function($event, $object_type, $object)
{
 
    ... do stuff ...
 
}

If the function returns false, it halts the calling of other event handlers and may stop the execution of some code in the Elgg core.

Parameters

$event The event type.
$object_type The type of object (eg "user", "object")
$object The object itself or null

Trigger an Event

You can trigger an event in your plugin with the trigger_elgg_event function.

trigger_elgg_event($event, $object_type, $object = null)

$event The event type
$object_type The object type
$object Object passed to handlers

Example: trigger_elgg_event('validate', 'user', $user);

Special events

Elgg has four events that occur on almost every pageload.

Boot

System boot connects to the database, starts the session, and establishes some base variables and configuration settings. This event is inaccessible to plugins, as it is triggered before plugins are loaded.

Init

This event is intended for plugins to perform configuration procedures. It is recommended that you add submenu items and perform similar activities in a yourplugin_init function attached to this event.

Pagesetup

Sometimes it's necessary to perform further procedures after the full Elgg framework has been loaded, but before any HTML content has been created. This event is called during the first reference to elgg_view (whether directly or through a call to a helper function like elgg_view_title or list_entities).

Shutdown

This event is triggered after the page has been fully rendered and sent to the browser. Registering to this event can be useful to perform events which may take a bit of time without slowing the user experience.

Elgg Events

Contents