Widgets

IN THIS PAGE

  1. Widgets overview
  2. Connected Apps
  3. Widget types
  4. Create a widget
  5. Associate the widget with a connected app

1. Widgets overview 🔗

A widget is a customizable user interface (UI) component that helps improve efficiency and user experience in Bigin. It allows businesses to embed UI components, streamline interactions, and integrate third-party applications for improved workflows. Moreover, widgets provide flexibility and enable businesses to customize and expand Bigin's capabilities.

Widgets can be built using Connection Apps.

2. Connected Apps 🔗

Connected Apps in Bigin allow widgets to securely interact with third-party applications by handling authentication and data exchange. They enable widgets to authenticate users, fetch and send data, and enhance widget functionality.

By using Connected Apps, widgets can function seamlessly with external platforms while maintaining security and access control.

Connected apps are apps that can be built using Zoho Extension Toolkit (ZET). These connected apps only contain client files that run on a Node server.

3. Widget types 🔗

Widgets can be embedded in Custom Buttons, Related Lists, and Custom Actions in Workflows. Additionally, you can create a dedicated Settings page using widgets for your topping. Based on these, widgets are classified into the following types:

Custom Button and Related List Widget

Custom button embedded widget in Bigin trigger actions like invoking a URL, executing a function, opening an external widget, which enhances automation and user interaction.

Related list embedded widget, on the other hand, integrate third-party data contextually within a module's related list, which provides seamless access to external information without leaving the Bigin.

Settings Widget

The Setting widget enables users to manage configuration settings for toppings within Bigin. It provides a centralized interface to define how external data sources interact with the Bigin, which ensures smooth integration and functionality.

Custom Actions Widget

A Custom Action is a configuration that can be used as an Instant Action when configuring a workflow. That means, when you create a workflow rule, the custom actions appear alongside default Instant Actions. You can build workflow widgets to allow users to configure input values and create functions that execute when the custom action is triggered. Inputs from the custom page are passed as JSON objects into the function.

To know more about how the custom action widget works, see the Associate the widget with a connected app section below.

4. Create a widget 🔗

To create and embed a widget in Bigin, you must first complete the following steps:

Step 1: Install Node.js Package and ZET CLI Tool

Visit the Downloads page of Node.js ↗ and download the appropriate Node.js package based on your system's compatibility. Then, install it.

After installing the Node.js package, verify its version by running the following commands:

Copiednode -v

This will display the installed version of Node.js. Additionally, you can check the version of npm (Node Package Manager) with:

Copiednpm -v

The ZET CLI tool supports Node 6 or above, so make sure you have installed Node 6 or a newer version.

To install the ZET CLI tool, run the following command:

Copiednpm install -g zoho-extension-toolkit

To make sure the ZET CLI tool is installed successfully, run the following command:

Copiedzet -v

This will display the installed version of ZET CLI tool on your system.

💡 Tip: Make sure that the ZET CLI tool version is above 1.0.6. However, if the version is less than 1.0.6, update the ZET CLI tool using the following command:

Copiednpm install -i -g zoho-extension-toolkit

Step 2: Create a widget project

On the command line, navigate to the directory where you want to save your widget project.

To initialize your project directory and download all dependencies, use the following command:

Copiedzet init

From the list of Zoho services, select Bigin for your widget. This will set the widget to be integrated with Bigin.

When prompted for the Project Name, type the name you want to give your widget project.

The project directory is created successfully. To view the files of the widget project, navigate to the location where you have saved it.

A typical widget project directory will look like this:

To enhance the features of your widget, you can now add customized project files to the app folder within the project directory. This allows you to include additional code, assets, or configurations that are specific to your widget's functionality and user experience.

Step 3: Add Files to the app Folder

To further enhance your widget, you should create and customize the following files:

  • From the widget project directory, in the app > widget.html file, you can define the primary user interface (UI) of the widget. This file is where you can include stylesheets, custom JavaScript, and the JS SDK source, which allows you to customize the appearance and functionality of the widget.
  • You can create a new custom stylesheet in the app folder and name it style.css, if required. To apply the styles, include this stylesheet in the widget.html file by adding the following line within the <head> section:
Copied<link rel="stylesheet" type="text/css" href="style.css">
  • You can create a new custom JavaScript file for the widget to include any business logic, if required. Name the file as custom.js and include it in the widget.html file by adding the following line before the closing </body> tag:
Copied<script src="custom.js"></script>

  • In addition to these, you need to include the JS SDK's CDN URL in the widget.html file. This allows you to access Bigin's JS SDK bundle, which helps manage the Widget's UI, handle configurations and connections with third-party applications, and provide a seamless flow of data.

    To include the JS SDK, add the following <script> tag in the <head> section of your widget.html file:

Copied<script type="text/javascript" src="https://js.zohocdn.com/biginsdk/dist/js/bigin-widget-sdk.js"></script>

For more information on setting up the JS SDK, see the JS SDK's Basic Setup guide.

After adding necessary files to the app folder, the widget project directory structure will look like this:

After adding the above scripts, here's how the widget.html file typically looks like:

Copied<!DOCTYPE html>
<html>

<head>
    <meta charset="UTF-8">
    <link rel="stylesheet" type="text/css" href="style.css">
    <script type="text/javascript" src="https://js.zohocdn.com/biginsdk/dist/js/bigin-widget-sdk.js"></script>
</head>

<body>
    <h2>This is a sample Widget built using Zoho Extension toolkit.</h2>
    <script src="custom.js"></script>
</body>

</html>

Now, you can define the logic to customize the widget according to your business needs and enhance its functionality.

Step 4: Run the project on a local server

To launch the app locally and test it in the sandbox instance, you must start the local HTTP server. To achieve this, run the following command:

Copiedzet run

This confirms that the project is running on the server successfully. To view the output, copy the URL from the command line and paste it into a supported browser.

For example, after starting the local server, copy https://127.0.0.1:5000 and paste it into your browser to see the widget in action.

💡 Tip: You can run this project on the local server while testing Topping components in the Sandbox.

Step 5: Validate and package project directory

Navigate to the project directory, and to validate the project resource files, run the following command:

Copiedzet validate

You can now package the project directory. To achieve this, run the following command:

Copiedzet pack

This command generates a new dist folder within the project directory, which contains a zipped version of the project.

The next step is to host the widget and embed it into Bigin.

5. Associate the widget with a connected app 🔗

After packaging the widget, you can configure it to associate with a connected app. This enables you to host the widget either internally or externally on a server, which makes it ready to use within Bigin.

To associate the widget with a connected app, access the Bigin Developer Console and navigate to Connected Apps.

For Connected App Name, enter a name and provide a description for the app in the Description field.

For Choose Hosting, select one of the following options and click Save:

  • Internal Hosting: Host your widget app internally using Bigin. Upon selecting this, the Connected Apps page will refresh with these options:
    • Specify Base URL: The Sandbox Server URL is predefined as the base URL.
    • Upload Production Zip: Upload the packaged zip file from the dist folder of your Project Directory.
  • External Hosting: Host your widget app externally using third-party web hosting solutions. Upon selecting this, the Connected Apps page will refresh with these options:
    • Specify Base URL: Provide both the Sandbox URL and Production URL.

    • Modifiable Check box: When selected, the external hosting options become editable.

      💡 Tip: You can run this project on the local server while testing Topping components in the Sandbox.

You can now embed the widget associated with a connected app within Bigin.

For example, you can embed widgets contextually in Bigin using the following types:

Custom components (Custom Button & Related List)

After you configure the connected app to embed the widget using a custom button contextually, you can create a new button by selecting the Invoke a Widget action.

This invokes the widget to trigger an action when you click the custom button.

For more details about how to create a custom button by invoking a widget action, see Create a custom button.

On the other hand, to embed the widget using a custom related list, navigate to Components > Related Details and select Add Widgets.

Then, provide the custom related list widget name, select the module where the related list widget should be displayed, and configure the URLs for widget integration.

This invokes the widget to trigger an action when you view the custom related list section on the details page of a module in Bigin.

Settings Widget

Once you create a widget project to set up an interface for managing Topping settings during the Topping installation and configure it as a connected app, navigate to Settings Widget to embed it with the topping.

This invokes the widget during the Topping installation for managing necessary settings.

Custom Actions Widget

Once you create a widget project to set up a custom action for implementing tailored workflow actions and configure it as a connected app, navigate to Automate > Custom Actions.

To embed the widget and configure the custom action, click Create an Action and do the following:

I. Name your custom action: Provide a name for your custom action.

This allows you to find your custom action alongside the default Instant Actions when configuring a workflow rule.

II. Specify the widget URL: Provide the file location of the widget in the Sandbox URL.

This allows you to embed the widget with your custom action and enable users to configure input values for it in a custom page (Widget UI).

Sample HTML code snippet for a custom action

Copied<!DOCTYPE html>
<html>

<head>
    <meta charset="UTF-8">
    <script type="text/javascript" src="https://js.zohocdn.com/biginsdk/dist/js/bigin-widget-sdk.js"></script>
</head>

<body>
    <h2>Click here to save custom action<h2>
            <button type="button" onclick="saveBtn()">Save</button>
            <script>
                ZOHO.embeddedApp.on("PageLoad", function(data) {
                    console.log(data);
                });
                ZOHO.embeddedApp.init();

                function saveBtn() {
                    let configObject = {
                        config: "Workflow triggered",
                        saved_by_user: "org123456",
                        triggered_time: new Date().toISOString()
                    };

                    ZOHO.BIGIN.ACTION.setConfig(configObject).then(function(data) {
                        console.log("Custom action trigger SUCCESS response :: " + data);
                    }, function(data) {
                        console.log("Custom action trigger Failure response :: " + data);
                    });
                }

            </script>
</body>

</html>

III. Add a Deluge function for your custom function: Create a Deluge function that executes when the custom action is triggered in a workflow. You can pass inputs from the widget's custom page to the function as arguments. 

✍ Note: The arguments passed to the Deluge function are of the Map() data type and these arguments are passed in the ZOHO.BIGIN.ACTION.setConfig JS SDK function in the JSON format.

Sample Deluge code snippet

Copiedsaved_by_user = config.get("saved_by_user");
info "[LOGGER] Custom Action configured function trigger :: SUCCESS";

This means that whenever the workflow associated with this custom action is triggered, the values configured in the Topping are passed to the embedded widget, and then the Deluge function is executed.

Additional References

Custom Buttons

Bigin's Deluge Functions

JS SDK Functions