2.3.2. Module information

Prev		Next

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:

 <key>: <value>

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

<key>	<value>
title	This is the title for the module that is displayed in the "Modules" page of the admin interface. Example: `title: Foo`
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 <value> part is allowed. Example: `desc: This is a very cool module to do stuff.`
hook	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. Example: `hook: some_hook\|phorum_mod_foo_some_hook`
priority	This can be used for changing priorities and dependancies for modules and hooks. Possible values are (in order in which they are processed): `run module before\|after ` `run module before\|after <other module name>` `run hook <hook name> before\|after ` `run hook <hook name> before\|after <other module name>` Examples: Run this module before all other modules: `priority: run module before ` Run this module before the bbcode module. `priority: run module before bbcode` Run the "format" hook for this module before the "format" hook of the smileys module. `priority: run hook format before smileys` Run the "after_header" hook for this module after all other "after_header" hooks. `priority: run hook after_header after ` 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: `priority: run module before * priority: run hook foo after * priority: run hook bar before smileys`
require_version	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. Example: `require_version: 5.2.2`
author url version release_date	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. Example: `author: John Doe, Phorum hacker url: http://example.com/phorum/mod_foo/ version: 0.9.1-alpha release_date: May 17th, 2007`
category	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: admin Modules that are useful for performing administrative tasks and for handling advanced Phorum configuration. bbcode Modules that implement extra BBcode tags. embed_content Modules for embedding content (e.g. images, audio, video, flash, etc.) in message bodies. These modules implement viewers that are shown inside the message bodies when reading the message and which take away the need to launch some external viewer to open attachments and/or linked files. phorum3conversion Modules that can help sites to convert from the old Phorum 3 system to Phorum 5. email Modules that extend or enhance the email system. integration Modules that can be used for integrating Phorum with other systems. user_management These modules deal with user registration, logging in and out, login status and user management tasks. moderator Modules that extend or enhance the moderation system. posting Modules that extend or enhance posting and/or editing messages. search Modules that provide search features or that replace the full message search backend. seo Modules that apply search engine optimization measures to Phorum. spam Modules that help protecting Phorum against spam. user_features Modules that give the users new options and enhance their experience. viewlayout Modules that add information to or alter the view / layout of Phorum pages. uncategorized Modules that do not have a category assigned. This one is mainly mentioned for completeness. In the online module list, this category will be assigned to modules that don't have a category set in their info.txt. Example: `category: user_features` `category: posting`

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 <johndoe@example.com>
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".