Much of the process in registering WordPress widgets and making them available to your theme is automatically handled and cached by Vulnero on bootstrap. To create a widget, first create a new class file in the application/widgets/Widget directory with a file name matching your class name:

/* vim application/widgets/Widget/SampleBox.php */

class Widget_SampleBox {
    // The widget's title (required)
    protected $_title = 'Sample Widget Box';

    // Shown in the administration panel
    protected $_description = 'This is a sample widget.';

    public function displayAction(array $settings)
    {
        $this->view->version = VULNERO_VERSION;
    }
}

Here we implement the displayAction method which will be invoked when the widget is to be rendered on the page. This method is much like a controller action and has a view object associated with it in which you can assign values; the difference is that you are not required to have a displayAction method — excluding it will just render your view script with no injected variables.

The displayAction method takes a single parameter: an array of settings and values from your widget's setup (see: Settings below).

View Script

The next step is to specify the contents of your widget via the view script. Create a view script for your widget in application/views/scripts/widgets/sample-box.phtml. The name is generated from the second part of your class name, replacing capital letter with a lower-case, hyphenated version.

/* vim application/views/scripts/widgets/sample-box.phtml */

Hello world, this is a sample widget!

Autoloading

The simple presence of your new class and view script are all that's needed for Vulnero to locate and autoload your new widget. Login to the WordPress administration panel and click on Appearance — Widgets on the left-hand bar. Note that you must be using a WordPress theme that supports widgets for this to work.

Your new widget's title should appear among the widget choices. Drag the widget onto one of the regions on the right. The widget should now appear on your site.

Conditional Display

Often times you'll want your widget only to appear on certain pages. This can be achieved simply by implementing the isShown method in your class:

class Widget_SampleBox {
    ...
    protected function _isShown()
    {
        // Special method that returns the WordPress request URI
        return ($this->_getRequestUri() == '/about');
    }
}

One caveat to note is that widgets are rendered prior to routing, so you won't have access to the route from your application. To counter this, the getRequestUri method exists to retrieve the request string.

Display Options

By default, widgets are drawn with whatever wrappers your theme specifies. To remove the drawing of the title or the wrappers, implement the init method which is invoked when the widget is created:

class Widget_SampleBox {
    ...
    protected function _init()
    {
        // Do not draw the title
        $this->setDrawTitle(false);

        // Do not draw the wrappers (which also won't draw the title)
        $this->setDrawWrappers(false);
    }
}

Bootstrap

You may need access to your application's bootstrap to retrieve resources like caches or database connections. This can be achieved with the $_bootstrap class property:

class Widget_SampleBox {
    ...
    public function displayAction(array $settings)
    {
        $cache = $this->_bootstrap->bootstrap('cache')->getResource('cache');
        if (!$this->view->expensive = $cache->load('expensive')) {
            $this->view->expensive = some_expensive_operation();
        }

        $cache->save($this->view->expensive, 'expensive');
    }
}

Settings

WordPress widgets support forms rendered underneath the widget's section in the administration panel to collect settings like title or various other preferences. Adding such a form to a Vulnero_Widget can be done in two steps. First, implement a setupAction method:

public function setupAction(array $settings)
{
    $this->view->settings = $settings;
}

This method receives a single parameter, an array with the current settings and values just like the displayAction method. In most cases, you'll inject this into your view script to render the current values in your form.

Secondly, you must create another view script in the same directory and with the same name as your main widget view script, except that you append -setup before the extension:

/* vim application/views/scripts/widgets/sample-box-setup.phtml */
<p>
    <label for="title">Title</label>
    <input class="widefat" id="title" name="title" type="text" value="<?php echo $this->escape(isset($this->settings['title']) ? $this->settings['title'] : ''); ?>" />
</p>

No additional steps are required. Simply by implementing the setupAction method and adding a view script, your form will render in the administration area. All form inputs with valid names will automatically be saved by WordPress and passed into your widget's actions as an array.

Example Source Code

See the vulnero.com website plugin for additional example code. The download block on the right of this page is driven by a Vulnero_Widget object.

• Persisting Options with WordPress
• Adding a WordPress Administration Page