Events and hooks

Elgg's events and plugin hooks are an important part of the platform's extensibility. Plugins register functions that are called when an event occurs or a hook is triggered. Through these callback functions, plugins change or extend the functionality of Elgg's engine.

There is overlap between the functionality of events and plugin hooks. Broadly, they can be described as follows:

• Elgg events notify the registered callback function that something has happened

• Plugin hooks give callback functions the opportunity to change something that the core has done

The callback functions are called handlers, but do not confuse them with page handlers.

Elgg events

Event handlers are registered with the function elgg_register_event_handler():

elgg_register_event_handler('pagesetup', 'system', 'blog_page_setup');

Multiple handlers can be registered for an event. Each event is identified by two words ('pagesetup' and 'system' in this example). The handler is passed a single object involved in the event. If a blog post has been saved, then it is the blog object. If a comment has been posted, then it is the annotation object. Returning false prevents any other event handlers from running and may stop the core from carrying out its current task.

Plugin hooks

Plugin hook handlers are registered with the function elgg_register_plugin_hook_handler():

elgg_register_plugin_hook_handler('public_pages', 'walled_garden', 'twitter_api_public_pages');

Plugin hook handlers are passed a return value and other data associated with the hook. The handler function can return the original return value, a modified version, or something completely different.

Event handlers and plugin hooks do not all operate in the same manner. It is best to check the code and comments where the event or hook is triggered before attempting to use one. Possible events and hooks are found by searching the code for elgg_trigger_event() and elgg_trigger_plugin_hook().

Code location

Functions: /engine/lib/elgglib.php