Introduction

This article is a developer document for Customizer. Customizer is a developer tool in Vtiger CRM to enable developers to make client-side changes.  You can now customize UI and add dynamic behaviour to the page based on your business need.

Resources

Customizer lets administrator inject (Javascript, Stylesheet) with custom code. You can fine-tune the behaviour using runtime APIs

Runtime

VCRT - Vtiger Custom Runtime provides helper function to make your coding simple and exciting.

Customizer

Do custom changes on the UI with Customizer.

Customizer is a developer tool included within Vtiger CRM to enable developers to make client-side changes. Customizer is currently installed upon request by Administrator. Customizer can be launched from the Settings > Module Management > Module Manager > Customizer > Customize.

Steps to deploy a new script/stylesheet

1. Open Customizer

2. Click on New to add a new resource
   

   • Javascript - Choose this to change elements in the DOM, do validation,
   • Stylesheet

3. Add the code/style and save the resource

4. Publish the resource
   

Steps to test scripts before publishing

After editing a script, enable Developer mode. Now, only you will see the latest revision version of the script.

When you are happy that the script is working fine, click on Publish. When you publish the revision number is increased.

API’s

1. VCRT - Vtiger Customizer Runtime object lets you access, listen and trigger events on DOM elements just like jQuery, apart from this it will give the ability to access vtiger data through web services. For this, we have provided the following API’s

VCRT.$(selector) - this is equivalent to jQuery or $, you can use this to select any DOM element. Few common components can be accessed by using @, for others, you can search using standard jQuery selectors.
Eg:

VCRT.$('@global-search');
likewise we have page, global-navbar, side-bar, company-logo, app-menu, quickcreate-menu.

jQuery selector based will be called like below:

VCRT.$(‘#appnavigator’);

2. VCRT.$N(tagName, options) - this API lets you create HTML element and pass additional parameters.
   Eg:
   var button = VCRT.$N('button', {
'class': 'btn p-btn',
'style': 'position:absolute;z-index:1050;top:10px;left:50%;',
'click': function(){
app.helper.showAlertBox({message: 'Hello World!'});
}
});
VCRT.$('@page').append(button.html('Say Hello'));

3. VCRT.api.wsid(modulename,id,callback(wsid)) - this api fetches webservice id when modulename and record id is passed to it. The fetched webservice id will be given to the callback function
   Eg:
   VCRT.api.wsid(app.getModuleName(), app.getRecordId(),
function(wsid){
//code
}
);

4. VCRT.api.query(query,callback) - this api can be used to query webservice queries. Queried result will be given to callback function for further processing.
   Eg: var wsquery = "select amount from Potentials where related_to='"+ wsid +"' order by amount desc limit 1";
VCRT.api.query(wsquery, function(e, opps) { //code });

5. VCRT.api.retrieve(id,callback) - this api can be used to retrieve information of the given record id
   Eg: VCRT.api.retrieve(wsid, function(e, recorddata) {
   //code
   });

6. VCRT.api.describe(modulename,callback) - this api can be used to describe information of the given module
   Eg: VCRT.api.describe(‘Contacts’, function(e, moduleInfo) {
//code
});

app - default vtiger app object provides many utility function, some of the common ones are:

app.getModuleName() - Gives the current module name.
app.getRecordId() - Gives the current record id.
app.getViewName() - Gives the current view name. Eg: Edit, Detail, List etc,.
app.getParentModuleName() - Gives parent module name. Eg: Settings
app.getDecimalSeparator() - Gives current user’s preferred decimal separator
app.getGroupingSeparator() - Gives current user’s preferred digit grouping separator
app.getDateFormat() - Gives user’s date format.
app.getHourFormat() - Gives user’s hour format
app.getUserId() - Gives the current user id
app.isAdminUser() - Return boolean stating whether current user is admin or not.
app.getUserLanguage() - Gives the user preferred language
app.getUserTimeZone() - Gives the user’s timezone.
app.helper.showAlertBox({message: message}) - Shows an alert box with the given message.
app.helper.showSuccessNotification({message: message}) - Shows success notification with the given message
app.helper.showErrorNotification({message: message}) - Shows error notification with the given message.

Vtiger Events - Common events which are triggered on the client side
Pre.Record.Save - triggered before record is saved
Vtiger.Referece.Popup.Pre = triggered before reference popup is opened from edit view, quick create view.
Vtiger.Referece.Popup.Post - triggered after reference field popup is opened
Vtiger.Reference.Selection - triggered when reference field value is being selected from the popup
Vtiger.PostReference.Selection - triggered after reference field value is selected
Vtiger.Reference.Deselection - triggered when a value is removed from reference field
Vtiger.MultiReference.Selection - triggered when a value is selected in a reference field
Vtiger.PostReference.QuickCreateSave - triggered when a record is created from reference field’s add(+) option in quick create.

Examples

Hide the main menu

If you would like users to only navigate within an app, using the left menu, and hide the menu, you can do it easily with the following script.

Hide the default ‘All’ list

By default, users have an ‘All’ list in every module. For example, in Opportunities, the ‘All opportunities’ list that shows that all the opportunities a user can access as per sharing rules. If a business has some additional restrictions to limit visibility to only records that are assigned to the user, or some other restriction, then you can write a script to remove the ‘All’ list.

Hide option to duplicate or edit a list

Some businesses might want to limit the ability for users to create custom lists or edit the lists. Create list permission can be turned off from a user profile. But, the user can still edit an existing list or duplicate an existing list. To restrict the user from doing those, you can write a custom script as below

Show biggest opportunity amount on Organization record

Show Pending Invoices Total on Organization record

Show opportunity total in Organization record

Showing message in a status box instead of an alert box

Do validation to verify that Referrer candidate and a Referred candidate is not same.

If you have a Referral module that has 2 employee fields - Referred employee & Referer Employee - you can write a script to validate to make sure the same employee is not in both fields.

Apply brand level discounts in Quote line items

If your quote has many line items and a user wants to give 10% discount for products of one brand, and 15% discount for products of another brand, you can write a script to prompt a user to get discount per brand and apply the discount to all the line items.

Add Brand Discount option:

Popup to apply and save discounts:

Example Stylesheets

Change the background colour

Roadmap

We plan to extend this functionality and provide finer control at module level. We will give option to select module when creating javascript or css. So if you want to add custom behavior for only Contacts module then you can enable javascript for Contacts module, it will not affect other modules. We will also provide “All modules” option so that you can write script which will affect all modules.