How to add and use a HTML Form as custom widget in Bold BI?

The Form widget in Bold BI allows users to create interactive forms within their dashboards. This guide will walk you through the process of adding and configuring a Form widget in Bold BI.

Download, Modify and Publish the Form Widget

Step 1: Download the custom widget: Obtain the Form Custom Widget file from the attachment provided below.

Step 2: Modify the FORM: Refer to the below section Modify the Form Template to modify the form with your required content along with interaction changes during submission.

Step 3: Publish the custom widget: Use the help link to guide you through the process of publishing the custom widget to your Bold BI application.

Configuring the Form Widget

Step 4: Add Custom Attributes

Custom attributes can be added to the Bold BI to do the interaction from your form to API. We recommend you use Site-level attribute so that it will be common to all the users of that tenant site in case the URL is dynamic for user then you can use user-level or their group-level attributes in the tenant site with same name. To know more about custom attribute precedence, refer the above-mentioned documentation link. Below is an example of how to add a custom attribute:

Adding the Form Widget to Your Dashboard

Step 5: Drag and Drop the Widget

To begin, locate the Form widget within the Bold BI interface. Click and hold the widget, then drag it onto the designer canvas. Once the widget is in place, you can proceed to bind data to it.

Step 6: Configure Form widget

In the form widget’s “Assign Data” section, we have designated fields to collect values from the text input fields. The form template includes several input fields; however, if a user enters values, those data will not be retained by Bold BI. Instead, you can use the separate “Assign Data” field section to drag and drop data source columns to populate the fields. Please see the image below for reference.

As shown in the image below, the “First Name” field section represents the input text for the first name in the Form widget. The same applies for the “Last Name” field.

Note: If you modify the custom widget form template, please ensure that you also update the dataFields section in the widgetconfig.json. Please refer to the following documentation for configuring widget configuration file

Step 7: Utilize Custom Attributes

With the custom attribute created, you can now use it within your Form widget. Incorporate the custom attribute name and authentication information as shown in the example below:

Note: It supports two authentication types: Basic Authentication and Bearer Token Authentication. If you are using Basic Authentication, please enter your Username/API Key and Password/Secret Key. For Bearer Token Authentication, select the Bearer Token option.

Submitting Data

Step 8: Post Data to API

Fill the form and submit it by clicking the ‘Submit’ button. This action will post the data to your respective API endpoint.

Modify the Form Template

Follow the below steps to modify the form template of the custom widget:

1. Unpack the Widget: Unpack i.e. unzip the above downloaded Form custom widget (Form.bicw) by referring this link.

2. Modify Form: Once unzipped open the sourcefile.js file which is present in the src folder. init() method contains the form details so incorporate the necessary changes in that method and save the file.

   1. Modifying template of the Form Widget: The variable tempelement contains the HTML code which is the form template. You can create your own form by using HTML code.
   2. Adjusting form text size: Provide required font size for the form content in the variable textSize. You can modify font size based on your requirement.
      
      

3. Publish the Widget: Generate the custom widget with the changes by referring Converting the widget to a *.bicw file and then publish it by referring Publish Custom Widget

Methods and Use Cases in the Form widget Source File

The following table explains the use case of some main methods available in sourcefile.js.

Flexible Update Options: Using POST or PUT in Form Widget

We can use both POST and PUT actions with the Form Widget based on your needs:

• POST: POST is used to send data to a server to create/update a resource. Please refer to the below sample code block.

$.ajax({ 
    url: '/api/update', 
    type: 'POST', 
    data: { id, field1, field2 }, 
    success: function(response) { ... },
    error: function(xhr, status, error) { ... }
  }); 

• PUT: PUT which is idempotent request, used to send data to a server to create/update a resource. Please refer to the below sample code block.

$.ajax({
   url: '/api/resource/' + id,
   type: 'PUT',
   data: JSON.stringify({ field1, field2 }),
   contentType: 'application/json',
   success: function(response) { ... },
   error: function(xhr, status, error) { ... }
}); 

Handling Errors

If there is an error occurred in your API request, then its error response will be shown as displayed below. This helps in identifying and resolving any issues with your API request. Note that both the success and error message is showcased what is receiving in your API response.

Use Cases for Form Widget

The Form Widget in Bold BI allows you to invoke your REST API to add or update records in your database. Below is a detailed explanation of its functionality, including an example of how to create an employee record.

We have created a Form Widget named SampleFormWidget in the attachment to illustrate the use case of adding a new employee record to the database.

Adding a New Employee Record

1. Drag and Drop the Form Widget:
   Once you add the Form Widget to your dashboard, you can either enter data manually or configure it through the “Assign Data” section.
2. Fill the Form:
   Please enter employee details manually, keep in mind that these records won’t be saved when the page is reloaded. You must re-enter the details each time.
3. Field Input:
   Enter the values for First Name and Last Name in their respective input fields.
4. Add Button:
   Click the Add button. This action will trigger a POST request to your REST API, sending the entered data to your database based on the API implementation.

Updating an Employee Record

To update an existing employee record, you can develop a custom widget that invokes the PUT API method.

1. Search for Employee ID:
   Enter the Employee ID to retrieve the previous record. You can implement the code block to perform the Search action to find the relevant data for the given Employee ID.
2. Make Changes:
   Modify any details as necessary.
3. Update Button:
   Click the Update button to trigger the update action, which will send the modified data back to your REST API.

Conclusion

By following these steps, you can effectively use the Form widget within Bold BI to create interactive and data-driven forms. This feature is particularly useful for gathering user input and integrating it with your dashboards.

Additional References

• How to create a new custom widget?
• Publishing Custom Widgets