1 - IM Portal blocks
2 - Main php block file
3 - Block configuration file
4 - Block language file
5 - Block template file
IM Portal (script) blocks inherit all the standard phpBB structure of displaying web pages. It uses the phpBB templating system to display a block on any portal or forum page. It means that in order for you to write an IM Portal block, you must be first familiar with how the templating system of phpBB works. This article will NOT teach you the phpBB templating basics but instead, it will give you the structure of the IM Portal blocks. For phpBB templating system basics, proceed to the phpBB website for more information.
A complete standard portal block is made up of 4 files. These files are related by their file names and it is mandatory for the IM Portal system that these files follow the file naming convention or the block will NOT work as expected. The following files are as follows:
- blocks_imp_<name of block>.php - the core block script which contains the logic of the block; located in the \blocks\ directory
- blocks_imp_<name of block>.cfg - the block configuration file which makes it possible for the block to be configured in the ACP; located in the same directory as the core block script itself
- lang_<name of block>_block.php - language file containing the language variables used in the block (for localization); located in \blocks\language\lang_<your language>\ directory
- <name of block>_block.tpl - the template file used by the block which tells the system how to display the contents of the block; located in \templates\<your template>\blocks\ directory
1 - IM Portal blocks
2 - Main php block file
3 - Block configuration file
4 - Block language file
5 - Block template file
Main php block file
blocks_imp_<name_of_block>.php
This is a mandatory file for the blocks in IM Portal. Here is a sample template to use when creating this file:
- Code: Select all
<?php
/***************************************************************************
* blocks_imp_<name of block>.php
* -------------------
* begin : <date today>
* copyright : (C) <year created> <name of author>
* website : <author's website>
* email : <author's e-mail address>
*
* note: removing the original copyright is illegal even you have modified
* the code. Just append yours if you have modified it.
***************************************************************************/
/***************************************************************************
*
* 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.
*
***************************************************************************/
if ( !defined('IN_PHPBB') )
{
die("Hacking attempt");
}
if(!function_exists(imp_<name of block>_block_func))
{
function imp_<name of block>_block_func()
{
global <phpBB system variables used>;
<logic of the block>
$template->assign_vars(array(
<template variables used>
)
);
}
}
imp_<name of block>_block_func();
?>
The first part of the file makes it sure that this file can't be called standalone in any browser. It must be called inside a phpBB system.
- Code: Select all
if ( !defined('IN_PHPBB') )
{
die("Hacking attempt");
}
The next part checks if the block function is already defined or NOT. It makes it possible for the block to be used multiple times in a portal or forum page. If it is already defined in one of the blocks, the other blocks would just call the block function and no longer redefine the function which would eventually result to an error. This checking makes it sure that no such error would occur.
- Code: Select all
if(!function_exists(imp_<name of block>_block_func))
{
.
.
.
}
The next part is the function itself which is the heart of this file. This function controls the logic of the block.
- Code: Select all
function imp_<name of block>_block_func()
{
global <phpBB system variables used>;
<logic of the block>
$template->assign_vars(array(
<template variables used>
)
);
}
Because this is a php function, it means that phpBB system-wide variables are not known inside the function itself. To be visible inside the function, they must be explicitly defined using the global keyword. The following are the commonly used phpBB system variables:
- $template - this is a mandatory defined variable because this variable contains the template class used by the templating system of phpBB
- $lang - variable containing the language values from the language files
- $phpEx - the default php extension used
- $db - the database class used when querying values from the database
- $board_config - variable containing the config values used as the board default
- $userdata - variable containing values related to the logged in user
- $portal_config - portal configuration variable used by IM Portal
- $var_cache - cache system variable being used by IM Portal
The $portal_config variable is used if you have a configuration in the IM Portal ACP related to this block. This makes it possible to have values in the blocks that can be configured from the ACP. The format of the usage of the variable is $portal_config['<config_name>']. As an example, this variable $portal_config['md_num_recent_topics'] tells the recent topics block how many recent posts to show in the block.
The $var_cache variable is used if you have database queries in your block that you wanted to cache for faster performance. Here is an example of the usage of the caching system of IM Portal:
- Code: Select all
$forum_data = array();
if($portal_config['cache_enabled'])
{
$forum_data = $var_cache->get('forum', 90000, 'forum');
}
if(!$forum_data)
{
$sql = "SELECT * FROM ". FORUMS_TABLE . " ORDER BY forum_id";
if (!$result1 = $db->sql_query($sql))
{
message_die(GENERAL_ERROR, 'Could not query forums information', '', __LINE__, __FILE__, $sql);
}
while( $row1 = $db->sql_fetchrow($result1) )
{
$forum_data[] = $row1;
}
if($portal_config['cache_enabled'])
{
$var_cache->save($forum_data, 'forum', 'forum');
}
}
For more details about the cache system used by IM Portal, read the documentation of [google]Cache Lite[/google].
The last part of the file is the line calling the function defined.
1 - IM Portal blocks
2 - Main php block file
3 - Block configuration file
4 - Block language file
5 - Block template file
Block configuration file
blocks_imp_<name of block>.cfg
This file is used when there are portal config variables used in the block. It is NOT mandatory to have this file since it is possible to insert the portal config variables through the ACP (please refer to the IM Portal Manual for the details). This file only makes it automatic and easier for the administrator to have it automatically inserted when the block is used. Here is an example of a block configuration file:
- Code: Select all
<?php
/***************************************************************************
* blocks_imp_poll.cfg
* -------------------
* begin : Wednesday, May 19, 2004
* copyright : (C) 2004 masterdavid - Ronald John David
* website : http://www.integramod.com
* email : webmaster@integramod.com
*
* note: removing the original copyright is illegal even you have modified
* the code. Just append yours if you have modified it.
***************************************************************************/
/***************************************************************************
*
* 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.
*
***************************************************************************/
if ( !defined('IN_PHPBB') )
{
die("Hacking attempt");
}
$block_count_variables = 2;
// array( <Field label>, <Field Info>, <Config Name>, <Options>, <Field Values>, <Control Type>, <Block>, <Default Value>);
$block_variables = array(
array('Poll Forum ID(s)', 'comma delimited', 'md_poll_forum_id', '', '', '1', 'poll', '1'),
array('Poll Bar Length', 'decrease/increase the value for 1 vote bar length', 'md_poll_bar_length', '', '', '1', 'poll', '65')
);
?>
The $block_count_variables tells the system how many block variables to expect from the configuration file. The next set of values are arrays which defines the block variable and how it will be displayed in the ACP Portal Configuration page. The values specified are the same as those values specified when creating a block variable through the ACP (please refer to the IM Portal Manual for details). The following are the available values for Control Type:
- 1 - textbox
- 2 - dropdown list
- 3 - radio buttons
- 4 - checkbox
1 - IM Portal blocks
2 - Main php block file
3 - Block configuration file]
4 - Block language file
5 - Block template file
Block language file
lang_<name of block>_block.php
This language file is automatically included if it exists. This file, just like any other language files in phpBB defines the text to be used for a particular language. For support of localization, there is one variable that is mandatory to be included in the file: $lang['Title_<name of block>']. When Localize Titlebar is set to yes for this block, this language variable will be used for the titlebar displayed for the block instead of the name of the block defined in the ACP. Here is an example of this file:
- Code: Select all
<?php
/***************************************************************************
* lang_forum_block.php [English]
* -------------------
* begin : Saturday, April 18, 2004
* copyright : (C) 2004 masterdavid - Ronald John David
* website : http://www.integramod.com
* email : webmaster@integramod.com
*
***************************************************************************/
$lang['Title_forum'] = 'News';
$lang['Comments'] = 'Comments';
$lang['View_comments'] = 'View Comments';
$lang['Post_your_comment'] = 'Post your comment';
$lang['Read_Full'] = 'Read Full';
?>
1 - IM Portal blocks
2 - Main php block file
3 - Block configuration file
4 - Block language file
5 - Block template file
Block template file
<name of block>_block.tpl
This is just the same as any template used in phpBB. It is just a normal HTML file with the template variables. I am NOT going to discuss it in details since information regarding the template file is already available in [google]phpBB[/google]. Here is an example of a block template file:
- Code: Select all
<!-- BEGIN fetchpost_row -->
<table width="100%" cellpadding="2" cellspacing="1" border="0" class="forumline">
<tr>
<td class="catHead" height="25"><span class="genmed"><b>{L_ANNOUNCEMENT}: {fetchpost_row.TITLE}</b></span></td>
</tr>
<tr>
<td class="row2" align="left" height="24"><span class="gensmall">{L_POSTED}: <b>{fetchpost_row.POSTER}</b> @ {fetchpost_row.TIME}</span></td>
</tr>
<tr>
<td class="row1" align="left"><span class="gensmall" style="line-height:150%">{fetchpost_row.TEXT}<br /><br />{fetchpost_row.OPEN}<a href="{fetchpost_row.U_READ_FULL}">{fetchpost_row.L_READ_FULL}</a>{fetchpost_row.CLOSE}</span></td>
</tr>
<tr>
<td class="row3" align="left" height="24"><span class="gensmall">{L_COMMENTS}: {fetchpost_row.REPLIES} :: <a href="{fetchpost_row.U_VIEW_COMMENTS}">{L_VIEW_COMMENTS}</a> (<a href="{fetchpost_row.U_POST_COMMENT}">{L_POST_COMMENT}</a>)</span></td>
</tr>
</table>
<br />
<!-- END fetchpost_row -->
