Create a Widget

This section provides information about how to set up a connected app, create a widget, and then embed the widget as a button or a related list.

Before you get started

For creating and embedding a widget in Bigin, you'll first need to complete the following steps:

Step1: Install Node.js Package and Zet CLI Tool

From the Downloads page of Node.js ↗, download and install the node.js package based on your system's compatibility.

After you install the node.js package, verify its version using the following commands:

node -v
npm -v

The Zet CLI tool supports Node 6 or above, make sure you have installed the Node 6 or above version.

Now, install the Zet CLI tool using the following command:

npm install -g zoho-extension-toolkit

To make sure the Zet CLI tool is installed successfully, use the following command:

zet -v

The above command displays the version of Zet CLI tool that is installed on your system.

Step 2: Create a Widget Project

On the command line tool, navigate to the location you want to save your widget project.

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

zet init

From the list of Zoho services, select a service for your widget. In this case, you must select Bigin.

When the Project Name prompts, type the name of the project.

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

A typical project directory of a widget looks like the following:

To enhance the features of your widget, you can now add customized project files to the app folder in the project directory.

Step 3: Add Files to the app Folder

To enhance your widget further, you should provide structure, definition, and logic to the widget by adding html, css, and js files.

From the project directory, you can add the files to the app folder.

In the app folder, first create html, css, and js folders, and then add the following files to the appropriate folders:

After adding files to the app folder, the directory structure of the app folder looks like the following:

Step 4: Package Project Directory

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

zet validate

Once the project resource files pass all the validation rules, you can now start the local server.

To start a local server with the current directory as context, use the following command:

zet run

To view the output, from the command line, copy the URL and paste the copied URL into any of the supported browsers on your system.

For example, after starting the server locally, you can copy https://127.0.0.1:5000. Then, to view the output of the widget, you can paste the copied URL into any of the supported browsers on your system.

You can now package the project directory using the following command:

zet pack

This command creates a new dist folder inside the project directory, and the dist folder contains the zipped version of the project directory that can be used to associate with a connected app.

Adding a Widget

Now you can add a widget to your topping. When you install the topping associated with a widget in Bigin, the features of the widget start appearing on your Bigin account.

To add a widget, you'll need to do the following:

• Setting up a Connected App
• Embedding a widget

Setting up a Connected App

You can set up a Connected App to integrate with Bigin contextually in the form of a widget.

To create a connected app, follow these steps:

1. On the developer console, from the left-pane, go to Connected Apps.

   The Connected Apps page appears.

2. For Connected App Name, type a name for the connected app.
3. For Description, type a description for the connected app.
4. For Choose Hosting, select one of the following:
   • Internal Hosting - You can host your widget app internally using Bigin.

     When you select Internal Hosting, the Connected Apps page refreshes with the following options:

     • For Specify Base URL, the SandBox Server URL is predefined and serves as the base URL.
     • For Upload Production Zip, from the dist folder of your Project Directory, upload the packaged zip file.
   • External Hosting - You can host your widget app externally using third-party web hosting solutions.

     When you select External Hosting, the Connected Apps page refreshes with the following options:

     • For Specify Base URL, provide the SandBox URL and Production URL.
5. Click Save.

Embedding a Widget

After you integrate a widget using a connected app, you can now embed a widget in Bigin as the following:

• Embed a Widget as Custom Button
• Embed a Widget as Related List

Embed a widget as Custom Button

To embed a widget as a custom button, follow these steps:

1. From the Bigin Developer Console, go to Components > Links & Buttons.

   The Customization Links and Buttons page appears.

2. Click the Create New Button button.

   The Create Your Button page appears.

3. On Create Your Button page, do the following:
   1. In which module would you like to create a new button? - From the drop-down, select a module on which you want to create a new button.
   2. What would you like to name the button? - Type the name of the button.
   3. (Optional) Description - Type the description of the button.
   4. Where would you like to place the button? - From the drop-down, select the placement of the button on the Bigin UI. For more information, see Custom Button on Bigin UI.
   5. What action would you like the button to perform? - From the drop-down, select the Invoke a Widget action.
4. When you select the Invoke a Widget action, the page refreshes with the following fields:
   • For SandBox URL, the base URL is pre-defined, you can now append the HTML file location of the widget to base URL.
   • For Production URL, the URL is pre-defined and gets updated automatically based on the appended HTML file location to base URL.
   • For Dimension, select Pixel or Percentage, and then type the appropriate size of the widget.
5. Click Save.

The new custom button is added.

Embed a widget as Related List

To embed a widget as a custom related list, follow these steps:

1. From the Bigin Developer Console, go to Components > Related Details.

   The Add Related List page appears.

2. Click the Add Widgets button.

   The Create Custom Widget page appears.

3. In the Name field, type the name of the related list.
4. From the Module drop-down list, select a module to which you want associate the related list.
5. For SandBox URL, the base URL is pre-defined, you can now append the HTML file location of the widget to base URL.
6. For Production URL, the URL is pre-defined and gets updated automatically based on the appended HTML file location to base URL.
7. For Height, type the appropriate height of the widget in pixels.
8. Click Save.