 |
Module Coding Guidelines |
This is the November, 2002 revision of the Module Coding Guidelines
Please send corrections, additions and new questions to Acyd Burn.
This Guide is intended for Statistics Mod Module Authors/Writers, to show them what they are able to use within their Modules. And to show
them what they need to do in order to package up a valid Module.
- Main Module Layout
- Directory Structure
- Global Variables
- Licensing
- The use of the Statistics Class
- Voting Bars
- Calculations
- Forum Permissions
- The use of the DB based cache
- The use of the Result based cache
- Functions to cache Variables and Arrays
- Assign Vars
- Assign Block Vars
- Assign Templated Block Vars
- Functions to use cached Variables and Arrays
- Get Vars
- Retrieve Number of Block Vars
- Get Block Arrays
- Get Block Vars
- Layout of the info.txt file
- Overview of all Variables
- Info.txt Variable Definitions
- [author]
- [condition]
- [email]
- [extra_info]
- [name]
- [stats_mod_version]
- [update_time]
- [url]
- [version]
- Copyright and Disclaimer
1. Main Module Layout
1.1 Directory Structure
A Module have to retain a certain Structure in order to work, some Files are optional, others are Required:
Filename/Directory |
Status |
Description |
info.txt |
[FILE] Required |
Informations about the Module |
module.php |
[FILE] Required |
Within this File the Module Coding takes place |
module.tpl |
[FILE] Required |
This is the Template File for the Module |
install_mssql.sql |
[FILE] Optional |
Within this File you are able to place MSSQL specific SQL Statements, executed on Module Installation |
install_mysql.sql |
[FILE] Optional |
Within this File you are able to place MySQL specific SQL Statements, executed on Module Installation |
install_postgresql.sql |
[FILE] Optional |
Within this File you are able to place PostgreSQL specific SQL Statements, executed on Module Installation |
lang_english |
[DIR] Required |
This Directory holds the English Language File, it is required, because the Statistics Mod switches back to English if no appropiate File could not be found |
lang_* |
[DIR] Optional |
This Directory holds another Language File, depending on the Language, it is the same structure as the normal Language Directory within your phpBB Installation |
lang_*/lang.php |
[FILE] Required |
This File holds the Language Variables for the specific Language |
Every Module packaged up has to be placed within a seperate Directory, mentioning the Module Name, for example the Top Smilies Module is
placed into the Directory top_smilies.
The Module Directory Name have to be all lowercase and whitespaces are disallowed.
It is not allowed to deliver a Module without a specific Directory.
WRONG:
|
. <- no directory
| module.php
| module.tpl
| info.txt
|
+---lang_english
lang.php
|
CORRECT:
|
top_smilies <- Directory
| module.php
| module.tpl
| info.txt
|
+---lang_english
lang.php
|
Conventions you should follow:
Within your lang.php file, you should always use $lang['module_name'] for defining your Modules Name:
$lang['module_name'] = "Top Smilies";
Always use the Global Variable $return_limit to specify the number of returned Values.
1.2 Global Variables
There are some Variables (beside the Classes explained in this Document) you have access to within your Module (module.php).
These are:
Variable Name |
Type |
Description |
$return_limit |
Integer, default Value is 10 |
Control Panel defined number of items to display |
$module_info['name'] |
String |
The Module Name, specified within the info.txt file |
$module_info['email'] |
String |
The Author Email |
$module_info['author'] |
String |
The Author Name |
$module_info['version'] |
String |
The Module Version |
$module_info['url'] |
String |
The Author URL |
$module_info['dname'] |
String (Directory) |
The Directory the Module resides in |
1.3 Licensing
Because the Statistics Mod is licensed under the GPL (as phpBB is licensed under), your Module have to be placed under the GPL too.
You are encouraged to use the following Header within the module.php file:
/***************************************************************************
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
***************************************************************************/
You are free to add additional Lines mentioning Author Notes or whatever.
2. The use of the Statistics Class
With the Statistics Class you are able to access some basic Functions. The following paragraph tries to explain these
functions and how you are able to use them within your Module.
2.1 Voting Bars
Voting Bars are a common way to show Percentage based Statistics with a Module.
Function Name |
Variables |
Call |
Function Definition |
init_bars |
$bars (Optional Value) |
$statistics->init_bars([images]) |
function init_bars($bars = '') |
Called for initialize voting bars, Modules are able to call this function to setup the voting bars for displaying things.
If its called without a variable, the Statistics Mod uses the default Bar Images:
$statistics->init_bars();
|
Default Bar Images are:
Left Bar = images/vote_lcap.gif
Right Bar = images/vote_rcap.gif
Bar = images/voting_bar.gif
|
The user is able to call this function with defined Bar Images, the Array have to look like
this:
$bars = array(
'left' => 'images/vote_lcap.gif',
'right' => 'images/vote_rcap.gif',
'bar' => 'images/voting_bar.gif'
);
|
The variable name is not relevant. ;)
The call would be like this then:
$statistics->init_bars($bars);
|
To use the Bars within the TPL-Files, use the following:
{LEFT_GRAPH_IMAGE} for the Left Bar Cap
{RIGHT_GRAPH_IMAGE} for the Right Bar Cap
{GRAPH_IMAGE} for the Bar
|
The default use within the module.tpl file would be:
<table cellspacing="0" cellpadding="0" border="0" align="left">
<tr>
<td align="right"><img src="{LEFT_GRAPH_IMAGE}" width="4" height="12" /></td>
</tr>
</table>
<table cellspacing="0" cellpadding="0" border="0" align="left" width="{*.BAR}%">
<tr>
<td><img src="{GRAPH_IMAGE}" width="100%" height="12" /></td>
</tr>
</table>
<table cellspacing="0" cellpadding="0" border="0" align="left">
<tr>
<td align="left"><img src="{RIGHT_GRAPH_IMAGE}" width="4" height="12" /></td>
</tr>
</table>
|
{*.BAR} is the Bar Percentage (see the next function)
2.2 Calculations
This Function is for Calculating the Percentage Value and the corresponding Bar width.
Function Name |
Variables |
Call |
Function Definition |
do_math |
firstval: The highest determined value
value: The current Value
total: The complete number of all Values (The Sum)
|
$statistics->do_math($firstval, $value, $total) |
function do_math($firstval, $value, $total) |
This Function fill two Variables you are able to use:
$statistics->percentage: the Percentage
$statistics->bar_percent: The Percentage width for the displayed bar
|
This Function is called to calculate the Percentage of things (users, smilies... whatever), returning a value for the Percentage and
for the displayed bar width.
The $statistics->bar_percent is normally used in templates defining the length: width="{*.BAR}%"
2.3 Forum Permissions
This Function is used for getting Forum Permissions.
Function Name |
Variables |
Call |
Function Definition |
forum_auth |
userdata: The $userdata array
auth: Permission to look up. Valid Values are:
AUTH_ALL, AUTH_VIEW, AUTH_READ, AUTH_POST, AUTH_REPLY, AUTH_EDIT, AUTH_DELETE, AUTH_STICKY, AUTH_ANNOUNCE, AUTH_VOTE, AUTH_POLLCREATE
If you are using the Attachment Mod, these Values are allowed too:
AUTH_ATTACH, AUTH_DOWNLOAD
|
$statistics->forum_auth($userdata, [auth-value]) |
function forum_auth($userdata, $auth = AUTH_VIEW) |
This function returns a comma seperated list with all allowed forum id's. It should be used for further queries.
The default Permission used is AUTH_VIEW.
Now a complete List of known Auth Values:
AUTH_VIEW |
-> |
Permission to view the Forum |
AUTH_READ |
-> |
Permission to read Posts within the Forum |
AUTH_POST |
-> |
Permission to post Messages within the Forum |
AUTH_REPLY |
-> |
Permission to reply to Messages within the Forum |
AUTH_EDIT |
-> |
Permission to edit Posts within the Forum |
AUTH_DELETE |
-> |
Permission to delete Posts within the Forum |
AUTH_STICKY |
-> |
Permission to make Posts Sticky within the Forum |
AUTH_ANNOUNCE |
-> |
Permission to make Announcements within the Forum |
AUTH_VOTE |
-> |
Permission to Vote in Polls within the Forum |
AUTH_POLLCREATE |
-> |
Permission to create Polls within the Forum |
AUTH_ATTACH |
-> |
Permission to attach Files to Posts within the Forum |
AUTH_DOWNLOAD |
-> |
Permission to Download Files within the Forum |
3. The use of the DB based cache
Instead of calling the DBAL directly with $db->anyfunction, you are able to use $stat_db->anyfunction now.
Supported Functions:
Original DBAL Call |
Cached DBAL Call |
$db->sql_query |
$stat_db->sql_query |
$db->sql_numrows |
$stat_db->sql_numrows |
$db->sql_fetchrow |
$stat_db->sql_fetchrow |
$db->sql_fetchrowset |
$stat_db->sql_fetchrowset |
You should use the DB Cache if you are sure that the cached Data is not too much.
With some Modules, the DB Cache is just not appropiate, for example the Top Smilies Module.
The Top Smilies Module is querying a bunch of Posts (resulting in Posts Texts to be grabbed).
Such an enourmous Data to be cached is inappropiate and is not worth the effect.
4. The use of the Result based cache
With the Result Cache you are able to cache Variables and Arrays to use them later within the Module.
Please do NOT cache Language Variables or Theme Variables, because this will lead you to problems. ;)
The Result Cache is called in a similar way you do with the Template.
To initiate the Result cache, please call:
$result_cache->init_result_cache();
|
once within your module.
To see if the cached output is wanted from the Statistics Mod, refer to the
$statistics->result_cache_used
|
variable, it is set to TRUE if the Statistics Mod wants to use the cached output.
A good Example of how to use this Method is the Top Smilies Module.
4.1 Functions to cache Variables and Arrays
4.1.1 Assign Vars
Call:
$result_cache->assign_vars($vararray);
|
This function is for caching single variables.
For example:
$result_cache->assign_vars(array(
'firstvar' => $first_variable,
'colour' => $row_colour)
);
|
You see, it's the same you will do with the Template Class.
4.1.2 Assign Block Vars
Call:
$result_cache->assign_block_vars($blockname, $vararray);
|
This function is for caching Block Variables. You are able to assign more than one array to a block.
For example:
$result_cache->assign_block_vars('myrow', array(
'NAME' => $name,
'VALUE' => $value)
);
|
You are able to do this in a for loop too, for example:
for ($i = 0; $i < $return_limit; $i++)
{
$result_cache->assign_block_vars('myrow', array(
'POS' => $i+1,
'NAME' => $name,
'VALUE' => $value)
);
}
|
4.1.3 Assign Templated Block Vars
Call:
$result_cache->assign_template_block_vars($blockname);
|
This function is doing the same as the previous one, but without the need to assign an array.
The array is taken from the last addition to the Template.
For example, you have assigned a block to the Template:
$template->assign_block_vars('myrow', array(
'NAME' => $name,
'VALUE' => $value)
);
|
Now you want to cache the block, without re-defining it:
$result_cache->assign_template_block_vars('myrow');
|
Within a loop, it would be like this:
for ($i = 0; $i < $return_limit; $i++)
{
$template->assign_block_vars('myrow', array(
'POS' => $i+1,
'NAME' => $name,
'VALUE' => $value)
);
$result_cache->assign_template_block_vars('myrow');
}
|
4.2 Functions to use cached Variables and Arrays
4.2.1 Get Vars
Call:
$result_cache->get_var($key);
|
This function is for getting a cached variable, in our previous example we have assigned/cached firstvar.
We are getting the value of it by using this:
$firstvar = $result_cache->get_var('firstvar');
|
Now the Variable $firstvar is holding the cached value from the assigned variable firstvar.
4.2.2 Retrieve Number of Block Vars
Call:
$result_cache->block_num_vars($blockname);
|
This function is for getting the number of assigned arrays to the given block.
This is useful if you want to rebuild a loop. ;)
For example:
$result_cache->block_num_vars('myrow');
|
This will return the number of assigned arrays to the block myrow.
4.2.3 Get Block Arrays
Call:
$result_cache->get_block_array($blockname, $count);
|
This function is for getting a given array from a cached block.
The $count variable is identifying the given position.
For example, if you want to grab the second array from the block myrow (we count from zero on):
$variable = $result_cache->get_block_array('myrow', 1);
|
This function is very useful to fill the Template Variables. ;)
This example rebuilds the previous assigned Template Block:
The Assignment again:
for ($i = 0; $i < $return_limit; $i++)
{
$template->assign_block_vars('myrow', array(
'POS' => $i+1,
'NAME' => $name,
'VALUE' => $value)
);
$result_cache->assign_template_block_vars('myrow');
}
|
Now we want to rebuild it:
for ($i = 0; $i < $result_cache->block_num_vars('myrow'); $i++)
{
$template->assign_block_vars('myrow', $result_cache->get_block_array('myrow', $i));
}
|
It is very easy and powerful if you get into it. :D
4.2.4 Get Block Vars
Call:
$result_cache->get_block_var($blockname, $key, $count);
|
This function is for getting a specific key out of an cached block.
The same as above, but the result is the value of the given key (second parameter).
The above example of retrieving the block, but now with the get_block_var function:
The Assignment again:
for ($i = 0; $i < $return_limit; $i++)
{
$template->assign_block_vars('myrow', array(
'POS' => $i+1,
'NAME' => $name,
'VALUE' => $value)
);
$result_cache->assign_template_block_vars('myrow');
}
|
Now we want to rebuild it:
for ($i = 0; $i < $result_cache->block_num_vars('myrow'); $i++)
{
$template->assign_block_vars('myrow',
'POS' => $result_cache->get_block_var('myrow', 'POS', $i),
'NAME' => $result_cache->get_block_var('myrow', 'NAME', $i),
'VALUE' => $result_cache->get_block_var('myrow', 'VALUE', $i))
);
}
|
5. Layout of the info.txt file
This Part of the Document describes the Layout of the info.txt file.
The info.txt file is essential in order to let your Module work with the Statistics Mod.
You are able to use comments, if you put this character in front of a line: #
for example:
# This is a comment
Comment Lines will be not parsed by the Statistics Mod.
The info.txt file contains a bunch of 'variables', enclosed within brackets.
All Variables are available to the Modules, for further use, all within one array called $module_info['variable_name'].
5.1 Overview of all Variables
Variable Name |
Status |
Placement |
[name] |
Required |
The complete Information have to be placed in one Line |
[author] |
Required |
The complete Information have to be placed in one Line |
[email] |
Required |
The complete Information have to be placed in one Line |
[url] |
Required |
The complete Information have to be placed in one Line |
[version] |
Required |
The complete Information have to be placed in one Line |
[extra_info] |
Required |
The Block have to be ended with [/extra_info] |
[stats_mod_version] |
Optional |
The complete Information have to be placed in one Line |
[update_time] |
Optional |
The complete Information have to be placed in one Line |
[condition] |
Optional |
The Block have to be ended with [/condition] |
6. Info.txt Variable Definitions
6.1 [author]
This one defines your Name, the Author of the Module.
Status: Required Variable, One Line Entry
Example:
6.2 [condition]
This one is a condition setting, where you are able to check if the requirements for your Module are meeted.
Here you are able to enter PHP Code.
If the condition does not return true, the Module will be not installed.
The result have to be placed into the variable $return_val. Valid values are TRUE and FALSE.
Status: Optional Variable, Block Entry with Escape Variable ([/condition])
Example (checks if the Attachment Mod is installed):
[condition]
if (!defined(ATTACH_VERSION))
{
$return_val = FALSE;
}
else
{
$return_val = TRUE;
}
[/condition]
|
6.3 [email]
This one holds your Email Address, in order to contact you if a problem occur.
Status: Required Variable, One Line Entry
Example:
6.4 [extra_info]
Within this block you write down what your Module is doing, a little Description.
It will be displayed on Installation of the Module.
Status: Required Variable, Block Entry with Escape Variable ([/extra_info])
Example:
[extra_info]
This Module will display the most used Smilies on your Board.
It is recommended that you put a update time limit to this module on larger boards.
A default Update Time of 1000 Minutes was set.
[/extra_info]
|
6.5 [name]
This one defines the Module Name, displayed at the Administration Panel.
Status: Required Variable, One Line Entry
Example:
6.6 [stats_mod_version]
Within this Variable you are able to define the minimum required Statistics Mod Version in order to let your Module work fine.
Status: Optional Variable, One Line Entry
Example:
[stats_mod_version] 2.1.3
|
6.7 [update_time]
This Value is for defining the Default Update Time set on Installation.
Status: Optional Variable, One Line Entry
Example:
6.8 [url]
This one is for defining your Homepage or the Webpage where you give support for your Modules (if you have one) ;).
Status: Required Variable, One Line Entry
Example:
[url] http://www.opentools.de/board
|
6.9 [version]
With this one you are able to define the Version of your Module.
Status: Required Variable, One Line Entry
Example:
7. Copyright and Disclaimer
This application is opensource software released under the GPL. Please see source code for more details.
This Document is Copyright © 2002 Acyd Burn, All Rights Reserved.
|