Table Of Contents

Previous topic

World Clock

Next topic

An Entity Module Example

City Lookup

This example will walk you through the steps of developing a module “City Lookup” extension on Vtiger 6 Framework. It introduces you to the way of manipulating the UI element of other module based on Client side.

Pre-requisites

  • Vtiger 6 installed on your server (assuming it would be used for development).
  • PHP CLI is setup to be invoked from the command prompt or terminal.
  • Gone through module development docs: Develop Extensions For Vtiger

Terminology

  • <vtigercrm> - root-directory / document root where Vtiger 6 is installed.
  • http://<vtigercrm> - web entry access.

Note

You can download “CityLookup-v1.zip” from here.

Step 1: Create files

Switch to your working directory (say.. Desktop) and create the following files.

manifest.xml
modules/CityLookup/CityLookup.php
modules/CityLookup/views/List.php
modules/CityLookup/js/CityLookupAutofill.js
languages/en_us/CityLookup.php

Step 2: manifest.xml

Edit manifest.xml and fill in basic information required for getting the extension installed in Vtiger.

<?xml version="1.0"?>
<module>
        <type>extension</type>
        <name>CityLookup</name>
        <label>City Lookup</label>
        <parent>Tools</parent>
        <version>1.0</version>
        <dependencies>
                <vtiger_version>6.0.0</vtiger_version>
                <vtiger_max_version>6.*</vtiger_max_version>
        </dependencies>
</module>

Step 3: Module Class

Update the module class file (modules/CityLookup/CityLookup.php).

<?php

class CityLookup {

        public function vtlib_handler($moduleName, $eventType) {
                if ($eventType == 'module.postinstall') {
                        $this->_registerLinks($moduleName);
                } else if ($eventType == 'module.enabled') {
                        $this->_registerLinks($moduleName);
                } else if ($eventType == 'module.disabled') {
                        $this->_deregisterLinks($moduleName);
                }
        }

        protected function _registerLinks($moduleName) {
                $thisModuleInstance = Vtiger_Module::getInstance($moduleName);
                if ($thisModuleInstance) {
                        $thisModuleInstance->addLink("HEADERSCRIPT", "City Autofill", "modules/CityLookup/js/CityLookupAutofill.js");
                }
        }

        protected function _deregisterLinks($moduleName) {
                $thisModuleInstance = Vtiger_Module::getInstance($moduleName);
                if ($thisModuleInstance) {
                        $thisModuleInstance->deleteLink("HEADERSCRIPT", "City Autofill", "modules/CityLookup/js/CityLookupAutofill.js");
                }
        }
}

Note

vtlib_handler is invoked by ModuleManager with specific $eventType. The javascript is registered / deregistered accordingly.

Step 4: View Class

Edit modules/CityLookup/views/List.php - nothing much just a placeholder in this case.

<?php

class CityLookup_List_View extends Vtiger_Index_View {

        public function process(Vtiger_Request $request) {
                echo "<center><h1>Welcome to CityLookup<h1>".
                "<h4>The support is enabled through Javascript for Leads & Contacts!</h4></center>";
        }
}

Step 5: Javascript Autofill

Edit modules/CityLookup/js/CityLookupAutofill.js

jQuery(function() {

        // Pre-configure list of cities.
        var cities = [
                "New York", "Los Angeles", "Chicago", "Houston", "Philadelphia",
                "Phoenix", "San Diego", "San Antonio", "Dallas", "Detroit", "Other"
        ]

        // Enable auto-fill editview / detailview (ajaxedit)
        var activeModule = app.getModuleName(), activeView = app.getViewName();
        if (activeView == 'Edit' || activeView == 'Detail') {
                // For target module
                if (activeModule == 'Leads' || activeModule == 'Contacts') {
                        // For target field.
                        var fieldName = 'city';
                        var field = jQuery("#"+activeModule+"_editView_fieldName_"+fieldName);
                        field.autocomplete({
                                source: cities
                        });
                }
        }

});

Step 8: Default i18n

Edit languages/en_us/CityLookup.php

<?php

$languageStrings = array(
        'City Lookup' => 'City Lookup'
);

Note

Add all the string constants used by the module - required for i18n support.

Step 9: Package files

zip -r CityLookup-v1.zip manifest.xml modules/CityLookup/CityLookup.php modules/CityLookup/views/List.php modules/CityLookup/js/CityLookupAutofill.js languages/en_us/CityLookup.php

Refer to Package Structure

Step 10: Install in Vtiger

You can import through Module Manager UI.

The module is now installed and ready, you can find it under All > Tools section.