Difference between revisions of "Creating a module"

Revision as of 15:03, 29 September 2008

Group-Office makes it very easy to rapidly develop an application. You can create your first basic module in about 15 minutes!

Basics

First set Group-Office to debugging mode so it won't use compressed javascript files. Set $config['debug']=true; in config.php.

Create a folder in the modules folder. Give it a name without special characters. In this example:

modules/mymodule/

Also create:

modules/mymodule/language
modules/mymodule/themes/
modules/mymodule/themes/Default
modules/mymodule/themes/Default/images/

Create the file:

modules/mymodule/themes/Default/style.css

/* This class is used to show the icon in the main tabpanel of GO */
.go-module-icon-mymodule {
	background-image: url('images/mymodule.png') !important;
}
/* This class is used to show the icon of a mymodule when it's linked to something */
.go-link-icon-10 {
	background-image: url('images/mymodule.png') !important;
	width:16px;
	height:16px;
}

for the module styles. This stylesheet is included automatically by the Group-Office framework.

Create the file:

modules/mymodule/scripts.txt and put this line in it.

modules/mymodule/MainPanel.js

This file is used by Group-Office to determine which scripts it will include in the page. Without this file your module will never work!

Now we will create the main panel of the module. A Group-Office module is an extension of an Ext Panel. So it can be put in any other Ext container.

MainPanel.js:

Ext.namespace('GO.mymodule');
 
GO.mymodule.MainPanel = function(config){
	
	if(!config)
	{
		config = {};
	}

	config.html='My first Group-Office module!';
	
	GO.mymodule.MainPanel.superclass.constructor.call(this);
}

Ext.extend(GO.mymodule.MainPanel, Ext.Panel,{
	
	
});

/*
 * This will add the module to the main tabpanel filled with all the modules
 */
GO.moduleManager.addModule('mymodule', GO.mymodule.MainPanel, {
	title : 'Mymodule',
	iconCls : 'go-module-icon-mymodule'
});

/*
 * If your module has a linkable item, you should add a link handler like this. 
 * The index (no. 12 in this case) should be a unique identifier of your item.
 * See classes/base/links.class.inc for an overview.
 * 
 * Basically this function opens a task window when a user clicks on it from a 
 * panel with links. 
 */
GO.linkHandlers[12]=function(id){
	
	var taskDialog = new GO.mymodule.TaskDialog();
	 
	taskDialog.show({task_id: id});
}

Now we have a very simple module that is only an empty panel. Now it's up to you to add some usefull functionality. Everything that works in the ExtJS framework works in GO. Do study the Ext extensions we already created for GO in the documentation.

Putting custom fields in module items

Create a file called 'scripts.inc.php' in the module directory. A script with this name will automatically be included by the Group-Office framework. Put this in it:

<?php
require_once($GO_MODULES->modules['customfields']['class_path'].'customfields.class.inc.php');
$cf = new customfields();
echo $cf->get_javascript(3, 'Companies');

The link type in this case is 3. The name for these custom fields is 'Companies'. Now we can mange the fields in the Custom fields admin module. Now you can add them to a tabpanel for example: In this example variable items is an array of Ext Panels:

if(GO.customfields && GO.customfields.types["3"])
{
	for(var i=0;i<GO.customfields.types["3"].panels.length;i++)
	{			  	
		items.push(GO.customfields.types["3"].panels[i]);
	}
}

Or we can add it to an Ext Xtemplate:

if(GO.customfields)
{
	template +=GO.customfields.displayPanelTemplate;
}

Where the var template is a basic Ext Xtemplate config string.

We must supply the JSON data for the template and/or the formpanels. In json.php for the Xtemplate:

if(isset($GO_MODULES->modules['customfields']))
{
	require_once($GO_MODULES->modules['customfields']['class_path'].'customfields.class.inc.php');
	$cf = new customfields();
	$response['data']['customfields']=
		$cf->get_all_fields_with_values(
			$GO_SECURITY->user_id, 3, $company_id);			
}

In json.php for the FormPanels:

if(isset($GO_MODULES->modules['customfields']))
{
	require_once($GO_MODULES->modules['customfields']['class_path'].'customfields.class.inc.php');
	$cf = new customfields();
	$values = $cf->get_values($GO_SECURITY->user_id, 3, $company_id);				
	$response['data']=array_merge($response['data'], $values);			
}

We must save the submitted values in action.php:

if(isset($GO_MODULES->modules['customfields']))
{
	require_once($GO_MODULES->modules['customfields']['class_path'].'customfields.class.inc.php');
	$cf = new customfields();
	$cf->update_fields($GO_SECURITY->user_id, $company_id, 3, $_POST);
}

That's it. Now you have your own custom fields in a module. You module must create on table for the custom fields. In this case:

CREATE TABLE IF NOT EXISTS `cf_3` (
  `link_id` int(11) NOT NULL default '0',
  PRIMARY KEY  (`link_id`)
) ENGINE=MyISAM;

Making your items linkable

1. Assign a link_type for your item. eg. An appointment has link_type: 1 a contact has link_type 2. You can find already used link types in classes/base/links.class.inc.php. Use a number higher then 100 so that it will never conflicted with new types officially released by Intermesh.
2. Create a style for the icon to display next to your linked item:

   .go-link-icon-100 {

   background-image

   url('images/16x16/icon-notepad.png') !important;

   width

   16px;

   height

   16px;

   }

   where 100 is the link type

Maintaining modules

When bugs are fixed or new features are made to a module the database has to be updated in some cases. Group-Office has a very nice mechanism to maintain modules. You can create SQL and PHP scripts for installing, updating and removing modules.

A module must have an "install" directory with the following files:

• install.inc.php: Is executed when a module is installed
• uninstall.inc.php: Is executed when a modules is uninstalled
• install.sql: Plain SQL code that is executed when a module is installed
• uninstall.sql: Plain SQL code that is executed when a module is uninstalled
• updates.inc.php: An array of SQL queries and scripts that are executed on an upgrade.

For eg. if you put the following in updates.inc.php:

<?php
$updates[] = "ALTER TABLE `ab_mailing_contacts` ADD `mail_sent` ENUM( '0', '1' ) NOT NULL ;";
$updates[] = "ALTER TABLE `ab_mailing_contacts` ADD `status` VARCHAR( 100 ) NOT NULL ";
$updates[] = "script:1.inc.php";

When the administrator runs install/update.php Group-Office will check how many queries of updates.inc.php it has already performed. If the number is lower then the amount of queries in the file then it will perform those queries and store the amount of queries performed in the database.

Sometimes you will need some PHP scripting in the update process. Then you can put script:filename.inc.php in the updates.inc.php file. This script must be put in the folder "updatescripts".

Important! Queries will be performed from top to bottom. So put new queries at the bottom of the updates.inc.php file.