This tutorial will show you the very basics of creating a self-installing vBulletin 5.x modification. One of the strengths of vBulletin has always been the ability to create and share modifications of the code. Modifications and support for modifying code can be found at www.vbulletin.org.

What you will learn in this tutorial is:
  • The back-end work for setting up a new modification
  • How to create settings for your modification
  • How to setup and use a Stylevar (Style Variable)
  • How to create a new custom template
  • How to create a new hook
  • Where to upload your mod’s php file and how to make it auto-install


When a programmer learns a new language it is tradition they create the “Hello World” program. This is always a simple script which usually displays the words “Hello World” on a screen or other output device. For us that output device will be your vBulletin 5 site.

Before we get started it is essential you put your vBulletin 5 site in debug mode. Debug mode gives admins more options than they usually see in the Admin CP as well as debug information on the bottom of the forum. For this reason it is not recommended you run your live forums in debug mode, all development ideally takes place on a private “test” forum that you have already setup.
To enter debug mode you must edit both config.php files and un-comment a line.

Specifics here:

For info on setting up a “Test” forum see here:


At this point I must warn you that a basic understanding of PHP will also be necessary. This is a basic modification; any serious modifications you make on your own will of course need more PHP knowledge. This tutorial is more to teach people how vBulletin words more than how PHP works.

Assuming your Debug mode is now on, let us jump in and get started.
To start, open your Admin CP, expand Products & Hooks” on the side menu, and choose “Product Manager.” On the page that opens choose “Add/Import Product.”


Click image for larger version

Name:	vb5-hw-01.jpg
Views:	1
Size:	90.1 KB
ID:	3725554

On the next page you must fill in the details of the new mod. We are “adding” one as opposed to “importing” one because the mod hasn't been developed yet!

Click image for larger version

Name:	vb5-hw-02.jpg
Views:	1
Size:	96.3 KB
ID:	3725555

The Product ID, Title, and Version are required information. Enter the following values- Product ID and Version must be entered exactly:

Product ID: helloworld
Title: Hello World
Version: 1.0.0

Note- Product ID should be letters only, do not use spaces, underscores, or symbols. Numbers are OK if necessary-

A description that describes the mod in 1 short sentence is recommended but not required. The Product URL and Version Check URL are used only if you plan on sharing this mod on vBulletin.org. Although you won’t be sharing this mod I will explain them here so you know how to use them in the future.

The Product URL is a link to the mod thread. You can’t know the real URL to the thread of course until you make it, but once you’ve made it you should already be uploading the modification, not going back to edit sections. For this reason vBulletin.org has a utility that will forward people to the correct mod thread based on the Product ID which you already know and must be unique to your mod on vbulletin.org, so don’t use basic product ids. Bad choices are: addon, gallery, coolmod, etc… Good product ids include something unique to you so you never need worry about having the same product id as someone else. In my case I use “bop5” in any product id so: bop5addon, bop5gallery, bop5coolmod would all be unique.
The URL you enter for the Product URL is:
http://www.vbulletin.org/forum/misc.php?do=producthelp&pid=helloworld
Of course you replace the ending helloworld with the actual Product ID you’ve assigned in the first step. If you are not releasing the mod on vBulletin.org you can set any URL you wish. Users who click on the mod title in Product Manager will be taken to this URL.

The Version Check URL is another optional vBulletin.org only feature. If you enter a value for this setting then Admins who install your mod can quickly see if a newer version exists on vBulletin.org for them to download. This assumes you will update the mod and keep the version number updated- if you won’t just leave this blank.
The Version URL is:
http://www.vbulletin.org/forum/misc.php?do=productcheck&pid=helloworld
Again, change helloworld to your actual Product ID.

OK when you’re done filling in values hit the “Save” button.


Click image for larger version

Name:	vb5-hw-03.jpg
Views:	1
Size:	80.0 KB
ID:	3725556


You will be taken back to Product Manager where you will see the product now listed. Now we must continue actually building this modification.


Click image for larger version

Name:	vb5-hw-04.jpg
Views:	1
Size:	86.6 KB
ID:	3725557


Since we want this mod to output data onto the pages of our forum we know we want to show a template inside another template. To do this we use hooks. Choose “Manage Hooks” on the side menu and then click the link “Add New Hook.”

Click image for larger version

Name:	vb5-hw-05.jpg
Views:	1
Size:	84.2 KB
ID:	3725558

This is the Add New Hook screen. You will need to enter or select values for each option- starting from the top:
  1. Product: Choose “Hello World” from the drop down menu to tie it to our product.
  2. Hook is Active: Yes
  3. Hook Location: --header_before_content – This is a good location to be near the top of every page. (Every page because the header is on every page and near the top because it is before the main content of the page. Finding the right hook is sometimes trial and error, but will come with experience.)
  4. Execution Order: 10 (leave this as the default, 10, unless you have reason to change it. Lower numbers get executed first.)
  5. Template Name: hello_world (Enter it exactly like this; we will need to make a custom template later with this same name.)
  6. Hook Arguments: page=page (This just means we are passing the page variable from the original template to our custom template and we’re keeping it the same name (page) to avoid confusion. We could change the name if we wanted. For more info on how hooks work read this blog: https://www.vbulletin.com/forum/entr...te-Hook-system


When all done click on SAVE.

Now that we have setup our hook and we know we will have a custom template later, let us setup a custom Style Variable so we can easily apply styling to our output. For this example we will setup only a single stylevar- most custom templates would have multiple stylevars to control things like backgrounds, borders, font colors, padding, and more. Our mod will only have one stylevar for the background.

Click image for larger version

Name:	vb5-hw-06.jpg
Views:	1
Size:	88.0 KB
ID:	3725559

In the Admin CP side menu expand “Styles & Templates” and choose Style Manager. On the Style Manager page take note that “Master Style” is visible- this is only visible on Debug Mode. On the Master Style line click the “Go” to go to the Master Style Variable Editor.

Click image for larger version

Name:	vb5-hw-07.jpg
Views:	1
Size:	94.9 KB
ID:	3725560

On the Style Variable Editor page click on the option “Add New Stylevar” button. By adding this to the Master Style it will automatically be copied to all styles on the forum and also be exported later when we export the mod to share it.

Click image for larger version

Name:	vb5-hw-08.jpg
Views:	1
Size:	80.8 KB
ID:	3725561

In the Style Variable editor you must again choose and enter values.
  1. Product: Choose the “Hello World” product from the drop down menu.
  2. Group: This will be a bold letter grouping under which one or my stylevars will be listed. You can choose any value or use an existing group name- for this example call it HelloWorld.
  3. Stylevar ID: hwbackground (This must be entered exactly as this will be the variable name we need later when we use this Stylevar in a template. This value must be unique to all Stylevars ever installed on your forum so make it unique. The fact it begins with “hw” is to show it is part of the Hello World mod and hopefully another coder doesn’t decide to use the name name for something different in the future.)
  4. Friendly Name: This is a better name shown only in the Stylevar Editor to explain to the Admin what it controls. I chose- Hello World Background.
  5. Description: A short description better describing its use, such as- Choose the background for the Hello World mod. (Optional)
  6. Data Type: Choose Background from the drop down menu. Other types of options are available for stylevars meant to control other things. The Background type will have a color picker to easily choose a color and an option for a background image if the Admin prefers, as well as options unique to background CSS.
  7. Validation Regular Expression: Leave this blank. If you were making a custom type you could enter a regular expression to verify the value the user enters is valid, but this is very advanced and almost never needed.


Finally, click “SAVE.”

Now that you have setup the Stylevar you will have to choose the default value for the Stylevar and you can do so on the next screen.

Click image for larger version

Name:	vb5-hw-09.jpg
Views:	1
Size:	67.7 KB
ID:	3725562


This is where you choose values for the Stylevar. You see all the options the “Background” type has available. For the sake of brevity we will simply choose a background color by clicking on the box next to background color and choosing a color. I’m choosing yellow but you can pick any color you wish.

When done click on SAVE.

The stylevar is now set and we will use it later in a custom template. First we want to add options to this mod.

Click image for larger version

Name:	vb5-hw-11.jpg
Views:	1
Size:	93.4 KB
ID:	3725563


To add options in the Admin CP expand “Settings” and click on “Options.” On the next screen click the link to “Add New Settings Group.”

Click image for larger version

Name:	vb5-hw-12.jpg
Views:	1
Size:	82.7 KB
ID:	3725564

On this page you must again enter and select some values.

  1. Varname: The value you enter here is not often used but make sure it is unique to all mods. For this mod I chose “hworld” but even better would be to use a custom string like “bop5hworld” to reduce the risk another coder uses the same value.
  2. Title: Hello World (Usually you choose the same title as the Mod but it is not a requirement.)
  3. Product: Choose “Hello World” from the drop down menu.
  4. Display Order: Higher numbers get displayed last. The max value is default, this puts new mods at the bottom of the list of settings which is customary on custom vBulletin modifications.
  5. vBulletin Default: Yes (always choose Yes)


When done click SAVE.

You will be brought to a screen that has no settings listed (yet.)


Click image for larger version

Name:	vb5-hw-13.jpg
Views:	1
Size:	42.1 KB
ID:	3725565


Choose the link “Add Setting” – You will be taken to a screen with a number of options.

Click image for larger version

Name:	vb5-hw-14.jpg
Views:	1
Size:	86.4 KB
ID:	3725566

Even though this mod is designed only to say “Hello World” however in order to get experience adding options we will make the “World” part come from this option rather than be hard-coded in the template.

  1. Varname: hello_world (Enter it exactly as listed. In general you can use letters, numbers, and underscores, no spaces and no symbols allowed. Varnames must always be unique to all mods on a site so be sure you choose values no other coder will ever choose. Again this is a good place to prefix all varnames with a custom string like “bop5_hello_world” HOWEVER we are not using that prefix in this example.
  2. Setting Group: Hello World will already be selected, choose it if not selected.
  3. Product: Again Hello World will be chosen, if not select it.
  4. Title: A title for the setting- I used “Text That Follows Hello” since whatever text is entered by the Admin will show up on the forum after the word Hello.
  5. Description: A longer optional description if the title isn’t sufficient. You can use HTML in this description to add links or other advanced coding options.
  6. Option Code: Leave this blank for normal text boxes. There are several built in options for more advanced setting types- more info on these can be found on vBulletin.org as well as the ability to add custom code- all of which is beyond the scope of this tutorial however.
  7. Default: The default value that will be shown in the box- for us it is: World
  8. Data VerificationType: Free – This means any data (text) is allowed. If you needed to limit the data input here to certain types you could choose a different option.
  9. Validation PHP Code: [Leave Blank] Again this is an advanced feature we will not be using. It can be used with custom PHP code if there was a pressing need to verify the input data before using it.
  10. Display Order: 10 (by default this value will be 10 more than the previous setting, you should only change it if you have reason to display the settings in a different order.)
  11. Blacklist: No (I really don’t know what this does, just leave it No.)
  12. vBulletin Default: Yes (This will let it be overwritten during mod upgrades)
  13. Is Public: Yes (This will allow us to get the value in our custom PHP code later on.)


When done click SAVE.

Click image for larger version

Name:	vb5-hw-15.jpg
Views:	1
Size:	51.5 KB
ID:	3725567


You will be returned to the Settings page and the 1 setting will be shown.

IMPORTANT- Due to a bug in the software please press the SAVE button below the settings once more- this will force all the settings to take their default values, otherwise they may display empty even with a default value set.

We have completed adding our one setting for this mod. Most mods would have additional settings- you continue to add settings by clicking on the “Add Setting” link.

Now It is time we add our custom template.


Click image for larger version

Name:	vb5-hw-16.jpg
Views:	1
Size:	93.1 KB
ID:	3725568


In the Admin CP click on “Style Manager” under the “Styles & Templates” Group. Take Note of the Master Style again and choose “Add New Template” from the drop down box for the Master Style.


Click image for larger version

Name:	vb5-hw-17.jpg
Views:	1
Size:	60.3 KB
ID:	3725569


On the New Template page choose and enter the following-
  • Product: Choose the Hello World product from the drop down menu.
  • Style: Make sure it says Master Style (you can’t edit this here)
  • Title: hello_world (this must match exactly the template name entered previously into the hooks section.)
  • Template: Here we enter the following text which is the HTML code for the custom template:

Code:
[CENTER]
    Hello {vb:raw page.hwWorld}.
[/CENTER]
You can see in this template code is the stylevar we created for the background. You also see the code after Hello- this will be a value we receive from our custom PHP file we’ll create soon. For more info on vBulletin Template Syntax check out - http://www.vbulletin.com/docs/html/m...emplate_syntax or check on www.vbulletin.org.

When done entering the template code click SAVE.

Now go back to your Forum home page and re-load the page, let’s see what it looks like-

Click image for larger version

Name:	vb5-hw-18.jpg
Views:	1
Size:	85.9 KB
ID:	3725570


Your forum should look something like this. You’ll see the color you chose in the stylevar for the background and the word “Hello” however there is no “World” yet. To get the final part we must now work on creating a custom PHP file.

Before we begin the custom PHP file you should create some folders (AKA directories) on your local computer and some sub-folders.

All vBulletin 5 modifications should be uploaded to the /core/packages/[package-name] directory on your server. Therefore on your local computer you should create a new folder for each modification you write. Give this folder an easy to read descriptive name, such as “Hello World Mod.”

  • Inside the folder “Hello World Mod” create a subfolder called: packages
  • Within packages create another sub-folder, this sub-folder must exactly equal your product id, in our case it is: helloworld
  • Inside helloworld create two sub-folders, api and xml.
  • Inside the api folder will go our custom .php files.
  • Inside the xml folder will go any .xml files necessary and for us that means the product XML file we will export as our last step. More complicated mods may have additional .xml files used to create Admin CP links and other advanced features.


Now that we have the directory structure setup it is time to create our PHP file. Go to your api directory, create a new file called Page.php and enter the following code:

PHP Code:
class helloworld_Api_Page extends vB_Api_Extensions
{
  public 
$product 'helloworld';
  public 
$version '1.0.0';
  public 
$developer 'BirdOPrey5';
  public 
$title 'Hello World Example App';
  public 
$minver '5.0.0 Beta 1';
  public 
$maxver '6.0.0';
  public 
$infourl '';
  public 
$checkurl '';
  public 
$AutoInstall 1;
  public 
$extensionOrder 5;

    public function 
fetchPageById($page$pageid$routeData = array())
    {
       
$page['hwWorld'] = vB::getDatastore()->getOption('hw_world');      
                         
      return 
$page;
    } 

Much of the above may not make sense to you- if you are familiar with PHP you may recognize you are extending a class. The reasons why we are doing what we are doing here is out of the scope of this document- you will be able to find more info on the reasons as more info on vBulletin 5 modification is released. Here are just the basics:

Page.php was chosen because we are extending a class that is found in the built in page.php file found in the vBulletin directory core/vb/api/ . If we were extending a class in a different file we would use that file name instead.

The class helloworld_Api_Page was because:
  • helloworld – This is the Product ID.
  • _Api_ - This is always there
  • Page – The file name Is Page.php (capital letters are easier to read)


Next are all those “public” lines- most are self-explanatory and the values should match the values you used when “Adding” the new modification way back in the first steps of this tutorial. Some things to note-
  • $developer – This is your name or user name
  • $minver – This is the lowest value VB version the modification will run on. Beta 1 is lower than Beta 10, and all Beta versions are lower than non-Beta versions.
  • $maxver – Unlike $minver this is the first version value the mod will NOT work on so 6.0.0 is usually more appropriate than 5.9.9.
  • $infourl & $checkurl – These are the not really used yet but should match the values for the Product URL and Version Check URL from the first step if you are using them.
  • $AutoInstall – If this is 1 the mod will attempt to autoinstall itself once it has been uploaded to a new server. If 0 the mod will not autoinstall and the Admin will have to import the XML file like they needed to do in previous VB versions.
  • $extensionOrder – This is the order in which the file is executed when there are multiple extensions of the same class. Lower numbers get executed first. Don’t ever use the value of 1 unless there is absolute need your extension gets processed first.


The public function declaration is standard PHP – we are adding code that will execute after the built in function fetchPageById in the built in page.php file.

The next line adds ‘hwWorld’ as an element of the $page array. The $page array already holds a number of existing built in values, this code adds the new custom element and the getDataStore method is used to read in the value “World” we previously set in the mod settings. You see the option name ‘hw_world’ is the name of the Varname created when we created the “Text after Hello” setting earlier.

Finally we return $page to end the execution of our custom code.

I don’t expect someone with no VB or PHP experience to fully understand why I chose page.php and this class to extend- suffice to say in my experience this is a good class because it executes on every page load and for this mod we wanted the “Hello World” message to display on every page. Finding the correct API file and class can be time consuming but will come with experience. In the beginning it involves reading through a lot of built in code or hopefully finding someone who already knows the answer.

Well now that we have created the page.php file we need to upload it to our forum.

Using an FTP client open your forum on the remote connection, go to your /core/packages/ directory so you see a list of other packages in the window. The built in VB5 packages are viglinks and forumrunner, as well as a number of others, so you will see some listed here even on a fresh install.

On the local side of your FTP client navigate to the packages folder you created for this mod so the helloworld directory is visible, and upload the entire directory to the remote site so helloworld is now listed as a package on the remote site.

If everything has been done correctly you should now see “Hello World.” When you reload you forum home page (or any forum page.)

Click image for larger version

Name:	vb5-hw-20.jpg
Views:	1
Size:	84.7 KB
ID:	3725571

If you see the above you can breathe a sigh of relief.

However we are not quite done, yet. This mod is working on your site, but if this was a modification you wanted to share with other Admins or on vBulletin.org there is another step. We must create a Product XML file. This file will create all the settings, all the templates, all the Stylevars, All the Phrases (we didn’t use phrases in this example) and all other content we added via the Admin CP.

Click image for larger version

Name:	vb5-hw-21.jpg
Views:	1
Size:	91.4 KB
ID:	3725572


Go back to the Admin CP. Expand Products & Hooks again and choose “Manage Products.”

Find the Hello Mod listed, go to the drop down menu for this mod and choose “Export”

A file-save dialog will open in your browser. Navigate to the folders you made earlier and save it in the xml sub-folder under the helloworld package-


Click image for larger version

Name:	vb5-hw-22.jpg
Views:	1
Size:	67.7 KB
ID:	3725573

Save the file under the original file name- do not change it. It will always be product_productid. (Where productid is the Product Id you created for this mod.)

Once the file is saved now go back to your file folders on your computer, go to your /packages/ folder so you see the helloworld folder.

You can now add helloworld folder (and all subfolders) to a .ZIP file you can share. In Windows you Right Click on helloworld and choose “Send To” from the menu and Send To a Compressed (Zip) file.

This will create a .zip file you can upload to vBulletin.org and share with friends or other admins. If all works like it should simply unzipping the files and uploading the package to their package directory should cause the mod to automatically install within the first couple page loads of their forum.

I know this was a boring mod but I hope the tutorial gave you an idea of what is involved in creating a basic mod and some of the features available to make mod creation relatively quick and easy.