[How To] Create an Add-On for phpBB Statistics

Post by **Marc** » Fri 27. Mar 2009, 21:31

The phpBB Statistics MOD is supposed to be easy to upgrade. In order to achieve that, there are some basic add-on rules you should follow when writing an add-on.

As you might have noticed, you are not able to create an Add-On in the Release Add-Ons forum. We want to maintain a basic level of coding and Add-Ons standards in the Released Add-Ons and therefore Add-Ons have to be validated. You will find more info on the validation process further down the page.
We urge you to follow the guidelines in this How to.

1. Basic structure of Add-Ons
An Add-On usually consists of 3 files:

the Add-On's php file
the Add-On's language file
the Add-On's HTML file

All PHP command like DB queries have to be inside the php file. Add-Ons that need to execute PHP Code inside a HTML file will be deleted, even if they are inside the "Add-Ons in Development" forum, as this poses a security threat.

All language variables have to be declared in the Add-On's language file and used in the Add-Ons HTML file. Please do not use hardcoded language in either your PHP-File nor in your HTML file.

2. The Add-On's PHP-File

The Add-On's PHP-File has to be saved inside the statistics/addons/ folder, i.e. statistics/addons/stats_mymod.php where stats_mymod is the classname of your Add-On.

The basic PHP-File looks like this:

Code: Select all

<?php
/**
*
* @package phpBB Statistics
* @version $Id: stats_test.php 135 2010-04-28 14:31:26Z marc1706 $
* @copyright (c) 2009 Marc Alexander(marc1706) www.m-a-styles.de
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*/


/**
* @ignore
*/
if (!defined('IN_PHPBB') || !defined('IN_STATS_MOD'))
{
    exit;
}

/**
* @package phpBB Statistics - Test Add-On
*/
class stats_test
{    
    /**
    * module filename
    * file must be in "statistics/addons/"
    */
    var $module_file = 'stats_test';
    
    /**
    * module language name
    * please choose a distinct name, i.e. 'STATS_...'
    * $module_name always has to be $module_file in capital letters
    */
    var $module_name = 'STATS_TEST';
    
    /**
    * module-language file
    * file must be in "language/{$user->lang}/mods/stats/addons/"
    */
    var $template_file = 'stats_test';
    
    /**
    * set this to false if you do not need any acp settings
    */
    var $load_acp_settings = false;
    
    /**
    * you can add some vars here
    */
    var $u_action;
    
    /**
    * add-on functions below
    */
    function load_stats()
    {
        global $config, $db, $template, $stats_config;
        global $phpbb_root_path, $phpEx;
        
        // add functions and everything here
        
        /**
        $sql = 'SELECT something
                FROM something_table
                WHERE something = 'something'
                GROUP BY something
                ORDER BY something DESC';
        $result = $db->sql_query_limit($sql, $limit_count);
        
        ...
        
        */
    }
    
    /**
    * acp frontend for the add-on
    * put the function in a comment or delete it if you don't need an acp frontend
    */
    function load_acp()
    {
        $display_vars = array(
                    'title' => 'STATS_TEST',
                    'vars' => array(
                        'legend1'                             => 'STATS_TEST',
                        'stats_test'                        => array('lang' => 'STATS_TEST_SHOW'  , 'validate' => 'bool'  , 'type' => 'radio:yes_no'  , 'explain' => true),
                    )
                );
        
        return $display_vars;
    }
    
    
    /**
    * API functions
    */
    function install()
    {
        global $db;
        
        $sql = 'SELECT addon_id AS addon_id FROM ' . STATS_ADDONS_TABLE . ' ORDER BY addon_id DESC';
        $result = $db->sql_query_limit($sql, 1);
        $id = (int) $db->sql_fetchfield('addon_id');
        $db->sql_freeresult($result);
    
        set_stats_addon($this->module_file, 1);
        
        $sql = 'UPDATE ' . STATS_ADDONS_TABLE . '
                SET addon_id = ' . ($id + 1) . "
                WHERE addon_classname = '" . $this->module_file . "'";
        $result = $db->sql_query($sql);
        $db->sql_freeresult($result);
    }
    
    function uninstall()
    {
        global $db;
        
        $del_addon = $this->module_file;
        
        $sql = 'DELETE FROM ' . STATS_ADDONS_TABLE . "
            WHERE addon_classname = '" . $del_addon . "'";
        return $db->sql_query($sql);
    }
}
?>

This image should explain all of the top variables:

: stats1.png (100.56 KiB) Viewed 31106 times

All PHP-Code that needs to be executed on the statistics page of your Add-On needs to be executed inside function load_stats().
If you need help creating the Template vars or querying the database, take a look at the phpBB Wiki.

Function load_acp() defines all boxes for your ACP settings:

: stats2.png (32.45 KiB) Viewed 31099 times

The allowed validation types are:
string, int and bool

Possible types are:

'radio:yes_no'
texty - where x needs to be replaced by the width of the textfield in numbers (i.e. 3 lets 3 numbers fit), y needs to be replace by the maximum allowed length of the entered string

3. The Add-On's language file
This is what a normal language files looks like:

Code: Select all

<?php
/**
*
* @package phpBB Statistics
* @version $Id: stats_gallery.php 99 2010-03-04 20:40:53Z marc1706 $
* @copyright (c) 2009 - 2010 Marc Alexander(marc1706) www.m-a-styles.de
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
* @translator (c) ( Marc Alexander - http://www.m-a-styles.de ), TheUniqueTiger - Nayan Ghosh
*/

if (!defined('IN_PHPBB') || !defined('IN_STATS_MOD'))
{
    exit;
}

if (empty($lang) || !is_array($lang))
{
    $lang = array();
}


/*    Example:
$lang = array_merge($lang, array(    
    'STATS'                                => 'phpBB Statistics',    

));
*/

$lang = array_merge($lang, array(    
    'STATS_MYMOD'                => 'My Mod',
));
?>

You should at least have the title of your MOD in this file, i.e. 'STATS_MYMOD'.
The filename of this file has to be same as previously declared in the PHP-File and it has to be saved in language/*yourlanguage*/mods/stats_addons/ .
Make sure to save this file as UTF8 without BOM, else you will get a white page.

The language strings of the ACP settings also have to be put in this file.
If you set 'explain' to true behind an ACP option, you will need two language strings for this option:
'STATS_MYMOD_AUTO' - title of the option
'STATS_MYMOD_AUTO_EXPLAIN' - explanation

4. The HTML file:

The HTML files work like the normal phpBB3 HTML files. HTML variables you defined in the PHP-File, will be available in this file.
Save your HTML file inside the styles/*yourstyle*/template/stats/addons/ folder. It has to have the same name as your class, i.e. stats_mymod.html.
The basic file looks like this:

prosilver:

Code: Select all

<!-- INCLUDE stats/stats_header.html -->
<form id="stats" method="post" action="{S_STATS_ACTION}"{S_FORM_ENCTYPE}>
<h2>{L_TITLE}</h2>

<div class="panel">
	<div class="inner_fs"><span class="corners-top"><span></span></span>
	
	<!-- Put your code here -->
	
	<!-- <hr /><div class="user_prompt"><span>{LIMIT_SELECT_BOX}</span></div><br /> -->
	<hr /><div style="text-align:right;"><span><i>{AS_ON}</i></span></div>
	<span class="corners-bottom"><span></span></span></div>
</div>
</form>
<!-- INCLUDE stats/stats_footer.html -->

subsilver2:

Code: Select all

<!-- INCLUDE stats/stats_header.html -->
<form id="stats" method="post" action="{S_STATS_ACTION}"{S_FORM_ENCTYPE}>
<table class="tablebg" width="100%" cellspacing="1">
<tr>
	<th colspan="3" width="100%">{L_STATS} - {L_TITLE}</th>
</tr>
<tr>
	<td class="row1" colspan="3" align="center"><p class="genmed"><img src="images/spacer.gif" width="4" alt="" /></p></td>
</tr>

<!-- Put your code here -->

<tr>
	<td style="text-align: right;"><span><i>{AS_ON}</i></span></td>
</tr>
</table>
<div>{S_FORM_TOKEN}</div>
</form>
<!-- INCLUDE stats/stats_footer.html -->

If you don't know how to use the phpBB template syntax, take a look at the phpBB Wiki.

Updated April 29th, 2010