Module

Class Vtiger_Module provides an API to work with vtiger CRM modules.

include_once('vtlib/Vtiger/Module.php');
$moduleInstance = new Vtiger_Module();
$moduleInstance->name = 'Payslip';
$moduleInstance->save();
$moduleInstance->initTables();
$menuInstance = Vtiger_Menu::getInstance('Tools');
$menuInstance->addModule($moduleInstance);

Vtiger_Module->initTables() API will initialize (create) the 3 necessary tables a module should have as explained below:

Vtiger_Menu->addModule(<ModuleInstance>) API will create menu item which serves as UI entry point for the module.

Module Block

Class Vtiger_Block provides API to work with a Module block, the container which holds the fields together. The example given below describes the way of creating new blocks for the module created earlier:

include_once('vtlib/Vtiger/Module.php');
$blockInstance = new Vtiger_Block();
$blockInstance->label = 'LBL_PAYSLIP_INFORMATION';
$moduleInstance->addBlock($blockInstance);
$blockInstance2 = new Vtiger_Block();
$blockInstance2->label = 'LBL_CUSTOM_INFORMATION';
$moduleInstance->addBlock($blockInstance2);

Note

LBL_CUSTOM_INFORMATION block should always be created to support Custom Fields for a module.

Module Field

Class Vtiger_Field provides API to work with a Module field, which are the basic elements that store and display the module record data.

The example given below describes the way of creating new field for the module created earlier:

include_once('vtlib/Vtiger/Module.php');
$fieldInstance = new Vtiger_Field();
$fieldInstance->name = 'PayslipName';
$fieldInstance->table = 'vtiger_payslip';
$fieldInstance->column = 'payslipname';
$fieldInstance->columntype = 'VARCHAR(100)';
$fieldInstance->uitype = 2;
$fieldInstance->typeofdata = 'V~M';
$blockInstance->addField($fieldInstance);
($fieldInstance);

Note

The fieldInstance name is a mandatory value to be set before saving / adding to block. Other values (if not set) are defaulted as explained below

Optional Settings

Entity Identifier

One of the mandatory field should be set as entity identifier of module once it is created. This field will be used for showing the details in ‘Last Viewed Entries’ etc...

$moduleInstance->setEntityIdentifier($fieldInstance);

Set Picklist Values

If the field is of Picklist type (uitype 15, 16, 33, 55, 111) then you can configure the initial values using the following API:

$fieldInstance->setPicklistValues( Array ('Value1', 'Value2') );

Set Related Module

If the field is of Popup select type (uitype=10), you can configure the related modules which could be selected via Popup using the following API:

$fieldInstance->setRelatedModules(Array('OtherModule1', 'OtherModule2'));

To unset the related module you can use the following API:

$fieldInstance->unsetRelatedModules(Array('OtherModule2'));

Set MassEdit property

You can make the field available for mass editing use the following ways described below: When creating the field you can set the property:

include_once('vtlib/Vtiger/Module.php');
$fieldInstance = new Vtiger_Field();
$fieldInstance->name = 'TestField';
...
...
$blockInstance->addField($fieldInstance);

$fieldInstance->setMassEditable(value);

The value set for masseditable property has the following meaning:

Module Filter

Class Vtiger_Filter provides API to work with a Module’s custom view or filter. The list view display is controlled via these filters.

The example given below describes the way of creating new filter for the module:

include_once('vtlib/Vtiger/Module.php');
$filterInstance = new Vtiger_Filter();
$filterInstance->name = 'All';
$filterInstance->isdefault = true;
$moduleInstance->addFilter($filterInstance);

Configure fields

To add fields to the filter you can use the following API:

$filterInstance->addField($fieldInstance, $columnIndex);

Where $columnIndex (optional) is the order/index at which the field should appear in the list view.

Setup Rules

Once the field is added to filter you can setup rule (condition) for filtering as well using the following API:

$filterInstance->addRule($fieldInstance, $comparator, $compareValue, $columnIndex);

Where comparator could be one of the following:

$compareValue is the value against with the field needs to be compared.

$columnIndex (optional) is the order at which this rule condition should be applied.

Module Related List

One module could be associated with multiple records of other module that is displayed under “More Information” tab on Detail View.

The example given below describes the way of creating a relation between a Payslip and Accounts module:

include_once('vtlib/Vtiger/Module.php');
$moduleInstance = Vtiger_Module::getInstance('Payslip');
$accountsModule = Vtiger_Module::getInstance('Accounts');
$relationLabel  = 'Accounts';
$moduleInstance->setRelatedList(
      $accountsModule, $relationLabel, Array('ADD','SELECT')
);

With this you can Add one or more Accounts to Payslip records. To drop the relation between the modules use the following:

$moduleInstance->unsetRelatedList($targetModuleInstance);

About setRelatedList API

Vtiger_Module->setRelatedList(<TARGET MODULE>[, <HEADER LABEL>, <ALLOWED ACTIONS>, <CALLBACK FUNCTION NAME>]);

Note

This API will create an entry in the vtiger_crmentityrel table to keep track of relation between module records. Standard modules available in vtiger CRM handles the relation in separate tables and performs the JOIN to fetch data specific to each module. This is an attempt to achieve generic behavior. You can write custom call back functions to handle related list queries that will meet your requirements.

Limitations

Following limitations apply for the related list APIs

1. Standard module class variables are not set as required by the get_related_list vtlib module API. Case handling should be handled @function vtlib_setup_modulevars in include/utils/VtlibUtils.php
2. get_related_list API added to module class does not handle JOIN on tables where some modules like (Accounts) store information hence complete details are not fetched in the Related List View. (Example Sorting on the city field on related list view will fail if dieOnError is true)

Module Sharing Access

Sharing access configuration for the module can be done as shown below:

The example given below describes the way to configure the Payslip module as Private

include_once('vtlib/Vtiger/Module.php');
$moduleInstance = Vtiger_Module::getInstance('Payslip');
$moduleInstance->setDefaultSharing('Private');

The <PERMISSION_TYPE> can be one of the following:

Module Tool

Features like Import, Export are termed as module tools. Such tools can enabled or disabled as shown below:

The example given below describes the way to enable and disable the tools for Payslip module

include_once('vtlib/Vtiger/Module.php');
$moduleInstance = Vtiger_Module::getInstance('Payslip');
$module->enableTools(Array('Import', 'Export'));
$module->disableTools('Export');

Module Event

To register an event for a module, use the following:

include_once('vtlib/Vtiger/Event.php');
Vtiger_Event::register('<MODULENAME>', '<EVENTNAME>', '<HANDLERCLASS>', '<HANDLERFILE>');

Example

Registering event callback before and after save.

if(Vtiger_Event::hasSupport()) {
      Vtiger_Event::register(
            'Payslip', 'vtiger.entity.aftersave',
            'PayslipHandler', 'modules/Payslip/PayslipHandler.php'
      );
      Vtiger_Event::register(
            'Payslip', 'vtiger.entity.beforesave',
            'PayslipHandler', 'modules/Payslip/PayslipHandler.php'
          );
}

modules/Payslip/PayslipHandler.php

<?php
class PayslipHandler extends VTEventHandler {
      function handleEvent($eventName, $data) {
            if($eventName == 'vtiger.entity.beforesave') {
                 // Entity is about to be saved, take required action
                        }
            if($eventName == 'vtiger.entity.aftersave') {
                 // Entity has been saved, take next action
                        }
          }
}
?>

Module Webservice

You will need to invoke the setup API to enable the support for the custom modules.

include_once('vtlib/Vtiger/Module.php');
$moduleInstance = Vtiger_Module::getInstance('Payslip');
$moduleInstance->initWebservice();

Note

When the module is imported the Webservice initialize API is automatically invoked.

Module Link

You can add custom web link to the module using the following API:

include_once('vtlib/Vtiger/Module.php');
$moduleInstance = Vtiger_Module::getInstance('ModuleName');
$moduleInstance->addLink(<LinkType>, <LinkLabel>, <LinkURL>);

Attention

REVIEW for Vtiger 6.0

In module’s ListView handler page (modules/Payslip/ListView.php) you will need this piece of code (before the call to $smarty->display()) :

include_once('vtlib/Vtiger/Link.php');
$customlink_params = Array('MODULE' => $currentModule, 'ACTION'=>
vtlib_purify($_REQUEST['action']), 'CATEGORY' => $category);
$smarty->assign('CUSTOM_LINKS', Vtiger_Link::getAllByType(getTabid($currentModule),
Array('LISTVIEW', 'LISTVIEWBASIC'), $customlink_params));

In module’s DetailView handler page (modules/Payslip/DetailView.php) you will need this piece of code (before the call to $smarty->display()) :

include_once('vtlib/Vtiger/Link.php');
$customlink_params = Array('MODULE' => $currentModule, 'RECORD' => $focus->id, 'ACTION'=>
vtlib_purify($_REQUEST['action']));
$smarty->assign('CUSTOM_LINKS', Vtiger_Link::getAllByType(getTabid($currentModule),
Array('DETAILVIEW', 'DETAILVIEWBASIC', 'DETAILVIEWWIDGET'), $customlink_params));

Note

The $MODULE$, $ACTION$ and $RECORD$ variables in the LinkURL, will be replaced with the values set through DetailView.php The $MODULE$, $ACTION$, $CATEGORY$ variables in the LinkURL, will be replaced with the values set through ListView.php

Special LinkType

Following LinkTypes are treated specially while processing for display:

Package Export

vtlib provides API to export module as a zip (package) file which can used for importing through Module Manger.

require_once('vtlib/Vtiger/Package.php');
require_once('vtlib/Vtiger/Module.php');
$package = new Vtiger_Package();
$package->export('<MODULE Instance>', '<DESTINATION DIR>', '<ZIPFILE NAME>', <DIRECT DOWNLOAD>);

Example

require_once('vtlib/Vtiger/Package.php');
require_once('vtlib/Vtiger/Module.php');
$package = new Vtiger_Package();
$package->export(
      Vtiger_Module::getInstance('Payslip'),
      'test/vtlib',
      'Payslip-Export.zip',
      true
);

Note

Please make sure test/vtlib directory exists under vtigercrm root directory and is writeable.

Package Import

Tip

Use Module Manager

Language Export

vtlib provides API to export language pack as a zip (package) file which can used for importing through Module Manger.

require_once('vtlib/Vtiger/Module.php');
require_once('vtlib/Vtiger/Language.php');
$language = new Vtiger_Language();
$language->export('<LanguagePrefix>', '<DESTINATION DIR>', '<ZIPFILE NAME>', <DIRECT DOWNLOAD>);

Example

require_once('vtlib/Vtiger/Module.php');
require_once('vtlib/Vtiger/Language.php');
$language = new Vtiger_Language();
$language->export(
      'en_us',
      'test/vtlib',
      'en_us-Export.zip',
      true
);

Note

Please make sure test/vtlib directory exists under vtigercrm root directory and is writeable.

Console Tool

This CLI (command line interface) tool will assist you to get the skeleton implementation of extensions for Vtiger.

Jump Start

php -f vtlib/tools/console.php

Have a good time. Press CTRL+C to "quit".
Choose the options below:
1. Create New Module.
2. Create New Layout.
3. Create New Language Pack.
4. Create Test Language Pack.
5. Import Module.
6. Update Module.
7. Remove Module.
Enter your choice:

Create New Module

Enter your choice: 1
>>> MODULE <<<
Enter module name: MySandboxModule
Entity field (Name): name
Creating ...DONE.

Create New Layout

Attention

Experimental

Create New Language Pack

Enter your choice: 3
>>> LANGUAGE <<<
Enter (languagecode_countrycode): kn_in
Creating ...DONE.

Import Module

Enter package path: /Downloads/OthModule.zip
Importing ...DONE.

Note

php -f vtlib/tools/console.php -- --import=/Downloads/OthModule.zip

Update Module

Enter package path: /Downloads/OthModule-v2.zip
Updating ...DONE.

Note

php -f vtlib/tools/console.php -- --update=/Downloads/OthModule-v2.zip

Remove Module

Enter package path: /Downloads/OthModule.zip
Removing ...DONE.

Note

php -f vtlib/tools/console.php -- --remove=OthModule