How to write a Joobsbox plugin

From JoobsBox Documentation

You want to extend Joobsbox with some fancy functionality but you don't intend to dive into the core of the application? No problemo! That's why Joobsbox gives you plugins to extend its functionality. Below you can find out how to create such a plugin.

[edit] The plugin architecture

While doing its job, Joobsbox raises some flags from time to time. These flags are called events. When this happens, it also looks for plugins that care about these flags and invites them to stage to perform their action. Here's an example:

• Joobsbox homepage requests the available jobs from the database boss
• When it receives these jobs, it raises a flag: "received_jobs"
• It then calls each plugin that has eyes for this event. This is done by simply defining a method called "event_received_jobs".
• Each plugin has its moment of glory
• Joobsbox continues normal operation and shows the jobs

Each plugin defines *event handlers* or *filters* that get executed when a flag is raised.

[edit] Events vs filters

Joobsbox features two flavours of plugin related functionality. Above you've seen how an event works. Joobsbox doesn't expect an event handler to return anything. However, there is a special type of handlers called filters. A filter is given some pieces of information and is then expected to return it. It's each plugin's job to take care about that data.

[edit] Creating a new plugin

To create a plugin, make a new folder in plugins/ starting with a capital letter and named uniquely as your plugin name.

[edit] Let's create the plugin

For the sake of simplicity, we'll use an example plugin named Hello plugin, the simplest Joobsbox plugin in the world.

• Create the folder plugins/Hello
• Create a php file called Hello.php in this folder.
• Open Hello.php in your favourite source code editor

This file needs to contain your plugin class called Hello, just as the plugin name, plugin folder and plugin file. This class needs to extend the core class Joobsbox_Plugin_Base. You'll find out what magic happens by extending this class. That's it! You have a plugin. Now you have to teach it to watch the flags. In order to decide the precise moment your plugin is going to stage to perform, consult the list of events and filters. Again for the sake of example, we'll consider a filter and an event.

The event: received_jobs This flag gets raised when the homepage receives the jobs from the Jobs model. To create an event handler, you need to define a function called quite imaginatively event_received_jobs. From now on, every time the homepage is loaded, your plugin's received_jobs event handler will get executed.

The filter: job_description This filter is requested every time a job description needs to be displayed. A common place for this to happen is the job detail page. This filter for example sends the job description string as a parameter to your function. Your plugin filter function will then make modifications to the string and return it.

Whether your function receives 1 or 10 arguments, they need to be returned in an array, ordered exactly the same as they were received. This is because, as mentioned above, filter functions from different plugins chain.

[edit] What magic happens by extending Joobsbox_Plugin_Base

[edit] Plugin data storage

Simple means of storing data in the database, as key-value pairs. You can store text data that only your plugin can read and write. This can be done by using the following functions:

getConfiguration($key) // retrieves the value that coresponds to $key
deleteConfigurationByName($key) // deletes the entry that corresponds to $key

[edit] Get easy access to Joobsbox models

getModel($name)

[edit] Get easy access to Joobsbox helpers

$this->_helper->makeLink('something that has to get formatted as a link')

[edit] Admin plugins

Simple plugins and admin plugins share the same plugins/ folder and the same magic mentioned above. However, admin plugins are something a little more advanced, thus, if they want, they can also show up in the dashboard on the admin panel home page.

[edit] The configuration file

Each admin plugin has to set up a config.xml of its own. If Hello plugin were an admin plugin, it would have to provide Joobsbox with the file plugins/Hello/config.xml. This file needs to have the following format:

<?xml version="1.0"?>
<Hello>
  <main>
    <title_en>Hello</title_en>
    <image>hello.png</image>
    <version>0.1</version>
    <description>Hello plugin has a crucial importance to Joobsbox. Nothing more to say.</description>
  </main>
</Hello>

What this does is that it sets the plugin title both in the admin panel menu and dashboard. The directive title_$lang is there to set up the title for different languages. You could for example set up title_fr for the French title.

[edit] Appearing on the Dashboard

In order for a plugin to appear on the dashboard, it has to implement the function dashboard() and also have a dashboard view script, located in Hello/views/dashboard.phtml.

[edit] Magic inherits

Each admin plugin features a few variables and methods that save lives. The view scripts have the following methods and variables:

Methods and variables accessible in the plugin class:

$this->_helper // provides access to Joobsbox helpers