Creating a Custom vBulletin(4.X) Forum Block

By using the Forum Block Manager in vBulletin, you can customize your forum dynamically, without having to modify any code or css.

The Forum Block Manager is visible by logging into the backend and going to: Forums & Moderators -> Forum Blocks Manager.

From there, depending on your theme, you can click Add New Block and choose from one of the predefined Forum Blocks, which will then show up on your sidebar or wherever it is set to display in your theme.

There are a number of very useful and customizable ones, such as “New Forum Posts(Recent Posts)” and “Forum Threads” that can be used to display posts in a variety of manners, as well as blocks to display custom PHP or HTML.

Recently, however, a client that runs a rather large vBulletin forum wanted to add a custom forum block, pulling data from a thread ranking plugin that I created.

In order to do this without modify any of the VB source, while still working with the forumblock manager and the Everywhere Sidebar plugin, it was necessary to create a custom forum block type that would display the rankings.

The process is fairly straightforward, but there are a few items that are a little tricky, specifically how phrases work in conjunction with vBulletin Blocktypes.

This guide describes the process for a vBulletin forum that is running 4.2.X, but the process should be similar for other 4.X versions, like vb 4.1.

General Overview

In vBulletin, forum blocks are created by extending the vB_BlockType class and then adding functionality primarily to the getData and getHTML functions.

vB_BlockType is defined as an abstract class in ./includes/class_block.php around line 183, depending on your vBulletin version(this is a forum running 4.2.x)

The blocks are defined in the ./includes/blocks folder, with files in that folder included automatically.

The basic process of creating a custom vBulletin 4.X forum block is as follows:

1. Create new class that extends vB_BlockType, saving it in ./includes/blocks
2. Update the getHTML and getData functions as needed to provide the necessary functionality
3. Create the necessary phrases, which are used for settings and the title of the new forum block.
4. Create a custom template for the new forum block(potentially optional.)
5. Add the newly created Forum Block via Forum Blocks Manager

Overriding the vB_BlockType Class

For the purpose of this tutorial, we will be copying the vB_BlockType_Newposts class, which can be used to display the Recent Posts in the sidebar, or however you configure it within the forumblocks manager.

Start by copying the file ./includes/block/newposts.php file to ./includes/block/new_block.php

Now, open ./includes/block/new_block.php in your favorite editor and change the class name from vB_BlockType_Newposts to vB_BlockType_New_Block.

Adding the Required Phrase for the Block Title

The title seen when you Add a New Block via the Block Manager is handled by a phrase in the “vBulletin-> Forum Blocks” phrase group.

If you were to goto the forum block manager now and reload the blocks, you would see a blank line in the list of blocks.

In order for the block name/title to show up, you need to add a new phrases: blocktype_new_block

1. Goto: Languages & Phrases -> Phrase Manager -> Add New Phrase
2. Select “Forum Blocks” as the Phrase Type and “vBulletin” as the product
3. Make sure the “Varname” is set to blocktype_new_block
4. Set the Text to “New Test Block”
5. Click Save

It is important to note the varname it is “blocktype_$class_name,” where $class_name is the name of the class you created in the new file, in this case vB_BlockType_New_Block.

Adding your “new” blocktype

Before your new blocktype will showup in the Forum Block Manger, you need to rebuild the blocktypes, which will update them in your vBulletin Database.

Goto: Forums & Moderators -> Forum Blocks Manager -> Click the Reload Block Types link towards the bottom of the page.

You should now be able to goto Forums & Moderators -> Forum Blocks Manager -> Add New Block and see the New Test Block.

Of course, this is just an exact copy of the newposts block, so if you were to add it now, it would not be anything new. Instead, you will need to modify the getData and getHTML functions.

Creating a new Custom Setting

Settings for a blocktype are defined in the $settings array. Like the Class Title, the setting name and description that is displayed in the admincp forumblock manager is also controlled using the Phrase Manager.

Lets add a new custom phrase called ‘new_block_limit.’

In ./includes/block/new_block.php, around line 58, change the settings variable as follows:

	protected $settings = array(
	
		'new_block_limit' => array(
			'defaultvalue' => 5,
			'displayorder' => 1,
			'datatype'     => 'integer'
		),
	
...

Since this is a copy of the newposts class, we will leave the other settings for now.

Next, we need to add phrases for the new settings:

1. Goto: Languages & Phrases -> Phrase Manager -> Add New Phrase
2. Select “Forum Blocks Settings” as the Phrase Type and “vBulletin” as the product
3. Make sure the “Varname” is set to setting_new_block_limit_title
4. Set the Text to “Setting Name”
5. Click Save
6. Add another phrase with “Forum Blocks Settings” as the Phrase Type and “vBulletin” as the product
7. This time the the “Varname” needs to be setting_new_block_limit_desc
8. Set the Text to “The Description”
9. Click Save

The Setting Title and Setting Description both use the format setting_$class_name_$setting_name, adding “_title” or “_desc” for the title/description.

When you goto add the new block, you should now see the new setting displayed. Within the php code itself, you can get the value of this setting like so:

echo $this->config['new_block_limit'];

echo intval($this->config['new_block_limit']);

Changing the getData and getHTML function

As it stands now, you should be able to use the newly created forum block, although if you are using Everywhere Sidebar, you would probably still need to create a new template and modify the getHTML function.

In order for this to be useful and different from the existing newposts class, you would need to modify, at minimum, the getData function.

The getData function formulates a query and then uses db->query_read_slave and a while db->fetch_array loop to populate the postarray variable.

For the use of this client, we changed this to pull posts from our new post ranking plugin, which allows an admin to give posts various ratings and rankings, so the query was updated.

In the getHTML function, you may also want to customize the template, as well as what/how additional variables are registered. You would, of course, need to add the new template, and then change the call to vB_Template::create() to the new template name, as well as register any additional variables.