phpBB

Development Wiki

Difference between revisions of "Add Events"

From phpBB Development Wiki

m (moved Add Ledges to Add Events)
(Events and Listeners)
Line 1: Line 1:
==What are ledges?==
+
==What are events?==
A ledge is a hook location. 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 ledges. For more information, see the wiki article for [[hooks]].
+
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]].
  
==How to add a ledge to everything except templates==
+
==How to add an event to everything except templates==
You would add a ledge you would use this code:
+
You would add an event you would use this code:
 
<php>
 
<php>
 
global $phpbb_dispatcher
 
global $phpbb_dispatcher
Line 12: Line 12:
 
extract($event->get_data_filtered($vars));
 
extract($event->get_data_filtered($vars));
 
</php>
 
</php>
This code takes variables used by phpbb, packages them into an event object and dispatches the event to any registered hooks. Then it extracts the variables back, therefore allowing hooks to modify them. It is the magic incantation for adding ledges.
+
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 a ledge does not need any arguments, you can use this short version:
 
If a ledge does not need any arguments, you can use this short version:
Line 23: Line 23:
 
You only need to register the global if you are inside a function.
 
You only need to register the global if you are inside a function.
  
Identifier will need to be changed to the name of the ledge. This should be prefixed by `core.` if it is a ledge in the core and not in your extension (you can have ledges 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.
+
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 hooks. 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.
+
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 a ledge and just need to document it as below.
+
And now you've made an event and just need to document it as below.
  
==How to add a ledge to templates==
+
==How to add an event to templates==
 
This is very simple to do
 
This is very simple to do
 
<pre><!-- RUNHOOKS identifier --></pre>
 
<pre><!-- RUNHOOKS identifier --></pre>
Just replace the identifier with the name of the hook by just using underscores, numbers and lowercase letters.
+
Just replace the identifier with the name of the listenr by just using underscores, numbers and lowercase letters.
  
==Core Ledges List==
+
And now you've made an event and just need to document it as below.
If you add a ledge to the core you need to ensure you add it to the ledges list to ensure it remains a comprehensive and exhaustive list.
+
  
Requested ledges can also be added to the list and they will be added at some point to the phpBB repository.
+
==Core events List==
 +
If you add a events to the core you need to ensure you add it to the events list to ensure it remains a comprehensive and exhaustive list.
  
You can view and edit the ledges list page [[Ledges_List|here]]
+
You can view and edit the events list page [[Events_List|here]]
  
==Examples of ledges being added==
+
==Examples of events being added==
 
* [https://github.com/p/phpbb3/commit/15e4bdd67f69844b8f7c2387196fa3c54b66ff7c core.memberlist_profile_data ledge.]
 
* [https://github.com/p/phpbb3/commit/15e4bdd67f69844b8f7c2387196fa3c54b66ff7c core.memberlist_profile_data ledge.]
 
* [https://github.com/p/phpbb3/commit/7e3cc2a333b4969f69622620cfd7b08ae595a219 Display forum ledges]
 
* [https://github.com/p/phpbb3/commit/7e3cc2a333b4969f69622620cfd7b08ae595a219 Display forum ledges]
  
 
+
[[Category:Events and Listeners]]
Based on the blog article [http://blog.phpbb.com/2010/10/09/explaining-hooks/ Explaining Hooks]
+
[[Category:Ledges and Hooks]]
+

Revision as of 10:54, 17 March 2012

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.

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');
$event = new phpbb_event_data(compact($vars));
$phpbb_dispatcher->dispatch('identifer'$event);
extract($event->get_data_filtered($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 a ledge 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

This is very simple to do

<!-- RUNHOOKS identifier -->

Just replace the identifier with the name of the listenr by just using underscores, numbers and lowercase letters.

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

Core events List

If you add a events to the core you need to ensure you add it to the events list to ensure it remains a comprehensive and exhaustive list.

You can view and edit the events list page here

Examples of events being added