Carnage
02-17-2010, 10:00 PM
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_yourWidgetTypeCla ssName 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_yourWidgetTypeClassNam e extends vBCms_Widget
{
protected $package = 'yourPackageClassName';
protected $class = 'yourWidgetTypeClassName';
protected $canconfig = false;
public function getPageView()
{
$this->assertWidget();
$view = new vBCms_View_Widget('yourpackageclassname_widget_you rwidgettypeclassname_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_yourwidgettypeclassnam e_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_yourwidgettypeclas sname 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.
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_yourWidgetTypeCla ssName 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_yourWidgetTypeClassNam e extends vBCms_Widget
{
protected $package = 'yourPackageClassName';
protected $class = 'yourWidgetTypeClassName';
protected $canconfig = false;
public function getPageView()
{
$this->assertWidget();
$view = new vBCms_View_Widget('yourpackageclassname_widget_you rwidgettypeclassname_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_yourwidgettypeclassnam e_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_yourwidgettypeclas sname 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.