Michael Biddle

<div>Widget Programming

Introduction
This is intended for reasonably experienced PHP programmers with some experience in vBulletin programming. You should have at least a basic understand of the vB templating system and phrasing. If you don’t, I strongly recommend you do some homework before trying to program a widget. I will use as an example the static html widget.

It's very early to be writing this, I know. I can't say exactly when alpha testing will start on the CMS system, which will be part of the suite. Soon, but I'm not in a position to give a date. I've had several requests for more information, so here it is. I've attached a zip file for two widgets- the static html and the rss. This may not be the final code, but it's close.

I've walked through the statichtml widget, because it's the simplest. If you understand that, there are two more things you need to know. You can call $this->content->getNodeId() to get the unique id of the page you are on. This allows you to do things like make navigation widgets that are page-dependent. Neither of these widgets need that. Also, most widgets should be cached. There is a generic caching algorithm- the first parameter is a value or array of values that form a key. vB_Cache::instance()->write and vB_Cache::instance()->read() do this for you.

At the risk of repeating myself, let me explain the hierarchy.

In the CMS system you define grids. Grids divide the page into columns, with optional header and sidebar settings.

Then you create widgets. Widgets are a combination of a widget type (i.e. static html), plus a configuration. If you want ten different Youtube videos, that's ten instances of a statichtml type widget. If you want five different Google gadgets, that's five more instances of the statichtml type.

Then you make layouts. Layouts put the primary content into a grid, and optionally place one or more widgets in specific places. You apply a layout and style to each section (section is the primary organization system in the CMS, but not the only one). All the pages in that section get that layout.

Let's say you wanted to have a form-type widget where users could enter information about each article. You could create your own database table and use that. Or you could use the widget storage we designed. In that case you would want to use a per-page configuration. We haven't written any of those, yet, but the setConfig and getConfig calls will handle per-page configuration.

I don't want to take credit for something I don't deserve. I didn't write the CMS system, but I've been working in it a lot for the last couple months. I think you'll find it powerful and well designed for extension.

Code Example
Files
You will need at least two files. You will need to define a package and class. The package should be something unique. The class can be anything you like, but it’s generally something descriptive. You will need to create the following file structure.

/packages (already there>

/

/item

/content

/

/content

/

Note that we use all lower case file and path names. The static HTML widget has package = vBCms, class=Static. The files are
/packages/vbcms/item/content/static.php
/packages/vbcms/ content/static.php

Database
You will need to create two database entries to use your widget. In the TABLE_PREFIXpackage table you need to insert a record with package= . In the TABLE_PREFIXwidgettype table you need to create an entry with class= , packageid = .

Item/Content file
This file is simple. It’s just for the convenience of the CMS router. You declare a class, and define the package and class. If you have a default configuration setting you should put it here. Here is the file for Static HTML (I’ve removed the comments and licensing.)


class vBCms_Item_Widget_Static extends vBCms_Item_Widget
{

protected $package = 'vBCms';
protected $class = 'Static';
protected $config = array('html' => 'Enter HTML here.');

}


Content file
This is the file that does the work. You need, at a minimum, to create two functions: getConfigView and getPageView. The first is called to configure your widget, and the second is called to render the view. With most widgets you’ll want to do some caching. For the static html widget it’s one query to get the data, and I couldn’t see executing a query to see if I needed to run one simple query.

Below is the file.



This php file should never be called directly, only from a properly initialized page. This call ensures that.