Custom Widget Plugin

Widgetkit is modular and extendable by design: Widget content and widget rendering are separate from each other.

In this article you will learn how to create your own widget plugin. A widget plugin is used by Widgetkit to determine how a given content element is rendered. This allows a content element to be reused and to be rendered in different ways each time.

Start From Scratch

In order to create your own widget plugin you can copy an existing one and start adapting it to your needs. Alternatively, you can create a new one from scratch following the steps explained here. In both scenarios you should rely on the existing plugins as reference. They are located in the /wp-content/plugins/widgetkit/plugins/widgets folder in WordPress and /administrator/components/com_widgetkit/plugins/widgets folder in Joomla.

Note Please make sure to store your customizations in a way so that they don't get lost during a Widgetkit update.

File Structure

|-- plugin.php          // main plugin content
|-- widget.svg          // plugin icon in SVG format
+-- views/
|      edit.php         // edit form layout
|      widget.php       // widget form layout

plugin.php

The plugin.php file contains a PHP array to set your plugin by passing the configurations and event functions to Widgetkit. Don't forget the return statement, as this file is supposed to return a valid configuration array.

<?php

return array(

    // Main class the plugin is extending
    'main' => 'YOOtheme\\Widgetkit\\Widget\\Widget',

    // Plugin configuration
    'config' => function($app) {

        return array(

            // Plugin raw name
            'name'  => 'PLUGIN-NAME',

            // Plugin label which will be displayed to the user
            'label' => 'PLUGIN-LABEL',

            // Url to the icon that will be used in the widget plugin overview
            'icon'  => $app['url']->to('plugins/widgets/PLUGIN-NAME/widget.svg'),

            // Path to the view file that will be used when rendering the widget
            'view'  => 'plugins/widgets/PLUGIN-NAME/views/widget.php',

            // Supported widget fields
            // A list of fields the widget requires from a selected content element.
            // Example: The map requires a 'location' field to be present.
            'item'  => array('title', 'content'),

            // Default settings to be used for every widget instance
            'settings'  => array(
                'key' => 'value'
            )
        );
    },

    // An array of Widgetkit events you want to listen to
    'events' => array(

        // Triggered when Widgetkit is initialized in the back end
        'init.admin' => function($event, $app) {

            // Registers the edit view
            $app['angular']->addTemplate('PLUGIN-NAME.edit', 'plugins/widgets/PLUGIN-NAME/views/edit.php', true);
        },

        // Triggered when Widgetkit is initialized in the front end
        'init.site' => function($event, $app) {},

        // Triggered when Widgetkit is initialized
        'init' => function($event, $app) {}
    )

);

views/edit.php

The view/edit.php file contains the form layout that will be displayed when setting up the Widget rendering options. It relies on UIkit for its styling and on AngularJS for the logic. Check the respective documentation for further information.

<!-- wrap the content with uk-form and uk-grid styles -->
<div class="uk-grid uk-grid-divider uk-form uk-form-horizontal" data-uk-grid-margin>

    <!-- set the left column -->
    <div class="uk-width-medium-1-4">

        <!-- set the wk specific style -->
        <div class="wk-panel-marginless">

            <!-- set the navigation connecting it to the uk-switcher -->
            <ul class="uk-nav uk-nav-side" data-uk-switcher="{connect:'#nav-content'}">
                <li><a href="/">General</a></li>
                <li></li>
                <!-- keep adding them as you need -->
            </ul>
        </div>

    </div>

    <!-- set the right column -->
    <div class="uk-width-medium-3-4">

        <!-- set the uk-switcher content -->
        <ul id="nav-content" class="uk-switcher">

            <!-- general switcher section content -->
            <li>
                <div class="uk-form-row">
                    <label class="uk-form-FIELD-NAME" for="wk-columns">FIELD-LABEL</label>
                    <div class="uk-form-controls">
                        <select id="wk-FIELD-NAME" class="uk-form-width-medium" ng-model="widget.data['FIELD-NAME']">
                            <option value="1">1</option>
                            <option value="2">2</option>
                        </select>
                    </div>
                </div>
            </li>

            <li></li>
            <!-- keep adding one for each section you have set -->

        </ul>

    </div>
</div>

views/widget.php

This file is used to render the widget in the front end. Content and render settings are combined and converted into HTML for your browser.

The best way to understand the rendering possibilities is by looking at the code of the built-in Widgets. To get you started, here is a quick reference of available variables inside views/widget.php.

Note When iterating over the $items you can access the custom fields by their keys. The available keys are specified in the item configuration of the content provider, e.g.: $item['customkey'].