Explore How to Invoke a Widget using Client Script in Zoho CRM as a Validation Alert

Explore How to Invoke a Widget using Client Script in Zoho CRM as a Validation Alert

Requirement Overview

A Zoho CRM user wants to have a customized validation pop-up based on changes made in the record by any user.

Use-case

A Car Company that has multiple warehouses located in different locations (i.e., India, USA, UAE, etc.). It would be difficult to provide the product shipping price for each location. Hence, user can dynamically select the required warehouse, and prices will be automatically updated in the record's respective field. 

Here, The Company wants a validation alert based on the Shipping address which gives users an option to choose another location dynamically on the widget popup.

  1. Challenges to achieve this directly:

                  => As of now, we do not have a direct option to show the pop-up. Though, we have an option "i.e., method - getInput()" using Client Script to show the pop-up with the required fields and button. However, a user cannot have a required modification or customization on the pop-up based on business requirement.
                  => Hence, the user can create a widget (using HTML, JavaScript, CSS, etc.) in Zoho CRM and invoke it using Client Script.

Notes
Refer to following Help Link to know more about getInput() method in Client Script.
Alert
Info
Why It is Important:
  1. Validation with customized pop-up, improves User Experience
  2. Error Prevention
  3. Data Quality & Accuracy
  4. Speed up internal process of Business
Info

Permissions & Availability

-> Users with the Manage Extensibility can configure & setup Client Script and Widget.
-> Users with the Manage Sandbox permission can manage the sandbox and test this use-case.

Configuration

Since business use cases vary based on each company's requirements. To help you with basic understanding, we will develop a easier customized pop-up using Widget and learn how it can be invoked within a record on any page (i.e. Create/Edit/Detail/etc.).

Step1 - Creation of Widget in Zoho CRM

-> If you are creating a widget for the first time, then let us explore how exactly a user can create a sample widget from scratch with initial understanding. 
Info
Refer to the following Help Link to install the necessary components in your system to create a first project.
-> Once installed, the user can follow the instructions and create a first project.
Info
Refer to the following Help Link which explains in detail about creating a sample widget. 
-> Now that you have created your first project, you could find the HTML file for the widget in the app folder, named "widget.html" by default. Users can copy paste the below sample HTML script for the widget.
  1. Widget HTML Sample Script:
  1. <!DOCTYPE html>
  2. <html lang="en">
  3.   <head>
  4.    <meta charset="UTF-8" />
  5.     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  6.     <link rel="stylesheet" href="./stylee.css" />
  7.     <title>Simple Calculator</title>
  8.         <style>
  9.         body {
  10.             font-family: Arial, sans-serif;
  11.             background-color: #f43c15;
  12.             color: #721c24;
  13.             text-align: center;
  14.             padding: 50px;
  15.         }
  16.         .p1 {
  17.             font-weight: bold;           
  18.         }
  19.         .error-container {
  20.             border: 1px solid #f5c6cb;
  21.             background-color: #f8d7da;
  22.             padding: 20px;
  23.             border-radius: 5px;
  24.             display: inline-block;
  25.             width: 300px;
  26.             margin-left: -25px;
  27.             margin-top: -50px
  28.             
  29.         }
  30.         h1 {
  31.             margin: 0;
  32.         }
  33.         p {
  34.             margin: 10px 0;
  35.         }
  36.         select {
  37.             margin: 10px 0;
  38.             padding: 10px;
  39.             width: 100%;
  40.         }
  41.         button {
  42.             padding: 10px 20px;
  43.             margin: 5px;
  44.             border: none;
  45.             border-radius: 5px;
  46.             cursor: pointer;
  47.         }
  48.         .cancel {
  49.             background-color: #f5c6cb;
  50.             color: #721c24;
  51.         }
  52.         .proceed {
  53.             background-color: #28a745;
  54.             color: white;
  55.         }
  56.     </style>
  57.   </head>
  58.   <body>
  59.     <div class="error-container">
  60.     <h1>Delivery Error</h1>
  61.         <p>We're sorry, but there was an issue with your delivery.</p>
  62.         <p>Please select the correct warehouse:</p>
  63.       <input type="text" class="text" id="result">
  64.     <br />
  65.       <div class="buttons">
  66.       <p class="p1">Available Warehouses</p>
  67.         <button class="number" onclick="appendToResult('USA')">USA</button>
  68.         <button class="number" onclick="appendToResult('UAE')">UAE</button>
  69.         <button class="number" onclick="appendToResult('Pakistan')">Pakistan</button>
  70.         <button class="number" onclick="appendToResult('Russia')">Russia</button>
  71.         
  72.       </div>
  73.       <button class="proceed" id="flyout">Proceed</button>
  74.     </div>
  75.     </div>
  76.     <script src="https://live.zwidgets.com/js-sdk/1.2/ZohoEmbededAppSDK.min.js"></script>
  77.     <script>

  79. var result = document.getElementById("result");
  80. var sendData = document.getElementById("flyout");

  82. var FLYOUT_ID = null;

  84. function transportData() {
  85.   ZDK.Client.sendResponse(FLYOUT_ID, {
  86.     incrementedNumber: result.value,
  87.   });
  88. }

  90. sendData.addEventListener("click", transportData);

  92. function appendToResult(value) {
  93.   result.value += value;
  94. }

  96. function clearResult() {
  97.   result.value = "";
  98. }

  100. function calculateResult() {
  101.   try {
  102.     result.value = eval(result.value);
  103.     console.log("result.value", eval(result.value));
  104.   } catch (error) {
  105.     //result.value = "Error";
  106.   }
  107. }

  109. /*
  110.  * Subscribe to the EmbeddedApp onPageLoad event before initializing
  111.  */

  113. ZOHO.embeddedApp.on("PageLoad", function (data) {
  114.   console.log(data);
  115.   //Custom Bussiness logic goes here
  116. });

  118. ZOHO.embeddedApp.on("Notify", function (data) {
  119.   console.log("Client Script flyout notification", data);
  120.   ZDK.Client.sendResponse(data.id, {
  121.     choice: "mail",
  122.     value: "example@zoho.com",
  123.   });
  124. });

  126. ZOHO.embeddedApp.on("NotifyAndWait", function (data) {
  127.   console.log("Client Script synchronous flyout notification", data);
  128.   console.log(data.data);

  130.   result.value = data.data.data;

  132.   FLYOUT_ID = data.id;

  134. });

  136. /*
  137.  * initializing the widget.
  138.  */
  139. ZOHO.embeddedApp.init();
  140.   </script>
  141.   </body>
  142. </html>
  1. HTML Script Explanation
-> Under Style tag, we have simple css line of codes to show a required pop-up with customized colors and format.

-> Under Body tag, we have added all headers, paragraph and buttons by assigning class. We have also passed 'id' tag to "Result" text field & "Proceed" button to use it in Flyout code within HTML script.

-> Under Script tag, we have a code which communicate back to Client Script via Flyout. 

      -> Firstly, fetching both result text & proceed button. Then, sending result data back by using addEventListener("click", transportData). Here, 'transportData' is a function which sends response to Flyout.
  1. Creating Widget in Zoho CRM
Now, user can create a Widget in CRM as Button type to be invoked via Client Script.

Navigate to Setup (⚙️) in Zoho CRM >> Developer Hub >> Widgets.

Create New Widget and choose the options as per below screenshot:


Notes
Notes:
-> Ensure to select Type as - Button
-> Select Hosting as Zoho and Get the complete widget file as Zip to upload.
-> Pass the Index Page with html file name. For example: When you create a first project, html file name is "widget.html", user can pass index as "/widget.html".

Step2 - Creation of Client Script

Now, let us create a Client Script on Edit Page of a 'Sales Order' Module for a Page Event based onSave trigger. As an example, whenever the user clicks on "Save" button in Edit Page, script will be triggered and throw a pop-up to end user based on validation.

Follow the steps below to configure the Client Script for this use case:

1) Provide the basic information, like Name and Description based on script purpose.

2) In the Category Details section, please choose the following:

* Category as Module.
* Page as Edit.
* Module as Sales Order.
* Choose the required Layout.

3) In the Event Details section, please choose the following:

* Type as a Page Event.
* Event as onSave

The Code

  1. console.clear();
  2. var field_obj = ZDK.Page.getField('Warehouse');
  3. var warehouse = field_obj.getValue();

  5. if (warehouse == "India") {
  6.     console.log("entered");
  7.     var WIDGET_API_NAME = "Popup1";
  8.     ZDK.Client.createFlyout('myFlyout', { header: "Delivery Error Alert", animation_type: 1, close_icon: false, height: '385px', width: '240px', left: 'center' });
  9.     
  10.     ZDK.Client.getFlyout('myFlyout').open({ api_name: WIDGET_API_NAME, type: 'widget' });
  11.     console.log("Flyoutcreated");

  13.     var response = ZDK.Client.getFlyout('myFlyout').notify({ data: ZDK.Page.getField('Warehouse').getValue() }, { wait: true });

  15.     ZDK.Client.getFlyout('myFlyout').close();
  16.     console.log('??? ', response);

  18.     console.log(response.incrementedNumber)
  19.     ZDK.Page.getField('Warehouse').setValue(response.incrementedNumber);

  21.     ZDK.Client.showMessage('Warehouse has been sucessfully updated', { type: 'info' });
  22. }

  1. Client Script Code Explanation

-> Initially, we will fetch the warehouse field value and store it in variable (i.e., warehouse).

-> As a basic validation, whenever user selects "India" as warehouse and click on Save button, validation error pop-up will be thrown to select the different warehouse. Hence, if user selects "India", we are performing below actions:

                  Flyout method

                        -> Flyouts are floating User Interface that can be controlled using Client Script. User could invoke a widget as popup or component in any place on page.
                        -> Flyouts will be useful to communicate between Widget and Client Script. 
                        -> It can wait for the input from widget and collect it by populating to respective fields in CRM.

-> As explained above, we will create a flyout (i.e. component in web page) and place it accordingly by adjusting height, widget, etc.
-> Then, we will pass the Widget to the created Flyout component.
-> Here, Flyout will wait and widget code (explained above) will be executed then, Flyout will get the data back from widget result text (where selected warehouse will be stored).
-> Then, Flyout will be closed and populate the data into CRM field.
-> It will also show a message pop-up at last by stating "Warehouse has been successfully updated", if the CRM field data was updated via widget.

Working Demo - Screencast


Idea
-> User can configure the same setup for other pages (i.e., List View/Create/Detail, etc.) as well.
-> Also, user can make an advanced customization using HTML & CSS in the widget and throw it to end user.
AlertTo ensure a smooth implementation, we recommend configuring and testing the setup in the sandbox environment before deploying it to production.

TIPS - Avoid Common Errors

-> Ensure to use the correct API Names for both Module & Fields in the script.

-> To ensure you get the intended output, we would suggest you to add logs() || console.log() to each variable to check the output for seamless functionality. i.e., you could view the output in the "Messages" tab within Client Script IDE for each logs() print. To view console logs, you could follow - "Right Click on browser page >> Inspect >> Console".
​
-> In case the expected functionality does not work, then try the script by verifying each output & loop along with that, cross-verify the syntax of each ZDK Client/CRM API method in the provided sample help document. 

InfoSample Scripts for each ZDK Client/CRM APIs methods - Help Reference
Notes
Notes: Refer to the following Guide - Article to learn the best practices for Optimizing the code and various ways to deploy Client Script across Zoho CRM.


If you need any further clarifications, please don’t hesitate to contact partner-support@zohocorp.com.

Notes
Additionally, we kindly ask all Europe and UK Partners to reach out to partner-support@eu.zohocorp.com.