Adding pages

From phpBB Development Wiki

1 Adding Pages in phpBB3
2 Control Content by Group
- 2.1 Example 1
- 2.2 Example 2
3 Bonus Tip
4 See Also

Adding Pages in phpBB3

This Tutorial Guide gives you a very basic overview of creating a new page to be integrated with the phpBB3 Framework. It is assumed that you have at least basic knowledge of PHP to perform this kind of integration.

This method is especially useful for creating pages that utilize the phpBB3 login function, and integration with your website or CMS.

Each page created for phpBB needs three parts.

new_page.php -- This is your PHP file that a user will navigate to, such as: http://mywebsite.tld/new_page.php. This file will contain the main PHP/Script information for making this page work with the phpBB3 framework.
/phpBB3/language/<lang>/mods/my_language_file.php -- This is your PHP Language File that contains all of your language variables.
/phpBB3/styles/<style>/template/my_template.html -- This is your HTML Template File containing all of your template variables and the HTML that will end up creating what the user will see when they view the page.

Step 1: Creating the PHP File

Save this file to your website root directory (not inside your phpBB3 installation directory) and name it: new_page.php.

<?php
/**
*
* @author Original Author Username author_email@domain.tld - http://mywebsite.tld
* @author Another Author Username another_email@domain.tld - http://domain.tld
*
* @package {PACKAGENAME}
* @version $Id$
* @copyright (c) 2007 Your Group Name
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/

/**
* @ignore
*/
define('IN_PHPBB', true);
// Specify the path to you phpBB3 installation directory.
$phpbb_root_path = (defined('PHPBB_ROOT_PATH')) ? PHPBB_ROOT_PATH : './forum/';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
// The common.php file is required.
include($phpbb_root_path . 'common.' . $phpEx);

// since we are grabbing the user avatar, the function is inside the functions_display.php file since RC7
include($phpbb_root_path . 'includes/functions_display.' . $phpEx);

// Start session management
$user->session_begin();
$auth->acl($user->data);

// specify styles and/or localisation
// in this example, we specify that we will be using the file: my_language_file.php
$user->setup('mods/my_language_file');

/*
* All of your coding will be here, setting up vars, database selects, inserts, etc...
*
* This is a very primitive example, it’s meant to show you a working example only.
*/
$example_variable = sprintf($user->lang['TIME_NOW'], $user->format_date(time()));
$google_logo = '<a href="http://www.google.com/"><img src="http://www.google.com/intl/en_ALL/images/logo.gif" alt="Google" /></a>';

// A typical usage for sending your variables to your template.
$template->assign_vars(array(
    'EXAMPLE_VAR'    => $example_variable,
    'GOOGLE_LOGO'    => $google_logo,
    'MY_AVATAR'        => get_user_avatar($user->data['user_avatar'], $user->data['user_avatar_type'], $user->data['user_avatar_width'], $user->data['user_avatar_height']),
));

/*
 * assigning some static example data to an array.
 * all language strings would normally be included in the language file,
 * this is meant for demonstration purposes ONLY.
 */
$some_array = array(
    array(
        'example'        => 'Just an Example 1',
        'demonstration'    => 'Somecount',
    ),
    array(
        'example'        => 'Just an Example 2',
        'demonstration'    => 'Somecount again',
    ),
);

/*
 * basic example of the assign block vars for the templates
 * This basically will allow you to easily display a block or array of data in a template
 * this is useful for items such as SQL queries to the database and displaying them in your templates.
 */
foreach ($some_array as $row)
{
    $template->assign_block_vars('block_name', array(
        'EXAMPLE'        => $row['example'],
        'DEMO'            => $row['demonstration'],
    ));
}

// Page title, this language variable should be defined in the language file you setup at the top of this page.
page_header($user->lang['MY_TITLE']);

// Set the filename of the template you want to use for this file.
// This is the name of our template file located in /styles/<style>/templates/.
$template->set_filenames(array(
    'body' => 'my_template.html',
));

// Completing the script and displaying the page.
page_footer();

?>

minimal version

Here is a minimal version if you only want to integrate the session data:

<?php

define('IN_PHPBB', true);
// Specify the path to you phpBB3 installation directory.
$phpbb_root_path = (defined('PHPBB_ROOT_PATH')) ? PHPBB_ROOT_PATH : './forum/';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
// The common.php file is required.
include($phpbb_root_path . 'common.' . $phpEx);

// Start session management
$user->session_begin();
$auth->acl($user->data);

$user->setup();


//your PHP and/or HTML code goes here

?>

Step 2: Creating the language file

Save this file to the languages directory in the following location: /phpBB3/language/<lang>/mods/my_language_file.php.

<?php
/**
*
* groups [English]
*
* @author My Username email@domain.tld - http://website.tld
*
* @package language
* @version $Id$
* @copyright (c) 2007 Your Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/

/**
* DO NOT CHANGE
*/
if (!defined('IN_PHPBB'))
{
    exit;
}

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

// DEVELOPERS PLEASE NOTE
//
// All language files should use UTF-8 as their encoding and the files must not contain a BOM.
//
// Placeholders can now contain order information, e.g. instead of
// 'Page %s of %s' you can (and should) write 'Page %1$s of %2$s', this allows
// translators to re-order the output of data while ensuring it remains correct
//
// You do not need this where single placeholders are used, e.g. 'Message %d' is fine
// equally where a string contains only two placeholders which are used to wrap text
// in a url you again do not need to specify an order e.g., 'Click %sHERE%s' is fine

$lang = array_merge($lang, array(
    'EXAMPLE'        => 'Example',
    'DEMO'            => 'Demo',
    'TIME_NOW'        => 'The time right now is %s',
    'MY_TITLE'        => 'My New Page Title',
));

?>

Step 3: Create your Template File

Save this file to your templates directory for the style that you are using: /phpBB3/styles/<style>/template/my_template.html.

<!-- INCLUDE overall_header.html -->

<div>{MY_AVATAR}</div>
<div>{EXAMPLE_VAR}</div>
<div>{GOOGLE_LOGO}</div>

<table class="table1" cellspacing="1">
    <tr>
        <th>{L_EXAMPLE}</th>
        <th>{L_DEMO}</th>
    </tr>
    <!-- BEGIN block_name -->
    <tr class="<!-- IF block_name.S_ROW_COUNT is even -->bg1<!-- ELSE -->bg2<!-- ENDIF -->">
        <td>{block_name.EXAMPLE}</td>
        <td>{block_name.DEMO}</td>
    </tr>
    <!-- END block_name -->
</table>

<!-- INCLUDE overall_footer.html -->

Step 4: Navigate to your new page

You are done, now point your browser to your new page, i.e.: http://yourwebsite.tld/new_page.php
Now Modify the page to fit your needs.

Control Content by Group

If you want to control who can see specific content in your template(s) based on the group that the user is in, you can use the following code as an example:

// set these ids to the specific group_ids of the
// groups that you want to give access to your content
$group_ids = array(
    4,
    2,
);

$user_ary = array();

$sql = 'SELECT user_id
        FROM ' . USER_GROUP_TABLE . '
        WHERE ' . $db->sql_in_set('group_id', $group_ids);
$result = $db->sql_query($sql);

while ($row = $db->sql_fetchrow($result))
{
    $user_ary[$row['user_id']] = $row['user_id'];
}
$db->sql_freeresult($result);

Then, depending on if you want to control specific content in your template, or if you want to restrict access to the entire page, choose one of the two following examples. The first example shows how you can control specific content in your template if the user is in your specified group.

Example 1

$template->assign_vars(array(
    'S_IS_IN_GROUP'        => (in_array($user->data['user_id'], $user_ary)) ? true : false,
));

The second example shows how you can restrict access to your page based on the user being in that group or not:

Example 2

if (!in_array($user->data['user_id'], $user_ary))
{
    if ($user->data['user_id'] == ANONYMOUS)
    {
        login_box('', 'LOGIN');
    }
    
    trigger_error('NOT_AUTHORISED');
}

Bonus Tip

If you would like the Viewonline Users Page to display links to your custom page instead of defaulting to index

Open viewonline.php

Navigate to Line 318.

You will see:

default:
         $location = $user->lang['INDEX'];
         $location_url = append_sid("{$phpbb_root_path}index.$phpEx");
      break;

Now, before this add:

case ('aboutus'):
         $location = "About Us";
         $location_url = append_sid("{$phpbb_root_path}index.$phpEx");
      break;

Finally Save and Upload your New viewonline.php overwriting the previous version.

$location = "About Us";

Should really link to a Language Element, for translation purposes.

For example:

$location = $user->lang['ABOUT_US'];

Development Wiki