Using widgets to extend the Bigin UI
Hello Biginners,
In our previous forum post, we explored schedules and workflow functions and learned how to automate real-time and time-based actions inside a topping. In this post we'll look at how to embed custom UI components inside Bigin using widgets.
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. Widgets provide the flexibility to customize and expand Bigin's capabilities, which makes them the right tool whenever a topping needs to bring in a custom interface.
To understand how widgets work in practice, let's walk through a common requirement in customer onboarding.
The challenge: Tracking onboarding steps consistently across every contact
When a small business takes on a new customer, the onboarding process usually involves the same set of steps every time: scheduling an intro call, collecting a project brief, provisioning access, and so on. Most teams track these steps in spreadsheets or external tools, which quickly drift out of sync with Bigin.
Two needs come up here:
- The admin needs a single place to define and manage the master list of onboarding steps for the organization.
- The sales rep needs that checklist surfaced directly on each contact's detail page so they can track which steps are complete for that contact.
We can solve both of these needs with widgets.
Overview of the topping
We'll build a Client Onboarding Checklist topping that uses two widgets working together:
- A Settings widget that lets the admin define and manage the master list of onboarding checklist items for the organization.
- A Related List widget that appears on every contact's detail page, displays the configured checklist, and lets the sales rep track progress for that contact with a live progress bar.
Prerequisites
Before building the widgets, make sure the development environment is ready. The toolchain—Node.js, npm, the Zoho Extension Toolkit (ZET), and the Bigin JS SDK—and the exact install and verification commands are covered detail in the Bigin developer documentation on creating widgets.
You'll also need a topping created in the Bigin Developer Center, since a widget is embedded within a topping. For detailed instructions on creating a topping, refer to this post for a tutorial.
With the environment ready, we can create the widget project.
Creating the widget project
In your working directory, run:
zet init
This command prompts you to select the Zoho service you want to create a widget for, followed by the project name. Choose Bigin and enter the project name. The project will be initialized with the npm dependencies.
Zoho Service: Bigin
Project Name: Onboarding_Checklist
This recording shows the full zet init flow: selecting Bigin as the service, entering the project name Onboarding_Checklist, and initializing the project with npm dependencies.
Once the project is initialized, move into the project directory.
Inside the app folder, we'll be adding the widget files (HTML, CSS, and JavaScript).
Organizing the widget files
Since this topping has two widgets, we'll keep both of them directly inside the app folder:
settings.html: The Settings widget, which is a single self-contained file with inline styles and script
widget.html, style.css, and custom.js: The Related List widget, split across three files for better readability
Each widget's HTML file must include the Bigin JS SDK script tag inside the <head> so it can communicate with Bigin. The SDK script tag and its setup are covered in the official Bigin developer documentation on creating widgets.
(The zip file of the widget folder is added at the end of this post.)
With the file structure in place, let's build the first widget.
Building the Settings widget
The Settings widget is the admin's control panel for the topping. It opens during installation and is also accessible afterwards from the topping's settings page. This is where the admin defines and manages the master list of onboarding checklist items for the organization.
It renders an editable list of checklist items, lets the admin add or remove items, and saves the configured list so that the Related List widget can pick it up later.
Overview of the Settings widget logic
- Initializing the widget: When the widget loads, the Bigin JS SDK fires the PageLoad event. We use this event to load any previously saved checklist into the UI, and then call ZOHO.embeddedApp.init() to confirm the widget is ready.
- Adding and removing items: The addChecklistItem function renders an editable row for each item. Each row has a Remove button so the admin can drop items that are no longer needed.
With the Settings widget in place, we can build the Related List widget.
Building the Related List widget
The Related List widget is the user-facing side of the topping. It appears as a section on every contact's detail page, displays the master checklist defined in the Settings widget, and lets the sales rep track progress on that specific contact.
The widget reads the contact's record context using the Bigin JS SDK, so the same widget code automatically adapts to whichever contact is being viewed. It also shows a live progress bar and a completion banner once every item is checked off.
This widget is built from three files inside the app folder of the widget project: widget.html, style.css, and custom.js.
Overview of the Related List widget logic
- Reading the contact context: The Bigin JS SDK passes the current record's ID through the PageLoad event. We store this as contactId, which is what lets us track checklist progress per contact.
- Toggling items and tracking progress: When a checkbox is toggled, toggleItem flips that item's state and re-renders the checklist. The updateProgress function updates the progress bar, and shows the Onboarding Complete! banner once every item is done.
Once both widgets are built, the next step is to test and package them.
Testing the widgets locally
ZET provides zet validate to check the project's resource files, zet run to start a local server for previewing the widgets, and zet pack to package the project into a zip file inside the dist folder. Detailed usage of each command is covered in the official Bigin developer documentation.
After testing the widgets locally and packing them into a zipped file, the next step is to host the widgets and embed them in Bigin.
Embedding the widgets in the topping
Once the zip file has been generated by zet pack, the widgets need to be hosted before they can be embedded inside the topping. In Bigin, widgets are hosted through a connected app, which acts as the wrapper that holds the widget files and makes them available to the topping.
To create one, navigate to Connected Apps in the left panel of the Bigin Developer Console and click Create Connected App. Give the connected app a name (for example, Client Onboarding Widget), choose Internal Hosting as the hosting type, and upload the zip file generated from the dist folder by zet pack in the Upload Production Zip field. Save the connected app. This makes the widget files available to be embedded inside the topping.
With the connected app saved, each widget needs to be embedded in the specific section of the topping where Bigin should render it. Since this topping has two widgets, this is done in two places.
The Settings widget is embedded in the Settings Widget section of the Bigin Developer Console. Navigate to it from the left panel, name the Settings widget Client Onboarding Settings Widget, and select settings.html as the entry file. This is what makes the Settings widget open during installation of the topping.
The Related List widget is embedded by navigating to Components, then Related Details, then Add Widgets in the left panel of the Bigin Developer Console. Provide a name for the related list (for example, Client Onboarding Checklist), choose the Contacts module so the widget appears on each contact's detail page, name the widget Onboarding Checklist, and select widget.html as the entry file.
Once both widgets are embedded, publish the topping from the Developer Console. The topping is now ready to be installed and used inside Bigin.
What happens when the topping is installed
When the admin installs the Client Onboarding Checklist topping, the Settings widget opens, prompting them to configure the onboarding checklist items. The admin can add new items, remove the ones that no longer apply, and save the final list. This becomes the master checklist for the organization.
Once the Settings widget is configured, the sales rep can open any contact in Bigin. On the contact's detail page, inside the Contacts module, the Client Onboarding Checklist related list section loads with the same items the admin configured. The rep can check off each item as the onboarding step is completed.
As the rep ticks off each step, the progress bar advances and the item is struck through. Once every item is checked, the Onboarding Complete! banner appears at the top of the widget.
In this post, we explored how the Settings widget and the Related List widget work together to extend Bigin's UI and deliver a consistent, admin-managed experience across every contact. The Settings widget defines the configuration once at the org level, and the Related List widget surfaces that configuration contextually on each record.
Stay tuned for more posts, where we'll dive deeper into additional features and best practices for developing powerful toppings in Bigin.