vtlib vtiger development library

DISCLAIMER: The vtlib library development is in progress and subje t to hange! "hile #e ma$e every e%%ort to ma$e sure modules developed using vtlib #ill be ompatible #ith %uture versions o% vtiger CRM& some in ompatible hanges may be re'uired %or the ne(t release o% vtiger! In #hi h ase you #ill have to re) reate your modules #ith an upgraded version o% vtlib %or the spe i%i version o% vtiger CRM!

vtlib

Table of Contents
A*I +ersion ,istory!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!About vtlib!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!. vtlib A*I ) /ui $ Re%eren e!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!0 Module Types!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!1 Entity Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!1 E(tension Module !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!1 Language *a $!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!1 2undles!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!1 Creating a ne# Entity Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!3 2a $end !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!3 4rontEnd!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!3 *a $aging !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!3 About *ayslip Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!3 Step 5: Creating Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!6 Step 7: Creating 2lo $ 8in 9I 4orm:!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!5; Step <: Adding 4ields!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!55 Entity Identi%ier!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!57 Set *i $list +alues!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!57 Set Related Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!57 Set ,elp In%ormation!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!5< Set MassEdit property!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!5. Step -: Creating 4ilters!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!50 Con%igure %ields!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!50 Setup Rules!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!50 Step .: Related Lists!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!51 Step 0: Sharing A ess Rules!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!56 Step 1: Module Tools!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!7; =ptional Step: Module Events!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!75 =ptional Step: Module "ebservi es!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!77 =ptional Step: Module Templates!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!7< =ptional Step: Custom Lin$s!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!7Spe ial Lin$Type!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!7. 4inal Completed S ript 82a $end:!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!70 E(e uting Module Creation S ript!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!76 Step 3: Creating module %iles 84rontend:!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<; Language 4ile *reparation!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<5 >e# Module Tour!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<7 List vie#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<7 Create vie#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<7

vtlib

Detail vie#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<< List vie#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<< Sharing A ess!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<Custom 4ields!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<Step 6: *a $aging!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<. *a $age E(port!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<. *a $age Stru ture!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<0 *a $age Import!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<3 *a $age 9pgrade!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<6 Limitations!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!<6 E(tension Module !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-; 2undles!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-5 Language *a $!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-7 Adding Li ense!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-< Adding Migration Details!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-Module Manager!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-0 Disabling Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-1 Enabling Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-1 E(porting Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-3 Importing Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!-6 Module Spe i%i Settings!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.7 Module 9pgrade!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.< Appendi( 5 ) A*I Changes!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.. Creating Module!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.. Creating 2lo $!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.. Creating 4ield!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.0 Setting Entity Identi%ier!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.0 Set *i $list +alues!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.0 Creating 4ilter!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.1 Con%igure Tools!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.1 Con%igure Sharing A ess!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.1 Appendi( 7 ? S hema Changes!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.3 Appendi( < ? 9sing vtiger@imageurl A*I!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!.6 Appendi( - ? vtlib@handler Method!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!0; Appendi( . ? vtlib@listvie# javas ript A*I!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!05 4A/s ? 4re'uently As$ed /uestions!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!07 5! ,o# to #rite o#n templatesA!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!07 7! ,o# is module template usedA!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!07 <! Cannot See Module ManagerB!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!0< -! Tips %or using %ield names!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!0<

vtlib

API Version History

Version Release Date 7!7 7!5 7;;6!;5!;1 Highlights C C C C C C C Installing Language *a $& E(tension module using Module Manager ModuleDir #as re)organiDed to be spe i%i to a vtiger version Module Manager handles Li ense agreement be%ore installation! 2asi support added %or module upgrades #ith Module Manager! Ability to add ustom #eb lin$s %or a module! Support added to allo# help in%ormation %or the module %ields! Added vtiger@imageurl A*I

Integrated to 5.1.0 C Added spe ial module event triggers 8vtlib@handler method invo ation:

7!;

7;;3)55)70

C A*I provided to related modules 8related list: C A*I hanges %or reating %ields& blo $s& module C 9I type 5; #as added %or generi popup %ield C E(porting and Importing #as added to Module Manager

5!5!<

7;;3);6)76 7;;3);6);5

C Module Manager #as added %or Administrators to install and enableEdisable the ne# modules developed using vtlib! C A*I to setup *i $list values C Sharing A ess A*I #as added C A*IFs to enable and disable tools li$e E(port& Import #ere added C 2asi A*I #as added to reated %ields& blo $s& module

5!7 5!5 5!;

7;;3);3)76 7;;3);3)71 7;;3);3)56

vtlib

About vtlib
vtlib is a library to ease ne# module development %or vtiger CRM! vtlib in ludes A*Is to reate or modi%y the ba $end elements %or a module! These A*Is help ma$e the ne essary hanges to the database! vtlib in ludes Module Manager #hi h allo#s ne# modules to be pa $aged into Dip %iles that other vtiger CRM installations an easily install and use!

vtlib

vtlib API

!ui"# Re$eren"e

vtlib in ludes the %ollo#ing A*Is that an be used to reate ne# modules! 4or more details please loo$ at the A*I do s!

+tiger@Module name add2lo $8: add4ilter8: initTables8: setRelatedList8: setDe%aultSharing8: enableTools8: disableTools8: save8: addLin$8: +tiger@Menu addModule8: +tiger@2lo $ label add4ield8: +tiger@4ield table olumn olumntype uitype typeo%data set,elpIn%o8: setEntityIdenti%ier8: set*i $list+alues8: setRelatedModules8:

+tiger@4ilter name isde%ault add4ield8: addRule8: +tiger@Event register8:

vtlib

%odule &ypes
vtiger 5! 7! <! -! CRM modules an be lassi%ied into %ollo#ing types: Entity Module E(tension Module Language *a $ 2undles

'ntity %odule

Modules in this ategory #ill reate entity re ords in vtiger CRM! The module #ill provide Create vie#& Edit vie#& Detail vie# and List vie#! Gou #ill be able to reate %ilters et ! Entity modules are re ommended %or ases #here a ne# type o% data obje t& e!g! Timesheet& needs to be added into the system as part o% the ne# module! These ne# data obje ts an be vie#ed and managed by administrators and users! Leads& Conta ts& A
'(tension %odule

ounts& *ayslip et !!! are Entity Modules!

Modules in this ategory need not %ollo# the general behavior o% Entity Module! The re ords reated by Entity module ould be used to provide a e(tended %un tionality or the re ords reationEediting an be handled in its o#n #ay! E(tension modules an be used #hen add)on %un tionality is needed& #ithout the need %or ne# $inds o% data obje ts that users vie# and manage! Dashboard& Reports& *ortal et !!! are E(tension Modules!
)anguage Pa"#

Language *a $s %or vtiger CRM are also treated as another $ind o% module by vtlib!
*undles

2undles let you install a set o% inter dependent vtlib modules in the spe i%ied order!
>=TE: Module manager #ill provide the ability to install these di%%erent modules!

vtlib

+reating a ne, 'ntity %odule

vtlib simpli%ies reation o% ne# vtiger CRM modules! Developers an use vtlib to develop vtiger CRM modules that add ne# %un tionality to vtiger CRM! These modules an then be pa $aged %or easy installation by the Module Manager!
-.&': In this do ument #e #ill e(plain the pro ess o% reating a ne# module by building an e(ample F*ayslipF Module! This e(ample ode is in luded as part o% vtlib pa $age& and an be used as a starting point to reate ne# modules! *lease re%er to the F9sing the e(ample ode provided #ith the vtlib A*IF se tion in this do ument %or more in%ormation!

The %ollo#ing are important steps that should be %ollo#ed to get a basi #or$ing module! The ba $end se tion overs database level hanges %or the module& and the %rontend se tion overs the 9I %iles!
*a"#end

Step 5 Step 7 Step < Step Step . Step 0 Step 1

/ront'nd

Create module instan e& reate database tables& and add it to Menu Add 9I blo $s %or the module! Add %ields and asso iate it to blo $s! Set at)least one %ield as entity identi%ier!
Create de%ault list vie# and additional %ilters 8ma$e sure to reate a %ilter named All #hi h is the de%ault %ilter: Create Related List 8to sho# in the FFMore in%ormationFF tab: Setting Sharing A ess Rules 8i!e!& ImportEE(port:

Setting Module Tools options

Step 3
Pa"#aging

Creating Module dire tory and %iles

Step 6

*a $aging

Additional .ptions Module Module Module Module Templates 8to ustomiDe 4orm& List +ie#& and Settings 9I : Settings 8to allo# administrators to on%igure your module: Events 8only available in vtiger CRM version .!5: "ebservi es 8only available in vtiger CRM version .!5:

These steps are e(plained in detail in the ourse o% this se tion! "e are using the e(ample module F*ayslipF to e(plain the use o% vtlib A*Is! About Payslip %odule It #ill have the ability to reate& edit& delete payslip re ords! Gou an reate Custom 4ilters %or the Listvie#& #hi h displays the list o% payslip instan es! "e shall asso iate this module #ith the Tools menu!

vtlib

0tep 11 +reating %odule

Class +tiger@Module provides an A*I to #or$ #ith vtiger CRM modules! include_once('vtlib/Vtiger/Module.php'); $moduleInstance = ne Vtiger_Module(); $moduleInstance!"name = '#a$slip'; $moduleInstance!"save(); $moduleInstance!"init%ables(); $menuInstance = Vtiger_Menu&&getInstance('%ools'); $menuInstance!"addModule($moduleInstance); Vtiger_Module!"init%ables() A*I #ill initialiDe 8 reate: the < ne essary tables a module should have as e(plained belo#:
Table 2asetable Jrouptable >aming onvention vtiger@HM=D9LE>AMEI Des ription Contains the de%ault %ields %or the ne# module Contains ustom %ields o% the module

Customtable vtiger@HM=D9LE>AMEI %

vtiger@HM=D9LE>AMEIgrouprel 9sed #hen re ords are assigned to a group

Vtiger_Menu!"addModule('ModuleInstance") A*I #ill reate menu item #hi h serves as 9I entry point %or the module!

vtlib

0tep 21 +reating *lo"# 3in 4I /orm5

Class +tiger@2lo $ provides A*I to #or$ #ith a Module blo $& the ontainer #hi h holds the %ields together!
The e(ample given belo# des ribes the #ay o% reating ne# blo $s %or the module reated earlier:

include_once('vtlib/Vtiger/Module.php'); $bloc(Instance = ne Vtiger_)loc((); $bloc(Instance!"label = '*)*_#+,-*I#_I./01M+%I0.'; $moduleInstance!"add)loc(($bloc(Instance); $bloc(Instance2 = ne Vtiger_)loc((); $bloc(Instance2!"label = '*)*_34-%0M_I./01M+%I0.'; $moduleInstance!"add)loc(($bloc(Instance2);
-.&': L2L@C9ST=M@I>4=RMATI=> blo $ should al#ays be reated to support Custom 4ields %or a module!

vtlib

0tep 61 Adding /ields

Class +tiger@4ield provides A*I to #or$ #ith a Module %ield& #hi h are the basi elements that store and display the module re ord data!
The e(ample given belo# des ribes the #ay o% reating ne# %ield %or the module reated earlier:

include_once('vtlib/Vtiger/Module.php'); $5ieldInstance = ne Vtiger_/ield(); $5ieldInstance!"name = '#a$slip.ame'; $5ieldInstance!"table = 'vtiger_pa$slip'; $5ieldInstance!"column = 'pa$slipname'; $5ieldInstance!"columnt$pe = 'V+136+1(788)'; $5ieldInstance!"uit$pe = 2; $5ieldInstance!"t$peo5data = 'V9M'; $bloc(Instance!"add/ield($5ieldInstance);
-.&': The %ieldInstan e name is a mandatory value to be set be%ore saving E adding to blo $! =ther values 8i% not set: are de%aulted as e(plained belo#: K%ieldInstan e)Itable K%ieldInstan e)I olumn K%ieldInstan e)I olumntype K%ieldInstan e)Iuitype K%ieldInstan e)Itypeo%data K%ieldInstan e)Ilabel ModuleFs basetable K%ieldInstan e)Iname in lo#er ase
LThe table #ill be altered by adding the olumn i% not presentM

+ARC,AR87..: 5 +N= K%ieldInstan e)Iname

LMapping entry should be present in module language %ile as #ellM

.ptional 0ettings K%ieldInstan e)Ipresen e ; ? Al#ays A tive 8Cannot be modi%ied using Layout Editor in .!5!;: 5 ? Mar$ it In A tive 8.!5!; on#ards: 7 ? A tive *roperty an be modi%ied using Layout Editor 8.!5!; on#ards: ; ? Enable %ield in /ui $ Create 4orm 5 ? Disable %ield on /ui $ Create 4orm ; ? *ermanently Disallo# %ield %or mass editing 8.!5!; on#ards: 5 ? Allo# %ield %or mass editing 8.!5!; on#ards: 7 ? Disallo# %ield %or mass editing 8but an be made available using Layout Editor .!5!; on#ards:

K%ieldInstan e)I'ui $ reate K%ieldInstan e)Imasseditable

vtlib

'ntity Identi$ier

=ne o% the mandatory %ield should be set as entity identi%ier o% module on e it is reated! This %ield #ill be used %or sho#ing the details in FLast +ie#ed EntriesF et !!! $moduleInstance!"set:ntit$Identi5ier($5ieldInstance);
0et Pi"#list Values

I% the %ield is o% *i $list type 8uitype 15& 50& <<& ..& 555: then you an on%igure the initial values using the %ollo#ing A*I: $5ieldInstance!"set#ic(listValues( +rra$ ('Value7'; 'Value2') );
0et Related %odule

I% the %ield is o% *opup sele t type 8uitypeO5;:& you an on%igure the related modules #hi h ould be sele ted via *opup using the %ollo#ing A*I: $5ieldInstance!"set1elatedModules(+rra$('0therModule7'; '0therModule2')); To unset the related module you an use the %ollo#ing A*I: $5ieldInstance!"unset1elatedModules(+rra$('0therModule2'));

vtlib

0et Help In$ormation

*roviding help in%ormation %or module %ield #ill be use%ul to edu ate users! include_once('vtlib/Vtiger/Module.php'); $5ieldInstance = ne Vtiger_/ield(); $5ieldInstance!"name = '*in(%o'; ... $5ieldInstance!"helpin5o = '1elate to an e<isting contact'; ... $bloc(Instance!"add/ield($5ieldInstance); Gou an provide set the help te(t %or an e(isting %ield using the %ollo#ing A*I: $5ieldInstance!"set6elpIn5o('6:*# 30.%:.%');
-.&': ,EL* C=>TE>T an be plain or ri h te(t! See the re ommended usage belo#!

"hen a %ield has help in%ormation& helpi on #ill be sho#n beside the %ield label!

Cli $ing on it #ill sho# the help ontent as sho#n:

vtlib

-.&': Jiven belo# is the snippet o% ode that should be added to Edit+ie#!php o% e(isting module to enable ,elp I on support!

// ... // =ather the help in5ormation associated ith 5ields $smart$!"assign('/I:*>6:*#I./0'; vtlib_get/ield6elpIn5o($currentModule)); // :.> // ... i5($5ocus!"mode == 'edit') $smart$!"displa$('sales:ditVie .tpl'); else $smart$!"displa$('3reateVie .tpl'); Re"ommended1 *rovide translation mapping %or the helpin%o being used %or a %ield! :<ample set the helpin5o as 6:*#_/I*:>.+M:_I./0 and provide the contents in the language 5ile. $5ieldInstance!"set6elpIn5o('6:*#_/I:*>.+M:_I./0'); In module/'M0>4*:.+M:"/language/en_us.lang.php $mod_strings = +rra$( ... '6:*#_/I:*>.+M:_I./0' =" '/ieldname help contents should be here'; ...);

Avoid ne#lines in the help ontent& you an use HbrI tag instead *re%erably es ape 8F& P& H& I: #ith ,TML entities li$e 8Q'uotR& QltR QgtR: It is good to have $eep the ontent less& i% you #ant to provide more details you an lin$ to a e(ternal page as sho#n in the e(ample belo#: 4ill your onta ts name here! To $no# more about itHbrI Ha hre%OFhttp:EEen!vtiger! omE#i$i!htmlFIsee moreHEaI

vtlib

0et %ass'dit property -.&': Mass edit %eature is available %rom vtiger .!5 on#ards

Gou an ma$e the %ield available %or mass editing use the %ollo#ing #ays des ribed belo#: "hen reating the %ield you an set the property: include_once('vtlib/Vtiger/Module.php'); $5ieldInstance = ne Vtiger_/ield(); $5ieldInstance!"name = '%est/ield'; ... $5ieldInstance!"masseditable = 7; ... $bloc(Instance!"add/ield($5ieldInstance); I% you have an e(isting %ield its property an be updated using the A*I: $5ieldInstance!"setMass:ditable(value); The value set %or masseditable property has the %ollo#ing meaning:
Value ; 5 7 Des"ription >ot available %or mass edit and this property annot be ontrolled by user! Available %or mass edit >ot available %or mass edit but the property an be ontrolled by user 8via Layout Manager et :

vtlib

0tep 71 +reating /ilters

Class +tiger@4ilter provides A*I to #or$ #ith a ModuleFs ustom vie# or %ilter! The list vie# display is ontrolled via these %ilters!
The e(ample given belo# des ribes the #ay o% reating ne# %ilter %or the module:

include_once('vtlib/Vtiger/Module.php'); $5ilterInstance = ne Vtiger_/ilter(); $5ilterInstance!"name = '+ll'; $5ilterInstance!"isde5ault = true; $moduleInstance!"add/ilter($5ilterInstance);

+on$igure $ields

To add %ields to the %ilter you an use the %ollo#ing A*I: $5ilterInstance!"add/ield($5ieldInstance; $columnInde<); "here K olumnInde( 8optional: is the orderEinde( at #hi h the %ield should appear in the list vie#!
0etup Rules

=n e the %ield is added to %ilter you an setup rule 8 ondition: %or %iltering as #ell using the %ollo#ing A*I: $5ilterInstance!"add1ule($5ieldInstance; $comparator; $compareValue; $columnInde<); "here omparator ould be one o% the %ollo#ing:
E/9ALS >=T@E/9ALS STARTS@"IT, E>DS@"IT, C=>TAI>S D=ES@>=T@C=>TAI>S LESS@T,A> JREATER@T,A> LESS@=R@E/9AL JREATER@=R@E/9AL

K ompare+alue is the value against #ith the %ield needs to be ompared! K olumnInde( 8optional: is the order at #hi h this rule ondition should be applied!

vtlib

0tep 51 Related )ists

=ne module ould be asso iated #ith multiple re ords o% other module that is displayed under PMore In%ormationS tab on Detail +ie#!
The e(ample given belo# des ribes the #ay o% reating a relation bet#een a *ayslip and A ounts module:

include_once('vtlib/Vtiger/Module.php'); $moduleInstance = Vtiger_Module&&getInstance('#a$slip'); $accountsModule = Vtiger_Module&&getInstance('+ccounts'); $relation*abel = '+ccounts';

$moduleInstance!"set1elated*ist( $accountsModule; $relation*abel; +rra$('+>>';'-:*:3%') ); "ith this you an Add one or more A ounts to *ayslip re ords!

To drop the relation bet#een the modules use the %ollo#ing: $moduleInstance!"unset1elated*ist($targetModuleInstance); About setRelatedList A*I Vtiger_Module!"set1elated*ist('%+1=:% M0>4*:"?; '6:+>:1 *+):*"; '+**0@:> +3%I0.-"; '3+**)+3A /4.3%I0. .+M:"B);
HTARJET M=D9LEI H,EADER LA2ELI Module name to #hi h relation is being setup! =ptional 8de%ault O HTARJET M=D9LEI: Label to use on the More In%ormation related list vie#! HALL="ED ACTI=>SI =ptional ADD or SELECT 8de%ault O %alse: "hat buttons should be sho#n in the related list vie# #hile adding re ords! HCALL2ACT 49>CTI=> >AMEI =ptional 8de%ault O get@related@list: The %un tion should be de%ined in the HS=9RCE M=D9LEI lass! This should generate the listvie# entries %or displaying! -.&'1 This A*I #ill reate an entry in the vtiger@ rmentityrel table to $eep tra $ o% relation bet#een module re ords! Standard modules available in vtiger CRM handles the relation in separate tables and per%orms the U=I> to %et h data spe i%i to ea h module! This is an attempt to a hieve generi behavior! Gou an #rite ustom all ba $ %un tions to handle related list 'ueries that #ill meet your re'uirements!

vtlib

)imitations 4ollo#ing limitations apply %or the related list A*Is 5! 7! Standard module lass variables are not set as re'uired by the get@related@list vtlib module A*I! Case handling should be handled V%un tion vtlib@setup@modulevars in in ludeEutilsE+tlib9tils!php get@related@list A*I added to module lass does not handle U=I> on tables #here some modules li$e 8A ounts: store in%ormation hen e omplete details are not %et hed in the Related List +ie#! 8E(ample Sorting on the ity %ield on related list vie# #ill %ail i% die=nError is true:

vtlib

0tep 81 0haring A""ess Rules

Sharing a ess on%iguration %or the module an be done as sho#n belo#:

The e(ample given belo# des ribes the #ay to on%igure the *ayslip module as *rivate

include_once('vtlib/Vtiger/Module.php'); $moduleInstance = Vtiger_Module&&getInstance('#a$slip'); $moduleInstance!"set>e5ault-haring('#rivate'); The H*ERMISSI=>@TG*EI an be one o% the %ollo#ing:

*ubli @Read=nly *ubli @Read"rite *ubli @Read"riteDelete *rivate

vtlib

0tep 91 %odule &ools

4eatures li$e Import& E(port are termed as module tools! Su h tools an enabled or disabled as sho#n belo#:
The e(ample given belo# des ribes the #ay to enable and disable the tools %or *ayslip module

include_once('vtlib/Vtiger/Module.php'); $moduleInstance = Vtiger_Module&&getInstance('#a$slip'); $module!"enable%ools(+rra$('Import'; ':<port')); $module!"disable%ools(':<port');

vtlib

.ptional 0tep1 %odule 'vents

Eventing A*I is supported %rom vtiger .!5 on#ards 8read more here:! To he $ i% your vtiger CRM supports Eventing use the %ollo#ing: include_once('vtlib/Vtiger/:vent.php'); boolean Vtiger_:vent&&is-upported(); To register an event %or a module& use the %ollo#ing: include_once('vtlib/Vtiger/:vent.php'); Vtiger_:vent&&register(''M0>4*:.+M:"'; '':V:.%.+M:"'; ''6+.>*:13*+--"'; ''6+.>*:1/I*:"');
HM=D9L>AMEI HE+E>T>AMEI H,A>DLERCLASSI H,A>DLER4ILEI Module %or #hi h events should be registered vtiger!entity!a%tersave vtiger!entity!be%oresave Event handler lass& loo$ at the e(ample belo# 4ile #here ,A>DLERCLASS is de%ined 8should be #ithin vtiger CRM dire tory:

E(ample: Registering event allba $ be%ore and a%ter save! i5(Vtiger_:vent&&has-upport()) C Vtiger_:vent&&register( '#a$slip'; 'vtiger.entit$.a5tersave'; '#a$slip6andler'; 'modules/#a$slip/#a$slip6andler.php' ); Vtiger_:vent&&register( '#a$slip'; 'vtiger.entit$.be5oresave'; '#a$slip6andler'; 'modules/#a$slip/#a$slip6andler.php' ); D
modules:Payslip:PayslipHandler.php

'Ephp class #a$slip6andler e<tends V%:vent6andler C 5unction handle:vent($event.ame; $data) C i5($event.ame == 'vtiger.entit$.be5oresave') C // :ntit$ is about to be saved; ta(e reFuired action D i5($event.ame == 'vtiger.entit$.a5tersave') C // :ntit$ has been saved; ta(e ne<t action D D D E"

vtlib

.ptional 0tep1 %odule ;ebservi"es

"ebservi es A*I is supported %rom vtiger .!5 on#ards 8read more here:! Gou #ill need to invo$e the setup A*I to enable the support %or the ustom modules! include_once('vtlib/Vtiger/Module.php'); $moduleInstance = Vtiger_Module&&getInstance('#a$slip'); $moduleInstance!"init@ebservice();

-.&': "hen the module is imported the "ebservi e initialiDe A*I is automati ally invo$ed!

vtlib

.ptional 0tep1 %odule &emplates

I% you #ould li$e to ustomiDe the list vie# or have a ustom Settings page %or the module& then you #ill need to reate a Smarty template a ordingly! Gou #ill need to have some $no#ledge o% Smarty templates usage be%ore yuu pro eed! Gour module spe i%i Smarty template %iles should be reated under -mart$/templates/modules/ '.e Module.ame"! 9se vtlib_getModule%emplate($module; $template.ame) A*I 8in ludeEutilsE+tlib9tils!php: as: $smart$!"displa$(vtlib_getModule%emplate($currentModule; 'M$*istvie .tpl'));

vtlib

.ptional 0tep1 +ustom )in#s

Gou an add ustom #eb lin$ to the module using the %ollo#ing A*I: include_once('vtlib/Vtiger/Module.php'); $moduleInstance = Vtiger_Module&&getInstance('Module.ame'); $moduleInstance!"add*in(('*in(%$pe"; '*in(*abel"; '*in(41*");
Lin$Type Type o% Lin$ li$e ) DETAIL+IE" : "ill add a lin$ in the FMore A tionsF menu on the Detail +ie# o% the re ord! DETAIL+IE"2ASIC : "ill add a lin$ to the FA tionsF list on the Detail +ie# o% the Re ord! DETAIL+IE""IDJET : "ill add a #idget on the right hand side o% the Detail +ie# o% the Re ord& similar to Tag Cloud #idget! LIST+IE" : "ill add a lin$ under the FMore A tionsF button on the List +ie# o% a module! LIST+IE"2ASIC : "ill add a button on the List +ie# o% the module similar to Delete& Mass Edit buttons! Label to use %or the lin$ #hen displaying 9RL o% the lin$! You can use variables like $variablename$

Lin$Label Lin$9RL

In moduleFs List+ie# handler page 8modules/Payslip/ListView.php) you #ill need this pie e o% ode 8be%ore the all to Ksmarty)Idisplay8:: : include_once('vtlib/Vtiger/*in(.php');
$customlin(_params = +rra$('M0>4*:' =" $currentModule; '+3%I0.'=" vtlib_puri5$($_1:G4:-%?'action'B); '3+%:=01,' =" $categor$); $smart$!"assign('34-%0M_*I.A-'; Vtiger_*in(&&get+ll)$%$pe(get%abid($currentModule); +rra$('*I-%VI:@'; '*I-%VI:@)+-I3'); $customlin(_params));

In moduleFs Detail+ie# handler page 8modules/Payslip/DetailView.php) you #ill need this pie e o% ode 8be%ore the all to Ksmarty)Idisplay8:: : include_once('vtlib/Vtiger/*in(.php');
$customlin(_params = +rra$('M0>4*:' =" $currentModule; '1:301>' =" $5ocus!"id; '+3%I0.'=" vtlib_puri5$($_1:G4:-%?'action'B)); $smart$!"assign('34-%0M_*I.A-'; Vtiger_*in(&&get+ll)$%$pe(get%abid($currentModule); +rra$('>:%+I*VI:@'; '>:%+I*VI:@)+-I3'; '>:%+I*VI:@@I>=:%'); $customlin(_params));

-.&': The KM=D9LEK& KACTI=>K and KREC=RDK variables in the Lin$9RL& #ill be repla ed #ith the values set through Detail+ie#!php The KM=D9LEK& KACTI=>K& KCATEJ=RGK variables in the Lin$9RL& #ill be repla ed #ith the values set through List+ie#!php

vtlib

Jiven belo# is an e(ample #hi h adds a lin$ to the Detail+ie# o% the Module! include_once('vtlib/Vtiger/Module.php'); $moduleInstance = Vtiger_Module&&getInstance('#a$slip'); $moduleInstance!"add*in(( '>:%+I*VI:@'; '.e +ction'; );

'inde<.phpEmodule=0therModuleHaction=-ome+ctionHsrc_module=$M0>4*:$Hsrc_record=$1:301>$'

=n the Detail+ie# page you #ill %ind More ctions lin$! "hen you mouse hovers on this all the related ustom lin$s #ill be sho#n as a drop do#n! See the s reenshot belo#:

0pe"ial )in#&ype

4ollo#ing Lin$Types are treated spe ially #hile pro essing %or display:
)in#type ,EADERSCRI*T Des"ription The lin$ #ill be treated as a javas ript type and #ill be imported in the head se tion o% the ,TML output page as !script type"#te$t/%avascript# src"#linkurl#&!/script& The lin$ #ill be treated as a CSS type and #ill be imported in the head se tion o% the ,TML output page as !link rel"#stylesheet# type"#te$t/css# hre'"#linkurl& Gou an see these lin$ grouped under More on the top header panel! 9se%ul i% you #ant to provide utitlity tools li$e 2oo$mar$let et !

,EADERCSS

,EADERLI>T

vtlib

/inal +ompleted 0"ript 3*a"#end5

,ere is the omplete s ript 8vtlib!Test!Create!Module5!php: #hi h reates the *ayslip module 'Ephp // %urn on debugging level $Vtiger_4tils_*og = true; include_once('vtlib/Vtiger/Menu.php'); include_once('vtlib/Vtiger/Module.php'); // 3reate module instance and save it 5irst $module = ne Vtiger_Module(); $module!"name = '#a$slip'; $module!"save(); // InitialiIe all the tables reFuired $module!"init%ables(); /JJ J 3reates the 5ollo ing table& J vtiger_pa$slip (pa$slipid I.%:=:1) J vtiger_pa$slipc5(pa$slipid I.%:=:1 #1IM+1, A:,) J vtiger_pa$slipgrouprel((pa$slipid I.%:=:1 #1IM+1, A:,; groupname V+136+1(788)) J/ // +dd the module to the Menu (entr$ point 5rom 4I) $menu = Vtiger_Menu&&getInstance('%ools'); $menu!"addModule($module); // +dd the basic module bloc( $bloc(7 = ne Vtiger_)loc((); $bloc(7!"label = '*)*_#+,-*I#_I./01M+%I0.'; $module!"add)loc(($bloc(7); // +dd custom bloc( (reFuired to support 3ustom /ields) $bloc(2 = ne Vtiger_)loc((); $bloc(2!"label = '*)*_34-%0M_I./01M+%I0.'; $module!"add)loc(($bloc(2); /JJ 3reate reFuired 5ields and add to the bloc( J/ $5ield7 = ne Vtiger_/ield(); $5ield7!"name = '#a$slip.ame'; $5ield7!"table = $module!"basetable; $5ield7!"column = 'pa$slipname'; $5ield7!"columnt$pe = 'V+136+1(2KK)'; $5ield7!"uit$pe = 2; $5ield7!"t$peo5data = 'V9M'; $bloc(7!"add/ield($5ield7); /JJ 3reates the 5ield and adds to bloc( J/ // -et at!least one 5ield to identi5ier o5 module record $module!"set:ntit$Identi5ier($5ield7); $5ield2 = ne Vtiger_/ield(); $5ield2!"name = '#a$slip%$pe'; $5ield2!"label = '#a$slip %$pe'; $5ield2!"columnt$pe = 'V+136+1(788)'; $5ield2!"uit$pe = 7K; $5ield2!"t$peo5data = 'V90';// Varchar90ptional $bloc(7!"add/ield($5ield2); /JJ table and column are automaticall$ set J/ $5ield2!"set#ic(listValues( +rra$ (':mplo$ee'; '%rainee') ); $5ieldL = ne Vtiger_/ield(); $5ieldL!"name = 'Month'; vtlib

$5ieldL!"uit$pe = 2L; $5ieldL!"t$peo5data = '>9M'; // >ate9Mandator$ $bloc(7!"add/ield($5ieldL); /JJ table; column; label; set to de5ault values J/ $5ieldM = ne Vtiger_/ield(); $5ieldM!"name = '*in(%o'; $5ieldM!"label= '*in( %o'; $5ieldM!"table = 'vtiger_pa$slip'; $5ieldM!"column = 'lin(to'; $5ieldM!"columnt$pe = 'V+136+1(788)'; $5ieldM!"uit$pe = 78; $5ieldM!"t$peo5data = 'V90'; $5ieldM!"helpin5o = '1elate to an e<isting contact'; $bloc(7!"add/ield($5ieldM); $5ieldM!"set1elatedModules(+rra$('3ontacts')); /JJ 3ommon 5ields that should be in ever$ module; lin(ed to vtiger 31M core table J/ $5ieldK = ne Vtiger_/ield(); $5ieldK!"name = 'assigned_user_id'; $5ieldK!"label = '+ssigned %o'; $5ieldK!"table = 'vtiger_crmentit$'; $5ieldK!"column = 'smo nerid'; $5ieldK!"uit$pe = KL; $5ieldK!"t$peo5data = 'V9M'; $bloc(7!"add/ield($5ieldK); $5ieldN = ne Vtiger_/ield(); $5ieldN!"name = '3reated%ime'; $5ieldN!"label= '3reated %ime'; $5ieldN!"table = 'vtiger_crmentit$'; $5ieldN!"column = 'createdtime'; $5ieldN!"uit$pe = O8; $5ieldN!"t$peo5data = '%90'; $5ieldN!"displa$t$pe= 2; $bloc(7!"add/ield($5ieldN); $5ieldO = ne Vtiger_/ield(); $5ieldO!"name = 'Modi5ied%ime'; $5ieldO!"label= 'Modi5ied %ime'; $5ieldO!"table = 'vtiger_crmentit$'; $5ieldO!"column = 'modi5iedtime'; $5ieldO!"uit$pe = O8; $5ieldO!"t$peo5data = '%90'; $5ieldO!"displa$t$pe= 2; $bloc(7!"add/ield($5ieldO); /JJ :.> J/ // 3reate de5ault custom 5ilter (mandator$) $5ilter7 = ne Vtiger_/ilter(); $5ilter7!"name = '+ll'; $5ilter7!"isde5ault = true; $module!"add/ilter($5ilter7); // +dd 5ields to the 5ilter created $5ilter7!"add/ield($5ield7)!"add/ield($5ield2; 7)!"add/ield($5ieldK; 2); // 3reate one more 5ilter $5ilter2 = ne Vtiger_/ilter(); $5ilter2!"name = '+ll2'; $module!"add/ilter($5ilter2); // +dd 5ields to the 5ilter $5ilter2!"add/ield($5ield7); vtlib

$5ilter2!"add/ield($5ield2; 7); // +dd rule to the 5ilter 5ield $5ilter2!"add1ule($5ield7; '30.%+I.-'; '%est'); /JJ +ssociate other modules to this module J/ $module!"set1elated*ist(Vtiger_Module&&getInstance('+ccounts'); '+ccounts'; +rra$('+>>';'-:*:3%')); /JJ -et sharing access o5 this module J/ $module!"set>e5ault-haring('#rivate'); /JJ :nable and >isable available tools J/ $module!"enable%ools(+rra$('Import'; ':<port')); $module!"disable%ools('Merge'); E"

vtlib

'(e"uting %odule +reation 0"ript

5! To e(e ute the vtlib!Test!Create!Module5!php s ript& open http:EElo alhostEvtiger rmEvtlib!Test!html

7! Cli $ on Create *ayslip Module to test reation o% *ayslip Module

vtlib

0tep <1 +reating module $iles 3/rontend5

Ea h ne# module should have a dire tory under modulesE %older! To help speed up the module ode reation& vtlib omes bundled #ith s$eleton module stru ture based on the F*aySlipF module! This ode is in lude in vtlibEModuleDir %older #hi h an be used as a template %or ne# module that is reated! It ontains sour e %iles that needs to be hanged as e(plained belo#!
>=TE: ModuleDir has sub)dire tories spe i%i to vtiger version& please ma$e sure to use the right one! 5! 7! <! -! .! Copy ModuleDir/!tar(et)vti(er)version& ontents to ne#ly reated modulesEH>e#Module>ameI %older! Rename H>e#Module>ameIEModule4ile!php as H>e#Module>ameIEH>e#Module>ameI!php 8as noted in the table belo#: Rename H>e#Module>ameIEModule4ileAja(!php as H>e#Module>ameIEH>e#Module>ameIAja(!php Rename H>e#Module>ameIEModule4ile!js to H>e#Module>ameIEH>e#Module>ameI!js Edit H>e#Module>ameIEH>e#Module>ameI!php a: Rename Class ModuleClass to H>e#Module>ameI b: 9pdate Ktable@name and Ktable@inde( 8Module table name and table inde( olumn: : 9pdate KgroupTable d: 9pdate Ktab@name& Ktab@name@inde( e: 9pdate Klist@%ields& Klist@%ields@name& Ksortby@%ields& Klist@lin$@%ield %: 9pdate Kdetailvie#@lin$s g: 9pdate Kde%ault@order@by& Kde%ault@sort@order h: 9pdate Kre'uired@%ields i: 9pdate K ustom4ieldTable j: Rename %un tion ModuleClass to %un tion H>e#Module>ameI LThis is the Constru tor ClassM

>=TE: =ther %iles under modulesEH>e#Module>ameI need not be hanged! '(ample %oduleDir inde(!php Module4ile!php Module4ileAja(!php Module4ile!js CallRelatedList!php Custom+ie#!php Delete!php Detail+ie#!php Detail+ie#Aja(!php Edit+ie#!php E(portRe ords!php Import!php List+ie#!php *opup!php /ui $Create!php Save!php Purpose Module entry point through Menu Module lass de%inition %ile! 2ase %ile %or aja( a tions used under Listvie# et !!! Module spe i%i javas ript %un tion an be #ritten here More In%ormation Detail vie# handler Custom vie# or 4ilter handler Module re ord deletion handler Detail vie# handler Detail vie# aja( edit handler Edit vie# handler Module re ord e(port handler Module re ords import handler List vie# handler *opup sele tion handler %or this module re ord /ui $ reation handler Module re ord save handler /ile under Payslip inde(!php *ayslip!php *ayslipAja(!php *ayslip!js CallRelatedList!php Custom+ie#!php Delete!php Detail+ie#!php Detail+ie#Aja(!php Edit+ie#!php E(portRe ords!php Import!php List+ie#!php *opup!php /ui $Create!php Save!php

vtlib

'(ample %oduleDir TagCloud!php updateRelations!php

Purpose Tag loud handler Related list re ord handler 8saveEdelete:

/ile under Payslip TagCloud!php updateRelations!php

4iles spe i%i to vtiger .!5!; version!

'(ample %oduleDir MassEdit!php MassEditSave!php 4indDupli ateRe ords!php *ro essDupli ates!php List+ie#*agging!php 9ni%iedSear h!php Purpose Mass Re ord Edit handler Mass Edit Re ord Save handler 4ind Dupli ate Re ords handler *ro ess Dupli ate Re ords 8merging: handler List +ie# *aging handler Jlobal Sear h handler /ile under Payslip MassEdit!php MassEditSave!php 4indDupli ateRe ords!php *ro essDupli ates!php List+ie#*agging!php 9ni%iedSear h!php

4iles to be updated %or a vtlib module build on version .!5!;& to ma$e it #or$ on .!7!; 8%rom vtlibE ModuleDirE.!7!;: :
'(ample %oduleDir CallRelatedList!php Detail+ie#Aja(!php List+ie#!php Module4ile!php Purpose o$ 4pgrade Related List +ie# Changes Related List +ie# Changes /uery Jenerator support /ile under Payslip CallRelatedList!php Detail+ie#Aja(!php *ayslip!php

=rder by issue %i(ed and /uery Jenerator support List+ie#!php

)anguage /ile Preparation

9pdate the translation mapping in the module language %ile 8modulesEH>e#Module>ameIElanguageEen@us!lang!php: Some o% the mandatory mapping that should be provided are as %ollo#s: $mod_strings = arra$ ( '.e Module.ame' '-I.=*:_.e Module.ame' =" '.e Module.ame_%ranslation'; =" '.e Module.ame/or-ingle1ecord';

'*)*_34-%0M_I./01M+%I0.' =" '3ustom In5ormation'; // *abel used 5or $our module 5ield '/ield*abel' =" '/ield *abel %ranslation' );

vtlib

-e, %odule &our

)ist vie,

+reate vie,

vtlib

Detail vie,

)ist vie,

vtlib

0haring A""ess

+ustom /ields

vtlib

0tep =1 Pa"#aging
Pa"#age '(port

vtlib provides A*I to e(port module as a Dip 8pa $age: %ile #hi h an used %or importing through Module Manger! reFuire_once('vtlib/Vtiger/#ac(age.php'); reFuire_once('vtlib/Vtiger/Module.php'); $pac(age = ne Vtiger_#ac(age(); $pac(age!"e<port(''M0>4*: Instance"'; ''>:-%I.+%I0. >I1"'; ''PI#/I*: .+M:"'; '>I1:3% >0@.*0+>");
HM=D9LE Instan eI HDESTI>ATI=> DIRI HWI*4ILE >AMEI HDIRECT D=">L=ADI +tiger@Module instan e to be e(ported 8pa $aged: 8=ptional: De%aultOtestEvtlib: Dire tory #here the Dip%ile output should be reated! 8=ptional: De%aultOmodulename)timestamp!Dip: Wip%ile name to use %or the output %ile! 8=ptional: De%aultO%alse: I% true& the Dip%ile reated #ill be streamed %or do#nload and Dip%ile #ill be deleted a%ter that!

E(ample: reFuire_once('vtlib/Vtiger/#ac(age.php'); reFuire_once('vtlib/Vtiger/Module.php'); $pac(age = ne Vtiger_#ac(age(); $pac(age!"e<port( Vtiger_Module&&getInstance('#a$slip'); 'test/vtlib'; '#a$slip!:<port.Iip'; true );
-.&': *lease ma$e sure testEvtlib dire tory e(ists under vtiger rm root dire tory and is #riteable!

vtlib

Package Structure

The e(ported Dip%ile 8pa $age: has the %ollo#ing stru ture: mani5est.<ml modules/ Module.ame/
'Module 1elated /iles"

language/ en_us.lang.php
'0ther language /iles"

templates/

'-mart$ templates o5 the Module"

mani5est.<ml has the meta in%ormation that #ill be use%ul during the import pro ess as sho#n: 'E<ml version=Q7.8Q encoding=Qut5!RQE" 'module" 'e<porttime",,,,!MM!>> hh&mm&ss'/e<porttime" 'name"M0>4*: .+M:'/name" 'version"7.8'/version" 'label"M0>4*: *+):*'/label" 'parent"M:.4'/parent" 'dependencies" 'vtiger_version"V%I=:1_V:1-I0._.4M):1'/vtiger_version" 'vtiger_ma<_version"V%I=:1_M+S_V:1-I0._-4##01%:>'/vtiger_ma<_version" '/dependencies" 'tables" 'table" 'name"%+)*:.+M:'/name" 'sFl"%+)*: -G*'/sFl" '/table" '/tables" 'bloc(s" 'bloc(" 'label")*03A *+):*'/label" '5ields" '5ield" '5ieldname"pa$slipname'/5ieldname" 'columnname"pa$slipname'/columnname" 'uit$pe"4I %,#:'/uit$pe" 'tablename"%+)*: .+M:'/tablename" 'generatedt$pe"=:. %,#:'/generatedt$pe" '5ieldlabel"/I:*> *+):*'/5ieldlabel" 'readonl$"1:+>0.*,'/readonl$" 'presence"#1:-:.3:'/presence" 'selected"-:*:3%:>'/selected" 'ma<imumlength"M+S*:.'/ma<imumlength" 't$peo5data"%,#:0/>+%+'/t$peo5data" 'Fuic(create"G4I3A31:+%:'/Fuic(create" 'displa$t$pe">I-#%,#:'/displa$t$pe" 'in5o_t$pe"I./0%,#:'/in5o_t$pe" 'helpin5o"'T?3>+%+?6:*# I./01M+%I0.BB"'/helpin5o" 'masseditable"M+--:>I% V+*4:'/masseditable" '/5ield" '/5ields" '/bloc(" '/bloc(s" 'customvie s" vtlib

'customvie " 'vie name"VI:@.+M:'/vie name" 'setde5ault"8'/setde5ault" 'setmetrics"7'/setmetrics" '5ields" '5ield" '5ieldname"/I:*>.+M:'/5ieldname" 'columninde<"8'/columninde<" '/5ield" '/5ields" '/customvie " '/customvie s" 'sharingaccess" 'de5ault"private'/de5ault" '/sharingaccess" 'actions" 'action" 'name":<port'/name" 'status"enabled'/status" '/action" 'action" 'name"Import'/name" 'status"enabled'/status" '/action" '/actions" 'customlin(s" 'customlin(" 'lin(t$pe">:%+I*VI:@'/lin(t$pe" 'lin(label"Visit -ite'/lin(label" 'lin(url"'T?3>+%+?http&// .vtiger.comBB"'/lin(url" 'lin(icon"'T?3>+%+?themes/images/vtiger!pa .UpgBB"'/lin(icon" 'seFuence"8'/seFuence" '/customlin(" 'customlin(s" 'events" 'event" 'eventname":V:.%_.+M:'/eventname" 'classname":V:.%_6+.>*:1_3*+--'/classname" '5ilename":V:.%_6+.>*:1_3*+--_/I*:'/5ilename" 'condition"'T?3>+%+?modulename in ?'M0>4*:.+M:'B BB"'/condition" '/event" '/events" '/module"

vtlib

Pa"#age Import

Gou an import a module %rom pa $age 8Dip: %ile using the %ollo#ing A*I reFuire_once('vtlib/Vtiger/#ac(age.php'); $pac(age = ne Vtiger_#ac(age(); $pac(age!"import('M0>4*: PI#/I*:"; 'over rite");
HM=D9LE WI*4ILEI Module Dip%ile 8pa $age:! 8=ptional: De%aultO%alse: =ver#rite the e(isting module dire tory i% present
*+,-. overwrite 'la( is i(nored currently. /t will be implemented in 'uture. Please make sure to check 'or directory non0e$istence be'ore importin(.

Hover#riteI

The pa $age %ile should be validated be%ore Importing #hi h an be done using the %ollo#ing A*I reFuire_once('vtlib/Vtiger/#ac(age.php'); $pac(age = ne Vtiger_#ac(age(); $pac(age!"chec(Pip('M0>4*: PI#/I*:");
HM=D9LE WI*4ILEI Module Dip%ile 8pa $age:!

chec(Pip returns true i% pa $age stru ture in Dip%ile is as spe i%ied in the se tion Pa"#age '(port above! Dete ting Module >ame being Imported reFuire_once('vtlib/Vtiger/#ac(age.php'); $pac(age = ne Vtiger_#ac(age(); $pac(age!"getModule.ame/romPip('M0>4*: PI#/I*:");
HM=D9LE WI*4ILEI Module Dip%ile 8pa $age:!

getModule.ame/romPip returns %odule-ame i% he $Wip su E(ample: reFuire_once('vtlib/Vtiger/#ac(age.php'); reFuire_once('vtlib/Vtiger/Module.php');

eeds!

$pac(age = ne Vtiger_#ac(age(); $module = $pac(age!"getModule.ame/romPip('test/vtlib/#a$slip.Iip'); $module_e<ists = 5alse; $module_dir_e<ists = 5alse; i5($module == null) C echo VModule Iip5ile is not validTQ; D else i5(Vtiger_Module&&getInstance($module)) C echo W$module alread$ e<istsTW; $module_e<ists = true; D else i5(is_dir(Wmodules/$moduleW)) C echo W$module 5older e<istsT 0ver riteEW; $module_dir_e<ists = true; D i5($module_e<ists == 5alse HH $module_dir_e<ists == 5alse) C $pac(age!"import('test/vtlib/#a$slip.Iip'); D vtlib

Pa"#age 4pgrade -.&': Currently this module upgrade %eature does not support deletion and modi%i ation o% e(iting module %ields! 2e%ore you use this %eature& please ensure your modi%ied module does not hange or delete e(isting %ields!

Gou an upgrade a module that #as imported earlier using the %ollo#ing A*I: reFuire_once('vtlib/Vtiger/#ac(age.php'); reFuire_once('vtlib/Vtiger/Module.php'); $pac(age = ne Vtiger_#ac(age(); $pac(age!"update('ModuleInstance"; 'M0>4*: PI#/I*:"; 'over rite");
HModuleInstan eI HM=D9LE WI*4ILEI Hover#riteI +tiger@Module instan e #hi h needs to be upgraded! Module Dip%ile 8pa $age:! 8=ptional: De%aultOtrue: =ver#rite the e(isting module dire tory i% present

E(ample: reFuire_once('vtlib/Vtiger/#ac(age.php'); reFuire_once('vtlib/Vtiger/Module.php'); $pac(age = ne Vtiger_#ac(age(); $moduleInstance = Vtiger_Module&&getInstance('#a$slip'); $pac(age!"update($moduleInstance; 'test/vtlib/#a$slip.Iip');

Limitations

5! Any property hange to e(isting blo $ or %ield #ill not applied during module upgrade!
-.&': Loo$ at Adding@Migration@Details se tion to $no# more about adding migration in%ormation to the pa $age %ile through mani%est!(ml

vtlib

'(tension %odule

Module Manager lets you install an e(tension module provided the mani%est!(ml 8in pa $age: has the %ollo#ing in%ormation! ,his 'eature is available 'rom vti(er 12M 3.4.5 onwards only.
mani$est.(ml

'E<ml version=W7.8W encoding=Qut5!RQE" 'module" 't$pe"e<tension'/t$pe" 'name"M0>4*:.+M:'/name" 'label"M0>4*: *+):*'/label" 'parent"%ools'/parent" 'version"7.8'/version" 'dependencies" 'vtiger_version"K.7.8'/vtiger_version" '/dependencies" 'tables" 'table" 'name"%+)*:!.+M:'/name" 'sFl"'T?3>+%+?31:+%:_%+)*:_-G*BB"'/sFl" '/table" '/tables" 'events" 'event" 'eventname":V:.%_.+M:'/eventname" 'classname":V:.%_6+.>*:1_3*+--'/classname" '5ilename":V:.%_6+.>*:1_3*+--_/I*:'/5ilename" 'condition"'T?3>+%+?modulename in ?'M0>4*:.+M:'BBB"'/condition" '/event" '/events" '/module"
type name label parent dependen ies 8vtiger@version: tables events Mandatory Mandatory Mandatory =ptional Mandatory =ptional =ptional Should have the value e(tension Module name 8should not ontain spa es or spe ial hara ters: Label used to display on the 9I Menu to #hi h this Module needs to be atta hed +ersion %or #hi h the pa $age is intended %or Tables that needs to be reated during installation o% module Events that needs to be registered during installation o% module

Package File The %ollo#ing %ile stru ture is re ommended %or e(tension module pa $age 8Dip %ile:! mani5est.<ml modules/ M0>4*:.+M:/ language/ en_us.lang.php inde<.php 'other module 5iles" templates/ 'smart$ templates"

vtlib

*undles

Module Manager lets you install bundles provided the mani%est!(ml 8in pa $age: has the %ollo#ing in%ormation! ,his 'eature is available 'rom vti(er 12M 3.6.5 onwards only.
mani$est.(ml

'E<ml version=W7.8W encoding=Qut5!RQE" 'module" 'name"M0>4*:.+M:'/name" 'version"7.8'/version" 'dependencies" 'vtiger_version"K.7.8'/vtiger_version" 'vtiger_ma<_version"K.J'/vtiger_ma<_version" '/dependencies" 'modulebundle"true'/modulebundle" 'modulelist" 'dependent_module" 'name")4.>*:_#+1%_7'/name" 'install_seFuence"7'/install_seFuence" '5ilepath"M0>4*:_/I*:_7.Iip'/5ilepath" '/dependent_module" 'dependent_module" 'name")4.>*:_#+1%_2'/name" 'install_seFuence"2'/install_seFuence" '5ilepath"M0>4*:_/I*:_2.Iip'/5ilepath" '/dependent_module" '/modulelist" '/module"
modulebundle name dependen ies 8vtiger@version: modulelist Mandatory Mandatory Mandatory =ptional Should have the value true Module name 8should not ontain spa es or spe ial hara ters: +ersion %or #hi h the pa $age is intended %or List o% modules #hi h are part o% the bundle #ith their name& installation se'uen e and the %ile name

Package File The %ollo#ing %ile stru ture is re ommended %or bundles pa $age 8Dip %ile:! mani5est.<ml M0>4*:.+M:_7.Iip M0>4*:.+M:_2.Iip ...

vtlib

)anguage Pa"#

Module Manager lets you install language pa $s to your vtiger CRM installation! The Language pa $age should %ollo# the pa $age stru ture as e(plained belo#:
mani$est.(ml

'E<ml version=W7.8W encoding=Qut5!RQE" 'module" 't$pe"language'/t$pe" 'name":nglish'/name" 'label"4- :nglish'/label" 'pre5i<"en_us'/pre5i<" 'version"7.8'/version" 'dependencies" 'vtiger_version"K.7.8'/vtiger_version" '/dependencies" '/module"
type name label pre%i( Mandatory =ptional Mandatory Mandatory Should have the value language Language pa $ omplete name Label to identi%y the language on the 9I 8on login page: The %ilename pre%i( used %or language %ile! =nly these %iles #ill be e(tra ted %rom the pa $age %ile during installation! +ersion %or #hi h the pa $age is intended %or!

dependen ies 8vtiger@version:

Mandatory

Package File The %ollo#ing %ile stru ture is re ommended %or e(tension language pa $age 8Dip %ile:! mani5est.<ml modules/ +ccounts/ language/ 'pre5i<".lang.php 3ontacts/ language/ 'pre5i<".lang.php *eads/ language/ 'pre5i<".lang.php ...

vtlib

Adding )i"ense

The mani%est!(ml o% the pa $age an ontain li ense in%ormation #hi h #ill be displayed to user during Module Manager installation pro ess! Gou #ill need to add >li"ense? node in the mani%est!(ml as des ribed belo#:
Inline )i"ense1

'module" 'name"M0>4*:.+M:'/name" 'label"M0>4*:_*+):*'/label" 'version"7.8'/version" 'dependencies" 'vtiger_version"K.8.M'/vtiger_version" '/dependencies" 'license" 'inline"'T?3>+%+?%his is under vtiger #ublic *icense BB"'/inline" '/license" ... '/module"
)i"ense $rom /ile1

Gou an spe i%i the LICE>SE4ILE in the pa $age that ontains the Li ense in%ormation! 'module" 'name"M0>4*:.+M:'/name" 'label"M0>4*:_*+):*'/label" 'version"7.8'/version" 'dependencies" 'vtiger_version"K.8.M'/vtiger_version" '/dependencies" 'license" '5ile"*I3:.-:/I*:'/5ile" '/license" ... '/module"

vtlib

Adding %igration Details

Module Manager supports upgrade o% modules built #ith vtlib! In some ases& ustom s hema hanges and data migration #ill be re'uired %or these module upgrades! "hen a ne# version o% a module is released it might have s hema hanges #!r!t older version! The upgrade pro ess might not be omplete unless re'uired s hema hanges and data migration are applied! In su h ases& you an add the migration in%ormation in your mani%est!(ml as des ribed belo#: 'E<ml version=W7.8W encoding=Qut5!RQE" 'module" 'name"M0>4*:.+M:'/name" 'label"M0>4*: *+):*'/label" 'parent"%ools'/parent" 'version"7.2'/version" 'dependencies" 'vtiger_version"K.8.M'/vtiger_version" '/dependencies" 'migrations" 'migration version='7.8'" 'tables" 'table" 'name"%+)*:!.+M:'/name" 'sFl"'T?3>+%+?+*%:1 %+)*: M$%able +>> 30*4M. .e 3olumn I.%BB"'/sFl" '/table" '/tables" '/migration" 'migration version='7.7'" 'tables" 'table" 'name"%+)*:!.+M:'/name" 'sFl"'T?3>+%+?4#>+%: M$%able -:% .e 3olumn=7 @6:1: .e 3olumn is .4**BB"'/sFl" '/table" '/tables" '/migration" '/migrations" 'tables" 'table" 'name"%+)*:!.+M:'/name" 'sFl"'T?3>+%+?31:+%:_%+)*:_-G*BB"'/sFl" '/table" '/tables" ... '/module"
-.&': The above snippet o% mani%est!(ml is %or version 5!7 o% a module! It ontains migration in%ormation %or version 5!; and 5!5

vtlib

Migration node details Hmigration versionOF5!;F!!! HtablesI HtableI HnameI!!! Hs'lI!!! This version indi ates the sour e version 8earlier version: %or #hi h the migration should be applied! Table name to migrate! S/L to use %or migration!

vtlib

%odule %anager
=n e vtlib is installed& it provides the Module Manager on%iguration tool under Settings! "ith this you an enable& disable or ontrol settings o% vtiger CRM modules! =n disabling a module& it #onFt be sho#n on the Menu and a ess is restri ted 8in luding %or the administrator:!

Modules are ategoriDed as Standard 8#hi h are provided as a ore part o% vtiger CRM:& and Custom 8#hi h you have imported or reated:

vtlib

Disabling %odule

Gou an disable module by li $ing on the green ti $ mar$ i on!

'nabling %odule

Gou an enable module by li $ing on the red ti $ mar$ i on!

vtlib

'(porting %odule

Cli $ on the 9* arro# i on in the module manager& #hi h #ill e(port the module as a Dip %ile!

vtlib

Importing %odule

Module manager #ill let you import ne# modules! 4ollo# the steps given belo#: Cli $ on the Import >e# button

Sele t the module Dip 8pa $age: %ile that #as previously e(ported or reated!

vtlib

+eri%y the import details parsed %rom Dip%ile! Cli $ Ges to pro eed or >o to an el!

Cli $ on 4inish to omplete the module import!

vtlib

-.&': I% you are trying to import a module #hi h already e(ists or a dire tory #hi h is present in the modules %older you #ill see the %ollo#ing message!

vtlib

%odule 0pe"i$i" 0ettings

A module an have its o#n spe i%i settings! In su h ases& Settings!php should be reated under the module %older! This %ile #ill be invo$ed 8i% %ound: #hen Settings i on is li $ed!

E(ample: Sample Settings!php %or *ayslip module 'Ephp $thisModule = $_1:G4:-%?'5ormodule'B; reFuire_once('-mart$_setup.php'); $smart$ = ne vtiger31M_-mart$();

// 4se the module speci5ic template 5ile // modules/#a$slip/M$-ettings.tpl $smart$!"displa$(vtlib_getModule%emplate('#a$slip'; 'M$-ettings.tpl')); E"

vtlib

%odule 4pgrade

9pgrading the module to ne(t version is no# possible through Module Manager!
-.&': Currently this module upgrade %eature does not support deletion and modi%i ation o% e(iting module %ields! 2e%ore you use this %eature& please ensure your modi%ied module does not hange or delete e(isting %ields!

Cli $ on the upgrade i on:

Sele t the ne# pa $age %ile %or the module:

vtlib

+eri%y the pa $age details be%ore you upgrade:

4inally your module #ill be upgraded:

vtlib

Appendi( 1

API +hanges

vtlib 7!; ontains hanges to the A*Is previous provided in 5!( version! The ne# A*Is are more modular and adhere to the ==D model! "e e(plain the hanges belo#!
+reating %odule

9sing vtlib 5!( Vtiger_%ab&&create('#a$slip'; '#a$slip'; '%ools'); Vtiger_4tils&&3reate%able('vtiger_pa$slip'; '(pa$slipid integer)'); Vtiger_4tils&&3reate%able('vtiger_pa$slipc5'; '(pa$slipid integer; primar$ (e$ (pa$slipid))'); Vtiger_4tils&&3reate%able('vtiger_pa$slipgrouprel'; '(pa$slipid integer; groupname varchar(788); primar$ (e$(pa$slipid))'); 9sing vtlib 7!( $moduleInstance = ne Vtiger_Module(); $moduleInstance!"name = '#a$slip'; $moduleInstance!"save(); $moduleInstance!"init%ables(); $menuInstance = Vtiger_Menu&&getInstance('%ools'); $menuInstance!"addModule($moduleInstance);
+reating *lo"#

9sing vtlib 5!( Vtiger_)loc(&&create('#a$slip'; '*)*_#+,-*I#_I./01M+%I0.'); 9sing vtlib 7!( $bloc(Instance = ne Vtiger_)loc((); $bloc(Instance!"label = '*)*_#+,-*I#_I./01M+%I0.'; $moduleInstance!"add)loc(($bloc(Instance);

vtlib

+reating /ield

9sing vtlib 5!( $5ieldInstance = ne Vtiger_/ield(); $5ieldInstance!" set('module'; '#a$slip') !" set('columnname'; 'pa$slipname') !" set('tablename'; 'vtiger_pa$slip') !" set('columnt$pe'; 'varchar(2KK)') !" set('generatedt$pe'; '7') !" set('uit$pe'; 2) !" set('5ieldname'; 'pa$slipname') !" set('5ieldlabel'; '#a$slip.ame') !" set('readonl$'; '7') !" set('presence'; '8') !" set('selected'; '8') !" set('ma<imumlength'; '788') !" set('seFuence'; null) !" set('t$peo5data'; 'V9M') !" set('Fuic(create'; '7') !" set('bloc('; null) !" set('bloc(label'; '*)*_#+,-*I#_I./01M+%I0.') !" set('displa$t$pe'; '7') !" set('Fuic(createseFuence'; null) !" set('in5o_t$pe'; ')+-'); $5ieldInstance!"create(); 9sing vtlib 7!( $5ieldInstance = ne Vtiger_/ield(); $5ieldInstance!"name = '#a$slip.ame'; $5ieldInstance!"table = 'vtiger_pa$slip'; $5ieldInstance!"column = 'pa$slipname'; $5ieldInstance!"columnt$pe = 'V+136+1(788)'; $5ieldInstance!"uit$pe = 2; $5ieldInstance!"t$peo5data = 'V9M'; $bloc(Instance!"add/ield($5ieldInstance);
0etting 'ntity Identi$ier

9sing vtlib 5!( $5ieldInstance!"set('entit$id5ield'; 'pa$slipid') !"set('entit$idcolumn'; 'pa$slipid'); $5ieldInstance!"set:ntit$Identi5ier(); 9sing vtlib 7!( $moduleInstance!"set:ntit$Identi5ier($5ieldInstance);
0et Pi"#list Values

9sing vtlib 5!( $5ieldInstance!"setup#ic(listValues( +rra$ (':mplo$ee'; '%rainee') ); 9sing vtlib 7!( $5ieldInstance!"set#ic(listValues( +rra$ (':mplo$ee'; '%rainee') );

vtlib

+reating /ilter

9sing vtlib 5!( Vtiger_3ustomVie &&create('#a$slip'; '+ll';true); $cv = ne Vtiger_3ustomVie ('#a$slip'; '+ll'); $cv!"add3olumn($5ieldInstance7) !"add3olumn($5ieldInstance2; 7); 9sing vtlib 7!( $5ilterInstance = ne Vtiger_/ilter(); $5ilterInstance!"name = '+ll'; $5ilterInstance!"isde5ault = true; $moduleInstance!"add/ilter($5ilterInstance); $5ilterInstance!"add/ield($5ieldInstance7)!"add/ield($5ieldInstance2; 7);
+on$igure &ools

9sing vtlib 5!( Vtiger_Module&&disable+ction('#a$slip';'Import'); Vtiger_Module&&enable+ction('#a$slip'; ':<port'); 9sing vtlib 7!( $moduleInstance!"enable%ools(+rra$('Import'; 'Merge')); $moduleInstance!"disable%ools(':<port');
+on$igure 0haring A""ess

9sing vtlib 5!( Vtiger_Module&&set>e5ault-haring+ccess('#a$slip'; '#rivate'); 9sing vtlib 7!( $moduleInstance!"set>e5ault-haring('#rivate');

vtlib

Appendi( 2 0"hema +hanges

Some o% the vtlib A*I ma$e the s hema hanges 8either adding a ne# table or ne# olumn to e(isting table: the details are aptured in this se tion
&able vtiger@%ield +olumn helpin%o TEXT A"tion Column Addition Table Addition Table Addition version +ARC,AR85;: Column Addition Table Addition Des"ription This olumn #ill store the helpte(t asso iated #ith vtiger@%ield Captures languages installed %or vtiger CRM Captures details o% ustom module lin$s Tra $ version o% module in use! 9se%ul during migration or upgrade o% module! Captures some o% the module pre%eren es li$e minimum version supported& ma(imum version supported et ! Captures the relation bet#een module re ords!
4or Jeneri related list handling!

vtiger@language vtiger@lin$s vtiger@tab vtiger@tab@in%o

vtiger@ rmentityrel vtiger@%ieldmodulerel vtiger@mailer@'ueue vtiger@mailer@'ueuein%o

Table Addition Table Addition Table Additions

Captures related module in%ormation %or the %ield o% uitype 5; These tables #ill be added #hen +tiger@Mailer lass #ill be use %or sending mails asyn hronously!

vtlib

Appendi( 6 4sing vtiger@imageurl API

There are reusable images under themesEimages %older and theme spe i%i images #ill be under themesEHT,EME>AMEIEimages %older! Gou an let the image easily on%igurable %or ea h theme& please ma$e sure to %ollo# the steps belo#: In GourSmarty4ile!tpl 87marty template 'ile: 'img src=QC'm$image.gi5'XYvtiger_imageurl&$%6:M:DQ" KT,EME variable #ill be sent by the alling s ript as %ollo#s: global $theme; $smart$!"assign('%6:M:'; $theme); $smart$!"displa$(',our-mart$/ile.tpl'); This gets translated to:
Himg sr OSthemesEHT,EME>AMEIEimagesEmyimage!gi%SI Himg sr OSthemesEimagesEmyimage!gi%SI I% myimage!gi% e(ists under HT,EME>AMEI %older De%ault path i% theme spe i%i image is not %ound

I% you dire tly building the 9I %rom *,* s ript& ma$e sure to use the A*I as %ollo#s: vtiger_imageurl ( 'imagename'; 'themename' );
-.&': vtiger@imageurl A*I is de%ined in in ludeEutilsE+tlib9tils!php

vtlib

Appendi( 7 vtlib@handler %ethod

Module lass should de%ine vtlib@handler method to handle spe ial events triggered as des ribed belo#:
'vent &ype module!postinstall module!preupdate module!postupdate module!disabled module!enabled module!preuninstall Des"ription =n e the module import is ompleted! 2e%ore updating module 8pa $age:! A%ter module 8pa $age: is updated! "hen module is disabled! "hen module is enabled! 2e%ore module instan e is deleted!

E(ample: vtlib)handler 'unction should be de'ined as Module 1lass method. /JJ J Invo(ed hen special actions are per5ormed on the module. J Yparam -tring Module name J Yparam -tring :vent %$pe J/ 5unction vtlib_handler($modulename; $event_t$pe) C i5($event_t$pe == 'module.postinstall') C // %0>0 6andle post installation actions D else i5($event_t$pe == 'module.disabled') C // %0>0 6andle actions hen this module is disabled. D else i5($event_t$pe == 'module.enabled') C // %0>0 6andle actions hen this module is enabled. D else i5($event_t$pe == 'module.preuninstall') C // %0>0 6andle actions hen this module is about to be deleted. D else i5($event_t$pe == 'module.preupdate') C // %0>0 6andle actions be5ore this module is updated. D else i5($event_t$pe == 'module.postupdate') C // %0>0 6andle actions a5ter this module is updated. D D
4se"ase "hen a module is disabled& through vtlib@handler no# it an de)register any Event noti%i ation unless it is enabled again!

vtlib

Appendi( 5 vtlib@listvie, Aavas"ript API

vtlib@listvie# javas ript A*I provides the ability to register listener %un tion %or some prede%ined event types! vtlib_listvie .register( ':V:.%_%,#:"; '6+.>*:1_/4.3%I0."; ?'6+.>*:1_/4.3%I0._0#%I0.+*_#+1+M:%:1-"B );
ell!onmouseover ell!onmouseout "hen the mouse moves over the listvie# ell! "hen the mouse moves out o% the listvie# ell!

The handler %un tion #ill be invo$ed #ith t#o set o% arguments:
Event *arameters

event : domnode : module : ieldname: $eco$did :

<EVENT_TYPE> HTML DOM node used to detect the event Module Name to which ield !elon"s #ield Name %eco$d &D dis'la(ed on the listview

D
=ptional *arameters This is the one that #as passed to the vtlib@listvie#!register A*I

E(ample: Gou an have the %ollo#ing in your javas ript %ile vtlib_listvie .register( 'cell.onmouseover'; 5unction(evtparams) C evtparams.domnode.st$le.bac(ground3olor = 'Z///>O3'; D); vtlib_listvie .register( 'cell.onmouseout'; 5unction(evtparams) C evtparams.domnode.st$le.bac(ground3olor = ' hite'; D);
>=TE: To ma$e the trigger on all the modules& you #ill need to on%igure the javas ript as ,EADERSCRI*T 8re%er Custom Lin$sYSpe ial Lin$Type:

vtlib

/A!s /reBuently As#ed !uestions

1. Ho, to ,rite o,n templatesC

Re%eren e: http:EE%orums!vtiger! omEvie#topi !phpApO1.-5;Y1.-5; .o I ant to set m$ o n templates. %he V%*ib documentation states that I do this& ,our module speci5ic -mart$ template 5iles should be created under -mart$/templates/modules/'.e Module.ame". 4se vtlib_getModule%emplate($module; $template.ame) +#I (include/utils/Vtlib4tils.php) as& $smart$!"displa$(vtlib_getModule%emplate($currentModule; 'M$*istvie .tpl')); M$ Fuestion is Solution: Let us assume you #ant to reate your o#n Listvie# %or your module TestModule& #hat you need to do is the %ollo#ing: 5! Create the MyListvie#!tpl under SmartyEtemplatesEmodulesETestModuleEMyList+ie#!tpl 7! In your modulesETestModuleEListvie#!php you #ill need to all the smarty display as: $smart$!"displa$(vtlib_getModule%emplate($currentModule; 'M$*istvie .tpl')); *lease re%er: http:EE###!smarty!netEmanualEenE to learn more about Smarty usage!
2. Ho, is module template usedC

here do I place this piece o5 codeE In the module creatorE

E(ample belo# e(plains ho# the module listvie# a tion gets pro essed using the smarty!

vtlib

6. +annot 0ee %odule %anagerD

I[ve installed vtlib on vitger K.8.M I can not seem to see the module manager under settings on either; is there a 5ile or dir I need to move some here in order 5or the module manager to populateE Solution:

Enable #rite a ess to modules/; -mart$/; cron/; test/ dire tory be%ore unDipping vtlib)(!y!Dip Delete the %iles under %older SmartyEtemplates@ 8having e(tension C!tpl!php: and re%resh the Settings page& you should see Module Manager!

7. &ips $or using $ield names

5! *re%erably use small ase hara ters %or %ield 8name and olumnname:! 7! Avoid any spe ial hara ters li$e 8@&:&): in names! Gou an use it %or labels <! ,aving same value %or %ield 8name and olumnname: #ould ma$es it easier to avoid on%usion to start #ith!

vtlib