New file |
0,0 → 1,1869 |
Creating Modules for Phorum5 |
============================ |
|
This document describes the Phorum5 module system. It is targeted at |
developers who want to do customization and extend the functionality |
of Phorum5. Modules are the preferred way to archieve this in |
Phorum5. |
|
For much of this document, we will be talking about an example module |
"foo". Of course you will not name your module "foo", but something much |
more appropriate. If you're not familiar with the terms "foo" and "bar", |
you can visit http://en.wikipedia.org/wiki/Metasyntactic_variable |
|
Be sure to read at least the **CAUTIONS AND SECURITY ISSUES** section, |
before making your own modules. |
|
|
Table of contents: |
|
1. Introduction |
1.1 Modules |
1.2 Hacks |
1.3 Hooks |
2. Creating your own modules |
2.1 What modules are built of |
2.1.1 Hook functions |
2.1.2 Module information |
2.1.3 Other "stuff" |
2.2 Module structure |
2.2.1 Single file modules |
2.2.2 Multiple file modules |
2.3 Supporting multiple languages |
2.4 Storing message data |
2.4.1 From hooks that are run before saving a message to the database |
2.4.2 From other hooks |
2.5 Storing user data |
2.6 Creating custom URLs |
2.7 Implementing settings for your module |
2.8 Changing the template |
2.9 Example modules |
3. **CAUTIONS AND SECURITY ISSUES** |
3.1 Make modules, not hacks |
3.2 Reload your module if you change the module information |
3.3 How to access the $PHORUM array from your hook functions |
3.4 How to access additional files in your multi file module |
3.5 Secure your PHP files agains hackers |
3.6 Secure your pages from XSS |
3.7 Prevent namespace collisions |
3.7.1 (Hook) functions |
3.7.2 Data stored in $PHORUM |
3.7.3 Language strings stored in $PHORUM |
3.7.4 Data stored in messages, users and settings |
4. Overview of available Phorum hooks |
4.1 Code hooks |
4.2 Template hooks |
5. Support |
|
|
1. Introduction |
------------------------------------------------------------------------------- |
|
|
1.1 Modules |
----------- |
|
Modules are self contained pieces of software, that can be added to |
Phorum to change or extend its functionality. Modules can do this |
without having to change anything in the standard Phorum distribution |
files or database structure. So installing a module means: drop in |
the code, go to the admin "Modules" page, enable the module and it |
works. |
|
|
1.2 Hacks |
--------- |
|
The moment it is neccessary to make changes to the standard Phorum |
distribution files or database structure to implement some kind of |
functionality, we're talking about a hack (even if the changes |
that have to be made are accompanied by a drop in module). |
|
Although there is nothing wrong with writing hacks, the Phorum team |
wants to urge you to try if you can write a module before resorting |
to a hack. Modules are the preferred way of modifying Phorum |
functionality, because that will make both upgrading your distribution |
and having your modification adopted by others easier. |
|
|
1.3 Hooks |
--------- |
|
Phorum uses hooks to run its modules. Hooks are points in the |
application where Phorum stops and runs its data through the modules |
that are configured to handle the hook. The modules can act upon and |
change this data. |
|
The following image visualizes what happens when Phorum reaches |
a hook point in the application, for which two modules ("foo" and |
"bar") have been configured. |
|
|
Phorum |
Application |
(1) (1) Phorum is running. |
| (2) Phorum reaches the |
| hook named "some_hook". |
v Phorum (3) Phorum sends data to |
some_hook >----- data ------+ the module system. |
(2) (3) | (4) The module "foo" is run. |
v (5) The module "bar" is run. |
(4) module "foo" (6) The Phorum data (which |
| might be modified by the |
v modules) is sent back |
(5) module "bar" to Phorum. |
| (7) Phorum continues running |
Phorum Modified | with the modified data. |
Application <---- data ------+ |
(7) (6) |
| |
| |
v |
|
|
2. Creating your own modules |
------------------------------------------------------------------------------- |
|
|
2.1 What modules are built of |
----------------------------- |
|
|
2.1.1 Hook functions |
-------------------- |
|
A module contains one or more PHP functions that act as hook |
functions. Hook functions will receive some data in a variable |
from Phorum and have to return the (possibly modified) data, which |
will then go either back to Phorum or to the input of another module |
which also handles the same hook (see 1.3). So the most basic (and |
useless :-) hook function you could write would look somewhat like this |
(see 3.7 for an explanation of the naming of the function): |
|
function phorum_mod_foo_some_hook ($data) { |
return $data; |
} |
|
The exact nature of the data that is sent to the hook functions |
depends solely on the hook that is run. In chapter 4 of this document |
you will find a description of all supported hooks, including a |
specification of the type of data that is sent. |
|
|
2.1.2 Module information |
------------------------ |
|
For each hook that you want to handle in your module, you will have |
to point the module system to the function in your module that will |
handle the hook. Together with some other information, used for |
describing the module, this is stored in the module information. |
The module information acts as the glue between Phorum and your |
module. |
|
Module information is formatted using lines of plain text. Each line |
contains a bit of information about the module. The general format |
of the lines in the module information is: |
|
<type>: <data> |
|
Here is a list of the types that can be used: |
|
+--------+-----------------------------------------------------------+ |
| <type> | <data> | |
+--------+-----------------------------------------------------------+ |
| title | This is the title for the module that is displayed in the | |
| | "Modules" page of the admin interface. | |
+--------+-----------------------------------------------------------+ |
| desc | This is the description that is displayed along with the | |
| | title in the admin interface, to give a little more | |
| | information about the module. Using HTML in the <data> | |
| | part is allowed. | |
+--------+-----------------------------------------------------------+ |
| hook | This describes which hook functions are called for which | |
| | Phorum hooks. The data consists of two fields, separated | |
| | by a pipe "|" symbol. The first field contains the name | |
| | of the hook that this module is hooking into. The second | |
| | field contains the name of the hook function that will be | |
| | called for the hook. | |
+--------+-----------------------------------------------------------+ |
|
It is allowed to use multiple hook lines in your module information, |
so your module can hook into multiple hooks. When doing this, it |
is also allowed to use the same hook function for handling different |
hooks in your module (asuming the hooks are compatible). |
|
Here's an example of what the module information for our example |
module "foo" might look like: |
|
title: Foo example module |
desc: This is the Foo module for Phorum. Nothing exciting... |
hook: some_hook|phorum_mod_foo_some_hook |
hook: some_other_hook|phorum_mod_foo_some_other_hook |
hook: yet_another_hook|phorum_mod_foo_some_other_hook |
|
So what this module info for example does, is telling Phorum that |
when it gets to "some_other_hook", it will have to call the function |
phorum_mod_foo_some_other_hook() in your module. It also tells |
that for "yet_another_hook" the same function has to be called. |
|
|
2.1.3 Other "stuff" |
------------------- |
|
Hook functions and the module information are all the parts needed |
for creating a working module. However, your module might need |
extra stuff like template, language and image files. You can |
store these files along with your module when using the multiple |
file module structure (see 2.2.2 below). |
|
If you do not need to store any other stuff with your module, you |
can also choose to use the single file (see 2.2.1 below) module |
structure. |
|
|
2.2 Module structure |
-------------------- |
|
|
2.2.1 Single file modules |
------------------------- |
|
Single file modules are useful in case case no additional files have |
to be distributed with your module. Because the module consist of |
only one single file, it is very easy to distribute. Beware that the |
moment you want to support for example a settings screen, multiple |
languages or custom images, you will have to switch to the multiple |
file module structure. |
|
Single file modules consist of one single PHP file, which contains |
both the module information and the hook functions. For storing the |
module informaton, a special PHP comment is used. This comment must |
look like the following: |
|
/* phorum module info |
<module information lines go here> |
*/ |
|
Using the example module info from 2.1.2, the complete single |
file module would look like this (see 3.5 why we use the |
check on PHORUM at the start of this file): |
|
<?php |
|
if(!defined("PHORUM")) return; |
|
/* phorum module info |
title: Foo example module |
desc: This is the Foo module for Phorum. Nothing exciting... |
hook: some_hook|phorum_mod_foo_some_hook |
hook: some_other_hook|phorum_mod_foo_some_other_hook |
hook: yet_another_hook|phorum_mod_foo_some_other_hook |
*/ |
|
function phorum_mod_foo_some_hook ($data) { |
// Do stuff for "some_hook". |
return $data; |
} |
|
function phorum_mod_foo_some_other_hook ($data) { |
// Do stuff for "some_other_hook" and "yet_another_hook". |
return $data; |
} |
|
?> |
|
Installation of a single file module is done by putting the PHP |
file (e.g. foo.php) directly in the directory {phorum dir}/mods/ |
and activating the module from the "Modules" screen in your |
admin interface. |
|
|
2.2.2 Multiple file modules |
--------------------------- |
|
Multiple file modules are useful in case you need additional files |
to be stored with your module, for example a settings screen, |
language files or custom images. |
|
Multiple file modules are stored in their own subdirectory below |
the directory {phorum dir}/mods/. So if you have a module named |
"foo", you will have to create a directory {phorum dir}/mods/foo/ for |
storing all module files. |
|
Inside this subdirectory, you will have to create a least two files. |
The first is a file called "info.txt". This file contains the |
module information for your module (see 2.1.2). The second file |
is the PHP file which contains the hook functions for your module. |
The basename of this file should be the same as the name of the |
module subdirectory. So for our example module "foo", you will have |
to create a file named "foo.php". |
|
Using the example module info from 2.1.2, the complete multiple |
file module would look like this (see 3.5 why we use the |
check on PHORUM at the start of the PHP file): |
|
info.txt: |
|
title: Foo example module |
desc: This is the Foo module for Phorum. Nothing exciting... |
hook: some_hook|phorum_mod_foo_some_hook |
hook: some_other_hook|phorum_mod_foo_some_other_hook |
hook: yet_another_hook|phorum_mod_foo_some_other_hook |
|
foo.php: |
|
<?php |
|
if(!defined("PHORUM")) return; |
|
function phorum_mod_foo_some_hook ($data) { |
// Do stuff for "some_hook". |
return $data; |
} |
|
function phorum_mod_foo_some_other_hook ($data) { |
// Do stuff for "some_other_hook" and "yet_another_hook". |
return $data; |
} |
|
?> |
|
So far, the module has exactly same functionality as the single |
file module from 2.2.1. From here on, the functionality can be |
extended. Some of the possibilities are: |
|
- Using custom files for your module (images, classes, libs, etc.); |
- Letting your module support multiple languages; |
- Creating a settings screen for your module; |
|
|
2.3 Supporting multiple languages |
--------------------------------- |
|
(this feature is only available for the multiple file module structure) |
|
If your module includes text that will be displayed to end users, |
you should strongly consider making it support multiple languages. |
This will allow Phorum installations using another language to display |
output of your module in the same language, instead of the language |
you have written the module in. |
|
For supporting multiple languages, the first thing to do is add the |
following to your module information file (info.txt): |
|
hook: lang| |
|
There is no hook function configured here, because the "lang" hook |
is only used as a marker for Phorum. This only tells Phorum that your |
module supports multiple languages. |
|
Next, you must provide at least one language file with your module. |
Language files are stored in a subdirectory name "lang" inside your |
module directory. So in our sample module, the full directory would be |
{phorum dir}/foo/lang/. The language files must be named identical |
to the main language files that Phorum uses. So, to include both |
English and French, your module would have the following file |
structure below the Phorum's mods directory: |
|
foo/info.txt |
foo/foo.php |
foo/lang/english.php |
foo/lang/french.php |
|
The structure of your language files will be almost identical to that |
of the main Phorum language files. However, for your own language files |
it is advisable to add an extra level in the language variables, to |
avoid conflicts with other modules or Phorum itself. Here is an |
example of how you would do that: |
|
<?php |
$PHORUM["DATA"]["LANG"]["mod_foo"]["Hello"] = "Hello!"; |
?> |
|
Here, the extra inserted level is ["mod_foo"]. You can add as many |
lines as you need for your module. To access the above language string, |
from your module code you would use: |
|
$PHORUM["DATA"]["LANG"]["mod_foo"]["Hello"] |
|
From a template file, you would use: |
|
{LANG->mod_foo->Hello} |
|
In case a Phorum installation is using a language that your module |
does not support, Phorum will automatically attempt to fallback to |
English. So it is highly recommend that you include an english.php |
language file in all your modules. If both the current language and |
english.php are not found, Phorum will be unable to load a language |
for your module and will display empty space instead of language |
strings. |
|
Try to reuse strings that are already in the main Phorum language |
files itself. Only create custom strings when there is no alternative |
available. Having more text to translate is more work for everybody, |
especially the Phorum translators. |
|
|
2.4 Storing message data |
------------------------ |
|
If your module needs to store data along with a Phorum message, |
you can make use of the meta information array that is attached |
to each message ($message["meta"]). This array is a regular PHP |
array, which is stored in the database as serialized data |
(see http://www.php.net/serialize). Because Phorum and other modules |
make use of this meta data as well, you should not squash it, |
neither access the meta data in the database directly. Instead |
use the methods described in this section. |
|
Remark: because the meta data is stored as serialized data in the |
database, it is not possible to include data you store in there |
in SQL queries. |
|
When storing information in the meta data from a hook function, you |
can encounter two different situations, which both need a different |
way of handling. |
|
|
2.4.1 From hooks that are run before saving a message to the database |
--------------------------------------------------------------------- |
|
There are some hooks that send a full message structure to the |
hook functions, so these can change the message data before storing |
the message in the database. Examples are the hooks "pre_post" |
and "pre_edit". In this case you can simply update the meta |
information directly. Here's an example of how this would look |
in your hook function: |
|
function phorum_mod_foo_pre_post ($message) { |
$message["meta"]["mod_foo"]["foodata"] = "Some data"; |
$message["meta"]["mod_foo"]["bardata"] = "Some more data"; |
return $message; |
} |
|
Phorum will take care of storing the updated meta data in the database. |
|
|
2.4.2 From other hooks |
---------------------- |
|
For other hooks, the proper way to store information in the meta |
data is to retrieve the current meta data using phorum_db_get_message(), |
copy the meta data to a new message structure, make changes as needed |
and use phorum_db_update_message() to update the message in the |
database. Here is an example of how this could look in your hook |
function: |
|
function phorum_mod_foo_some_hook ($data) { |
|
// Somehow you get the id for the message. Here we asume |
// that it is stored in the $data parameter. |
$message_id = $data["message_id"]; |
|
// Retrieve the current message data. |
$message = phorum_db_get_message ($message_id); |
|
// Create updated meta data. |
$new_message = array("meta" => $message["meta"]); |
$new_message["meta"]["mod_foo"]["foodata"] = "Some data"; |
$new_message["meta"]["mod_foo"]["bardata"] = "Some more data"; |
|
// Store the updated data in the database. |
phorum_db_update_message($message_id, $new_message); |
|
return $data; |
} |
|
Changing meta data for a message this way will ensure that the |
existing meta data is kept intact. |
|
|
2.5 Storing user data |
--------------------- |
|
If your module needs to store data along with a Phorum user, |
you can make use of custom profile fields. In the admin interface, |
under "Custom Profiles", you can add your own profile fields |
(see also docs/creating_custom_userfields.txt). |
|
The custom profile fields will be accessible from within the user |
data. E.g. if you have created a custom profile field named "foobar", |
the value of that field will be stored in $user["foobar"]. |
|
When using a custom profile field for storing module information, |
you can use a separate field for each piece of data you want to |
store. But instead, you can also create a single field for storing |
a complete array of information. Phorum will automatically take care |
of storing this information (serialized) in the database. You only |
should make sure that the custom profile field is large enough to |
store all the data. When your module needs to store multiple fields, |
this is the preferred way. |
|
For storing data in the custom profile field, you can make use of the |
phorum_user_save() function. Below are two pieces of code which show |
how our example module might store data for a user (asuming $user_id |
is the id of the user that must be changed). |
|
When using multiple fields "mod_foo_foodata" and "mod_foo_bardata": |
|
$user = phorum_user_get($user_id); |
$user["mod_foo_foodata"] = "Some user data"; |
$user["mod_foo_bardata"] = "Some more user data"; |
phorum_user_save($user); |
|
When using a single custom field "mod_foo" for this module: |
|
$user = phorum_user_get($user_id); |
$user["mod_foo"] = array ( |
"foodata" => "Some user data", |
"bardata" => "Some more user data" |
); |
phorum_user_save($user); |
|
|
2.6 Creating custom URLs |
------------------------- |
|
Phorum uses the function phorum_get_url() to consistenly build URLs |
that point to parts of Phorum. It is recommended that you use this |
function as well when creating links yourself, so special features |
and future changes will automatically be incorporated in the links |
you use. |
|
Here's an example of building an URL, which will open the profile |
for the user with user_id = 17: |
|
$url = phorum_get_url(PHORUM_PROFILE_URL, 17); |
|
The argument list that this function takes, depends on the first |
argument which tells Phorum what kind of URL has to be built. |
So when building other URLs, other arguments will probably |
be used. |
|
If you need to build a custom URL to link to your own module, you |
can use phorum_get_url() as well. The way to go is simple. You |
need to use PHORUM_CUSTOM_URL as the first argument and add all |
URL building parameters to it. |
|
The first parameter needs to be the filename of the file to link |
to, without the (.php) extension. The second parameter needs to |
be 0 or 1. If it is 1, the current forum_id is added to the URL. |
All other parameters are added comma separated to the URL. |
|
Here's an example of building a custom URL which links to the |
file "myfile.php". The URL has to have the forum_id in it and |
needs to contain the additional parameter "foo=bar": |
|
$url = phorum_get_url(PHORUM_CUSTOM_URL, "myfile", 1, "foo=bar"); |
|
|
2.7 Implementing settings for your module |
----------------------------------------- |
|
(this feature is only available for the multiple file module structure) |
|
Some modules that you write might need to store settings for later |
use. For those, you can create a settings page which will be used |
from within the admin interface. |
|
The settings page must be put in your modules's directory by the |
name of "settings.php". So for our example module "foo" the file |
would go in {phorum dir}/mods/foo/settings.php. In the admin |
interface under the option "Modules", a link to the settings.php |
page will automatically be added if the settings.php file is |
available for your module. |
|
Although you can do anything you want from your settings.php script, |
it is recommended that you use the tools that are handed to you |
by Phorum for building pages and storing settings. |
|
One of those tools is a PHP object "PhorumInputForm" which |
can be used to create standard input forms and table displays in |
the admin interface. The best example here is to look at one of the |
modules that come with Phorum like "bbcode" or "replace". |
|
Another tool is the function phorum_db_update_settings() which can |
be used for storing settings in the database. To store settings using |
this function you do something like the following: |
|
$foo_settings["foodata"] = "Some setting data"; |
$foo_settings["bardata"] = "Some more setting data"; |
phorum_db_update_settings(array("mod_foo" => $foo_settings)); |
|
$foo_settings can be anything you like: an array, object, string, etc. |
The first request after you have stored your settings, the setting |
data for this example will be available in $PHORUM["mod_foo"]. |
|
To ensure that your settings file is only loaded from the admin |
interface, place this line at the top of your settings.php file |
(see also 3.5): |
|
if(!defined("PHORUM_ADMIN")) return; |
|
|
2.8 Changing the templates using template hooks |
----------------------------------------------- |
|
|
2.8.1 When to use a template hook |
--------------------------------- |
|
Changing the templates should be avoided as much as possible when |
writing a module. This will basically turn your mod into a hack, |
because files have to be edited for it. Inexperienced users might |
find it hard to install your module if they have to modify files |
to get it to work. |
|
If you cannot avoid changing the template, then consider to use |
template hooks for this. You can use these if your template change |
involves adding extra code to a template. The advantage is that |
there's only little code that has to be added to the templates, |
which makes things less confusing to users that want to install the |
module. |
|
|
2.8.2 How to use a template hook |
-------------------------------- |
|
To create a template hook, you do the following: |
|
* Add "{HOOK tpl_some_hook}" to the template at an appropriate spot; |
|
* Put "hook: tpl_some_hook|phorum_mod_foo_tpl_some_hook" in your |
module info; |
|
* Create the hook function phorum_mod_foo_tpl_some_hook() that |
prints out the code that has to be placed at the position of |
the "{HOOK tpl_some_hook}" code the the template. |
|
If you want to pass on the data from template variables to |
the hook function, you can simply add the variables to the hook |
definition in the template. Example: |
|
{HOOK tpl_some_hook DATA1 DATA2} |
|
The hook function will get the contents of these variables passed in |
a single array. This can for example be useful if your template hook |
needs access to loop data. Example: |
|
{LOOP MESSAGES} |
... |
{HOOK tpl_some_hook MESSAGES} |
... |
{/LOOP MESSAGES} |
|
|
2.8.3 Preventing collisions in hook names |
----------------------------------------- |
|
You can use any name for "tpl_some_hook", but beware that your |
name does not collide with an already existing hook name. |
|
The easiest way to do this is use the techniques from section 3.7. |
As a rule of thumb, you can use the following format: |
|
tpl_mod_<modulename>_<identifier> |
|
Example: If a buttonbar is added in one of the templates for a module |
named "foo", the name for the hook could be "tpl_mod_foo_buttonbar". |
|
|
2.9 Example modules |
------------------- |
|
The best way of learning how to write modules is probably looking |
at existing module code. In your Phorum distribution's docs directory, |
you will find the directory example_mods. This directory contains a |
couple of example modules, demonstrating the features described in this |
document. The modules have no real functional purpose, but they might |
be easier to read than the real Phorum modules. |
|
|
3. **CAUTIONS AND SECURITY ISSUES** |
------------------------------------------------------------------------------- |
|
|
3.1 Make modules, not hacks |
--------------------------- |
|
Making modules that require database changes are discouraged and may |
not be accepted as an approved module. We want modules to be as |
transparent as possible for upgrades. Please attempt to store your |
data in the proper place. See chapter 2 for more information on that. |
|
|
3.2 Reload your module if you change the module information |
----------------------------------------------------------- |
|
If you are changing the module info for a module that is already |
activated in your Phorum installation, you must deactivate and |
reactivate it to have Phorum reload the changed information. For |
performance reasons the module information is only read when the |
module is activated. |
|
If you have added a new hook function to your module and it seems |
not to be run, it probably is because you did not do this. |
|
|
3.3 How to access the $PHORUM array from your hook functions |
------------------------------------------------------------ |
|
The $PHORUM array is in the global scope. From inside a function, |
you can not directly access this array. So you will have to import |
the $PHORUM array into your function scope. The Phorum team |
recommends the following method for doing this (check out the |
faq.txt to see why we do not use the "global" keyword): |
|
function phorum_mod_foo_some_hook ($data) { |
$PHORUM = $GLOBALS["PHORUM"]; |
|
// Do stuff for "some_hook". |
|
return $data; |
} |
|
|
3.4 How to access additional files in your multi file module |
------------------------------------------------------------ |
|
All standard Phorum pages are run from the Phorum installation |
directory. The hook functions that you write also work from |
the same directory. So if you want to access files in your module |
directory, you will have to specify the relative path to those |
files. This path looks like: |
|
./mods/<module>/<filename> |
|
So let's say that our module "foo" has a subdirectory "images" |
which contains "bar.gif", then we could display that image |
using the HTML code: |
|
<img src="./mods/foo/images/bar.gif" /> |
|
Another example: let's say that there is a function library |
named "my_module_functions.php" in the module, which must be |
included from then module code, then this is done using: |
|
include("./mods/foo/my_module_functions.php"); |
|
|
3.5 Secure your PHP files agains hackers |
---------------------------------------- |
|
To prevent hackers from loading your PHP module files directly, you |
should add the following to the start of your PHP files: |
|
if(!defined("PHORUM")) return; |
|
This will make sure that the file will only work when loaded from |
the Phorum application. If you are writing pages that are loaded |
from the admin interface (like a settings screen for your module), |
then use the following line instead: |
|
if(!defined("PHORUM_ADMIN")) return; |
|
This will make sure that the file will only work when loaded from |
the Phorum admin interface. |
|
|
3.6 Secure your pages from XSS |
------------------------------ |
|
XSS stands for cross site scripting. This means that hackers |
can feed HTML data to your application, which is displayed on |
screen without stripping or escaping the HTML data. This way |
it can be possible for hackers to feed malicous javascript |
code into the browser of users on the forum, causing a security |
risk. If you want to learn more about XSS, please visit |
http://en.wikipedia.org/wiki/XSS |
|
To prevent XSS security holes, you must take care that all |
user input is properly sanitized before displaying it on screen. |
Sanitizing can be done by either stripping all HTML from |
the data (e.g. using http://www.php.net/strip_tags) or by escaping |
all html characters (using http://www.php.net/htmlspecialchars). |
|
Example: |
|
If your module needs to display the username for a user on |
screen, it must not simply do: |
|
print $user["username"]; |
|
Instead you must use: |
|
print htmlspecialchars($user["username"]); |
|
It's not only for security that you have to sanitize data before |
displaying it. You must use htmlspecialchars() to prevent some other |
possible problems as well. Imagine you have a user with the username |
"<b>ob". Without htmlspecialchars() the username would be interpreted |
as HTML code, possibly making the full page bold from the username on. |
|
|
3.7 Prevent namespace collisions |
-------------------------------- |
|
When creating modules, you must always be aware that you are |
working in the same namespace as other modules and Phorum itself. |
This means that there is a risk of duplicate use of function |
and variable names. By following a couple of simple rules, you |
can greatly reduce this risk. |
|
|
3.7.1 (Hook) functions |
---------------------- |
|
Always construct names for your module functions like this: |
|
phorum_mod_<module name>_<identifier> |
|
So if you are writing functions for a module named "foo", all |
function names will look like: |
|
phorum_mod_foo_<identifier> |
|
You can use whatever you like for the <identifier> part. When writing |
a hook function, it is recommended to use the name of the hook for |
which you are writing the function (this will make clear what the |
function does, without having to check the module info). So in case |
you are writing a hook function for the hook "some_hook", the full |
function name would be: |
|
phorum_mod_foo_some_hook |
|
If your hook function handles multiple hooks at once, then |
simply use one of the hook's names as the <identifier> or make up |
something yourself. |
|
|
3.7.2 Data stored in $PHORUM |
---------------------------- |
|
When storing data in $PHORUM, always prepend the array key name |
with mod_<module name>. If your module is named "foo", do not use: |
|
$PHORUM["mydata"] |
|
but instead: |
|
$PHORUM["mod_foo_mydata"] |
|
|
3.7.3 Language strings stored in $PHORUM |
---------------------------------------- |
|
When storing your custom language strings, do not put them directly |
in $PHORUM["DATA"]["LANG"] like Phorum does, because that might |
result in conflicting language strings. Instead add an extra data level, |
which makes sure that your module keeps all language strings to itself. |
|
If your module is named "foo", you should store language strings in: |
|
$PHORUM["DATA"]["LANG"]["mod_foo"] |
|
See also section 2.3. |
|
|
3.7.4 Data stored in messages, users and settings |
------------------------------------------------- |
|
When using the Phorum provided ways of storing data in messages, |
users and settings, always prepend the data key with |
mod_<module name>. SO if your module is named "foo", do not use |
things like: |
|
$new_message["meta"]["foodata"] = "Some data"; |
$user["foodata"] = "Some data"; |
phorum_db_update_settings(array("settings" => $foo_settings)); |
|
but instead: |
|
$new_message["meta"]["mod_foo_foodata"] = "Some data"; |
$user["mod_foo_foodata"] = "Some data"; |
phorum_db_update_settings(array("mod_foo" => $foo_settings)); |
|
See also sections 2.4 (message data), 2.5 (user data) and 2.7 (settings). |
|
|
4. Overview of available Phorum hooks |
------------------------------------------------------------------------------- |
|
In this chapter you will find an overview of all available Phorum |
hooks and a description of what they do. |
|
Remarks: |
|
* Input is what your module function should expect as parameters. |
|
* Return is what your module function should return. Most hooks |
expect the same data structure as was sent. For those items, |
the Return is listed simply as "Same as Input". |
|
* Normally, hook functions are allowed to modify the data that was |
sent as input. If this is not allowed, the input data will be |
flagged as read-only. |
|
* In most cases the hook description will provide only one or more |
of the possible uses for the hook. The full leverage of each hook |
is only limited by the imagination of the module writer (it's |
as much a cliche as it is true). |
|
* It may be that you need to hook into a spot where there is |
currently no hook available. If that is the case, let the dev |
team know by posting a message in the development forum |
on phorum.org, explaining where and why you need an extra hook. |
Hooks will be added as neccessary, especially while Phorum 5 |
is young. |
|
|
4.1 Code hooks |
-------------- |
|
Code hooks are hooks that are called from within the Phorum core |
code. These hooks are typically used for modifying Phorum's internal |
datastructures. |
|
|
---------------------------------------------------------------------------- |
admin_general |
|
Where : admin interface |
When : Right before the PhorumInputForm object is shown. |
Input : The PhorumInputForm object. |
Return : Same as Input |
|
This hook can be used for adding items to the form on the |
"General Settings" page of the admin interface. |
|
---------------------------------------------------------------------------- |
admin_file_purge |
|
Where : admin interface, option "Purge Stale Files" |
When : Right before stale files are deleted from the database. |
Input : An array, containing a description of all stale files. |
Return : Same as Input |
|
The primary use of this hook would be to cleanup stale files, created |
by an alternate storage system for attachments (see after_attach and |
after_detach as well). The array that is passed on to the hook function |
contains arrays, which contain the following fields: |
|
file_id : Internal id to reference the file. |
filename : Name of the file. |
filesize : Filesize in KB. |
add_datetime : Epoch timestamp for the time the file was created. |
reason : A description why this file is considered to be stale. |
|
---------------------------------------------------------------------------- |
after_attach |
|
Where : include/posting/action_attachments.php |
When : Just after a file attachment is saved in the database |
Input : Two part array where the first element is the message array and |
the second element is a file array that contains the name, size, |
and file_id of the newly saved file. |
Return : Same as Input |
|
The primary use of this hook would be for creating an alternate storage |
system for attachments. You would need to use the before_attach hook to |
remove the file data and in this hook it could be saved properly. You will |
need to use the file hook to retreive the file data later. |
|
---------------------------------------------------------------------------- |
after_detach |
|
Where : include/posting/action_attachments.php |
When : Just after a file attachment is deleted from the database |
Input : Two part array where the first element is the message array and |
the second element is a file array that contains the name, size, |
and file_id of the deleted file. |
Return : Same as Input |
|
The primary use of this hook would be for creating an alternate storage |
system for attachments. Using this hook, you can delete the file from |
your alternate storage. |
|
---------------------------------------------------------------------------- |
after_header |
|
Where : Every page, except for the admin interface pages |
When : Right after the header is displayed. |
Input : none |
Return : none |
|
This hook can be used for creating content at the end of the header, |
just before the main content is displayed. |
|
---------------------------------------------------------------------------- |
after_login |
|
Where : login.php |
When : After a successful login, just before redirecting the |
user to a Phorum page. |
Input : The redirection URL. |
Return : Same as Input |
|
This hook can be used for performing tasks after a successful user |
login and for changing the page to which the user will be redirected |
(by returning a different redirection URL). If you need to access the |
user data, then you can do this through the global $PHORUM variable. |
The user data will be in $PHORUM["user"]. |
|
---------------------------------------------------------------------------- |
after_logout |
|
Where : login.php |
When : After a logout, just before redirecting the user to |
a Phorum page. |
Input : The redirection URL. |
Return : Same as Input |
|
This hook can be used for performing tasks after a successful user |
logout and for changing the page to which the user will be redirected |
(by returning a different redirection URL). The user data will still |
be availbale in $PHORUM["user"] at this point. |
|
---------------------------------------------------------------------------- |
after_register |
|
Where : register.php |
When : Right after a successful registration of a new user is done |
and all confirmation mails are sent. |
Input : Array containing the user data of the user (read-only). |
Return : Same as Input |
|
This hook can be used for performing tasks (like logging and |
notification) after a successful user registration. |
|
---------------------------------------------------------------------------- |
before_attach |
|
Where : include/posting/action_attachments.php |
When : Just before a file attachment is saved in the database |
Input : Two part array where the first element is the message array and |
the second element is a file array that contains the name, size |
and data. |
Return : Same as Input |
|
The primary use of this hook would be for creating an alternate storage |
system for attachments. You would need to use the after_attach hook to |
complete the process as you do not yet have the file_id for the file. You |
will need to use the file hook to retreive the file data later. |
|
---------------------------------------------------------------------------- |
before_editor |
|
Where : posting.php |
When : Just before the message editor is displayed. |
Input : Array containing data for the message that will be shown |
in the editor screen. |
Return : Same as Input |
|
This hook can be used for changing message data, just before the editor |
is displayed. This is done after escaping message data for XSS prevention |
is done. So in the hook, the module writer will have to be aware that |
data is escaped and that he has to escape data himself if needed. |
|
This hook is called every time the editor is displayed. If modifying |
the message data does not have to be done on every request (for example |
only on the first request when replying to a message), the module will |
have to check the state the editor is in. Here's some hints on what |
you could do to accomplish this: |
|
* Check the editor mode: this can be done by looking at the "mode" field |
in the message data. This field can be one of "post", "reply" and "edit". |
|
* Check if it's the first request: this can be done by looking at the |
$_POST array. If no field "message_id" can be found in there, the |
editor is handing the first request. |
|
Using this, an example hook function that appends the string "FOO!" |
to the subject when replying to a message (how useful ;-) could look |
like this: |
|
function phorum_mod_foo_before_editor ($data) |
{ |
if ($data["mode"] == "reply" && ! isset($_POST["message_id])) { |
$data["reply"] = $data["reply"] . " FOO!"; |
} |
|
return $data; |
} |
|
Beware: this hook function only changes message data before it is |
displayed in the editor. From the editor, the user can still change |
the data. Therefore, this hook cannot be used to control the data which |
will be stored in the database. If you need that functionality, then |
use the hooks pre_edit and/or pre_post instead. |
|
---------------------------------------------------------------------------- |
before_footer |
|
Where : Every page, except for the admin interface pages |
When : Right before the footer is displayed. |
Input : none |
Return : none |
|
This hook can be used for creating content at the end of the main |
content, just before the footer. It can also be used for |
performing tasks that have to be executed at the end of each page. |
|
---------------------------------------------------------------------------- |
before_register |
|
Where : register.php |
When : Right before a new user is stored in the database. |
Input : Array containing the user data of the user. |
Return : Same as Input |
|
This hook can be used for performing tasks before user registration. |
This hook is useful if you want to add some data to or change some |
data in the user data and to check if the user data is correct. |
|
When checking the registration data, the hook can set the "error" field |
in the returned user data array. When this field is set after running |
the hook, the registration processed will be halted and the error |
will be displayed. If you created a custom form field "foo" and you |
require that field to be filled in, you could create a hook function |
which looks like this: |
|
function phorum_mod_foo_before_register ($data) |
{ |
$myfield = trim($data['your_custom_field']); |
if (empty($myfield)) { |
$data['error'] = 'You need to fill in my custom field'; |
} |
|
return $data; |
} |
|
---------------------------------------------------------------------------- |
buddy_add |
|
Where : pm.php |
When : Right after a buddy has been added successfully. |
Input : The user id of the buddy that has been added. |
Return : Same as Input |
|
This hook can be used for performing actions after a buddy has been |
added for a user (e.g. sending the new buddy a PM about this event, |
update popularity counters, do logging, synchronizing with other |
databases, etc.). |
|
---------------------------------------------------------------------------- |
buddy_delete |
|
Where : pm.php |
When : Right after a buddy has been deleted successfully. |
Input : The user id of the buddy that has been deleted. |
Return : Same as Input |
|
This hook can be used for performing actions after a buddy has |
been deleted for a user. |
|
---------------------------------------------------------------------------- |
cc_save_user |
|
Where : control.php |
When : Right before data for a user is saved in the control panel. |
Input : Array containing the user data to save. |
Return : Same as Input |
|
This hook works the same way as the before_register hook, so you can |
also use it for changing and checking the user data that will be |
saved in the database. There's one difference. If you want to |
check a custom field, you'll also need to check the panel which |
you are on, because this hook is called from multiple panels. |
The panel that you are on, will be stored in the 'panel' field |
of the user data. |
|
If you have added a custom field to the template for the option |
"Edit My Profile" in the control panel, your hook function will |
look like this: |
|
function phorum_mod_foo_cc_save_user ($data) |
{ |
// Only check data for the panel "user". |
if ($data['panel'] != "user") return $data; |
|
$myfield = trim($data['your_custom_field']); |
if (empty($myfield)) { |
$data['error'] = 'You need to fill in my custom field'; |
} |
|
return $data; |
} |
|
---------------------------------------------------------------------------- |
check_post |
|
Where : post.php |
When : Right after performing preliminary posting checks, unless |
these checks have returned something bad. |
Input : Array containing: |
0 => the $_POST array with form data |
1 => $error, to return errors in |
Return : Same as Input |
|
This hook can be used for modifying data in the $_POST array and for |
running additional checks on the data. If an error is put in $error, |
Phorum will stop posting the message and show the error to the user |
in the post-form. |
|
Beware that $error can already contain an error on input, in case |
multiple modules are run for this hook. Therefore you might want to |
return immediately in your hook function in case $error is already |
set. |
|
Below is an example of how a function for this hook could look. |
This example will disallow the use of the word "bar" in the |
message body. |
|
function phorum_mod_foo_check_post ($args) { |
list ($message, $error) = $args; |
if (!empty($error)) return $args; |
|
if (stristr($message["body"], "bar") !== false) { |
return array($message, "The body may not contain 'bar'"); |
} |
|
return $args; |
} |
|
---------------------------------------------------------------------------- |
close_thread |
|
Where : moderation.php |
When : Right after a thread has been closed by a moderator. |
Input : The id of the thread that has been closed (read-only). |
Return : Same as Input |
|
This hook can be used for performing actions like sending notifications |
or making log entries after closing threads. |
|
---------------------------------------------------------------------------- |
common |
|
Where : common.php, so in practice every page |
When : Right before the end of the common.php include script. |
Input : none |
Return : none |
|
This hook can be used for applying custom settings or altering |
Phorum settings based on external parameters. |
|
---------------------------------------------------------------------------- |
common_no_forum |
|
Where : common.php, so in practice every page |
When : Right after no forum settings were found, before doing the redirect |
Input : none |
Return : none |
|
This hook can be used for returning some other message (i.e. a 404-page) |
to the visitor if the requested forum was not found. |
|
---------------------------------------------------------------------------- |
common_post_user |
|
Where : common.php, so in practice every page |
When : Right after loading the user from the database, but just |
before making descisions on language and template. |
Input : none |
Return : none |
|
This hook can be used for applying custom settings or altering |
Phorum settings based on external parameters. |
|
---------------------------------------------------------------------------- |
common_pre |
|
Where : common.php, so in practice every page |
When : Right after loading the settings from the database, but just |
before making descisions on language, template and user. |
Input : none |
Return : none |
|
This hook can be used for applying custom settings or altering |
Phorum settings based on external parameters. |
|
---------------------------------------------------------------------------- |
delete |
|
Where : moderation.php |
When : Right after deleting a message from the database. |
Input : Array of ids for messages that have been deleted (read-only). |
Return : none |
|
This hook can be used for cleaning up anything you may have created |
with the post_post hook or any other hook that stored data tied to |
messages. |
|
---------------------------------------------------------------------------- |
external |
|
The external hook functions are never called from any of the standard |
Phorum pages. These functions are called by invoking script.php on the |
command line with the --module parameter. This can be used to pipe |
output from some arbitrary command to a specific module, which can do |
something with that input. If your module does not need any command |
line input and is meant to be run on a regular basis, you should |
consider using the scheduled hook. |
|
Mind that for using an external hook, the module in which it is |
handled must be enabled in your admin interface. So if an external |
hook is not running, the containing module might be disabled. |
|
To run the external hook from the command line, you have to be in |
the phorum installation directory. So running the external hook of |
a module named "external_foo" would be done like this on a UNIX |
system prompt: |
|
# cd /your/phorum/dir |
# php ./script.php --module=external_foo |
|
For easy use, you can of course put these commands in a script file. |
|
---------------------------------------------------------------------------- |
file |
|
Where : file.php |
When : When attachments are requested. |
Input : Two part array where the first element is the mime type already |
detected by file.php and the second part is the file array that |
contains the filename, file_data, filesize, etc. |
Return : Same as Input |
|
This hook could be used to count file downloads, or along with after_attach |
an alternate file data storage mechanism could be created. |
|
---------------------------------------------------------------------------- |
format |
|
Where : phorum_format_messages() in include/format_functions.php |
When : Everytime phorum_format_messages() is called for formatting |
a message, just before it is sent to the templates. |
Input : Array of messages. |
Return : Same as Input |
|
This hook can be used for applying custom formatting to messages. The |
message fields that are most applicable for this are "body" and "author". |
When writing a module using this hook, you probably want to format |
those fields. In practice you can apply formatting to all the fields |
you want. |
|
The changes you make to the messages are for displaying purposes |
only, so the changes are not stored in the database. |
|
---------------------------------------------------------------------------- |
hide |
|
Where : moderation.php |
When : Right after a message has been hidden by a moderator. |
Input : The id of the message that has been hidden (read-only). |
Return : Same as Input |
|
This hook can be used for performing actions like sending notifications |
or making log entries after hiding a message. |
|
---------------------------------------------------------------------------- |
index |
|
Where : include/index_new.php and include/index_classic.php |
When : Right before the list of forums is displayed. |
Input : Array of forums. |
Return : Same as Input |
|
This hook can be used for changing or adding data to the forums |
in the list. |
|
---------------------------------------------------------------------------- |
lang |
|
The lang hook is a only a 'marker'. It flags Phorum that your module |
supports multiple languages. It does not take a hook function in |
your module information. If you do define a hook function, it will |
never be called. |
|
Read section 2.3 for information on the use of multiple languages. |
|
---------------------------------------------------------------------------- |
list |
|
Where : list.php |
When : Right before the messages are formatted and displayed. |
Input : Array of threads (or messages in threaded mode). |
Return : Same as Input |
|
This hook can be used for changing or adding data to the messages |
in the list. |
|
---------------------------------------------------------------------------- |
moderation |
|
Where : moderation.php |
When : At the start of moderation.php |
Input : The id of the moderation step which is run (read-only). |
Return : none |
|
This hook can be used for logging moderator actions. You can |
use the $PHORUM-array to retrieve additional info like the |
moderating user's id and similar. |
|
The moderation step id is the variable $mod_step that is used in |
moderation.php. Please read that script to see what moderation |
steps are available and for what moderation actions they stand. |
|
When checking the moderation step id for a certain step, always use |
the contstants that are defined for this in include/constants.php. |
The numerical value of this id can change between Phorum releases. |
|
---------------------------------------------------------------------------- |
move_thread |
|
Where : moderation.php |
When : Right after a thread has been moved by a moderator. |
Input : The id of the thread that has been moved (read-only). |
Return : none |
|
This hook can be used for performing actions like sending notifications |
or for making log entries after moving a thread. |
|
---------------------------------------------------------------------------- |
pm_sent |
|
Where : include/controlcenter/pm.php |
When : Right after a PM and its email notifications have been sent. |
Input : Array containing the private message data (read-only). |
Return : none |
|
This hook can be used for performing actions after sending a PM. Before |
PM notification by email was put in the Phorum core, this hook was |
used to send those notifications. |
|
---------------------------------------------------------------------------- |
post_edit |
|
Where : include/moderation_functions.php |
When : Right after storing an edited message in the database. |
Input : Array containing message data (read-only). |
Return : none |
|
This hook can be used for sending notifications or for making log entries |
in the database when editing takes place. |
|
---------------------------------------------------------------------------- |
post_post |
|
Where : post.php |
When : Right after storing a new message in the database and just |
before the user is redirected back to the list. |
Input : Array containing message data (read-only). |
Return : none |
|
This hook can be used for performing actions based on what the message |
contained. |
|
---------------------------------------------------------------------------- |
posting_permission |
|
Where : posting.php |
When : Right after Phorum has determined all abilities that apply |
to the logged in user. |
Input : none |
Ouput : none |
|
This hook can be used for setting up custom abilities and permissions |
for users, by updating the applicable fields in $GLOBALS["PHORUM"]["DATA"] |
(e.g. for giving certain users the right to make postings sticky, without |
having to make the full moderator for a forum). |
|
Read the code in posting.php before this hook is called to find out |
what fields can be used. |
|
Beware: Only use this hook if you know what you are doing and understand |
Phorum's editor permission code. If used wrong, you can open up security |
holes in your Phorum installation! |
|
---------------------------------------------------------------------------- |
pre_edit |
|
Where : include/moderation_functions.php |
When : Right before storing an edited message in the database. |
Input : Array containing message data. |
Return : Same as Input |
|
This hook can be used for changing the message data before storing it |
in the database. |
|
---------------------------------------------------------------------------- |
pre_post |
|
Where : post.php |
When : Right before storing a new message in the database. |
Input : Array containing message data. |
Return : Same as Input |
|
This hook can be used for changing the message data before storing it |
in the database. |
|
---------------------------------------------------------------------------- |
profile |
|
Where : profile.php and include/controlcenter/summary.php |
When : Right before a user profile is displayed. |
Input : Array containing user profile data. |
Return : Same as Input |
|
This hook can be used for making changes to the profile data. This |
is for displaying purposes only, so the changes are not stored in the |
database. |
|
---------------------------------------------------------------------------- |
quote |
|
Where : reply.php, read.php (for inline reply form support) |
When : Right after the message to reply to has been loaded. |
Input : Array containing: |
0 => The message author |
1 => The message body |
Return : The quoted body to use in the post form. |
|
When quoting a message for reply, by default Phorum formats quoted |
messages using an old school email style of quoting. By using the quote |
hook, you can implement a different quoting mechanism. |
|
Your hook function will retrieve an array containing two elements: |
the author and the body of the message to be quoted. The return |
value for your hook function must be the quoted body that will |
be pre-filled into the reply form. |
|
The BBCode module that is distributed with Phorum has a quote hook |
function. Because it does not make sense to have more than one quote |
hook active, the BBCode module has an option to disable its quote hook |
function. You need to make sure that its quote hook function is disabled |
when using your own quote hook. |
|
---------------------------------------------------------------------------- |
read |
|
Where : read.php |
When : Right before messages are formatted for displaying. |
Input : Array of messages. |
Return : Same as Input |
|
This hook can be used for making changes to the message data when |
reading messages. This is for displaying purposes only, so the |
changes are not stored in the database. |
|
---------------------------------------------------------------------------- |
read_user_info |
|
Where : read.php post.php include/moderation_functions.php |
When : Right after retrieving user data. |
Input : Array of users. |
Return : Same as Input |
|
This hook can be used for changing information for the users before |
being displayed. For example: add a border around user signatures. |
This is for displaying purposes only, so the changes are not stored |
in the database. |
|
---------------------------------------------------------------------------- |
readthreads |
|
Where : read.php |
When : At the start of the threaded read handling, just before |
sorting and displaying the threads. |
Input : Array of messages. |
Return : Same as Input |
|
This hook does exactly the same as the read hook, except that this |
one is only applied to messages when viewing the message list in |
threaded mode. |
|
---------------------------------------------------------------------------- |
reopen_thread |
|
Where : moderation.php |
When : Right after a thread has been reopened by a moderator. |
Input : The id of the thread that has been reopened (read-only). |
Return : Same as Input |
|
This hook can be used for performing actions like sending notifications |
or making log entries after reopening threads. |
|
---------------------------------------------------------------------------- |
report |
|
Where : report.php |
When : Just before a reported message is sent to the moderators. |
Input : Array with maildata (see report.php for the exact contents). |
Return : Same as Input |
|
This hook can be used for changing the report data that will be |
sent to the moderators or for performing actions like making log |
entries. |
|
---------------------------------------------------------------------------- |
sanity_checks |
|
Where : include/admin/sanity_checks.php |
When : Just before the admin interface's sanity checks are run |
Input : Array with sanity checks. Each sanity check is an array with: |
function => The function that runs the sanity check |
description => A description to show in the admin interface |
Return : Same as Input |
|
This hook can be used to add custom sanity checks to the admin |
interface option "System Sanity Checks". |
|
Each checking function is expected to return an array containing |
two elements: |
|
[0] A status, which can be one of |
PHORUM_SANITY_OK No problem found |
PHORUM_SANITY_WARN Problem found, but no fatal one |
PHORUM_SANITY_CRIT Critical problem found |
|
[1] A description of the problem that was found or NULL. |
|
A general checking function looks like this: |
|
function check_foo() { |
$check_ok = ...some check...; |
if (!$check_ok) { |
return array(PHORUM_SANITY_CRIT, "Foo went wrong because ..."); |
} else { |
return array(PHORUM_SANITY_OK, NULL); |
} |
} |
|
---------------------------------------------------------------------------- |
scheduled |
|
Scheduled hook functions are similar to external ones, except these |
functions do not require any input from the command line. The modules |
containing a scheduled hook are invoked by running script.php with |
the --scheduled argument (no module name is taken; this argument |
will run all scheduled hooks for all available modules). |
|
Like the name of the hook already suggests, this hook can be used for |
creating tasks which have to be executed on a regular basis. To |
archieve this, you can let script.php run from a scheduling |
service (like a cron job on a UNIX system). |
|
In general, scheduled hooks are used for automating tasks you want |
to execute without having to perform any manual action. Practical |
uses for a scheduled hook could be housekeeping (cleanup of |
stale/old data), daily content generation (like sending daily digests |
containing all posted messages for that day) or forum statistics |
generation. |
|
Mind that for using a scheduled hook, the module in which it is |
handled must be enabled in your admin interface. So if a scheduled |
hook is not running, the containing module might be disabled. |
|
To run the scheduled hook from the command line or from a scheduling |
service, you have to be in the phorum installation directory. So |
running the scheduled hooks for your Phorum installation would |
be done like this on a UNIX system prompt: |
|
# cd /your/phorum/dir |
# php ./script.php --scheduled |
|
When creating a scheduling service entry for running this |
automatically, then remind to change the directory as well. |
You might also have to use the full path to your PHP binary |
(/usr/bin/php or whatever it is on your system), because |
the scheduling service might not know the path to it. An entry |
for the cron system on UNIX could look like this: |
|
0 0 * * * cd /your/phorum/dir && /usr/bin/php ./script.php --scheduled |
|
Please refer to your system's documentation to see how to |
use your system's scheduling service. |
|
---------------------------------------------------------------------------- |
search |
|
Where : search.php |
When : Right before messages are formatted for displaying. |
Input : Array of messages. |
Return : Same as Input |
|
This hook can be used for making changes to the message data when |
searching for messages. This is for displaying purposes only, so the |
changes are not stored in the database. |
|
---------------------------------------------------------------------------- |
send_mail |
|
Where : include/email_functions.php in the function phorum_email_user() |
When : Right before email is sent using PHP's mail() function. |
Input : Array with maildata (read-only) containing: |
addresses => Array of e-mail addresses, |
from => The sender address, |
subject => The mail subject, |
body => The mail body, |
bcc => Whether to use Bcc for mailing multiple recipients |
Return : true/false - see description |
|
This hook can be used for implementing an alternative mail sending |
system (e.g. like the SMTP module does). The hook should return true if |
Phorum should still send the mails himself. If you do not want to have |
Phorum send the mails also, return false. |
|
---------------------------------------------------------------------------- |
user_list |
|
Where : include/users.php include/controlcenter/groupmod.php |
When : Whenever phorum_user_get_list() is called. |
Input : Array containing: |
<user_id> => <data> |
Where <data> is an array containing: |
username => the username for the user |
displayname => the way to display the username |
Return : Same as Input |
|
This hook can be used for reformatting the list of users in some |
way, such as changing the sort order or changing the format of |
the displayed names. |
|
|
4.2 Template hooks |
------------------ |
|
Template hooks are called from within Phorum's template files. |
These hooks can be used to extend the user interface with custom |
elements. From a hook function for one of these template hooks, the |
module writer can print the HTML code that has to be added to the |
interface at the postition of the hook call in the template. |
|
|
---------------------------------------------------------------------------- |
tpl_editor_after_subject |
|
Where : posting_messageform.tpl |
When : After the Subject: field in the message editor. |
Input : none |
Return : none |
|
This hook can be used to add custom form fields to the message editor. |
In the default template, the hook is run from within a two column table. |
Column one contains the labels and column two the form fields. So your |
hook function for adding a field to the editor could look like this: |
|
function phorum_mod_foo_tpl_editor_after_subject() |
{ |
$value = isset($_POST["mod_foo"]) ? $_POST["mod_foo"] : ""; |
?> |
<tr> |
<td> |
Foo field |
</td> |
<td> |
<input type="text" name="mod_foo" |
value="<?php print htmlspecialchars($value) ?>"/> |
</td> |
</tr> |
<?php |
} |
|
---------------------------------------------------------------------------- |
tpl_cc_usersettings |
|
Where : cc_usersettings.tpl |
When : After the built-in usersettings fields. |
Input : Array containing the user's current profile. |
Return : Same as Input |
|
This hook can be used to add extra fields to the settings pages in the |
user's control center. Here's an example hook function that will add |
an extra field to the "Edit My Profile" page. |
|
function phorum_mod_foo_tpl_cc_usersettings($profile) |
{ |
// Check if we're on the userprofile page of cc_usersettings.tpl. |
if (! isset($profile["USERPROFILE"]) || ! $profile["USERPROFILE"]) |
return; |
|
$value = isset($profile["shoesize"]) |
? htmlspecialchars($profile["shoesize"]) : ""; |
?> |
<tr> |
<td>Shoe size</td> |
<td><input name="shoesize" type="text" value="<?=$value?>"></td> |
</tr> |
<?php |
} |
|
---------------------------------------------------------------------------- |
tpl_editor_attachment_buttons |
|
Where : posting_attachments_list.tpl |
When : Before the delete button for an attachment. |
Input : Array containing attachment information. |
Return : Same as Input |
|
This hook can be used to add extra buttons to each attachment in the |
editor, so you can do custom actions for attachments. |
|
To make your buttons look the same as Phorum's buttons, use the |
CSS class "PhorumSubmit". |
|
Here's an example hook function that will add a button to the attachments, |
which will send a javascript alert to the user when clicked. |
|
function phorum_mod_foo_tpl_editor_attachment_buttons($data) |
{ |
$id = $data["file_id"]; |
?> |
<input type="submit" class="PhorumSubmit" value="Say it!" |
onclick="alert('You clicked attachment id <?php print $id ?>')" /> |
<?php |
} |
|
---------------------------------------------------------------------------- |
tpl_editor_before_textarea |
|
Where : posting_messageform.tpl |
When : Before the textarea. |
Input : none |
Return : none |
|
This hook can be used to add custom user interface elements before the |
textarea in the message editor. |
|
---------------------------------------------------------------------------- |
tpl_editor_buttons |
|
Where : posting_buttons.tpl |
When : Before the main editor buttons (like Preview, Post and Cancel). |
Input : none |
Return : none |
|
This hook can be used to add extra buttons to the editor buttons. |
|
To make your buttons look the same as Phorum's buttons, use the |
CSS class "PhorumSubmit". |
|
Here's an example hook function that will add a button to the editor, |
which will send a javascript alert to the user when clicked. |
|
function phorum_mod_foo_tpl_editor_buttons() |
{ ?> |
<input type="submit" class="PhorumSubmit" value="Say it!" |
onclick="alert('Hello, foo!')" /> |
<?php |
} |
|
|
6. Support |
------------------------------------------------------------------------------- |
|
If you have questions about creating modules for Phorum, please visit |
the website http://phorum.org/ and ask the development team for help in |
the Development forum. |
|