Table Of Contents

Previous topic

An Entity Module Example

Next topic

An Extension Module Example

Slideshow

This example will walk you through the use of Server APIs (accessing records) of Vtiger 6 Framework.

Note

Server APIs should be used when you are accessing records of any module. It takes care of retrieval with access control (Sharing access & Profile access) setup for the logged in user.

Important

Using direct SQL queries for retrieving records may open-doors for users to gain access to records that they do not have permission to view.

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 “Slideshow-v1.zip” from here.

Step 1: Create files

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

manifest.xml
modules/Slideshow/Slideshow.php
modules/Slideshow/views/List.php
modules/Slideshow/js/SlideshowShared.js
modules/Slideshow/js/remarkjs.min.js
languages/en_us/Slideshow.php
templates/ListViewContents.tpl

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>Slideshow</name>
        <label>Slideshow</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/Slideshow/Slideshow.php).

<?php

class Slideshow {

        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", "SlideshowShared",
                                "modules/Slideshow/js/SlideshowShared.js");

                        $leadsModuleInstance = Vtiger_Module::getInstance('Leads');
                        $leadsModuleInstance->addLink("LISTVIEW", "Slideshow",
                                'javascript:Slideshow.viewSelected();');

                        $contactsModuleInstance = Vtiger_Module::getInstance('Contacts');
                        $contactsModuleInstance->addLink("LISTVIEW", "Slideshow",
                                'javascript:Slideshow.viewSelected();');
                }
        }

        protected function _deregisterLinks($moduleName) {
                $thisModuleInstance = Vtiger_Module::getInstance($moduleName);
                if ($thisModuleInstance) {
                        $thisModuleInstance->deleteLink("HEADERSCRIPT", "SlideshowShared",
                                "modules/Slideshow/js/SlideshowShared.js");

                        $leadsModuleInstance = Vtiger_Module::getInstance('Leads');
                        $leadsModuleInstance->deleteLink("LISTVIEW", "Slideshow");

                        $contactsModuleInstance = Vtiger_Module::getInstance('Contacts');
                        $contactsModuleInstance->deleteLink("LISTVIEW", "Slideshow");
                }
        }
}

Note

vtlib_handler is invoked by ModuleManager with specific $eventType. The javascript & links on Leads & Contacts module is registered / deregistered accordingly.

Step 4: View Class

Edit modules/Slideshow/views/List.php - showcases retrieval of target module records using Server APIs (vtws_query)

<?php

/* Include dependency required for using Server API */
include_once 'include/Webservices/Query.php';

class Slideshow_List_View extends Vtiger_Index_View {

        public function process(Vtiger_Request $request) {

                // Current User Context
                $userContext = vglobal('current_user');
                $viewer = $this->getViewer($request);

                if ($request->has('ids') && $request->has('src_module')) {
                        // Was request made for the slideshow - lets act now.

                        // Prepare Webservices Query
                        $srcModule = $request->get('src_module');
                        $ids = array_map('intval', $request->get('ids'));
                        $idsuffix = trim(vtws_getWebserviceEntityId($srcModule, '0'), '0');
                        $wsids = array(); foreach ($ids as $id) $wsids[] = $idsuffix.$id;

                        $wsquery = sprintf("SELECT * FROM %s WHERE id IN ('%s');",
                                $srcModule, implode("','", $wsids) );

                        // Execute the query and fetch records
                        $records = vtws_query($wsquery, $userContext);

                        // Pass the records for rendering the slideshow.
                        $viewer->assign('RECORDS', $records);
                        $viewer->assign('SRCMODULE', $srcModule);
                        $viewer->assign('COUNT', count($records));
                }

                $viewer->view('ListViewContents.tpl', $request->getModule());
        }
}

Step 5: Javascript Hook

Edit modules/Slideshow/js/SlideshowShared.js

jQuery.Class('Slideshow', {
        viewSelected: function() {
                var listView    = Vtiger_List_Js.getInstance();
                var nothingSelected = listView.checkListRecordSelected();
                if (nothingSelected) {
                        alert('Nothing selected!');
                } else {
                        var selectedIds = listView.readSelectedIds(false);
                        var excludedIds = listView.readExcludedIds(false);
                        if (selectedIds.length) {
                                window.open("index.php?module=Slideshow&view=List&ids="+
                                        JSON.stringify(selectedIds)+"&src_module="+app.getModuleName());
                        }
                }
        }
}, {});

Step 6: Slideshow Renderer

Copy http://gnab.github.io/remark/downloads/remark-latest.min.js to modules/Slideshow/js/remark.min.js

Step 7: View Template

Edit templates/ListViewContents.tpl

<br>
{if !$RECORDS}
        <center><h1>Welcome to Slideshow<h1>
        <h4>The support is enabled through Javascript for Leads & Contacts!</h4></center>
{else}
<script type="text/javascript" src="modules/Slideshow/js/remark.min.js"></script>
<style type="text/css">
.remark-slide h1 { font-size: 30px; }
.remark-slide em { font-size: 18px; }
#page { display: none; }
</style>

<!-- Prepare remarkjs friendly source -->
<textarea id="source">
class: center, middle
# {$SRCMODULE} ( {$COUNT} )
---
{foreach item=RECORD from=$RECORDS}
Field | Value
---- | ---
{foreach key=FIELDNAME item=FIELDVALUE from=$RECORD}
{if $FIELDVALUE}
{$FIELDNAME} | {$FIELDVALUE}
{/if}
{/foreach}
---
{/foreach}

class: center, middle
# Thank you
</textarea>

<!-- Trigger rendering on the client-side -->
<script type="text/javascript">
        var slideshow = remark.create();
        jQuery(function(){
                jQuery('table').addClass('table table-bordered');
        });
</script>
{/if}

Step 8: Default i18n

Edit languages/en_us/Slideshow.php

<?php

$languageStrings = array(
        'Slideshow' => 'Slideshow'
);

Note

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

Step 9: Package files

zip -r Slideshow-v1.zip manifest.xml modules/Slideshow/Slideshow.php modules/Slideshow/views/List.php modules/Slideshow/js/SlideshowShared.js modules/Slideshow/js/remarkjs.min.js languages/en_us/Slideshow.php templates/ListViewContents.tpl

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.

Navigate to Leads / Contacts ListView > Select Desired Records > Click Slideshow under Actions