Slideshow

This example will walk you through the use of Server APIs (accessing records) of Vtiger 7 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 7 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 7 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
layouts/v7/modules/Slideshow/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>7.0.0</vtiger_version>
                <vtiger_max_version>7.*</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 layouts/v7/modules/Slideshow/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 layouts/v7/modules/Slideshow/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