How to Create a Custom Widget in Bold BI

This article provides a step-by-step guide on how to create a generic custom widget in Bold BI using the Custom Widget Utility.

Step 1: Create a Custom Widget Template

1. Download the Custom Widget Utility: Obtain the bicw.exe file by downloading the Custom Widget Utility and extracting the zipped folder.
   

   

2. Run the Utility: Locate and click on the bicw.exe file.
   

   

3. Create the Widget Template: Use the following command format to create a new widget template in the specified path:

   create c:\widgets\CustomWidgetName
   

   

   After executing the command, a folder named after the widget will be created in the specified location.
   

   

Step 2: Configure the widgetconfig.json

Below is an example code to configure the widgetconfig.json file for the Syncfusion SunburstChart Chart.

{
 "widgetName": "CustomWidgetName", // replace your custom widget name
 "displayName": "Custom Widget Name", // replace your custom widget display name
 "guid": "b0d5348d-f625-4b78-8db9-c5ed9d38eb45", // custom widget guid should be unique
 "category": "Miscellaneous",
 "version": "4.2.0.0",
 "srcFile": "src/sourcefile.js",
 "dependencies": { "scripts": [ "src/your.min.js" ] }, // replace the name of the min.js file here.
 "description": "Sunburst Chart is useful for visualizing hierarchical data. The center circle represents the root level in the hierarchy, with outer circles representing higher levels of the hierarchy.",
 "dataFields": [
     { 
 		"displayName": "Value", 
 		"valueType": "measure", 
 		"name": "Value", 
 		"min": 1, 
 		"max": 1, 
 		"optional": false 
 	},
     { 
 		"displayName": "Levels", 
 		"valueType": "dimension", 
 		"name": "Levels", 
 		"min": 1, 
 		"max": 4, 
 		"optional": false 
 	}
 ],
 "functionalities": [
 	{
 	"header": "Basic Settings",
 	"properties": [
 	{
       "displayName": "Enable Animation",
       "controlType": "bool",
       "name": "animation",
       "defaultValue": "false"
     } // Add other Basic Settings here as needed
   ]
 },
 	{
 	"header": "Legend Settings",
 	"properties": [
 	{
       "displayName": "Show Legend",
       "controlType": "bool",
       "name": "showLegend",
       "defaultValue": "false"
     } // Add other Legend Settings here as needed
   ]
 },
 {
 	"header": "Color Settings",
 	"properties": [
 	{
       "displayName": "Point 1 color",
       "controlType": "color",
       "name": "p1Color",
       "defaultValue": "#8d9aa2"
     } // Add other color points here as needed
   ]
 }
 ], 
 "filterSettings": { "masterFilter": { "visible": true, "defaultValue": false }, "ignoreMasterFilter": { "visible": true, "defaultValue": false } },
} 

Step 3: Replace the Icon Image

Replace the appropriate custom widget icon image located in the icon folder within the root directory of the custom widgets.

Step 4: Configuring the Widget Source File

The source file is essential for embedding the user-defined widget within the dashboard. Use the following API structure in the source file:

bbicustom.dashboard.registerWidget({
    guid: `Specifies the GUID used in widgetconfig.json`, 
    widgetName: `Specifies the name of the widget used in widgetconfig.json`,
    init: function () {
        /* init method will be called when the widget is initialized. */
    },
    update: function (option) {
        /* update method will be called when any update needs to be performed in the widget. */
        if (option.type == "resize") {
            /* update type will be 'resize' if the widget is being resized. */
        } else if (option.type == "refresh") {
            /* update type will be 'refresh' when the data is refreshed. */
        }
    }
});

Init Method

The init method is called when the widget is initialized.

Update Method

The update method is triggered for operations such as data updates and resizing. It handles two types of updates:

• Resize
• Refresh

Step 5: Pack the Widget

Use the following command to convert the widget to a *.bicw file:

pack C:\widgets\CustomWidgetName

• In this command, C:\widgets\CustomWidgetName denotes the root path of the widget to be packed.
• The CustomWidgetName.bicw file will be created in the output folder.
  

Step 6: Publish Custom Widget

1. Access Dashboard Settings: Click on the Settings icon in the Bold BI Server.
   

   

2. Navigate to Widgets Tab: Click on the Widgets tab.
   

   

3. Add New Widget: Click on the “Add New Widget” button.
   

   

4. Select Custom Widget File: Browse to the location of the custom widget file and select the custom widget (*.bicw) to be added to the designer.
   

   

5. Upload the Widget: Ensure the custom widget file is in the bicw format. Once uploaded, it will appear under the Custom Widgets category.
   

   
   
   
   

6. View in Designer: The custom widget will now be available in the Bold BI Designer.
   

   

Reference

• How to create and publish Bold Report Viewer as a Custom widget in Bold BI
• How to Add a Query Builder custom widget in Bold BI