|
DJ's "How To Install Modifications (Mods/Hacks)" for Beginners
by
15 Jan 2009
This article is intended to help out new vBulletin owners who are just starting out modifying their forum, but are very new to vBulletin and new or alien to coding in general. This guide will cover the basics, and tell you the things you need to know before, during, and after "installing" something you see here on vBulletin.org.
Let's get a couple of terms out of the way first.
"Mod" or "Hack": By now you probably have guessed that mod is just short for modification, and you'll see it frequently used here and on other vB sites (not to be confused with the shortened form of moderator). The other term often used is hack, which is just another nickname for modification.
"Install": You'll also notice that above I put installing in quotation marks. The reason I did that is because not every modification actually installs anything. Some things are simple template edits, while some use the core features already built into vBulletin. We use the term "install" for all of these, even though technically your not installing anything, nor are you making any actual modifications to your board.
Disclaimers
All sites that offer third party plugins to existing software come with the warning that you use these products at your own risk. If you install a modification from here and it doesn't work, or your forum becomes unusable, who's fault is that? The coders? vBulletin.org? Or you? The answer to that question falls squarely on the individual who chose to install the modification to begin with. So proceed with caution and don't blame anyone but yourself if things go wrong. One important way to remain cautious is to do a backup of your database prior to installing your modification. This will ensure that you can restore your forum back to a state when it was fully functional. If you don't know how to do that, here are a couple of good tutorials:
Downloading Modifications
You may notice that an author has attached several different types of files to his/her modification thread. This could be a PHP file  , an XML file , TXT files or a ZIP folder .
ZIP folders are the most common type of files attached to threads because they can contain file types that the forum ordinarily would not allow you to upload, but more importantly they're compressed, so an author can add lots of content in one file. In most cases, this is where your install instructions and other important documentation will be located along with whatever else the modification requires to run. You will need to download this file and extract the contents using some kind of decompression software. Your computer should already have this ability built in, but in the event it doesn't or you need a better manager, you can get an excellent free version from http://www.zipgenius.com/.
Install Instructions Can Have Different Steps
Now that we've got that out of the way, lets get to the reason why you called. Installing modifications is not as hard as it sounds, and coding skill is generally not required in most cases. Sometimes you may need to use a little common sense, and you should always follow your steps carefully and without distraction. The vast majority of problems that develop when installing modifications come from the user not following the directions carefully or completely. Then they want to blame the author if their forum looks funny afterwards, when all that's happened is they're missing a quotation mark, or they forgot to upload a file.
There is no one way to install modifications. They all work differently, and their application will invariable be different. However, if you were to take all the steps from every modification on vBulletin.org and break the steps down into their basic type, you'd only end up with six basic methods: Template Edits, File Edits, Upload Files, Import Product/Plugin, Use Core Content and Use External Content. Sometimes you'll have to do just one of these. Sometimes you'll have to do a combination of more. Highly unlikely you'd ever have to do all six, but I digress. Let's look at the steps you will no doubt be asked to do and address what they mean and what they accomplish.- Template Edits: This is probably one the most basic steps you'll find in a set of install instructions. For example, one of the steps in your instructions may tell you to open up your postbit_legacy template and put a line of code into it. TEMPLATES ARE NOT FILES. This is important, as this is something frequently mistaken by beginners. Templates are not the same thing as files uploaded to your server. Your templates are located in your Style Manager in your Admin CP. Templates control the look and feel of your forum and contain all the HTML code for each of your individual styles.
To access your templates go to your Admin CP >> Styles & Templates >> Style Manager.
Then, in whichever style you wish to edit, click the dropdown menu and choose Edit Templates.
This will open a big long alphabetical list of templates where you can search for the one your install instructions want you to edit. Notice that you have the same long list of templates for each individual style you have on your forum. If you're installing a modification and you want the same functionality across all of your styles, you're going to have to make the edits to that template in every one of your styles. This is why most vBulletin owners try to keep the number of styles they own down to a minimum, as having to make edits across multiple styles can be very time consuming, especially if a modification requires you to edit multiple templates.
Tip: Use the Search box to find lines of code in your template quickly.
Tip: Templates can be reverted to their original default state by selecting the template in the listing and clicking the Revert button in the right hand control area.
- File Edits: Technically speaking, anything you upload to your server is a file. But when modifications refer to "File Edits" it's usually referring to editing vBulletin core PHP files. Very few modifications will ask you to do this, as the results can sometimes be unpredictable. But in the event you want to give it a go, you'll want to be aware of a couple of things. You'll have to edit your file in a program that opens PHP files, such as Notepad. You can use more advanced editors like Dreamweaver, Microsoft Word, Front Page, etc, but be warned that these editors might make unwanted edits to your file without you even knowing.
Tip: Use your editor's "Find" feature to find lines of code quickly. In most cases you can access it by hitting Ctrl + F.
- Upload Files: You should already know what this is if you've done your vBulletin installation yourself. This is simply the process of adding files to your server through an FTP program. There's plenty of free FTP programs on the internet such as https://filezilla-project.org/ or https://www.smartftp.com/, or you may have one built into your HTML editor. Use whichever one works for you.
You may notice that the files the mod author wants you to upload are in a series of subfolders. A big time-wasting mistake new administrators make is thinking that they have to upload each of these files one at a time. This is NOT necessary and often leads to mistakes. Files will always be structured with the same "file tree" structure that your forum has. So for example, your forum has two folders named admincp and includes. The mod you're installing also has files in folders named admincp and includes. You DO NOT have to take the files out of each folder and upload them to each folder individually. Grab both folders at the same time and overwrite them onto your existing server's folders. All your files will be added to the appropriate folders and even subfolders.
Occasionally, you may notice the mod author has included all of his/her files in a folder called "forums". This is just for the convenience of vBulletin owners who happen to have their forum installed in a subfolder called forums (a common occurrence). That way they can just drag and drop all the content by moving one folder. This does not mean that you are supposed to add the forums folder if your site isn't configured that way. Just grab the content of the folder as described above. This would also be true if the folder is called "upload". You wouldn't move the whole upload folder, you'd move it's contents, again, in one swoop.
- Import Product/Plugin: Importing a product or a plugin is the easiest of all installation procedures. All you have to do here is go to your Admin CP and import a .XML file through a special set of controls. However, a product and plugin import from two different locations in your Admin CP, so make sure you've read the instructions carefully to determine which is which.
- To import a product, go to your Admin CP >> Plugins & Products >> Manage Products, then click the Add/Import Product that will appear at the bottom of the page.
Then click the Browse button to look for your product XML. (If you're upgrading a product, and you've been instructed to tick Allow Overwrite to Yes, be sure to do so now.)
- To import a plugin, go to your Admin CP >> Plugins & Products >> Download/Upload Plugins.
Then at the bottom of the of the page, click the Browse button to look for your plugin XML.
- Add Core Content: This is not a term you'll see much, if at all, but it's a term I use to describe a common modification that is not really a modification.
For instance, you may see a mod instructing you to go to your Admin CP and add a new BBCode. Adding custom BBCode is not a modification to your forum, but a default feature that comes with your vBulletin installation. Most threads with BBCode "mods" take it for granted that you already know what it is, so they'll just list the fields your supposed to fill in inside your Admin CP. So in case your wondering, go to your Admin CP >> Custom BBCode >> Add New BBCode. Then just fill in the corresponding fields in the mod instructions. They may even provide an image for you to use which you'd upload to your server.
Another mod might instruct you to create a custom field. Again, this is something your vBulletin installation can do by default, but you may need to edit a template or two if you want the content to show up someplace other then your user profile pages. To create a custom field go to your Admin CP >> User Profile Fields >> Add New User Profile Field, then follow the rest of the instructions for your modification.
- Add External Content: Some modifications pull in external content, that is, content from another website or resource. An example of this might be Phoogle, which embeds Google Maps into your posts, or FaceBook Connect, which let's your users integrate their vBulletin account with their FaceBook account. In these cases, there's no standard thing you would have to do. Phoogle, for example, requires you go to Google and get an API key, while FaceBook Connect requires you to register on their site and use one of their developer applications. Since the instructions in this instance could be anything, always follow these steps closely. Very seldom are they overly complex, but very often it will require you to register somewhere (for free of course).
Uninstalling Modifications
In most cases, uninstalling a product is the same thing as installing a product, only in reverse. In your Product Manager, you'll find a list of installed modifications. Most of the time, uninstalling is as simple as clicking uninstall. Usually anything more complex than that will come with it's own set of uninstall instructions. Either way, check the documentation that came with the product. You would be surprised how many mistakes can be avoided just be re-reading the original thread information or reading "READ ME" files included in the ZIP file.
Common Terms and Phrases
Here are a few common instructions you may run into that you may not readily know what they mean.- CHMOD 777: To CHMOD a folder, you must access that folder through your FTP program and change the permissions to 777. This is different depending on the program you use, but in most cases you can simply right click on the folder and click "Properties" or "File Attributes". This makes the folder readable, writable and executable, which is necessary for some modifications to work.
- Debug Mode: Debug mode enables aspects of your vBulletin that you wouldn't ordinarily have access to and should never be run on a live site for any extended period of time. To learn how to enable Debug Mode, refer to this article:
- Full Path: This is your server's path name starting with the root directory of your site. For example, the full path to your forum might be:
/home/account_name/public_html/domain_name/forums.
To find the full path name to a directory, copy the code below into a file, save it as a PHP file, upload it to the folder you want to find the path to and then navigate to it in your browser.
PHP Code:
<?php
echo getcwd();
?>
- Relative Path: This is simply the location of any file and folder, relative to another directory on your site. For example, you have a subfolder in your admincp folder called xml. The relative path from one level above your admincp folder is admincp/xml
- Root: The root is the topmost directory in a hierarchy. So your Site Root would be the uppermost directory on your server, whereas your Forum Root would be the directory where your vBulletin would be installed. For many people, the two are one and the same.
- Invalid or Validate: Every so often, it might be suggested to you that the code on a given page is invalid, and that this may be part of the problem you're having. In a nutshell, validated code is code that meets universal standards, so that every different type of browser displays the code on your page the same way. What looked perfectly normal in Internet Explorer may look horrendous in http://www.mozilla.com/firefox/ or http://www.opera.com/ or https://www.google.com/chrome. A universal standard for code ensures that all browsers will display your website they way you want it to look. A single error in your code structure can cause any number of problems that might not be obvious at first, and most inexperienced web owners can have hundreds of errors on one page. To check a given page on your website, W3C provides a http://validator.w3.org/ that you can use to check your pages using the URI (the link to your page), file upload or directly copy and pasting in your source code.
I Need HELP???!!!111?!! (Forum Etiquette 101)
Believe it or not, there are some things you need to do if you want to get help with a certain modification.
First and foremost, you should check to see if your question hasn't already been asked, possibly many times before. No, you don't have to search the whole forum, nor do you have to read every post in a 120 page thread. Use the Search this Mod feature in the top right corner of every modification thread. Remember that you can use quotation marks " " to search for phrases that have words that fall under the allowed character limit.
When that fails, your best bet on getting help will be from the original thread where you downloaded the mod. It doesn't matter that the thread is 3 years old, starting a new thread about a mod that already has one will just result in you being redirected back to the original.
Also, REMEMBER TO MARK AS INSTALLED. Why? Because a great many mod authors will not give support to people who have not marked a thread as installed, or will list them as low priority. Plus, clicking that little box will help you in the long run, as you will be notified of important updates and bug fixes to the modification.
Keep in mind that just because a thread is marked "Supported" doesn't mean that the author is going to get back to you in a timely manner. The author could be on vacation, working, sick, dealing with the loss of a loved one or a host of other possibilities. Also keep in mind that no one gets paid for their work here. All mods here are submitted for free and are developed in the author's spare time. So showing the same indignant attitude that you would for, say, a paid product, is not likely to get you a lot of help, as the danger of loosing your buisness is kind of a moot point.
Sometimes, not often, but sometimes, no one knows the answer to your question. It's unfortunate, and we all do our best to keep that from happening. But when it does, repeatedly bumping the thread with the same question over and over again is not going to help. Now, if quite a bit of time has passed and you notice that other's have been getting support in the interim, then give the thread a friendly bump. But keep in mind that no response is often tantamount to "I don't know", and not "I don't care".
Remember the old saying that you'll catch more flies with honey then you will with vinegar? Keep that in mind, because no one here at vB.org gets paid for their efforts and they are helping just because they can. That means they can choose to NOT help you just because they can. So don't give them any more reason not to, then they already have. Be patient, use common sense, check and double check your work carefully and be courteous when seeking help, and your experience on this site will be productive, enjoyable and you'll likely be able to work out any problems you may encounter.
|