Creating a Cerb5 Report Plugin
From Cerberus Helpdesk Wiki
Warning this code only works with Cerberus 4.2.3 and earlier. This example needs to be updated to the new format.
See the forums for more info on the updated format. http://www.cerb4.com/forums/showthread.php?t=2438
Cerberus Helpdesk is built using an application framework called Devblocks. Devblocks allows Cerberus to define extension points which define places in the application open to custom development in the form of plugins. A plugin developer can create extensions inside their plugins that take advantage of the extension points, allowing the custom code to look and work like it is part of Cerberus itself.
In this tutorial, we're going to create a simple Cerberus plugin containing a single extension to show a report that displays the workers of your helpdesk.
Contents |
Getting Cerberus
To develop a plugin, the first thing we need is a copy of Cerberus Helpdesk on your computer. You can download Cerberus and find the Quick Start instructions from here.
The Structure of a Plugin
Once you have the files placed in a web accessible directory on your machine you're ready to create your first plugin. Go into the plugins directory from within your Cerberus installation folder, and create a new folder, which you will name what you want your plugin to be called. A good naming convention to use is companyname.shortdescription. For this example we'll name our plugin wgm.reports.myreports .
Now inside the newly created directory create an empty file named plugin.xml . In that same directory create three folders for api, resources, and templates. Inside the api directory create an empty file called App.php . Inside the templates directory create an empty file called report_workers.tpl.php .
The file and directory structure should look like this:
<pluginname>\ plugin.xml api\ App.php resources\ templates\ report_workers.tpl
Plugin Manifest File
Open the plugin.xml and paste the following inside it:
<!DOCTYPE plugin SYSTEM "../../libs/devblocks/plugin.dtd"> <plugin> <id>wgm.reports.myreports</id> <name>WGM: Reports</name> <description>Reports created by WGM</description> <author>Mike Fogg</author> <revision>1</revision> <link>http://www.webgroupmedia.com/</link> <!-- Removed in 4.3.0 <class> <file>api/App.php</file> <name>WGMReportsPlugin</name> </class> --> <extensions> <extension point="cerberusweb.report"> <id>report.workers.my_workers_list</id> <name>My Workers Report</name> <class> <file>api/App.php</file> <name>WGMReportWorkers</name> </class> <params> <param key="report_name" value="My Workers Report" /> <param key="report_group" value="report.group.workers" /> </params> </extension> </extensions> </plugin>
The plugin manifest is a container that tells Cerberus what extensions your plugin defines, and what extension points those extensions are based on. The first six tags in the file contain general information about your plugin:
<id>wgm.reports.myreports</id> <name>WGM: Reports</name> <description>Reports created by WGM</description> <author>Mike Fogg</author> <revision>1</revision> <link>http://www.webgroupmedia.com/</link>
- <id> A unique identifier for your plugin. This should be named the same as the plugin directory you created before.
- <name> A user friendly readable name for your plugin. This will display in the plugins tab in the Cerberus Configuration area.
- <description> A brief description of what your plugin contains and does. This will also display in the "plugins" tab in the Cerberus Configuration area.
- <author> Where you should put your name or your company's name
- <revision> Your plugin revision should be an integer. "1" is fine here. (this setting comes in handy in a more advanced topic of plugin upgrades).
- <link> (optional) A link to your website which is accessible from the Cerberus Configuration area plugins tab.
The next few tell Cerberus where to find your code.
- No longer needed in 4.3.0+
<class> <file>api/App.php</file> <name>WGMReportsPlugin</name> </class>
- <class> The class tag has two elements inside it.
- <file> For specifying the relative path where it finds your main plugin class file, and the other
- <name> The name is where you tell the name of your main plugin class created inside the above file. It's important that this name be unique so you should prefix it with your company name, or something else reliably unique.
Then you define your extensions.
- <extensions> is where you need to include the extension details for any extensions you are creating. Since we are only creating one report at this time, we'll only have one <extension> tag inside it.
<extension point="cerberusweb.report"> <id>report.workers.my_workers_list</id> <name>My Workers Report</name> <class> <file>api/App.php</file> <name>WGMReportWorkers</name> </class> <params> <param key="report_name" value="My Workers Report" /> <param key="report_group" value="report.group.workers" /> </params> </extension>
The extension tag has an attribute “point” which is where you can specify the extension point that your extension is going to be used from. We want our report to automatically show up along with all the other existing reports so we'll specify the extension point cerberusweb.report .
- <name> is a friendly name for your report
- <class> is where you specify what file contains your report, and the class name. Again, be sure prefix it with your company name, or something else reliably unique to avoid namespace clashes.
- <params> are parameters specific to each extension point. The cerberusweb.report extension point has two parameters available. The report_name parameter is where you choose the name that will display on the report itself as the title. The report_group parameter is where you choose which group your report will be displayed under on the reports page in Cerberus. For this example we're going to assign our report to the workers group of reports.
The Plugin Class
- This in no longer needed as of 4.3.0
Open the file App.php that you created before and paste the following into it:
class WGMReportsPlugin extends DevblocksPlugin { function load(DevblocksPluginManifest $manifest) { } };
This creates the class that does any initialization for our plugin. Notice that the class has the same name we specified in the plugin.xml for our plugin's class name. We don't require any initialization for this plugin, so the class is minimal.
The Class for our Extension
While keeping App.php open from the previous step, paste this at the end of the file:
<?php class WGMReportWorkers extends Extension_Report { private $tpl_path = null; function __construct($manifest) { parent::__construct($manifest); $this->tpl_path = realpath(dirname(__FILE__).'/../templates'); } function render() { $tpl = DevblocksPlatform::getTemplateService(); $tpl->cache_lifetime = "0"; $tpl->assign('path', $this->tpl_path); $workers = DAO_Worker::getAll(); $tpl->assign('workers', $workers); $tpl->display('file:' . $this->tpl_path . '/report_workers.tpl'); } }; ?>
This is the main class for your extension. We've named the class the same as the class name we specified in the plugin.xml for our plugin. Also note that the class extends the Reports Extension class called Extension_Report.
The render() method is where we do whatever work will be required for our report. In our example, the render() method simply initializes the templating system and then does a Data Access Object (DAO) call for our workers. The DAO is a model abstraction that returns the list of workers in the helpdesk which happen to come from the worker table.
You could just as easily obtain your data using a SQL query using ADODB in the render method instead. To do so you would simply replace the line:
$workers = DAO_Worker::getAll();
with:
$db = DevblocksPlatform::getDatabaseService(); $sql = "SELECT first_name, last_name FROM worker "; $rs = $db->Execute($sql); $workers = array(); while(!$rs->EOF) { unset($worker); $worker->first_name = $rs->fields['first_name']; $worker->last_name = $rs->fields['last_name']; $workers[] = $worker; $rs->MoveNext(); }
For more complicated reports you might find it helpful to refer to the Cerberus Database Schema.
The last thing the render method does is assign the list of workers it obtained into a template variable, and tell the template to draw.
The Template
The template is where you define the markup that determines what your report will look like. Open the report_workers.tpl.php that you created near the beginning of this tutorial and paste the following inside it.
<h2>My Workers Report</h2> <br/> {foreach from=$workers item=worker} {$worker->first_name} {$worker->last_name}<br/> {/foreach}
Cerberus Helpdesk uses the Smarty template system, so if you're at all familiar with that this will look pretty straightforward. It loops through each worker and displays their names.
