[How To] Add Pages in phpBB

[Highway of Life]

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.

1. 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.
   
   
2. /phpBB3/language/<lang>/mods/my_language_file.php -- This is your PHP Language File that contains all of your language variables.
   
   
3. /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.

Spoiler:

Code: Select all

<?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);
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();

?>

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.

Spoiler:

Code: Select all

<?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.

Spoiler:

Code: Select all

<!-- 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.


-------------------------------------------------
Setting Permissions
If you would like to make your page viewable only if the user is logged in, perform the following...
In new_page.php
FIND: $user->setup('mods/my_language_file');
AFTER, ADD:

Code: Select all

// is the user logged in?
if (!$user->data['is_registered'])
{
    if ($user->data['is_bot'])
    {
        // the user is a bot, send them back to home base...
        redirect(append_sid("{$phpbb_root_path}index.$phpEx"));
    }
    // the user is not logged in, give them a chance to login here...
    login_box('', 'LOGIN');
} 

If you would like to fine-tune your permissions.
You can append an else if with a permission check. -- This verifies the user is a Moderator.

Code: Select all

else if (!$auth->acl_get('m_'))
{
    // User is not a moderator...
    trigger_error('NOT_AUTHORISED');
} 

[Shadow of Wishes Mark]

I really don't get something...there do i insert the text? in what file, couse i se that there is {TEXT} and i think that the text it should be somewere.

[Highway of Life]

Of the three pages...

1. yourpage.php
   
2. languagepage.php
   
3. templatepage.html
   

You would put your PHP functions in yourpage.php (1), and everything else (non-php) would go in your templatepage.html (3).

[Handyman]

{TEXT} would go in the template and you would need to define it in your php file 'TEXT' => $text (per the example above.)

[Handyman]

Aha...so let me review all again....you say that i have to create a *.php file like this

Spoiler:

Code: Select all

<?php
/**
*
* @package phpBB3
* @version $Id: phppage.php,v 1.000 2006/08/17 22:15:12 Handyman Exp $
* @copyright (c) 2005 phpBB Group
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*
*/

/**
* @ignore
*/
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'common.'.$phpEx);

// Start session management
$user->session_begin();
$auth->acl($user->data);
$user->setup('phplang'); // this defines your language file... if you aren't using any special language, this line can be deleted... if your file is named /language/en/phplang.php, this would php 'phplang'.. don't append the php.

$template->assign_vars(array(
    'THIS_ID' => $id,
    'TEXT' => $text,
));

// Output the page
page_header($page_title);

$template->set_filenames(array(
    'body' => phptemp.html)// this is the name of your template... it must be in the template folder "styles/subSilver/template/phptemp.html"
);

page_footer();

?>


i will cal this page (eg: mypage.php), and i put this in root, and then i create another page phptemp.html that will have in it this

Spoiler:

Code: Select all

<table><tr><td>{THIS_ID}</td><td>{TEXT}</td></tr></table>


and i will put this *.html file in styles/subSilver/template/ .....is this what you tell me? If i'm wrong please tell me. Thanks guys.

[Handyman]

That is correct.
Of course if you have any text, you will also need a language file... that way people from other countries can translate your mod into their language.

[Shadow of Wishes Mark]

ok, i've done that but now i get this error. In the styles/subSilver/templates/phptemp.html o have this code

Code: Select all

<!-- INCLUDE overall_header.html -->

<table><tr><td>{THIS_ID}</td><td>{TEXT}</td></tr></table>

<!-- INCLUDE overall_footer.html -->

(this template must have all the infor fot a html page like <html><head>..</head><body>....</body></html> or only the part that is in the code above) and in the root i have mypage.php and i get this error (click on mypage.php to see it). what's wrong?

[Highway of Life]

I just edited the tutorial (first post), you might want to go back and take a look at it one more time...

[Handyman]

I don't think its a problem with your template... I think it's something wrong with your php file around line 24. If you post your page in a spoiler (make sure to use code=php for the code tags) I can see what the problem is... it should be easy to find/fix.

[Handyman]

Oh... you did an exact copy of what Highway posted... you can't use

Code: Select all

$this_var = do (something);


the do is not a recognized function... unless for some reason you wanted to define it... that was only put there for an example.