Customization

Easily extend Widgetkit without loosing customizations during updates.

In Widgetkit you can add your own custom widget plugin, like a special Gallery, or your own custom content provider to load content from any source, like a shop extension. You can either store your customizations in the Theme Folder or as a Standalone Plugin.

Theme Folder

When using Warp7, you can place the customizations into a subfolder of THEME-NAME/widgetkit/. Widgetkit will automatically check that folder for any content providers or widget plugins.

• Place your custom content provider in THEME-NAME/widgetkit/content/PROVIDER-NAME/
• Place your custom widget plugin in THEME-NAME/widgetkit/widgets/WIDGETPLUGIN-NAME/

Standalone Plugin

Placing the customizations in your own standalone plugin will keep your customizations safe regardless of the Widgetkit or Theme changes. Your standalone plugin should load the Widgetkit App and register your custom Widgetkit plugins during the booting process.

WordPress

In WordPress your custom plugin only requires one main php file and be stored in the /wp-content/plugins/WP-PLUGIN-NAME folder. For the purpose for this tutorial will be placing the custom Widgetkit plugins into the /wp-content/plugins/WP-PLUGIN-NAME/plugins folder, but can be changed to whatever you prefer. All together the files structure would look like this.

+-- plugins/                            // Your custom Widgetkit plugins folder
+----- content/                         // Content provider plugins folder
|         WK-CONTENT-PLUGIN-NAME/
+----- widgets/                         // Widgets plugins folder
|         WK-WIDGET-PLUGIN-NAME/
|-- PLUGIN-NAME.php                     // The main Wordpress plugin file

In our custom plugin we need to execute our code after the Widgetkit main plugin has been executed, in order to do so we are relying on the 'plugins_loaded' action. Let's see how the code should look like.

Note In WordPress the main file only require the plugin name to be set into the Header comment, but there are plenty of other useful information to set there, as the version or author. Make sure to check out the WordPress documentation about it.

<?php

/*
    Plugin Name: PLUGIN-NAME
*/

use YOOtheme\Widgetkit\Application;

add_action('plugins_loaded', function() {

    if (!class_exists('YOOtheme\Widgetkit\Application')) {
        return;
    }

    $app = Application::getInstance();

    // Register plugin path
    $app['plugins']->addPath(__DIR__.'/plugin/plugin.php');
    $app['locator']->addPath('plugins/content/wkcustom', __DIR__.'/plugin');
});

Joomla

In Joomla your custom plugin requires two files, the main PHP file and the main XML file, both to be stored in the /plugins/system/JOOMLA-PLUGIN-NAME folder. For the purpose of this tutorial we'll be placing the custom Widgetkit plugins into the /plugins/system/JOOMLA-PLUGIN-NAME/plugins folder, but that can be changed to whatever you prefer. All together the files structure would look like this:

+-- plugins/                            // Your custom Widgetkit plugins folder
+----- content/                         // Content provider plugins folder
|         WK-CONTENT-PLUGIN-NAME/
+----- widgets/                         // Widgets plugins folder
|         WK-WIDGET-PLUGIN-NAME/
|-- PLUGIN-NAME.php                     // The main Joomla plugin file
|-- PLUGIN-NAME.xml                     // The main Joomla plugin xml file

In our custom plugin we need to hook our code into the onAfterInitialise Joomla event. In order to do so we are relying on the System Plugin. Let's see how the code should look like.

Note In Joomla the plugin must be installed through the admin installer before being recognized. Make sure to do so after having completed the main structure.

<?php

class plgSystemPLUGIN-NAME extends JPlugin
{
    public function onAfterInitialise()
    {
        // Load Widgetkit App
        if (!$app = @include JPATH_ADMINISTRATOR.'/components/com_widgetkit/widgetkit-app.php') {
            return;
        }

        // Register all plugins
        $app['plugins']->addPath(__DIR__.'/plugins/*/*/plugin.php');

        // Register each CONTENT provider plugin path
        $app['locator']->addPath('plugins/content/PLUGIN-NAME', __DIR__.'/plugins/content/PLUGIN-NAME');

        // Register each WIDGET plugin path
        $app['locator']->addPath('plugins/widgets/PLUGIN-NAME', __DIR__.'/plugins/widgets/PLUGIN-NAME');
    }
}

The PLUGIN-NAME.xml manifest file is necessary to be declared as well. There are many options available for which we invite you to check the Joomla documentation. For the purpose of this tutorial the following version will suffice.

<?xml version="1.0" encoding="utf-8"?>
<extension type="plugin" version="3.1" group="system" method="upgrade">
    <name>System - PLUGIN-NAME</name>
    <version>VERSION</version>
    <description>DESCRIPTION</description>
    <files>
        <filename plugin="PLUGIN-NAME">PLUGIN-NAME.php</filename>
        <folder>plugins</folder>
    </files>
</extension>