Register Members List Search Today's Posts Mark Forums Read

Article Options
Writing a basic widget.
Join Date: Jan 2005
Posts: 760

by Carnage Carnage is offline 18 Feb 2010

This guide will show you how to make a widget properly. I'm basing this on how I created a Top Posters widget, the source code for the entire widget will be avaliable as a mod on here in the next few days. I will update this page once that has been done. I used the default vbulletin direct php execution widget as a template for this; If you are struggling to follow this, taking a look at the code in there would be a good idea as its fairly simple and easy to follow.

Step 1.
Create a product in the normal manner. Make a note of your product id.

Step 2.
You need to insert rows into the following tables, this will eventually need to be done in the installation code, however for development purposes you can just insert it manually.

  • packageid
    - auto inc field, leave blank but make a note of the number it gets set to
  • productid
    - your product id
  • class
    - any valid name for a php class. This name will be used as a prefix for ALL the classes you make, ensure its unique enough to prevent clashes with other mods; vbCms, vbBlog or any other name begining vb should be avoided

  • widgettypeid
    - auto inc field, leave blank
  • package
    - your packageid from before (auto inc from package table
  • class
    - any valid name for a php class. This name will be used as a postfix for all your classes; you can be fairly uncreative here; but make sure its unique within your package.

Step 3:
In this step, we will create the required directory structure for a widget.

In the packages directory of your vbulletin installation you will need to create a new directory. This should match the class name from the Packages table however should be lowercase.

Inside this directory you need to create two directories named widget and item and inside the item directory, you need to create a second widget directory

the setup looks a bit like this:
  • packages
    • packageclassname
      • item
        • widget
      • widget

Step 4:
The item file.

For your widget to function, it needs an item class. This should be placed inside the item/widget directory. It should be named after your widget class name (from the widgettype table) The following code is the basic requirement for a widget item class:

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

Step 5:
The widget file.

The widget file is what does the work. It should be placed in the widget directory. It should be named after your widget class name (from the widgettype table) The following code is the basic requirement for a widget class:

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

Step 6:
the widget template.

Create the template yourpackageclassname_widget_yourwidgettypeclassname_page I suggest copying the contents of the static html widget template into it. You can then replace the {vb:var} for the content with your own template code.

For registering variables, its done differantly than to the rest of the forum. In the getPageView function, you need to set the propertys of the view object instead. If you would normally do $templater->register('myvar',$myvar) instead do $view->myvar = $myvar

Step 7:
You also need to create some phrases; anything your widget uses in its template should be a phrase in order to assist translations, you must also create the phrase widgettype_yourpackageclassname_yourwidgettypeclassname in the group CMS widget types, this is the name of the type that gets displayed in the admin cp, don't forget to select your product from the drop down so that the phrase gets exported with your product. Any other phrases you need should be created in the Content Management System group.

There may be other phrases that are needed, but so far my widget is working fine using just the widgetype phrase and some others for inside its templates.

Step 8:
Install code; the install code is easy for this basic widget; all you need to do is write code to do this table inserts from step 2.

This is a bit of a work in progress, i've not yet found all the phrases that need to be added and theres more work to be done to allow configuring a widget, but these basics should get you started until i've finished this guide.

Last edited by Carnage; 19 Feb 2010 at 10:37..
Views: 4772
Reply With Quote
Old 18 Feb 2010, 23:52
cellarius's Avatar
cellarius cellarius is offline
Join Date: Aug 2005
Real name: Sven
Great one, thanks Carnage! Looking forward to see this finished.
Please note that there will be no further updates to my addons, especially they will not be upgraded for vB5. I'm leaving vB, since IB choose to go the banana-way yet again.
Reply With Quote
Old 19 Feb 2010, 04:38
Mythotical Mythotical is offline
Join Date: Jun 2004
Very nice, you gave a tut on doing it by inserting into the database, I did one by adding and using a custom template.
Reply With Quote
Old 08 Mar 2010, 10:49
Carnage Carnage is offline
Join Date: Jan 2005
Creating a new widget requires creating a lot of code which is repeated for every widget, to assist in this process i've created the widget wizard.

Using this wizard skips a lot of the steps above. It creates:
  • A product file including the minimum required template, phrase and install code
  • The directory structure required
  • The widget item file
  • The widget controler file.

All you need to do to create a widget now is:

1. Fill out the form here:

2. Install the product and upload the files provided.

3. Fill in the code logic for your widget display (packages/yourpackage/widget/yourwidget.php) you'll need to add some logic to the getViewData() function to fill out the information you want in your widget; basic information is already filled out for you.

4. Edit the provided template (yourpackage_widget_yourwidget_page) again, it contains basic markup, you just need to replace the <vb:comment></vb:comment> tags i've left in there with your own content.

4. Optional extra if you wish to release your widget on vborg: write some uninstallation code; essentially needs to do the opposite of the installation code. (I left it out on purpose as if someone decided to play around with this and was uncreative with their package name they could end up trashing their board by removing default vb widgets)

When I finish the tutorial on widgets to include adding widget configs; I will update the wizard to generate those functions as well.

If you want/need to contact me, best thing is to pm me on that site, username Carnage.
Reply With Quote

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

New To Site? Need Help?

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

Layout Options | Width: Wide Color: