Vtiger CRM 6 introduces a complete new front-end

Overview

Vtiger CRM 6 introduces a complete new front-end to put more power in the hands of developers and users. The client-side code has been rewritten from ground up to improve extensibility and usability. Vtiger CRM 6 design makes it easy to add extensions to the product, and introduce new layouts and skins.

MVC Architecture

Vtiger CRM 6 front-end follows MVC architecture.

OOP principles have been introduced in Controllers to ease maintainability and improving extensibility.

Smarty templates have been cleaned up to remove all the data processing logic, and now retain only the presentation code.

New Libraries

The following libraries are being used in Vtiger CRM 6

• jQuery 1.7
• Bootstrap 2.0.4
• jQuery Class
• few more libraries for specific UI controls (ex: jqPlot, jCalendar)

These widely used and actively maintained libraries enable simplicity in development and bring the power of latest web technologies to vtiger users.

Vtiger CRM 5.4 client is still available for some more time

Both the 5.4 and 6.0 clients coexist in Vtiger CRM 6. Users can switch between the new and old UIs from the menu bar. 5.4 UI is being deprecated in Version 6

vtiger CRM 6 URL - http://yourserver.com/vtigercrm/vtiger6/index.php

Folder Structure

Vtiger CRM 6 folder contains all the related files and coexists with vtiger CRM 5.x

vtiger6/
  index.php  <- Main UI Entry point
  configs/   <- Configuration files
  includes/  <- Helper classes
  languages/ <- Translation files
  libraries/ <- Third-party libs
  main/      <- Entry point files
  modules/   <- Module specific files
  resources/ <- Common client resources
  layouts/   <- layouts and skins

Module Structure

Vtiger CRM 6 provides fallback implementation for commonly supported operations for Entity module. This eliminates the need for each module to reimplement controllers. Each module can override the fall back module implementation (in modules/Vtiger) only when required.

Following is the folder structure of the fall back module:

vtiger6/
  modules/
    Vtiger/
      models/ (ViewModels helper implementation)
        Record.php      (class Vtiger_Record_Model)
        Field.php       (class Vtiger_Field_Model)
        Module.php      (class Vtiger_Module_Model)
        …
     
      views/ (ViewControllers)
        Detail.php      (class Vtiger_Detail_View)
        Popup.php       (class Vtiger_Popup_View)
    
      actions/ (ActionControllers)
        BasicAjax.php   (class Vtiger_BasicAjax_Action)
        Delete.php      (class Vtiger_Delete_Action)
        DeleteAjax.php  (class Vtiger_DeleteAjax_Action)
        ExportData.php  (class Vtiger_ExportData_Action)
        MassEdit.php    (class Vtiger_MassEdit_Action)
        Save.php        (class Vtiger_Save_Action)
     
      dashboards/ (ModuleDashboards)
        History.php       (class Vtiger_History_Dashboard)
        UpcomingTasks.php (class vtiger_UpcomingTasks_Dashboard)
     
      handlers/ (EventHandlers)
        RecordLabelUpdater.php (class Vtiger_RecordLabelUpdater_Handler)

Creating custom Controllers and Views

Given below is the partial structure of Leads module which implements extended operations:

vtiger6/
  modules/
    Leads/
      dashboards/ 
        LeasByIndustry.php  (class Leads_LeadsByIndustry_Dashboard)
      views/
        ConvertLead.php     (class Leads_ConvertLead_View)
        SaveConvertLead.php (class Leads_SaveConvertLead_View)

Layouts Folder

Vtiger CRM 6 enables multiple layouts. Each layout is generated using Smarty templates.

Currently, the default layout is hard coded (in include/Runtime/Viewer.php), which in future is being planned to be configurable by user.

vtiger6/
  layouts/
    vlayout/  <-  (default)
      skins/
        default/
          style.less
          variables.less
          ..
      modules/
        Vtiger/ <- Fallback implementation     
   resources/ <- (Javascripts)     
            Header.tpl
            BasicHeader.tpl
      
            IndexViewPreProcess.tpl
            IndexPostProcess.tpl
      
            ListViewPreProcess.tpl
            ListViewPostProcess.tpl
            ListViewSidebar.tpl
            ListViewContents.tpl
            …

The fallback implementation templates look at module-specific templates for inclusion if one exists.

vtiger6/
  layouts/
    vlayout/
      modules/
        Leads/
          ListViewSidebar.tpl
          ConvertLead.tpl
          ConvertLeadError.tpl 

Skins for a layout

Each layout can be associated with one-or-more skins.

vtiger6/
  layouts/
    vlayout/  <-  (default)
      skins/
        default/
          images/
            style.less
            variables.less
        woodspice/              <- (additional skin)
          images/
            style.less
            variables.less

Client Framework

jQuery Class plugin is used to enable OO control on Javascript.

Each Module View can be associated with client-javascript, the inclusion of the script file is controlled in ViewController based on its existence for the module (otherwise the fallback file is included).

jQuery.Class('Classname', {
 /* Static properties / methods */
}, {
 /* Class properties / methods */
});

Classname format:

ModuleName_<TARGET>_Js

Helpers

<TBD>

app. …

Server Framework

i18n Framework

Vtiger CRM 6 simplifies localization structure, by bringing together all the language files into one folder. Each language file contains both server side ($phpStrings) and client side strings ($jsStrings) associated with a module in vtiger CRM.

vtiger6/
  languages/
    en_us/
      Accounts.php <- ($phpStrings, $jsStrings)
      Leads.php    <- ($phpStrings, $jsStrings)
      ..
    de_de/
      Accounts.php <- ($phpStrings, $jsStrings)
      Leads.php    <- ($phpStrings, $jsStrings)

<TBD>

ViewController vs ActionController

ViewController are responsible to process the incoming request and responds with HTML / JSON content, which will be further consumed by the client-framework.

ActionController are responsible to process the incoming request and respond with a redirection / JSON content.

Helpers

…

Customize View / Action

…

<TBD>

Embed 5.x UI inside vtiger 6

To make it easy for any extension module to quickly turn-on embed UI pattern we implemented the following:

vtiger6/modules/Vtiger/views/UI5Embed.php

<?php
class Vtiger_UI5Embed_View extends Vtiger_Index_View {
    protected function preProcessDisplay(Vtiger_Request $request) {}
    protected function getUI5EmbedURL(Vtiger_Request $request) {
        return '../index.php?action=index&module=' . $request->getModule();
    }
    public function process(Vtiger_Request $request) {
        $viewer = $this->getViewer($request);
        $viewer->assign('UI5_URL', $this->getUI5EmbedURL($request));
        $viewer->view('UI5EmbedView.tpl');
    } 
 }

vtiger6/templates/vlayout/Vtiger/UI5EmbedView.tpl

{include file="Header.tpl"|vtemplate_path:$MODULE}
{include file="BasicHeader.tpl"|vtemplate_path:$MODULE}

<div class="bodyContents">
 <div class="mainContainer row-fluid">
  <div class="span12">
   <iframe id="ui5frame" 
    src="{$UI5_URL}" width="100%" height="650px" 
    style="border:0;">
   </iframe>
 </div>

With this in place, any module that desires to embed older UI need the following implementation:

vtiger6/modules/MailManager/views/List.php

class MailManager_List_View extends Vtiger_UI5Embed_VIew {}

vtiger6/modules/RecycleBin/views/List.php

class RecycleBin_List_View extends Vtiger_UI5Embed_VIew {}

vtiger6/modules/DART/views/List.php

class DART_List_View extends Vtiger_UI5Embed_VIew {}

In case, the embed UI height varies dynamically then trigger to resize Iframe is desired from the javascript:

if (parent.resizeUI5Iframe) {
    parent.resizeUI5Iframe(self.document.body.scrollHeight);
}

Creating a Entity module in Vtiger CRM 6

Modules in this category will create entity records in vtiger CRM. The module will provide Create view, Edit view, Detail view and List view. You will be able to create filters etc.

Entity modules are recommended for cases where a new type of data object, e.g. Timesheet, needs to be added into the system as part of the new module. These new data objects can be viewed and managed by administrators and users.

Leads, Contacts, Accounts, Payslip etc... are Entity Modules.

Conventions

• Fieldname, Field Column - should be in lowercase and contain only alpha-numeric characters with an optional _.
• Picklist fieldname should be prefixed with module name lowercased. To avoid clash between other module picklist.

Setup script

Refer: Vtlib Documentation

Module Files

    vtigercrm
        modules/
            MyModule/
                language/
                    en_us.lang.php    (required to keep core APIs working)
                MyModule.php  (Refer: Vtlib Documentation)

NOTE: To make it work on Vtiger 6, you don't need any file under vtiger6/modules/MyModule unless you plan to customize or implement new view / action.

Module File Contents

Refer: Vtlib Documentation

Creating an Extension module in vtiger CRM 6

Modules in this category need not follow the general behavior of Entity Module. The records created by Entity module could be used to provide a extended functionality or the records creation/editing can be handled in its own way.

Extension modules can be used when add-on functionality is needed, without the need for new kinds of data objects that users view and manage.

Dashboard, Reports, Portal etc... are Extension Modules.

Setup script

<?php
$Vtiger_Utils_Log = true;

include_once 'vtlib/Vtiger/Module.php';
$myExtensionModule = Vtiger_Module::getInstance('MyExtension');
if ($myExtensionModule) {
 Vtiger_Utils::Log("Module already exits.");
} else {
 $myExtensionModule = new Vtiger_Module();
 $myExtensionModule->name = 'MyExtension';
 $myExtensionModule->label= 'My Extension';
 $myExtensionModule->parent='Tools';
 $myExtensionModule->save();
}

Module Files

    vtigercrm
        modules/
            MyExtension/
                language/
                    en_us.lang.php    (required to keep UI 5 working)
                MyExtension.php
        vtiger6/
            modules/
                MyExtension/
                    views/
                        List.php
            layouts/
                default/ (vlayout)
                    modules/
                        MyExtension/
                            Index.tpl
                            IndexViewPreProcess.tpl

Module File Contents

vtigercrm/modules/MyExtension/MyExtension.php - Module class definition

<?php
/** License Text Here **/
class MyExtension {
 /**
  * Invoked when special actions are performed on the module.
  * @param String Module name
  * @param String Event Type (module.postinstall, module.disabled, module.enabled, module.preuninstall)
  */
 function vtlib_handler($modulename, $event_type) {
  if($event_type == 'module.postinstall') {
   // TODO Handle post installation actions
  } else if($event_type == 'module.disabled') {
   // TODO Handle actions when this module is disabled.
  } else if($event_type == 'module.enabled') {
   // TODO Handle actions when this module is enabled.
  } else if($event_type == 'module.preuninstall') {
   // TODO Handle actions when this module is about to be deleted.
  } else if($event_type == 'module.preupdate') {
   // TODO Handle actions before this module is updated.
  } else if($event_type == 'module.postupdate') {
   // TODO Handle actions after this module is updated.
  }
 }
}

vtigercrm/modules/MyExtension/language/en_us.lang.php - Placeholder file required for UI 5

<?php
/** License Text Here **/
$mod_strings = array(
 'My Extension'=> 'My Extension'
);

vtigercrm/vtiger6/modules/MyExtension/views/List.php - Customize default behavior of List view - triggered from top-level Menu

<?php
/** License Text Here **/
class MyExtension_List_View extends Vtiger_Index_View {

 public function process(Vtiger_Request $request) {
  $viewer = $this->getViewer($request);
  $viewer->view('Index.tpl', $request->getModule());
 }
}

vtigercrm/vtiger6/layouts/default/modules/MyExtension/IndexViewPreProcess.tpl - Customize UI

{include file="Header.tpl"|vtemplate_path:$MODULE}
{include file="BasicHeader.tpl"|vtemplate_path:$MODULE}
<div class="bodyContents">
 <div class="mainContainer row-fluid">
  <div class="contentsDiv span12">

vtigercrm/vtiger6/layouts/default/modules/MyExtension/Index.tpl - Customize UI

<h2>{$MODULE} module <small>working now.</small></h2>

NOTE: vtigercrm/vtiger6/languages/en_us/MyExtension.php - controls the language translation for UI 6

<?php
/** License Text Here **/
$languageStrings = array(  
 'My Extension' => 'My Extension'
);

Creating a Language Pack

Refer: Vtiger 6 Language Translation

Creating a Layout and Skin

<TBD>

Porting existing extensions to vtiger CRM 6

<TBD>

API changes

<TBD>

Code Access / Report Issues

You can find the source code on our community svn: branches/6.0.0

Please use our issue tracker to report any issues/feedback on Vtiger6.

• Find issues reported on 6.0 ea