Secret Sauce

Hello. My name is Maurice.
I am addicted to Phorum programming.
“Hi Maurice!”.

Finally, as the last one of the Phorum core development team (you can now stop pointing at me and calling me names like “troglodyte” and “cavemen” guys), I started a blog. This is where I will be blogging about my Phorum addiction and about my attempts to stay addicted as much as possible.

I am a huge fan of the Phorum module system and have built many modules that make use of it already. So one of the things that I want to talk about here, is the way in which I solved certain module writing issues, to make other module writers benefit from it. Also, if you are a module writer that is running into troubles with implementing a certain feature as a module, then please drop me a line and explain your problem to me. If your problem is a general module design issue, then I will be most happy to write an article about it to help you out.

Secret sauce?

So what is “Secret Sauce”? Well, it’s a concept that I picked up last year when the Phorum team was able to meet up at the MySQL conference in the U.S. One night we went out to grab a bite and I was totally stuck at choosing something to eat from the menu. Just when I was prepared to order anything at random, my eyes were drawn towards two words that seemed to be highlighted by some devine glow: SECRET SAUCE. For no other reason than me liking the idea of secret sauce, I ordered the sandwich that went with it and later on adopted the name for referring to my Phorum development activities.

Making life easier for module writers

Phorum 5.1.16 has just been released. In this new version, a couple of simple enhancements were implemented to facilitate module writing. Most of the changes were made to allow for writing more self-contained modules that do not need manual intervention at installation/upgrade time for moving script and template files to the right locations within the Phorum directory.

In this post I will explain the new features that can be used.

Templates that are stored within the module directory

It’s now possible to easily access the Phorum template system from within your modules. Before, using your own templates could only be done by manually copying the required template files to the appropriate Phorum templates directories. This is no longer needed. Storing and using templates can now be fully contained in a module.

To use this new feature, you have to create a templates directory in your module’s directory, which uses the same template structure as Phorum’s main templates directory. If you write a module named “foo”, which needs a template called “bar.tpl”, then you can store this in the file:

./mods/foo/templates/default/bar.tpl

If you have a main Phorum template named “yourtemplate”, for which you need a modified “bar.tpl”, you can put the modified template in:

./mods/foo/templates/yourtemplate/bar.tpl

If a module template is requested, Phorum will automatically check if there is a template file available for the active template. If there is none, then the template file in templates/default will be used. This is a huge improvement over copying the template files to Phorum’s templates dirctory, because now you do not have to copy the file to each template directory that is in use.

After you have created the templates that are used by your module, you can access them by prefixing the template name by “<module name>::”. So for the example template from above, you could use the following methods to access the template:

Loading the template from (a module’s) PHP code:
$template = phorum_get_template(“foo::bar”);
print $template;

Including the template from another template file:
{INCLUDE foo::bar}

Addon scripts that can be contained in a module

Addon scripts are scripts that implement functionality that cannot be implemented through hooking into the standard module hook system. Mostly, these are scripts that implement totally new functionlity instead of tweaking exiting functionality.

A special script was added to the Phorum release, to make it possible to write scripts that act as addon scripts, but which are implemented through a module. The big advantage of doing this is that installing and maintaining becomes much easier for admins that are using your addon. Installing and upgrading will no longer include moving files to the right directories in Phorum. Instead, installing becomes as easy as installing and activating a standard module.

For information on how to use the new addon.php script for your addon, please read the addon.php script itself. In that file I documented the use of this script.

Better module support for the posting editor

The hook “posting_custom_action” was added to the editor code. This hook is at a convenient place for doing all kinds of processing in the message editing process. If you need to handle custom fields that were added to the editor, then this is the hook to use for processing them. Also, if you want to change meta data for a message, then this is the designated hook for doing that.

Which template the editor code shows, is now determined by the variable $PHORUM["posting_template"]. This allows for using your own templates for separate posting screens.

I wrote a new poll module from scratch, as a showcase for the new features in the posting editor code and the use of module templates. This module implements the poll editor as a fully separate screen in the posting process. Check out the code of the Topic Poll Module for an example of how to use the new possibilities.

Future changes

Phorum module writing is still in development and module authors will probably hit some (possibly brick) walls now and then. Those authors are invited to tell us what those walls are, so we can see if adjustments are needed to make Phorum more module friendy. Some things that I have already been thinking about are:

- better documentation (will be done for Phorum 5.2);
- a system for scheduling hook priorities (e.g. to always run the bbcode hook as the last hook). A beta system for this is already implemented in the Phorum 5.2 development tree;
- a library containing functions for recurring module tasks;
- more information in the module’s info.txt (like module version and compatibility).

More ideas for module writing improvements are welcome at all time.