Updated May 17, 2009 by dragonmantank
Labels:	Phase-Implementation, Phase-Deploy, Featured

CreatingPlugins

Instructions for setting up new plugins

Introduction

Under Kiroku plugins are what defines how a page is rendered. For example, the Text plugin allows a user to enter HTML that is later spit back onto the screen. The Externallink plugin allows the user to link to an external resource. Plugins are generally defined as a page that is not terribly complicated in the actions it takes; pages that need a larger scope would be better off as Sections.

Details

All plugins are stored in the 'plugin' directory off of the main installation path and contain the main Plugin object as well as any views that are associated with the plugin. To demonstrate we will create a plugin that reads in an RSS feed from Slashdot and displays it on the screen.

Folder Structure

The basic folder structure is as follows:

plugins/
   Pluginname/
     views/
       scripts/
         view1.phtml
         ...
     Plugin.php

'Pluginname' is the name of your plugin (Text, Cmslink, etc). For our example, we will name the plugin 'Slashdot'. Plugin.php is the plugin object, and the filename will always be Plugin.php due to the naming convention of plugins (technical reason: we take advantage of auto loading and the Pear naming convention). The full object name for our plugin will be 'Slashdot_Plugin'.

view1.phtml is the name of a view script that we can call at any time during the render. Most simple plugins only have an 'edit.phtml' view which is used on the Admin side of things, which more complicated plugins might have partial views or different views depending on conditions.

The Plugin Object

The Plugin itself extends a base class, Bcms_Module. Bcms_Module takes care of some low level things such as allowing plugins to be built in a factory design, setting up the basic paths for the views, and defining functions that need to be inherited by its children:

edit()

Used to render the Edit page under the Admin section

insertDefaultPage($pageId)

When a new page is created with the module, this function inserts a blank, default page into the correct table

_save()

Saves the module information to the database after editing

updateText($data)

Updates the plugin object, then calls _save() to save the info to the database

render()

Renders the page through the CMS

We will not be saving any information to a database (though I would suggest caching it under real-world conditions) so we will have a very basic object:

class Slashdot_Plugin extends Bcms_Module
{
    protected $_name    = 'Slashdot';
    protected $_feedURI = 'http://rss.slashdot.org/Slashdot/slashdot';

    public function edit()
    {
        echo 'This is a sample module. No editing at this time!';
    }

    public function insertDefaultPage($pageId)
    {
        return true;
    }

    protected function _save()
    {
        return true;
    }

    public function updateText($data)
    {
        return true;
    }

    public function render()
    {
        $feed = Zend_Feed::import($this->_feedURI);
        $view = $this->_getView();
        $view->title = $feed->title();
        $view->feed  = $feed;
        
        return $view->render('render.phtml');
    }
}

So, what did we do here? Since we are not dealing with a database I simply made all the DB-specific functions return true. The meat and potatoes of this is the render() function. We import the Slashdot feed, create a new Zend_View object ($this->_getView()), and pass it the feed title and the feed itself. We then return the output from rendering the view and that output appears on our site.

What does our View (render.phtml) look like?

The View

Plugins use Zend_View for all the view rendering and there is nothing special about our view:

<h1><?php echo $this->title; ?></h1>

<?php foreach($this->feed as $item): ?>
	<div style="border: 1px solid black; margin: 5px; padding: 5px">
	<b><a href="<?php echo $item->link(); ?>"><?php echo $item->title() ?></a></b>

	<p>
	<?php echo $item->description(); ?>
	</div>
<?php endforeach; ?>

We echo out the title and then loop through all the RSS items spitting out a link to the full story as well as the description of the article. Since this is being rendered by Zend_View you also have access to all the functions that Zend_View normally has.

We throw 'render.phtml' into the 'plugins/Slashdot/views/scripts/' folder and our Plugin can now see it and use it for rendering.

Conclusion

Plugins are incredibly easy to create since Kiroku leverages the power of the Zend Framework. The above steps can easily be modified to allow for caching (via Zend_Cache), saving the output to a DB over time, and anything else you want to do to the data. It is also very quick. I created this example from scratch and wrote this wiki article in under 30 minutes including proof reading and debugging the code.