IP.Board 3.1.0 Dev Update: Hook System

[Josh]

In IP.Board 3, we introduced the hook system, the goal of which was to cut down on file edits from modifications and make modifications easier to install. We designed the system to be as flexible as possible, primarily using the HTML logic feature to create hooks in virtually every portion of the output generated. However, we knew there were still cases where a file edit was needed, to access certain data or to reach any area of the board that was not a template or an action file.

One of our primary goals with IP.Board 3.1, is to expand the hook system to further reduce the need for file edits, as well as to make installing them even easier. We've read all the feedback on hooks from modification authors and are incorporating as much of it as possible into 3.1. Here's a quick rundown of the changes that we have mode so far:

New Hook Types

Our first goal was to extend the hook system to cover areas of the forum that are not currently accessible to hooks. Toward that end, we are introducing two new hook file types to address this issue:

Data Hooks

Modifications often need access to add their own data to insert/update queries that are run by IPB, at the moment that data is not accessible and must be queried separately and then hook has to run another insert/update query. To address this issue, we have added a new hook file type called a Data Hook. This type of hook allows you to access certain data arrays before they are inserted into the database. For example, you can create a hook that will receive the $post array before it is inserted into the posts table, this will give your hook a chance to add any data it needs or modify any data being saved. Technically, a Data Hook does not even have to modify the actual data array, you can use them as a simple code execution point as well.

Unlike Template Hooks, which are essentially generated automatically, Data hooks are manually specified in the code, so if you have suggestions on where you would like to see these placed, please reply to this blog post and let us know. At the moment, data hooks are used in the posting library, the messenger library, and some areas of the profile screen.

Library Hooks

There are many classes used within IPB that are inaccessible to hooks, as they are not actions or templates. However, it is often useful to be able to modify these classes with your own methods or to add on to existing methods. This leads to the second type of hook file that we are adding in 3.1, the Library Hook. This type of hook will allow you to extend the libraries that we use throughout IPB, a common example would be class_forums. This works in exactly the same way as an action overloader, your hook will extend the library you have selected and allow you to add to it or replace method calls with your own. Like the action overloaders, you will need to remember to call the parent method from your overloaded method.

In order for a library hook to work, we have to update the require call that includes that library. We're going through the code to try and find as many of these require calls as possible, but during beta you should check any includes that you are interested in extending to make sure we haven't missed them.

Other Changes

Hooks in AJAX requests

In the current release, any output returned via AJAX is not passed through the hook system. This has been changed in 3.1, now all returned output is properly run through the hooks system, allowing you to hook into any AJAX generated output.

Export CSS Files

There is a new option when exporting a hook that will allow you to specify CSS files that is used by that hook. The CSS files will be included in the hook xml and then imported along with the hook and cached to the file system.

Access Function Data

One of the most frequent requests we've seen is for a way to access template function data, with IP.Board 3.1 this will now be possible. Any active hooks within a template function will be able to access the function data through a special class property called functionData. To save resources, this data is not saved for any template function that does not contain active hooks. Here's an example of how to access function data inside of the topicViewTemplate function:

Function Declaration:

function topicViewTemplate($forum, $topic, $post_data, $displayData) {

All of this data will be accessible to your hook via $functionData:

$this->registry->output->getTemplate('topic')->functionData['topicViewTemplate']['forum']

$this->registry->output->getTemplate('topic')->functionData['topicViewTemplate']['topic']

Wrapping up

We've also made quite a few minor tweaks throughout the hook system, these changes include updates to the ACP interface, performance enhancements, a toggle to quickly disable/enable all hooks, changing hook positions without IN_DEV enabled, and more. If you have any suggestions regarding these changes or the existing hook system, please do not hesitate to reply to this entry and let us know about them. We're very excited to see what our community will do with these new features!

View full blog entry