Difference between revisions of "Creating a module"

Revision as of 15:59, 30 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

More information will follow. You can have a look at modules/notes/NoteDialog.js on how to add a links panel.

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.

Generate code for a module

Because the base of a lot of code is the same. We created a script that can generate the grids and dialogs of database table. The idea is that you create tables for modules first and then generate code to manipulate the interface.

Get the modulegenerator code from here:

http://sourceforge.net/project/showfiles.php?group_id=76359

Extract it and enter the directory. You must have the php5 command line interface installed (On Debian/Ubuntu: apt-get install php5-cli).

In this example we will generate a second notes module. I actually used this to generate the base of the Notes module. It will not create a perfect module, but it's a good start.

Edit config.inc.php and paste the following in it:

<?php
require('../../www/Group-Office.php');
//name of the module. No spaces or strange characters.
$module = 'notes2';

//Short name of the module. The prefix of the database tables.
$prefix = 'no';

$tables=array();
//Tables to create an interface for


/*
 * If you specify a link_type then linking will be enabled. Make sure your table also has a 
 * ctime and mtime column for this to work. Also either authenticate or authenticate related must be set.
 * 
 * If you specify authenticate. Then make sure your table has an acl_read and acl_write column
 */

$westpanel = array(
	'mainpanel_tag'=> 'WESTPANEL', //{WESTPANEL} will be replaced in the MainPanel template defined below.
	'template'=>'GridPanel.tpl', //The template to use for the grid. This is the only option at the moment
	'name'=>'no_categories',  //Name of the table
	'friendly_single'=>'category', //Name for a single item in this table. Must be lower case and alphanummeric
	'friendly_multiple'=>'categories',//Name for a multiple items in this table. Must be lower case and alphanummeric
	'authenticate'=>true,//Secure these items with authentication? If true then acl_read and acl_write columns must be defined in the table
	'paging'=>false, //Use pagination in the grid?
	'autoload'=>true, //Automatically load this table with data after rendering?
	'files'=>false //Can files be uploaded to these items?
	); 

$tables[] = $westpanel;

$tables[] = array(
	'mainpanel_tag'=> 'CENTERPANEL',
	'mainpanel_tags'=>array(
		'centerpanel_related_field'=>'category_id',
		'centerpanel_related_friendly_multiple_ucfirst'=>'Categories',
		'centerpanel_related_friendly_multiple'=>'categories',
		'centerpanel_friendly_single_ucfirst'=>'Note',
		'centerpanel_friendly_single'=>'note',
		'EASTPANEL'=>'GO.notes.NotePanel'
		), //Custom tags for the mainpanel template that will be replaced
	'template'=>'GridPanel.tpl',
	'name'=>'no_notes', 
	'friendly_single'=>'note', 
	'friendly_multiple'=>'notes',
	'paging'=>true,
	'autoload'=>false,
	'authenticate'=>false,
	'authenticate_relation'=>true, //Authenticate a related table. In this example the notes categories.
	'files'=>true,
	'link_type'=>4, //If a link type is specified then this item will be linkable to other items. Choose a free identifier above 100!
	'relation'=>array('field'=>'category_id', 'remote_field'=>'id', 'remote_table'=>$westpanel)); //Define a relation between the tables
		
$main_template='MainPanel.tpl'; //The template for MainPanel.js

You can also find this content in the file notes_config.inc.php

Adjust the path to Group-Office.php at the top of the config file.

Now run: "php create.php" from the command line. It will create the folder "modules/notes2". Now login to Group-Office as an administrator and install the new module!