Module information is the glue between your module and Phorum. It provides information to Phorum about your module. Before we explain how to add this module information to your module, we will first explain what data can be put in there and how that data is formatted.
Module information is formatted using lines of plain text. Each line contains a piece of information about the module. The general format for each of the lines in the module information is:
Empty lines are allowed between these key/value pairs. Below, you can find a list of the keys and values that can be used in the module information.
Table 2.1. Keys and values in module information
This is the title for the module that is displayed in the "Modules" page of the admin interface.
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 <value> part is allowed.
This describes which hook functions are called for which Phorum hooks. The value 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.
This can be used for changing priorities and dependancies for modules and hooks. Possible values are (in order in which they are processed):
Run this module before all other modules:
Run this module before the bbcode module.
Run the "format" hook for this module before the
"format" hook of the smileys module.
Run the "after_header" hook for this module after all
other "after_header" hooks.
The main difference between "run module" and "run hook" is that "run module" will affect the priority for each hook of the module and that "run hook" is used to specifically change the priority of a single hook. So to run all hooks for a module as early as possible, but run the "foo" hook as late as possible and the "bar" hook before the smileys mod, one could use the following priority lines:
This describes which phorum version is required to use this module. Modules with a requirement above the current phorum version are automatically disabled when going to the modules page. This feature was added in Phorum 5.2.
These fields are all informational. The information from these fields will be shown on the Modules admin page. You are allowed to omit these fields from the module information, but we advice you to fill them to provide as much useful info to the users of your module.
The fields are free form. The "url" field should contain a URL to a page where more information about the module can be found. This can for example be a dedicated page about your module or a discussion page in the phorum.org support forums.
The category field is used for categorizing the module. You can place your module inside one or more categories by adding one or more category lines to the module information. The category is used for automatically generating a categorized list of available modules on the phorum.org web site.
For consistency and for preventing wild growth of categories, we use a fixed set of categories from which you can choose. Please select your category / categories carefully and do not put your module in too many categories. Available categories to choose from are:
It is allowed to use multiple hook lines in your module information, so your module can act upon 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 is an example of what the module information for our example module "foo" might look like:
Example 2.1. Module information
title: Foo desc: This is the Foo module for Phorum. Nothing exciting... version: 1.0.2 release_date: Jan 1st, 2008 url: http://www.phorum.org author: John Doe <firstname.lastname@example.org> require_version: 5.2.2 category: user_features 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 priority: run some_hook before some_other_module
What this module info 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. It will also take care that the hook "some_hook" is run
before the same hook in the module "some_other_module".