vBulletin LTS

← Back to vBulletin 4 Articles

Writing a basic widget.
by Carnage 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.

Package:
  • 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

Cms_widgettype:
  • 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:

PHP Code:
class yourPackageClassName_Item_Widget_yourWidgetTypeClassName extends vBCms_Item_Widget
{
    protected $package = 'yourPackageClassName';
    protected $class = 'yourWidgetTypeClassName';
    protected $config = array();
} 
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:

PHP Code:
class yourPackageClassName_Widget_yourWidgetTypeClassName extends vBCms_Widget
{
    protected $package = 'yourPackageClassName';
    protected $class = 'yourWidgetTypeClassName';
    protected $canconfig = false;

    public function getPageView()
    {
         $this->assertWidget(); 
         $view = new vBCms_View_Widget('yourpackageclassname_widget_yourwidgettypeclassname_page');             $view->class = $this->widget->getClass();
         $view->title = $view->widget_title = $this->widget->getTitle();
         $view->description = $this->widget->getDescription();
         return $view;
    }
} 
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.

vblts.ru supports vBulletin®, 2022-2024