Developing a Hack
In this article we'll be looking at how you go about developing a hack for a vBulletin installation. Being based on the PHP language and on MySQL database infrastructure makes vBulletin very versatile, so we're going to have to limit our scope. Almost anything that you would want to do with vBulletin is possible if you know how to leverage PHP and MySQL!
In particular we will look at:
• How to hack a discussion board by changing one of the template files
• How to distribute a hack by giving other programmers clear instructions about the code changes
Hacking vBulletin
Let's take a look at how to create a vBulletin hack. The hack we're going to be developing here is one that allows you to control how vBulletin handles private message receipts. As we saw in Article 3, private messages, known as PMs, are messages that one member can send to another member of the board.

The member types a message into the private message window and then clicks on the SubmitMessagebutton.
The recipient can collect the message the next time they log in (or, if they are already logged in, the next time they request a new page from the board).
But there's one feature that seems to annoy some members (especially if it's a popular board where the members make a lot of use of the PM facility). This is the read receipt feature. When a PM is submitted, a message box is displayed asking the sender whether they want to request a read receipt.

Read receipts are a useful feature, but the problem is the message box displayed people find it gets in the way and often they won't want to send a read receipt with every message. You as the administrator can do something about this you can hack your vBulletin installation to give your members greater control over how read receipts are handled.
You have the power …
… to disable private messaging read receipts altogether. In the left-hand menu in the AdminCP, click on Usergroupsfollowed by Usergroup Manager. Then for each usergroup you don't want to have this feature, click on EditUsergroup and set CanUse Message Trackingand CanDeny Private MessageReadReceipt Requestto No. Doing this, however, will remove the ability for members to request a read receipt. It would be much better to simply change how the request works.

Making the Changes
Let's now work through how to make this hack possible. There are a few code changes you need to make to a vBulletin template. If things go wrong, you already know how to revert templates back to their original state. As long as you take care and follow the code here carefully, everything will work out fine. But always keep a backup just in case!
Locating the Template
In the left-hand menu of the AdminCP, click on Styles& Templates to expand it, and then click on Style Manager .

This brings up the Style Managerpage in the right-hand side screen. Click on the button marked << >> to expand the template window.

You now need to click on the new button marked << >> lower down on the page to expand all the templates so as to find the one you are looking for.

In the scrolling window, work your way down until you get to a template called pm_newpm. Double-click on the link to open the template.

Hacking the pm_newpm Template
You can now make a few changes to this template. These changes involve removing the existing code that causes the prompt to appear and adding new code that provides a checkbox so that the sender can request a read receipt if they want one.
The first thing you need to do is locate the following segment of JavaScript code in the template:
else if (formname.dopreview != true)
{
<if condition="$show['trackpm']">
if (confirm("$vbphrase[request_receipt_for_message]"))
{
formname.receipt.value = 1;
}
</if>
}
You need to remove this section of code. Rather than delete it outright it's much better to just comment out the code by adding // and a space to the beginning of each line of the script:
// else if (formname.dopreview != true)
// {
and so on.
While you're doing this, it's a good idea to add a note so that later you will be reminded later why you commented it out!
// Begin PM read receipt hack
// else if (formname.dopreview != true)
// {

// }
// End PM read receipt hack

Next, within the same template, find this segment of code:
<input type="hidden" name="receipt" value="0" />
(This will be on one long line, so it may be rather hard to find.) Comment this out too. Since this is HTML, we comment it out by placing <!-- and --> around the line. Again, it's wise to add comments to the code to remind you why you removed the line:
<!-- Begin PM read receipt hack -->
<!-- line removed -->
<!-- <input type="hidden" name="receipt" value="0" /> -->
<!-- End PM read receipt hack -->
Next, look for the following segment of code:
<div>
<label for="cb_parseurl">
<input type="checkbox" name="parseurl" value="1" id="cb_parseurl"
tabindex="1" $checked[parseurl] />
$vbphrase[automatically_parse_links_in_text]
</label>
</div>
When you locate it, you need to add below it as follows (again remembering to add the comments):
<!-- Begin PM read receipt hack -->
<!-- line added -->
<div>
<label for="cb_receipt">
<input type="checkbox" name="receipt" id="cb_receipt" value="1" />
Request Read Receipt?
</label>
</div>
<!-- End PM read receipt hack -->
Now that you've made the modifications to the code, you can save it by clicking on the Save button.
Testing the Hack
Testing is simple try sending a PM! When you are in the private message window, you will see the new checkbox enabling you to specify that you want a read receipt for the message you send. Try a couple of tests, one with a read receipt request and another one without, just to make sure it all works.

Next, within the same template, find this segment of code:
<input type="hidden" name="receipt" value="0" />
(This will be on one long line, so it may be rather hard to find.) Comment this out too. Since this is HTML, we comment it out by placing <!-- and --> around the line. Again, it's wise to add comments to the code to remind you why you removed the line:
<!-- Begin PM read receipt hack -->
<!-- line removed -->
<!-- <input type="hidden" name="receipt" value="0" /> -->
<!-- End PM read receipt hack -->
Next, look for the following segment of code:
<div>
<label for="cb_parseurl">
<input type="checkbox" name="parseurl" value="1" id="cb_parseurl"
tabindex="1" $checked[parseurl] />
$vbphrase[automatically_parse_links_in_text]
</label>
</div>
When you locate it, you need to add below it as follows (again remembering to add the comments):
<!-- Begin PM read receipt hack -->
<!-- line added -->
<div>
<label for="cb_receipt">
<input type="checkbox" name="receipt" id="cb_receipt" value="1" />
Request Read Receipt?
</label>
</div>
<!-- End PM read receipt hack -->
Now that you've made the modifications to the code, you can save it by clicking on the Save button.
Testing the Hack
Testing is simple try sending a PM! When you are in the private message window, you will see the new checkbox enabling you to specify that you want a read receipt for the message you send. Try a couple of tests, one with a read receipt request and another one without, just to make sure it all works.

Hack Distribution
So now you have a hack and you want to make it available to other people. The question is, how do you do this? The license agreement prevents you from distributing whole templates, and anyway, you're only making small changes to the template so it's silly to get people to replace code that is unchanged.
The best way to distribute hacks is in the form of clear instructions that others can easily follow. There are many ways to do this but the following is an example of one way that is clear and straightforward.
MODIFICATION – PM READ RECEIPT CHECKBOX Version 1.0.2
-----------------------------------------------------
Open TEMPLATE pm_newpm
Find and DELETE/COMMENT OUT:
else if (formname.dopreview != true)
{
<if condition="$show['trackpm']">
if (confirm("$vbphrase[request_receipt_for_message]"))
{
formname.receipt.value = 1;
}
</if>
}
Find and DELETE/COMMENT OUT:
<input type="hidden" name="receipt" value="0" />
Find:
<div>
<label for="cb_parseurl">
<input type="checkbox" name="parseurl" value="1"
id="cb_parseurl" tabindex="1" $checked[parseurl] />
$vbphrase[automatically_parse_links_in_text]
</label>
</div>
Below code ADD:
<div>
<label for="cb_receipt">
<input type="checkbox" name="receipt" id="cb_receipt" value="1" />
Request Read Receipt?
</label>
</div>
SAVE pm_newpm and CLOSE.
Test modification.
END OF MODIFICATION

With this hack we needed only to modify templates, but there are times when you need to document edits to settings or even to actual PHP files. Settings changes can be documented by specifying the menu navigation and the final setting change.

Admin CP -> Usergroups -> Usergroup Manager -> Edit Usergroup
Set "Can Use Message Tracking"
and "Can Deny Private Message Read Receipt Request" to "No".
The PHP file modification that we saw in Article 4 can also be documented in this way:
PAYPAL MODIFICATION Version 1.0.2
---------------------------------
Open includes\functions_subscriptions.php
Find:
<input type=\"hidden\" name=\"no_shipping\" value=\"1\" />
Replace with:
<input type=\"hidden\" name=\"no_shipping\" value=\"0\" />
SAVE and UPLOAD
Test modification.
END OF MODIFICATION
-------------------
Tips for Hack Distribution
Here are a few tips that make code distribution easier for both you and the person following the instructions:
1. Test hacks thoroughly. If possible, try them out on a test installation of vBulletin before making changes to your active board.
2. Be specific as to which file or template requires modification.
3. Replace whole lines of code don't mess about trying to explain which bit of the line needs changing.
4. Feel free to add comments to the code you include. This will make life easier for the person using the instructions but will also bulk out your code.
5. Be clear as to what code you want the user to find and what they should then do with it (e.g. replace it with different code or add something above or below it). Be careful to check that the code you want the user to search for isn't duplicated elsewhere in the file. If this is the case, then be more specific and display more than one line of code.
6. Don't use line numbers these can change with updates to the software. Also, any code changes (or other hacks) above the line will cause the line numbers to be wrong.
7. Make sure that you give the proper name for the template or PHP file you want editing. In the case of PHP files, include the path within the vBulletin installation.

8. Keep version numbers updated. If you make a small change to the code (to fix a typo say or make a small modification), then change the minor version number (say from 1.0.2 to 1.0.3). For big changes or alterations that allow the code to work for a new version of vBulletin, change the major version number (say from 1.0.4 to 2.0.0).