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.


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:

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:


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:


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:


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


We then need to the find the following comment:


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


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:


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:


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:


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:


Finally, find the following line of code


And add this line of code below it:

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:


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:


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:


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:


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


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


And then add this line of code below it:


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:

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:

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

__________________
Any fool can write code that a computer can understand. Good programmers write code that humans can understand.

Nice, vB to expensive though...maybe next year :).

__________________
PHP/XHTML Freelancer:
Cleanscript.com v3 - Programming starting at just $5 act now!