KB Archiv EN: Board3 Portal 2.0.0 - Module Documentation

[Kevin]

How to edit a module file

Starting from the top to the bottom, I'll explain how you can edit a module file.

You can use the portal/modules/portal_default.php as a base for your module.

First, edit the header to reflect your module name, i.e. this for the Gallery Block:

Code: Select all

/**
*
* @package Board3 Portal v2 - Gallery Block
* @copyright (c) Board3 Group ( www.board3.de )
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/  

Of course you can add your copyright to the header, but you must not remove the Board3 copyright.

Also make sure you change this line:

Code: Select all

/**
* @package Modulname
*/  

Just put your module name there, i.e.:

Code: Select all

/**
* @package Gallery Block
*/  

You can also just leave Board3 Portal v2 in the header and just change this line.

Now you have to modify the class name to reflect your module's name. If you filename is portal_gallery.php, you should name it portal_gallery_module:

Code: Select all

class portal_gallery_module

Afterwards you need to choose in which columns you should be able to install and move your module:

Code: Select all

    /**
    * Allowed columns: Just sum up your options (Exp: left + right = 10)
    * top        1
    * left        2
    * center    4
    * right        8
    * bottom    16
    */
    var $columns = 31;  

As stated in the comment, you need to sum up the options.

Set the language variable of your module title. This language variable needs to be defined in the language file of your block.

Code: Select all

    /**
    * Default modulename
    */
    var $name = 'PORTAL_GALLERY';  

If you block can be installed and moved to the side columns, you should define a module image:

Code: Select all

    /**
    * Default module-image:
    * file must be in "{T_THEME_PATH}/images/portal/"
    */
    var $image_src = 'portal_gallery.png';  

Afterwards define the name of the language file (without .php):

Code: Select all

    /**
    * module-language file
    * file must be in "language/{$user->lang}/mods/portal/"
    */
    var $language = 'portal_gallery_module';  

The comment states where the file needs to be put.

If you want to use a custom acp template file, you can define it here:

Code: Select all

    /**
    * custom acp template
    * file must be in "adm/style/portal/"
    */
    var $custom_acp_tpl = '';  

If you don't know what those files look like, take a look at the files inside the adm/style/portal/ folder of the Board3 Portal 2.0.x-package.

If your Block Title needs to change in the ACP or Portal depending on the settings in the ACP or you just don't want users to change the module title you can always force this by setting this switch to true:

Code: Select all

	/**
	* hide module name in ACP configuration page
	*/
	public $hide_name = false;

The following functions define the php code that will be executed on the portal page. Function get_template_center defines the php code for the top, center and bottom columns and function get_template_side defines the code for the side columns.

At the end of the function, you always return the template file that should be loaded:

Code: Select all

        return 'modulename_center.html';  

If you don't return anything, the block won't be displayed - i.e. when there is nothing to display.

With function get_template_acp() you can define the ACP options:

Code: Select all

    function get_template_acp($module_id)
    {
        return array(
            'title'    => 'ACP_PORTAL_BOTS_SETTINGS',
            'vars'    => array(
                'legend1'                            => 'ACP_PORTAL_BOTS_SETTINGS',
                'board3_last_visited_bots_number_' . $module_id    => array('lang' => 'PORTAL_LAST_VISITED_BOTS_NUMBER' ,    'validate' => 'int',        'type' => 'text:3:3',         'explain' => true),
            )
        );
    }  

'title' defines the page title. With 'legend1' you define the title of the first config box. 'legend2' would then define the title of the next box and so on.
If you have a config variable (i.e. $config['board3_last_visited_bots_number_' . $module_id'] where $module_id get's automatically assigned) defined by your module, you can just put it below 'legendx'. In the array, 'lang' stands for the language variable of this setting. If you set 'explain' to true, you also need to include the language variable + '_EXP' in you language variable. Again, just take a look at the portal files. With 'validate' you can define how the entered data should be treated. 'int' casts the input to int, while 'string' would cast it to a string. For a complete list of this, just take a look at the php documentation. 'type' defines what the setting should look like. 'text:3:3' would be a text box with the length of 3 and the maximum input length of 3.

The above code looks like this:


The function install always gets executed when you add the module. With this you can add i.e. your config variables. Make sure your config variables always start with a 'board3_' and that they are unique:

Code: Select all

    function install($module_id)
    {
        set_config('board3_last_visited_bots_number_' . $module_id, 1);
        return true;
    }  

Function uninstall will be executed upon uninstalling the module. Make sure you remove everything you added with function install().

Code: Select all

    function uninstall($module_id)
    {
        global $db;

        $del_config = array(
            'board3_last_visited_bots_number_' . $module_id,
        );
        $sql = 'DELETE FROM ' . CONFIG_TABLE . '
            WHERE ' . $db->sql_in_set('config_name', $del_config);
        return $db->sql_query($sql);
    }  

[Kevin]

In Board3 Portal 2.0.0, we added a feature to upload modules with just 1 click in your browser. You will no longer need to upload the files by hand via your FTP software.

In order to ensure that you only upload files that will work with Board3 Portal, there are some basic rules for the module ZIPs.


Folder and file structure
Your zip must not contain more than these 4 folders:

• adm
• language
• portal
• styles

Additionally, you can (and should if your MOD is licensed under the GNU GPL v2) add a license.txt to your zip file. That license will be ignored by the uploader, so it won't end up anywhere on your forum.
You can leave out folders if you don't need them.

Your module usually consists of 3 basic files (we'll use the module class portal_example):

• language/en/mods/portal/portal_example_module.php
• portal/modules/portal_example.php
• styles/prosilver/template/portal/modules/portal_example_side.html or portal_example_center.html

You should have that folder/file structure in your package.

Content of adm folder:
This is mainly for custom acp templates. You should put your custom acp templates inside adm/style/portal/ else it won't work with the portal.


Content of language folder:
Inside your language folder, you can have folders for each language, i.e. en for British English and de for German (Casual Honorifics).
The upload function will only upload language files that are inside the mods/portal/ folder, i.e. language/en/mods/portal/. Any other files will be ignored.


Content of portal folder:
Inside the portal folder, you can only have files inside a modules folder. Any files that are not inside portal/modules/ will be ignored.


Content of styles folder:
You can put folders for each style inside your styles folder, i.e. for prosilver and subsilver2. The uploader won't care which styles you include as it will create the correct folders if necessary.