Many of you have been waiting for this blog post, and I can assure you we've been equally as anxious to get it out to you, but we wanted to ensure the bulk of the system was in place first before releasing anything we had to pull back on.
General Overview
First, as used in this blog entry, the definition of a "hook" is a point in the code execution where a modification author can tell IP.Board to execute his or her code, and then return to the primary code execution. A "plugin" is a collection of hooks (any given modification may need to "hook" into 2 or 3 files, for instance, but remain one modification - which we will call a plugin).
IP.Board 3, as promised, will introduce a new hooks and plugin system for modification developers to make use of. The system is relatively extensive without a lot of "hook points" manually inserted into the source files which ultimately requires a lot of maintenance and never-ending "can you add a hook point at xyz location" requests. We wanted to provide something out of the box that would scale, that would be easy to manage and maintain, and that would accomodate most modification needs without requiring modifications to the core source code. At the same time, during development of the new hooks system we determined that we did not want to simply shift the modification responsibilities to the skin system either. While it is arguably much easier to modify the skin system than a source file, shifting responsibilities entirely would not solve the issue we are working to tackle. The ultimate goal, of course, is to allow you to enhance your board without having to modify source files to do so. This makes upgrading easier, as you don't have to reapply your mods, makes support easier, as we can easily disable your hooks without having to sift through files looking for changes, and makes adding plugins easier, as you don't have to spend 30 minutes applying code changes from an instruction file to do so.
How the hooks and plugins work for end users
There is a hooks management page in the admin control panel where all of your installed hooks are listed. You can enable and disable hooks from this page, and reposition what order they are executed in (while this generally shouldn't matter, the capability exists in case a plugin needs to hook into another plugin, for instance). You can also view detailed information about the plugin that the author has provided (such as the author name, email address and website, and all files associated with the plugin), and check your system against the minimum/maximum PHP and IPB versions the hook supports. The hooks system supports an update check URL that the author can use to notifiy you if a hook is out of date.
To install a hook, you will simply upload an XML file from the ACP interface - that's it! The hooks system, similar to the popular Universal Mod Installer for earlier versions of IP.Board, supports running necessary database queries, importing settings, language bits, skin templates, modules, tasks, help files and admin CP help files. The hook installation routine even supports a custom script callback system in case the installation routine needs to do something we don't support out of the box. Similarly, when you uninstall a hook, all of the changes are automatically reverted, and the custom script can perform additional cleanup if needed.
It's as simple as that. Import an XML file and view changes on your site immediately.
How the hooks and plugins work at the system level
When hooks are imported in the ACP, they are cached to .php files in a /hooks folder. Only hooks that are registered in the admin CP are executed, to avoid wasting resources hunting down hooks that are not being used presently.
There are three types of hooks in IP.Board 3:
- Action overloaders
- Skin overloaders
- Template hooks
Action overloaders allow you to extend an action file, allowing you to do nearly anything you can imagine. An example of this might be to extend the board index source file, add your output to $this->output, and then call parent::doExecute() to allow IP.Board to finish loading the board index with your output prepended. Or, you may want to extend a source file so that when a form is submitted, you can store additional data in the database. Most properties and methods in IP.Board are set as protected, giving you full access to them from your extended class.
Skin overloaders work similar to action overloaders, except that you are extending a skin file. A good example of why you might want to do this might be to entirely change a template's contents if the user meets a certain criteria, or if you want to prepend or append HTML to a template without requiring the user to manually edit each of their skins.
Finally, template hooks provide an extremely powerful way to manipulate the HTML output, which is what most modifications are designed to do. Before and after each foreach loop, if statement, and else statement, HTML comments are inserted into the HTML output (automatically by our skin system, so as to avoid annoying our beloved skinners) with a very specific syntax. When you register your template hook in the ACP, you specify where in the skin you want to hook into. During display, if your hook is enabled, it is executed and the HTML comment is replaced with the output returned from your hook.
Overall, this provides methods for injecting your code into source code functionality and into the final output engine, covering most cases for modification authors.
We will be providing some examples with the releases of IP.Gallery, IP.Blog and IP.Downloads. I don't want to give away any details on these just yet, but some of the things users have been begging us to do that we've always said we can't as it would require modifications to IP.Board will now be possible, allowing for a much tighter integration between our applications than has ever been possible.
How the hooks and plugins work for developers
In the admin CP when you create a new plugin, you fill in some basic details such as author, plugin name, and website. You create the hook files and then on the form when creating a new plugin you configure which files are a part of the plugin (there is no limit to the number of files you can add to a single plugin). You would then develop your work as normal.
When you go to export the plugin, you can interactively configure settings, setting groups, language bits, skin templates, modules, help files, ACP help files, custom installer/uninstaller scripts, tasks, and database changes that you want to export with the hook. If you have used the universal mod installer in the past, this system is similar, with the main difference being that you interactively configure these details in the admin CP instead of through an XML file.
When you finally export the hook, your source code is collected (as well as the source code for the install/uninstall script) and included within the XML file. The hook import routine takes care of caching the code and importing all of the data you configured to export with the plugin.
Closing
Before starting on the system we wrote down 5 different popular modifications and requests that we've seen for a while to verify that once finished we would be able to accomplish each of these modifications without actually modifying the source code in IP.Board 3 - and we've passed this baseline test. We intend to release more details on the system's specifics for modification developers closer to the release of IP.Board 3 to help them learn the new system, as well as examples of how to accomplish various things without modifying the source code, through our official resource site.