PDA

View Full Version : Writing a basic widget.


Carnage
18 Feb 2010, 17:06
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:


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:


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.

cellarius
18 Feb 2010, 23:52
Great one, thanks Carnage! Looking forward to see this finished.

Mythotical
19 Feb 2010, 04:38
Very nice, you gave a tut on doing it by inserting into the database, I did one by adding and using a custom template.

Carnage
08 Mar 2010, 10:49
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. (http://vb4.giveupalready.com/ww/wizard.php)

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: http://vb4.giveupalready.com/ww/wizard.php

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.