Register Members List Search Today's Posts Mark Forums Read

Reply
 
Article Options
[vB4] A Beginner's Guide To Creating vBulletin Products
MarkFL
Join Date: Feb 2014
Posts: 3,456

I'm a relative newcomer to vBulletin administration, but I am enjoying every second of it, thanks in large part to the community here at vBorg.

St. Augustine, FL
by MarkFL MarkFL is online now 28 May 2015
Rating: (10 votes - 4.90 average)

Hello vBulletin Community,

This article is aimed at those of you who are making manual template edits and writing plugins to customize your site in an effort to help guide you into turning your customizations into distributable products so that you can share your work with others in a user-friendly and professional manner.

When I first decided to try to create vBulletin products about 2 months ago, I began looking at the XML files distributed by some of the generous folks here uploading their products for our use. I naively began creating my own XML files using theirs as a template. While this works, it can be quite tedious and I later found there is a much better way to go about this. vBulletin has all the tools we need to easily and successfully turn our coding into products we can share with other vBulletin owners. If we follow the right steps, vBulletin will generate the XML file for us.

While not absolutely necessary, I highly recommend creating a dev site where you can develop and debug your products without worrying about blowing anything up or otherwise causing any downtime for your users. I set up a local dev site on my hard drive for just such a purpose. You may also choose to set up a dev site on your server.

I recently developed a simple add-on for the site I help administrate for displaying DBTech's thanks statistic for our users in their postbits and on their profile pages. I will take you through the process of developing this product as a means of demonstrating many aspects of vBulletin product development.

Step 1: Put Your Dev Site Into Debug Mode

Putting your dev site into debug mode will activate many AdminCP features that you will need to develop your products. To do this, locate the file:

/includes/config.php

and at the top under the opening tag <?php enter the following line:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

and save the file. That's all there is to it...but if you are using your live site for development you will want to set debug mode for admins only, please see this article:

3 methods for enabling debug mode for site admin ONLY

Okay, now that we are in debug mode, we are ready to begin product development.

2.) Adding The Product

We need to tell vBulletin that there is a new product with which to associate the templates and plugins we will be creating. So follow:

AdminCP ► Plugins & Products ► Manage Products

Scroll down to the bottom, click "[Add/Import Product]" and look for the block labeled "Add New Product." This is where we give vBulletin the details of our new product.

Product ID: We want to give our product an ID we know will be unique among all the other products that have ever been uploaded here at vBorg. I like to begin the ID with a descriptive string, and for this product I chose "displaythanksdata" and then to ensure uniqueness I append my username and the version of vB, so that my final Product ID is:

displaythanksdatamarkflvb4

You will likely develop your own naming conventions over time which is good; you just want to be sure your use a unique ID.

Title: Here you want to enter a descriptive title for your new product. This is what you will see when you manage your products and choose the product with which you wish to associate templates and plugins. I like to begin the title of each of my products with my username since vBulletin displays them alphabetically this will keep all of my own products together for ease of location. For this product, I chose the title:

MarkFL: Display DBTech Thanks Data

Version: Since this is a new product, I will use a version number of 1.0.

Description: You want to briefly describe what your product does. You know what it will do, but think of those who download your product and use it on their sites...they will appreciate seeing this description. For this product, I wrote:

Displays a user's thanks data in their postbits and/or profiles.

Product URL: If you will be uploading your product here for others to download and use, you will want them to easily be able to find your product thread so they can quickly go to that thread as a reference for installing, using, and see if perhaps an issue they may be having is answered there. The end of the URL contains the Product ID, and so the full Product URL for this product will be:

http://www.vbulletin.org/forum/misc.php?do=producthelp&pid=displaythanksdatamarkflvb4

Version Check URL: This will allow those who have installed your product to quickly ascertain if they are running the most current version of your product. Like the Product URL, the end of the string is the Product ID, and for this product, we have:

http://www.vbulletin.org/forum/misc.php?do=productcheck&pid=displaythanksdatamarkflvb4

Now, vBulletin has everything it needs to know about your new product, so click "Save."

3.) Add New Setting Group

We need to define the settings for our product, so that our users can configure the product to their liking. So follow:

AdminCP ► Settings ► Options

Because you are in debug mode, you will see a fieldset element on the left within the "vBulletin Options" block labeled "Developer Options." Click "Add New Setting Group."

Varname: We want to use a unique name here, and I like to begin with my username, then an underscore, and then an acronym for the product, and in this case I chose:

markfl_dtd

The "dtd" stands for "display thanks data." From here on out all variables associated with this product will begin with the string "markfl_dtd" for consistent naming convention.

Title: This is what the user will see when they choose from the options in the select element on the right of the "vBulletin Options" block. I like to use the title of the product here, and then append the version number, so I wrote:

MarkFL: Display DBTech Thanks Data v1.0

Product: From the drop-down menu choose the product you defined in step 2, in this case:

MarkFL: Display DBTech Thanks Data

Display Order: I have so far just used the default value of 65535.

vBulletin Default: I have so far left this set to the default value of "Yes."

Finally, click "Save" and you will be ready to add your product's settings. I always like to give the user the ability to disable products in the settings, so the first setting we will define will be to enable/disable the product. So, click "[Add Setting]" and now we can define this first setting.

Varname: This will be a variable we can use in our plugins to determine if actions should be taken or not depending on whether the product is enabled or not. I used:

markfl_dtd_enabled

and in our plugins, we can use $vbulletin->options['markfl_dtd_enabled'] to determine the value of this setting.

Setting Group and Product: From the dropdown menus, choose the options you previously defined.

Title: This should be a short descriptive name that will appear in bold above the elements that allow the user to configure this setting, such as radio buttons, checkboxes and textareas. Here, I used:

Product Enabled?

Description: This is used to explain to the user exactly what this setting does, and if needed how to use it. Since this is a simple Yes/No question we may simply use something like:

Choose "Yes" to enable this product.

Option Code: Here we may simply use:

yesno

This will instruct vBulletin to generate 2 radio buttons, one for Yes and one for No. The value of the associated setting variable will be 0 for No and 1 for Yes.

Default: I like to default my products to No which forces the user to visit the products options page and configure the product. So, we will use:

0

Data Validation Type: For this setting we want to choose:

Free

Validation PHP Code: Leave this blank as no validation is required.

Display Order: Use the default value of 10 presented there. You can edit this field later if you decide you want to change the order in which the settings appear on the page. vBulletin will use multiples of 10 to give you plenty of room to insert settings in between two previously defined settings if you realize you need to add one or more there.

Blacklist: I don't know what this does, but so far I have always left this at the default setting of "No."

vBulletin Default: "Yes"

Click "Save" and then we will be ready to add the next setting. I wanted to give users the ability to decide whether they want the thanks data displayed in user postbits or not. This will be another "Yes/No" setting defined in the same way as the first setting, with the differences being:

Varname: markfl_dtd_postbit

Title: Thanks Data In Postbits?

Description: Set whether thanks data is displayed in user postbits.

Display Order: 20

Click "Save." The next setting will allow the user to decide if they want the thanks data to be displayed on user profiles. This is another "Yes/No" setting, with the differences being:

Varname: markfl_dtd_profile

Title: Thanks Data In Profiles?

Description: Set whether thanks data is displayed in user profiles.

Display Order: 30

Click "Save." Now, the next 2 settings pertain to a value that is computed in the plugins, which is the ratio of thanks received to posts made. I help administrate a math help forum, and we decided our users might benefit by seeing this data for the users providing help to them. We didn't want to display this ratio if it is too low, nor for new users with a small number of posts. So, the next setting will allow the user to set the post threshold for display the thanks/post ratio.

Varname: markfl_dtd_tpp_postthreshold

Title: Thanks Per Post Post Threshold

Description: Set the minimum number of posts for a user before the thanks per post data is displayed.

Option Code: Leave Blank (this will instruct vBulletin to generate an input element of type "text.")

Default: 0

Data Validation Type: We want to make certain the user inputs a non-negative integer here, so choose:

Integer

Validation PHP Code: The Data Validation Type will ensure the input is an integer, but to make certain it is not negative, we can enter the following Validation PHP Code:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

An error message will display if a negative value is entered, and if the user ignores this warning, an alert will pop up letting them know the page has one or more errors if they try to save the settings. They can still save the settings, but they have been warned. We can take further measures to ensure valid data in our plugins if so desired.

Display Order: 40

The last setting will allow the user to set the minimum value for the thanks/post ratio before this datum will be displayed.

Varname: markfl_dtd_tpp_valuethreshold

Title: Thanks Per Post Value Threshold

Description: Set the minimum value of thanks per post for a user before the thanks per post data is displayed.

Default: 0

Data Validation Type: Numeric (We want to allow non-integral values here, but we don't want negative numbers, so use the same Validation PHP Code as the previous setting.)

We now have all the setting in place to allow the user to configure the product to their liking.

4.) Define The Custom Templates

This product uses 2 custom templates, one is rendered at a hook location within the "postbit_legacy" template, and the other will replace the "memberinfo_block_statistics" if the thanks data is to be displayed on user profiles. We will create the template for rendering the thanks data in user postbits first.

So, follow:

AdminCP ► Styles & Templates ► Style Manager

And for the "MASTER STYLE" select "Add New Template." Then on the generated form, select the product from the drop-down menu for which we wish to create the new template and the enter:

Title: markfl_thanks_postbit

Template:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Click "Save." Next, we will create the replacement template for displaying thanks data on user profiles.

Title: markfl_thanks_memberinfo_block_statistics

Template:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Now we have our templates defined, the next step is to write the plugins to make everything work.
Views: 7487
Reply With Quote
Comments
  #2  
Old 28 May 2015, 07:23
MarkFL's Avatar
MarkFL MarkFL is online now
 
Join Date: Feb 2014
Real name: Mark
5.) Write The Plugins

The first plugin will cache the custom templates if appropriate, that is, if the product is enabled, the right script is running and the associated setting is enabled.

So, follow:

AdminCP ► Plugins & Products ► Add New Plugin

Select the product we are developing, and then enter:

Hook Location: cache_templates

Title: Cache Templates

Execution Order: 5

Plugin PHP Code:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

The next plugin will create the template group for our product so that when the user views all the templates when editing templates, our custom templates will be grouped together for efficient organization.

So, add another new plugin, and choose the product we are developing, and then enter:

Hook Location: template_groups

Title: Create Product Template Group

Execution Order: 5

Plugin PHP Code:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

This instructs vBulletin to put any templates whose title begins with the string "markfl_thanks_" into a group named "MarkFL: Display DBTech Thanks Data."

The next plugin will instruct vBulletin to replace its default template with our custom version (if our product is enabled, thanks data on profiles is enabled, and the template to be replaced is running). So, add a new plugin and choose the product we are developing, and then enter:

Hook Location: template_render_output

Title: memberinfo_block_statistics Template Replacement

Execution Order: 5

Plugin PHP Code:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

The next plugin will render the thanks data in user postbits, if the appropriate settings are correct, and only for posts in threads or private messages, and if the user has not disabled the postbit stats in their settings for DBTech's product.

Hook Location: postbit_display_complete

Title: Render Thanks Data In Postbits

Execution Order: 1 (I wanted to ensure that the thanks data goes right below the number of posts in the postbit)

Plugin PHP Code:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

And the last plugin will render the thanks data on user profiles if the settings are appropriate:

Hook Location: member_build_blocks_start

Title: Render Thanks Data On Profile

Execution Order: 5

Plugin PHP Code:


Block Disabled:      (Update License Status)  
Suspended or Unlicensed Members Cannot View Code.

Okay, we now have all the coding done, and it is time to export the product, which will create the XML file we can distribute to others.

6.) Export The Product

Follow:

AdminCP ► Plugins & Products ► Manage Products

Scroll down to the product we have developed, and on the right, from the drop-down menu for our product, click "Export" and save the XML file in an appropriate location on your hard drive. I like to put each product's files in its own folder.

You should write a text file instructing those who download your product how to install it and state the purpose of the product and give its development history.

7.) Zip Up the Files

Use an application of your choice to compress all of the files associated with your product into a ZIP file. Now you are ready to share your product with others. If you are uploading here, you should be sure to include screenshots of your product's setting page in the AdminCP and your product in action.

The product developed in this article is very modest, but I wanted to keep it simple for the purposes of a tutorial on the general method for using vBulletin's intrinsic tools for developing and sharing products. I encourage those of you with years of experience, rather than the weeks of experience I have under my belt to offer further insights and/or corrections to what I have written.
Reply With Quote
  #3  
Old 28 May 2015, 12:50
Princeton's Avatar
Princeton Princeton is offline
 
Join Date: Nov 2001
Real name: Joe Velez
you took a lot of time writing this - thank you for sharing
__________________
Latest Articles:
Liquid Layout = Less Ad Revenue?
How to Monetize Your Site
Improve Web Page Performance
How To Write For The Web


If it needs instructions, there's room for improvement.
Give users what they actually want, not what they say they want. And whatever you do, don't give them new features just because your competitors have them!
Reply With Quote
  #4  
Old 28 May 2015, 20:52
Alan_SP's Avatar
Alan_SP Alan_SP is offline
 
Join Date: Nov 2009
Yes, very useful for all of us.

BTW, can't like your posts at the moment.
Reply With Quote
  #5  
Old 29 May 2015, 01:18
Manoel Júnior's Avatar
Manoel Júnior Manoel Júnior is offline
 
Join Date: Feb 2009
Real name: Manoel Júnior
Very thanks MarkFL
Reply With Quote
  #6  
Old 21 Oct 2015, 14:52
Jorandh's Avatar
Jorandh Jorandh is offline
 
Join Date: Jan 2015
Real name: Joran den Houting
I'm having this weird issue: The settings are not exported within the XML.. Everything else is there though.....

Any idea?
Reply With Quote
  #7  
Old 21 Oct 2015, 16:57
MarkFL's Avatar
MarkFL MarkFL is online now
 
Join Date: Feb 2014
Real name: Mark
Originally Posted by Jorandh View Post
I'm having this weird issue: The settings are not exported within the XML.. Everything else is there though.....

Any idea?
When you defined the new setting group, did you select the product for which they apply?
Reply With Quote
  #8  
Old 23 May 2016, 19:50
GHRake GHRake is offline
 
Join Date: Sep 2015
Real name: Anomander Rake
omg I've been looking for this article for days! finally found it
Reply With Quote
  #9  
Old 16 Feb 2017, 14:55
Mattwhf Mattwhf is offline
 
Join Date: May 2016
Very detailed guide MarkFL!

I bookmarked this page and I will try to write a simple Mod when I have free time.

Thanks and regards,
__________________
Web Hosting Forum - Learn web hosting and offer your hosting services for FREE!
Reply With Quote
Reply



Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Article Options

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Forum Jump


New To Site? Need Help?

All times are GMT. The time now is 07:04.

Layout Options | Width: Wide Color: