phpBB

Development Wiki

Difference between revisions of "Add Events"

From phpBB Development Wiki

(Core events List)
(What are events?)
Line 1: Line 1:
 
==What are events?==
 
==What are events?==
An event is a hook location (also once known as a ledge). When an extension wishes to hook its functionality into the phpBB core at a certain point, it can do so only at available hook locations, or events. For more information, see the wiki article for [[listeners]].
+
When an extension wishes to hook its functionality into the phpBB core at a certain point, it can do so only where respective events are triggered. For more information, see the wiki article for [[listeners]]. Events are also known as hook location and previously ledges.
  
 
==How to add an event to everything except templates==
 
==How to add an event to everything except templates==

Revision as of 00:53, 18 October 2013

What are events?

When an extension wishes to hook its functionality into the phpBB core at a certain point, it can do so only where respective events are triggered. For more information, see the wiki article for listeners. Events are also known as hook location and previously ledges.

How to add an event to everything except templates

You would add an event you would use this code:

global $phpbb_dispatcher;

$vars = array('var1''var2');
extract($phpbb_dispatcher->trigger_event('identifier'compact($vars)));

This code takes variables used by phpbb, packages them into an event object and dispatches the event to any registered listeners. Then it extracts the variables back, therefore allowing hooks to modify them. It is the magic incantation for adding events.

If an event does not need any arguments, you can use this short version:

global $phpbb_dispatcher;

$phpbb_dispatcher->dispatch('identifer');

You only need to register the global if you are inside a function.

Identifier will need to be changed to the name of the event. This should be prefixed by `core.` if it is an event in the core and not in your extension (you can have events in your extensions for other extensions to use). It should be unique and only use underscores and full stops/periods (for the prefix) and lowercase letters.

var1 and var2 should be replaced with the list of variables that are to be passed to listeners. Each of these variables should exist in the local scope where the ledge is being added. You can have as many as you wish inside this array or just 1.

And now you've made an event and just need to document it as below.

How to add an event to templates

Add the following code to a template:

<!-- EVENT identifier -->

Replace the identifier with the name of the listener. Make sure to only use underscores, numbers and lowercase letters.

That's it! You've created an event and should document it as described below.

Core events List

If you add an event to phpBB rather than one of your own templates, it must be added to the events list.

You can view and edit the events list here

Examples of events being added