phpBB

Development Wiki

Difference between revisions of "Add Events"

From phpBB Development Wiki

Line 5: Line 5:
 
You would add a ledge you would use this code:
 
You would add a ledge you would use this code:
 
<php>
 
<php>
$vars = array('arrayvariable');
+
global $phpbb_dispatcher
 +
 
 +
$vars = array('var1', 'var2');
 
$event = new phpbb_event_data(compact($vars));
 
$event = new phpbb_event_data(compact($vars));
 
$phpbb_dispatcher->dispatch('identifer', $event);
 
$phpbb_dispatcher->dispatch('identifer', $event);
 
extract($event->get_data_filtered($vars));
 
extract($event->get_data_filtered($vars));
 
</php>
 
</php>
Let's dissect that code<br />
+
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.
 
+
== Dissection ==
+
<pre class="narrow-codebox"> <nowiki>global $phpbb_dispatcher</nowiki></pre>
+
When its in a function this will need adding beforehand:
+
<br /><br />
+
  
<pre class="codebox"> <nowiki>$vars = array('arrayvariable');</nowiki></pre>
+
You only need to register the global if you are inside a function.
This just defines the variable vars as the variable for the array.
+
<br /><br />
+
  
<pre class="codebox"> <nowiki>$event = new phpbb_event_data(compact($vars));</nowiki></pre>
+
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.
This won't need any changes and is beyond the scope of this article.
+
<br /><br />
+
  
<pre class="codebox"> <nowiki>$phpbb_dispatcher->dispatch('identifier', $event);</nowiki></pre>
+
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.
This just sets the identifier name (see below) and input parameter which is event as per the previous line.
+
The identifer is the name for the hook. If its in the core it should be prefixed by `core.` but if its in an extension you should prefix it with a unique string related to your extension to prevent clashes with other extensions.
+
<br /><br />
+
  
<pre class="codebox"> <nowiki>extract($event->get_data_filtered($vars));</nowiki></pre>
+
And now you've made a ledge and just need to document it as below.
This gets the data from the hook. This won't need changing.
+
<br /><br />
+
  
 
==Core Ledges List==
 
==Core Ledges List==

Revision as of 08:44, 13 March 2012

What are ledges?

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.

How to add a ledge

You would add a ledge 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 hooks. Then it extracts the variables back, therefore allowing hooks to modify them. It is the magic incantation for adding ledges.

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.

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.

And now you've made a ledge and just need to document it as below.

Core Ledges List

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.

You can view and edit the ledges list page here

Examples of ledges being added


Based on the blog article Explaining Hooks