One page guide on creating a new modules to create home screen widget in ActiveCollab3 application.
First we need to create a directory for our module. We are going to create it under a /path/to/activecollab/custom/modules directory (where /path/to/activecollab is full path to activeCollab on your disk). For our example we are going to create my_reports directory:
Module Definition and Initialisation
After we’ve created directory for our module, we need to write module initialisation file. To do that, create an empty init.php file inside the /path/to/activecollab/custom/modules/my_reports directory and add following code to it:
/**
* My Reports module initialisation file
*/
define(‘MY_REPORTS_MODULE’, ‘my_reports’);
define(‘MY_REPORTS_MODULE_PATH’, __DIR__);
Next step is to create a module definiton class. Convention is that module definition class is named the same way as module directory, but in camel notation, plus word “Module”. Examples:
reports will be ReportsModule
sales_force_integration will be SalesForceIntegrationModule
ldap_provider will be LdapProviderModule
Save module definition class to a file that has the same name as definition class and add “.class.php” extension to it. In our case, we’ll add MyReportsModule.class.php to /path/to/activecollab/custom/modules/my_reports folder.
The code in MyReportsModule.class.php will look something like this:
/**
* My Reports module definition class
*/
class MyReportsModule extends AngieModule{
/**
* Short module name (should be the same as module directory name)
*
* @var string
*/
protected $name = ‘my_reports’;
/**
* Module version
*
* @var string
*/
protected $version = ‘1.0’;
/**
* Return module name (displayed in activeCollab administration panel)
*
* @return string
*/
function getDisplayName() {
return lang(‘My Reports’);
}
/**
* Return module description (displayed in activeCollab administration panel)
*
* @return string
*/
function getDescription() {
return lang(‘An example module’);
}
/**
* List events that this module listens to and define event handlers
*/
function defineHandlers() {
// Place where you can define your event handlers
}
/**
* List routes defined and used by this module
*/
function defineRoutes() {
// Place where you can define your routes
}
}
The next thing to do is to set an image for our module. For this we need to create directory /path/to/activecollab/custom/modules/my_reports/assets/default/images and place our image in it. It should be in 32×32 pixel PNG icon and it should be called module.png.
Now your module will be available for installation:
Creating a Home Screen Wiget
We want our new module to define a new home screen widget type that users can add to their home screens. To do that, we’ll need to do two things:
Add home screen widget definition class
Define event handler that enables activeCollab to discover our widget
Lets start by creating a home screen definition class. This class is part of activeCollab model, so we’ll out it in /model/homescreen_widgets folder of our module. We’ll call MyReportsHomeScreenWidget it and we’ll extend HomescreenWidget class (that’s part of activeCollab and provide plumbing that all home screen widgets use):
/**
* My reports home screen widget
*/
class MyReportsHomeScreenWidget extends HomescreenWidget {
/**
* Return home screen widget name (also widget label on home screen)
*
* @return string
*/
function getName() {
return lang(‘Example Widget’);
}
/**
* Return name of the widget group
*
* This value will determine where your widget will be displayed in Add a Widget dialog.
* It can be one of the existing groups, or a new group
*
* @return string
*/
function getGroupName() {
return lang(‘Examples’);
}
/**
* Return widget description (displayed when you select this widget in Add a Widget dialog)
*
* @return string
*/
function getDescription() {
return lang(‘Example how to make a homescreen widget’);
}
/**
* Render widget title
*
* @return string
*/
function renderTitle(IUser $user, $widget_id, $column_wrapper_class = NULL) {
return parent::renderTitle($user, $widget_id, $column_wrapper_class); // Inherit default title renderer (uses widget name)
}
/**
* Render widget body
*
* @return string
*/
function renderBody(IUser $user, $widget_id, $column_wrapper_class = NULL) {
return ‘Welcome to my reports widget’;
}
}
The code above is pretty much self-explanatory. What we can point out is that renderBody() usually uses templates, but for now returning a string is enough.
In order for activeCollab to recognise and load our new class we have to register it, and we are going to do that by putting following code inside init.php of our module (we created it in previous article):
MY_REPORTS_MODULE_PATH.’/models/homescreen_widgets/MyReportsHomeScreenWidget.class.php’
));
Autoloading Classes
AngieApplication::setForAutoload() will registers our new class and map it with a file where it is defined. This way, we do not need to include the file itself – activeCollab will do it for us automatically when class is needed.
In order for activeCollab to be able to discover our new home screen widget, we will need to listen to event that’s thrown by activeCollab when it wants to learn which widgets modules publish. Name of this event is defineHandlers and we’ll add following line to defineHandlers() method of our module definition class (MyReportsModule.class.php):
function defineHandlers() {
EventsManager::listen(‘on_homescreen_widget_types’, ‘on_homescreen_widget_types’);
}
Two parameters are important here:
Name of the event that we are listening
Name of the file where our event handler is defined (in most cases we’ll use same name as the event)
In order to write event handler that will be executed when this event is triggered, we’ll create on_homescreen_widget_types.php file and place it in /path/to/activecollab/custom/modules/my_reports/handlers directory. Content of this file is as follows:
/**
* on_homescreen_widget_types event handler
*/
/**
* Handle on_homescreen_widget_types event
*
* @param array $types
* @param IUser $user
*/
function my_reports_handle_on_homescreen_widget_types(&$types, IUser &$user) {
$types[] = new MyReportsHomeScreenWidget();
}
This small bit of code will add our widget to the list of known widget types when activeCollab requests it (when it prepares list of available widgets for Add a Widget dialog).
When you are done, go to your home screen and add your newly created widget to the page:
