Custom Content Provider

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

In this article you will learn how to create your own content provider plugin. A content provider plugin is used by Widgetkit to retrieve the data which will be rendered by the Widgets. This feature allows different content types and makes Joomla, ZOO or K2 integration possible.

In order to create your own content provider 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, which you can find in the /wp-content/plugins/widgetkit/plugins/content folder in WordPress and /administrator/components/com_widgetkit/plugins/content 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

Let's start by creating the file structure for our plugin. We need the main file, an icon and the view to render the content editor layout.

|-- plugin.php          // main plugin content
|-- content.svg         // plugin icon in SVG format
+-- views/
|      edit.php         // edit 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. Whatever logic you need, it must be passed through this array. Checkout the comments to get information about what each one of it does. Don't forget the return statement, as this file is supposed to return a valid configuration array.

<?php

return array(

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

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

    // Plugin configuration
    'config' => array(

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

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

            // Url to the plugin icon
            'icon'  => 'plugins/content/PLUGIN-NAME/content.svg',

            // Supported widget fields
            'item'  => array('title', 'content', 'link', 'media'),

            // Default configuration data
            'data'  => array(
                'key' => 'value'
            )
    ),

    // Function that will retrieve and return the widget items
    'items' => function ($items, $content, $app) {

        // Retrieve the data and maps it to the widget item
        foreach ($source as $value) {

            $data = array();
            $data['title'] = 'TITLE';
            $data['content'] = 'CONTENT';
            $data['link'] = 'LINK';
            $data['media'] = 'MEDIA';

            // Add new item to the widget array of items
            $items->add($data);
        }

    },

    // 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/content/PLUGIN-NAME/views/edit.php');
        },

        // 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 views/edit.php file contains the form layout that will be displayed in the Widgetkit admin area when setting up the content provider. 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 style -->
<div class="uk-form uk-form-stacked">

    <!-- wrap each field -->
    <div class="uk-form-row">

        <!-- set the field label -->
        <label class="uk-form-label" for="wk-FIELD-NAME">FIELD-LABEL</label>

        <!-- set the field inputs -->
        <div class="uk-form-controls">
            <input id="wk-FIELD-NAME" class="uk-form-width-large" type="text" value="" ng-model="content.data['FIELD-NAME']">
        </div>

    </div>

    <!-- other examples -->
    <div class="uk-form-row">
        <div class="uk-form-controls">
            <label><input type="checkbox" ng-model="content.data['FIELD-NAME']" ng-true-value="1" ng-false-value="0"> FIELD-LABEL</label>
        </div>
    </div>

    <div class="uk-form-row">
        <label class="uk-form-label" for="wk-FIELD-NAME">FIELD-LABEL</label>
         <div class="uk-form-controls">
            <select id="wk-FIELD-NAME" class="uk-form-width-large" ng-model="content.data['FIELD-NAME']">
                <option value="">VALUE</option>
            </select>
        </div>
    </div>

</div>