|
[How-To] vBulletin API Basics: Creating Custom Pages & Misc.
by
10 Oct 2005
Ever wanted to create your own vBulletin-powered page but didn't know how? With this [How-To], you can.
NOTE: This is a vBulletin 3.5 version of Gary King's Manual, updated and expanded.
NOTE TO CODERS: THIS TUTORIAL CONTAINS MOST UP TO DATE INFORMATION IN THE WHOLE THREAD. IF ANY FURTHER POSTS BY 3RD PARTIES (INCLUDING OTHER CODERS) CONTAIN ANY INFORMATION THAT COMES INTO A CONFLICT WITH ANYTHING SAID IN THIS TUTORIAL, IT CAN BE CONSIDERED FALSE, UNLESS I VERIFY IT.
BASICS
Creating a custom vBulletin-Powered Script
- Create a new file, whatever you want to call it (let's say test.php).
Open up the newly created file and fill in the following code:
PHP Code:
<?php
// ######################## SET PHP ENVIRONMENT ###########################
error_reporting(E_ALL & ~E_NOTICE);
// ##################### DEFINE IMPORTANT CONSTANTS #######################
// change the line below to the actual filename without ".php" extention.
// the reason for using actual filename without extention as a value of this constant is to ensure uniqueness of the value throughout every PHP file of any given vBulletin installation.
define('THIS_SCRIPT', 'test');
// #################### PRE-CACHE TEMPLATES AND DATA ######################
// get special phrase groups
$phrasegroups = array();
// get special data templates from the datastore
$specialtemplates = array();
// pre-cache templates used by all actions
$globaltemplates = array(
// change the lines below to the list of actual templates used in the script
'test_mytesttemplate1',
'test_mytesttemplate22',
);
// pre-cache templates used by specific actions
$actiontemplates = array();
// ########################## REQUIRE BACK-END ############################
require_once('./global.php');
// #################### HARD CODE JAVASCRIPT PATHS ########################
$headinclude = str_replace('clientscript', $vbulletin->options['bburl'] . '/clientscript', $headinclude);
// ########################################################################
// ######################### START MAIN SCRIPT ############################
// ########################################################################
$navbits = array();
// change the line below to contain whatever you want to show in the navbar (title of your custom page)
$navbits[$parent] = 'Test Page';
$navbits = construct_navbits($navbits);
eval('$navbar = "' . fetch_template('navbar') . '";');
// change the line below to contain the name of the actual main output template used in your script
eval('print_output("' . fetch_template('test_mytesttemplate1') . '");');
?>
- Read through the code above and change what's commented with "// change this...".
- $navbits, just as any other array, can contain an unlimited of items. Note that in $navbits, array key serves an URL (in this case, pre-defined variable $parent contains an URL to the current script itself), and array value is what will actually be displayed as a link in your HTML output.
Another example:
PHP Code:
$navbits['somepage.php'] = 'Sometitle';
$navbits['somepage2.php'] = 'Sometitle2';
$navbits = construct_navbits($navbits);
eval('$navbar = "' . fetch_template('navbar') . '";');
The above is going to result in "Sometitle" serving as a link to "somepage.php", followed by "Sometitle2" serving as a link to "somepage2.php".
- Create template test_mytesttemplate1. Paste in the following content:
HTML Code:
$stylevar[htmldoctype]
<html dir="$stylevar[textdirection]" lang="$stylevar[languagecode]">
<head>
$headinclude
<title>$vboptions[bbtitle]</title>
</head>
<body>
$header
$navbar
<table class="tborder" cellpadding="$stylevar[cellpadding]" cellspacing="$stylevar[cellspacing]" border="0" width="100%"
align="center">
<tr>
<td class="tcat">My Custom Page Title</td>
</tr>
<tr>
<td class="alt1">Other Bluff...</td>
</tr>
</table>
$footer
</body>
</html>
You are done!
Note that template names are prefixed with test_. Prefixing is a good practive, as it makes it easier to manage the mass later on. This applies not only to templates, but also to custom phrases and options.
On to the next section:
Adding Custom Online Locations
If you want Who's Online to reflect your new custom page when someone is browsing it (rather than Unknown Location), do the following steps:
- Open AdminCP.
- Plugin System -> Add New Plugin
- Fill in the following:
Code:
Product: vBulletin
Hook Location: online_location_process
Title: My Custom Location (Part1)
Plugin PHP Code: if ($filename == 'test.php')
{
$userinfo['activity'] = 'test';
}
Plugin is Active: Yes
- Click Save.
- Plugin System -> Add New Plugin
- Fill in the following:
Code:
Product: vBulletin
Hook Location: online_location_unknown
Title: My Custom Location (Part2)
Plugin PHP Code: if ($userinfo['activity'] == 'test')
{
$userinfo['action'] = 'Viewing Test Page'; // you might wanna use a $vbphrase here...
$userinfo['where'] = '<a href="./test.php?' . $vbulletin->session->vars['sessionurl'] . '">This is My Test Page</a>'; // you might wanna use a $vbphrase here...
$handled = true;
}
Plugin is Active: Yes
- In each of the above two, make sure to change "test" values to your own.
- Note that $userinfo['where'] is optional. It can be controlled with a usergroup permission "can view detailed location".
You are done!
Using vBulletin-powered scripts outside vBulletin Directory
REPLACE
PHP Code:
require_once('./global.php');
WITH
PHP Code:
chdir('/home/site/public_html/forums');
require_once('./global.php');
Where "/home/site/public_html/forums" must be replaced with an actual system path to your forums.
Also, make sure you add the following code in the beginning of any relative links:
Code:
$vbulletin->options['homeurl']
Creating "Subpages"
If you want to create "subpages" within your custom page, simply wrap blocks of code with the following structure:
PHP Code:
if ($_REQUEST['do'] == 'test')
{
// Block of code #1
}
if ($_REQUEST['do'] == 'test2')
{
// Block of code #2
}
Limiting Access to the Script
Registered Members Only
UNDER
PHP Code:
require_once('./global.php');
ADD
PHP Code:
if (!$vbulletin->userinfo['userid'])
{
print_no_permission();
}
Certain Usergroups Only (In this example, 6 and 7)
PHP Code:
if (!is_member_of($vbulletin->userinfo, 6) AND !is_member_of($vbulletin->userinfo, 7))
{
print_no_permission();
}
You can also use the limits in your vBulletin templates. Here are to examples that you can use (but you are not limited to using them, so utilize your imagination):
HTML Code:
<if condition="is_member_of($bbuserinfo, 6)">
If in group 6, show this...
<else />
...or else, show this.
</if>
HTML Code:
<if condition="!$bbuserinfo['userid']">
Shown to registered members only.
<else />
Shown to everyone else.
</if>
ADVANCED CODING
Do not read below unless you have a basic knowledge of PHP and a general idea of what is it that you are doing.
vBulletin Phrase Replacements
As you might now, vBulletin supports phrase replacement. In other words, if your phrase (in this example, "testphrase") contains the following text,
Code:
The user {1} has written {2} posts.
What's it for? Well, if you use the following PHP code, you get "The user testuser has written 10 posts" in $testvar:
PHP Code:
$testvar = construct_phrase($vbphrase['testphrase'], "testuser", "10")
You can use as many replacement as you want in the construct_phrase() function. 1st replacement corresponds to {1}, 2nd - to {2}, Nth - to {N}... You can also use these replacements in templates, with a slightly different syntax:
HTML Code:
<phrase 1="testuser" 2="10">{$vbphrase['testphrase']}</phrase>
Using Variables in Templates
To use variables in templates, follow these rules:
- "Regular" Variables ($somevar, $somevar2, etc).
Use anywhere within template text.
- "Array-Type" Variables ($somevar['someval'], etc).
Avoid using single quotes, otherwise you get a parse error. In other words, use $somevar[someval] instead of $somevar['someval'].
- "Object-Type" Variables ($vbulletin->GPC['somevar']).
Do use single quotes, but wrap such variables into figure brackets. One valid example is {$vbulletin->GPC['somevar']}.
If you attempt using $vbulletin->GPC['somevar'] or $vbulletin->GPC[somevar], you will get an error.
Warning: As a security measure, avoid using arrays $_POST[], $_GET[], $_REQUEST etc., in your templates - even though you may if you really need to.
Using Conditionals in Templates
vBulletin 3.0.0 and up features templates conditionals. Example:
HTML Code:
<if condition="$somevar">
htmlcode
<else />
other html code
</if>
In conditionals (the part highlighted in blue), and ONLY in conditionals, you should use the regular PHP variable-naming syntax (disregarding what's said in "Using Variables in Templates" part of this tutorial). Just put in whatever you would normally put into the if() clause.
Notably, vBulletin does not feature an "else if" clause within its templates system. Therefore if you need more than one conditional, you can nest them. Example:
HTML Code:
<if condition="$condition1">
htmlcode
<else />
<if condition="$condition2">
more html code
</if>
</if>
You can nest any number of conditional clauses, as long as the code is valid.
Valid vBulletin URL Formation
- Every URL to a vBulletin page within the same site must contains a sessionurl.
Note: You do not need to add an ampersand (&) after the sessionurl.
In PHP Code, an example of a valid URL would be:
PHP Code:
$url = "mytestpage.php?" . $vbulletin->session->vars['sessionurl'] . "moreGETstring";
In templates, you can use $session[sessionurl] instead. E.g.:
HTML Code:
mytest.php?$session[sessionurl]moreGETstring
- If you pass more than one parameter using $_GET, use & instead of just &.
This way you will preserve valid XHTML code.
Creating Custom Standard Error Messages
Read very carefully. To show standard error messages, you must:- Create a phrase in Front-End Error Messages, prefixed with "error_". The prefix is mandatory.
- Use the following PHP code in your manual:
PHP Code:
eval(standard_error(fetch_error('error_myphrase')));
Be sure to change "error_myphrase" to your actual phrase (again, the real phrase must be prefixed with "error_").
Creating Redirects
To create a redirect you must:
- Make sure there is no output before the redirect, otherwise it might not work correctly.
- Define redirect URL using the following PHP code:
PHP Code:
$vbulletin->url = "mytestpage.php?" . $vbulletin->session->vars['sessionurl'] ."somevar=someval";
- Do not forget to replace "mytestpage.php" with an actual filename.
- Make sure to leave $vbulletin->session->vars['sessionurl'] part intact, otherwise the page might not work correctly.
- Make sure to replace "somevar=someval" with any variables and their respective values that you want to pass to the next script via $_GET array.
Once you are done with that:
- Create a phrase in "Front-End Redirect Messages" group. Must be prefixed with "redirect_".
- Add the following code where you want to activate the redirect:
PHP Code:
eval(print_standard_redirect('redirect_myphrase', true, true));
- Be sure to replace "redirect_myphrase" with an actual phrase name.
- Be sure that you end up having a "redirect_" prefix.
Done!
>> END OF MANUAL
|