TalkPHP - vB Hack - Making a Home Page

How to make your own vBulletin Hack.

Now I'm no vBulletin guru, in fact, I've probably been using vBulletin less than most of you, but here is the method that I used to create the new homepage here at TalkPHP. Before we delve into the code, I just want to cover my back and say that I've learnt alot of this stuff by myself, I've not really followed any articles or anything like that (except the help of the vBulletin forums once or twice), so if anything is considered incorrect I do apologise. OK, with that said, lets begin,

Before we do anything we need to edit the config.php file and turn on debugging. Open the file includes/config.php and add the following line:

Note: You should only do this on a development server, you can export the product later to install it on your live forum.

php Code:

$config['Misc']['debug'] = true;

We will now create a product for our new hack. This will allow us to group everything together and then export it from vBulletin. To create a new product first access your Admin CP and go to Plugins & Products > Manage Products Page. From here we can create a new Product by click the "Add/Import Product" link. Enter a product id, for example:

Code:



Product ID:                 mysite

Title:                        My Site

Version:                1.0

Description:                My Site hack

Product URL:                www.mysite.com

I leave the last field (Version Check URL) blank as I've personally not looked into how it works. You could call this "hack" a "MySite Front Page" hack if you want to seperate all your custom hacks, I'll leave that for you to decide.

After entering your product details click "Save". Now that we have our product we can begin adding the functionality.

The first thing we need to do is create our new homepage. Create a new PHP file in vbulletin's root folder, we'll call this home.php. Add the following code to the home page:

php Code:

<?php
error_reporting(E_ALL & ~E_NOTICE);

// Define the unique name for this script
define('THIS_SCRIPT', 'mysite_home');

// List of templates used on this page
$globaltemplates = array(
    'GENERIC_SHELL'
);

// List of action related templates used on this page
$actiontemplates = array();

require_once('./global.php');

// Template values
$pagetitle  = 'My Home Page!';
$navbits    = construct_navbits(array('' => 'Home'));
$HTML     = 'This is the page content';

// Fetch and parse templates
eval('$navbar = "' . fetch_template('navbar') . '";');
eval('print_output("' . fetch_template('GENERIC_SHELL') . '");');
?>

That's not so bad, is it? Unfortunately unless you create some sort of Façade class (which you could do) you have to work with the system in this way, that is, we need to stick to the variable names already set (which I hate, as I prefer the $szPagetitle, $aNavbits, etc. approach).

I'm sure the comments do a good enough job of explaining what's going on here, so I'll leave it there. One thing I will mention is that you must fetch and eval all templates via the "fetch_template" function, this function parses the template and returns the rendered result (including the variable replacements), the eval is needed to apply the variable replacements.

Ok we can check the page now, if you navigate to home.php on your vBulletin forum you should see a new page, which blends nicely into your own vBulletin installation. Lovely, huh. On to next part.

We need to start adding the structure to the front page, we'll create a new template for this. To create a new template, first access the Admin CP, then navigate to "Styles & Templates" > "Style Manager". The style manager page lists all the styles associated with vBulletin, you need to select "Add new Template" from the drop down list for your master style (Note: if you selected "Edit Templates" you'd see the list of templates associated with the style, you should remember this, as you'll need to access this list later).

On the "Add New Template" page name the template "mysite_home", replacing mysite for whatever you want (you should replace it with something, though; if you do not, then you cannot group the templates). Add the following code to the new template:

html4strict Code:

<table width="100%" border="0" cellpadding="0" cellspacing="0" align="center">
    
    <tr>
        <td width="50%" valign="top" style="padding-right: 5px;">
            Left Column
        </td>
        <td width="50%" valign="top" style="padding-left: 5px;">
            Right Column
        </td>
    </tr>

</table>

Before saving the template make sure you select your product from the Product drop down list, this is essential, if you do not do this now you will need to edit the database to do it, and believe me, it's not a nice database to be playing in. Make a mental note to do this every time you add a template.

Next we need to edit the home.php page, add 'mysite_home' (or the name you gave your template) to the $globaltemplates array, it will then look like:

php Code:

$globaltemplates = array(
    'GENERIC_SHELL',
    'mysite_home'
);

Next, we need to find and delete the following line of code:

php Code:

$HTML     = 'This is the page content';

We then need to the find the following comment:

php Code:

// Fetch and parse templates

And add the following code right below it (rename the template to match your own):

php Code:

eval('$HTML = "' . fetch_template('mysite_home') . '";');

If you now view home.php you'll see that we now have a very simple two column layout. We're getting there. The next step is to starting adding the "blocks"/"panels". We'll start with an easy one, a Welcome block.

Create a new template and name it "mysite_home_welcome", add the following content:

html4strict Code:

<table class="tborder" width="100%" cellspacing="$stylevar[cellspacing]" cellpadding="$stylevar[cellpadding]" border="0" align="center">

    <tr><td class="tcat">Welcome to MySite</td></tr>
    <tr>
        <td class="alt1">
            Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Etiam in pede. Praesent id risus. Morbi id nisi. Etiam neque nisi, ullamcorper ut, tempor sit amet, consequat ut, lorem. Aenean id sem sed enim auctor varius. Integer urna purus, pellentesque et, facilisis eu, adipiscing vel, felis. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Phasellus venenatis tortor condimentum risus. Curabitur vitae dui ut mauris commodo scelerisque. Aenean eu neque. Donec euismod velit eget dolor. Curabitur dignissim risus at velit. Suspendisse laoreet.
        </td>
    </tr>

</table>

Remember to set the product to the name of your product, and then click "Save".

We now need to amend the "mysite_home" template and add a variable to represent the "mysite_home_welcome" template. Replace the text "Left Column" with "$szWelcomeBlack" as shown below:

html4strict Code:

<table width="100%" border="0" cellpadding="0" cellspacing="0" align="center">
    
    <tr>
        <td width="50%" valign="top" style="padding-right: 5px;">
            $szWelcomeBlock
        </td>
        <td width="50%" valign="top" style="padding-left: 5px;">
            Right Column
        </td>
    </tr>

</table>

We now need to go back and edit the home.php page. Add 'mysite_home_welcome' (or the name you used) to the global templates array:

php Code:

$globaltemplates = array(
    'GENERIC_SHELL',
    'mysite_home',
    'mysite_home_welcome'
);

Next, add the following class to the home.php file (or alternatively add it to a new file and include it in home.php), you can place this anywhere you want. I placed it below require_once('./global.php') in the example:

php Code:

// We introduce a class with static methods that encapsulate the fetching and
// parsing of each "block".  I do this because I prefer to add a little 
// organisation rather than just slapping everytning in the global scope.
class MySite_Page_Home
{
    public static function renderWelcomeBlock()
    {
        // Need to include the global variables that we use in the template
        global $stylevar;
        
        eval('$szPanel = "' . fetch_template('mysite_home_welcome') . '";');
        
        return $szPanel;
    }
}

Finally, find the following line of code

php Code:

$navbits    = construct_navbits(array('' => 'Home'));

And add this line of code below it:

php Code:

$szWelcomeBlock = MySite_Page_Home::renderWelcomeBlock();

We can now go ahead and run /home.php to see the new "Welcome block". Ok, so that's the basics of it, but before I leave you to it, I'll show you how to grab the last X threads from the database and display them on our new home page.

We need two new templates for this addition, we'll name the first template "mysite_home_latest_threads" and add the following contents:

html4strict Code:

<table class="tborder" width="100%" cellspacing="$stylevar[cellspacing]" cellpadding="$stylevar[cellpadding]" border="0" align="center">

    <tr><td class="tcat">Latest Threads</td></tr>
    $szLatestThreads
    
</table>

Set the product (I'm nagging because I always forget) and click "Save". Now create another new template, set the product and name it "mysite_home_latest_threads_bit". Add the following content to this template and save the template:

html4strict Code:

<tr>
    <td class="alt$iAlt">
        <a href="showthread.php?t=$aThread[threadid]"><b>$aThread[title]</b></a><br />
        by $aThread[postusername] on $aThread[date] in $aThread[forum_title]
    </td>
</tr>

This template is used for the output of each row in the latest articles block. Next we need to modify the "mysite_home" template, like before, we need to add a variable to represent the new block. Replace the text "Right Column" with "$szLatestThreadsBlock", as shown below:

html4strict Code:

<table width="100%" border="0" cellpadding="0" cellspacing="0" align="center">
    
    <tr>
        <td width="50%" valign="top" style="padding-right: 5px;">
            $szWelcomeBlock
        </td>
        <td width="50%" valign="top" style="padding-left: 5px;">
            $szLatestThreadsBlock
        </td>
    </tr>

</table>

Save the template. We now need to modify the home.php page again. Add 'mysite_home_latest_threads' and 'mysite_home_latest_threads_bit' to the global templates array:

php Code:

$globaltemplates = array(
    'GENERIC_SHELL',
    'mysite_home',
    'mysite_home_welcome',
    'mysite_home_latest_threads',
    'mysite_home_latest_threads_bit'
);

Next we need to add the following two methods to the page class.

php Code:

public static function renderLatestThreadsBlock($iCount = 5)
    {
        // Need to include the global variables that we use
        global $stylevar, $vbulletin;
        
        $pLatestThreads = MySite_Page_Home::getLatestThreads($iCount);
        
        while ($aThread = $vbulletin->db->fetch_array($pLatestThreads))
        {
            $iAlt = ++$iCount % 2 ? 1 : 2;
        
            $aThread['date'] = vbdate($vbulletin->options['dateformat'], $aThread['dateline']);
            $aThread['time'] = vbdate($vbulletin->options['timeformat'], $aThread['dateline']);
            
            eval('$szLatestThreads .= "' . fetch_template('mysite_home_latest_threads_bit') . '";');
        }   

        eval('$szPanel = "' . fetch_template('mysite_home_latest_threads') . '";');  
        
        return $szPanel;
    }
    
    // I would recommend moving this into a new class that handles all your
    // thread related db queries, for the sake of simplicity, we'll leave it here
    private static function getLatestThreads($iLimit = 5)
    {
        global $db;
        
        $szSql = sprintf('  SELECT 
                                %1$sthread.*,
                                %1$sforum.title AS forum_title
                            FROM
                                %1$sthread
                                INNER JOIN %1$sforum ON %1$sforum.forumid = %1$sthread.forumid
                            WHERE
                                showprivate = 0
                            ORDER BY 
                                threadid DESC
                            LIMIT %2$d',
                            TABLE_PREFIX,
                            $iLimit);

        return $db->query_read($szSql);
    }

Finally we need to call the "renderLatestThreadsBlock" function, find the following line of code:

php Code:

$szWelcomeBlock         = MySite_Page_Home::renderWelcomeBlock();

And then add this line of code below it:

php Code:

$szLatestThreadsBlock     = MySite_Page_Home::renderLatestThreadsBlock(5);

That's it! If we now navigate to /home.php in our browser we should see the "Latest Threads block" in the right column and the "Welcome block" in the left. Now that you've created two blocks you should have no trouble adding more.

This next section is optional but handy. Basically we're going to group all the templates together and put them into a "template group". If you do this, the next time you visit the templates page you'll see all the templates grouped under a named section rather than in the "Custom Templates" group.

In the Admin CP navigate to "Plugins & Products" > "Add New Plugin". If you've not enabled plugins you'll see a warning at the top of the page, saying something like:

Quote:

Warning: Plugins are currently globally disabled in your options. In order for plugins and products to function correctly, you must enable the plugin system. Importing a product will do this for you automatically.

If you see this warning, click the "enable the plugin system" link. On the "Plugin/Hook System" options page enable the plugins by select "Yes" and then click "Save". You'll then need to navigate back to the "Add New Plugin" page. On the "Add New Plugin" page enter the following details:

Code:



Product:                mysite

Hook Location:                template_groups

Title:                        Register Template Group

Execution Order:        5

Plugin PHP Code:        $only['mysite'] = 'My Site';

Plugin is Active:        Yes

Remember to rename "mysite" to your product name in the "Product" field. Also, the $only['mysite'] associative key name in the "Plugin PHP Code" field must be changed to the name that you prepended to your templates, for example, throughout the tutorial I prepended the templates with "mysite_" ("mysite_home", "mysite_welcome", etc.) and that is why I have used "mysite" in the example above.

vBulletin uses the associative key ("mysite") to match the templates that belong to this group. The string literal ('My Site') is used as the group name and you can name this anything you want.

Click "Save" when you're done and that's all there is to it, if you navigate to your templates list you should see the templates are now grouped under "My Site" (or whatever group name you entered).

You can now export this "hack" as a complete product and import it into any vBulletin installation you want. To export the product, simply navigate to "Plugins & Products" > "Manage Products" and then select "export" from the drop down list associated with your product.

I hope you enjoyed the tutorial, if you have any questions just ask