ECharts Custom Widget Tutorial

ECharts Custom Widget Tutorial

In this tutorial, we will guide you through the process of creating a Ring Gauge custom widget, which enables you to display multiple variables simultaneously in a interesting format.

To achieve this, we will leverage the ECharts library, a robust and highly customizable charting library that simplifies the development of interactive and visually appealing data visualizations. By utilizing ECharts, we can significantly speed up the development process and ensure that our custom widget is both efficient and aesthetically pleasing.



This tutorial is structured into three comprehensive sections to facilitate a smooth learning experience:

1. Installing Dependencies and Setting Up Your Development Environment: We will walk you through the initial setup, including the installation of necessary dependencies and configuring your development environment to ensure you have everything you need to get started.

2. Key Components of Your Custom Widget: `widget.tsx` and `widget.view.tsx`: We'll explore the two primary files that form the core of your custom widget: widget.tsx and widget.view.tsx. These files are crucial in determining the functionality and appearance of your widget.

3. Deploying Your Custom Widget Code to TagoIO Files: Finally, we will cover the deployment process, showing you how to upload your custom widget code to TagoIO and make it available for use within your dashboards.


Prerequisites:

Before you begin, ensure you have the following:


  1. A TagoIO account: You need an active TagoIO account to access the dashboard and deploy custom widgets. Click here to Create your account.
  2. Basic knowledge of TagoIO: Familiarize yourself with TagoIO's platform and understand the basics of creating and managing dashboards. Click here to Access our Learning Center and check out our training modules.
  3. Node.js and npm: Before you can create custom widgets, ensure you have Node.js and npm (Node Package Manager) installed on your machine.
  4. React: Basic knowledge of React is necessary as you will be using it to create custom widgets.
Our goal with this tutorial is to provide you with a solid foundation that you can build upon. The Ring Gauge custom widget example is designed to be a starting point—a kickstarter—that you can download, modify, and adapt to meet your specific requirements. We encourage you to experiment and enhance the widget to suit your unique use cases.

So let's get started!

Installing Dependencies and Setting Up your Development Environment

In this section, we will guide you through the essential steps to set up your development environment for creating custom widgets with TagoIO. By the end of this section, you will have downloaded the project repository, installed necessary dependencies, and configured your environment to view and develop your custom widget effectively.

Download the Project Repository

First, you need to download the project repository from GitHub. This repository contains the template and initial setup for creating custom widgets using react, html, and css.
  1. Custom Widget Repository 
To download the repository, you can either clone it using Git or download it as a ZIP file and extract it to your desired location.

Install Dependencies

Next, we need to install all the dependencies used in the project. These dependencies are essential for the project to function correctly.
Using NPM, run the following command to install all dependencies:
  1. npm install



Libraries Used:
  1. TagoIO Custom-widget: 
    1. This library provides the necessary tools and functions to create custom widgets for TagoIO dashboards. It simplifies the process of integrating with TagoIO's API and displaying data.

  2. Luxon: 
    1. Luxon is a library for working with dates and times in JavaScript. It provides a modern and easy-to-use API for handling date and time operations. The @types/luxon package provides TypeScript type definitions for Luxon.

  3. Echarts:
    1. Echarts is a powerful and flexible charting library for creating interactive charts. It supports a wide range of chart types and is highly customizable, making it ideal for creating visually appealing data visualizations.

Port Forward to Allow TagoIO to Access your Code

To view your custom widget in the TagoIO dashboard during development, you need to set up port forwarding. This allows TagoIO to access your local development server.
Visual Studio Code provides a port forwarding feature that we can utilize for this purpose. 



  1. Launch Visual Studio Code and open your project folder.
  2. Click on "Terminal" in the upper left corner.
    1. Select "New Terminal".
  3. In the terminal, type npm start and press Enter.
    1. This command will start the local server hosting your custom widget.
    2. Copy Port Number: Look for the server running message in the terminal.
  4. Forward Port:
    1. Above the terminal window, click on "Ports".
    2. Click on "Forward Port".
    3. Enter the port number you noted in step 3.
  5. Change Port Visibility:
    1. Right-click on the newly created port forward.
    2. Select "Change Visibility" and set it to "Public".
  6. Copy the URL provided, as you will need to add it to the custom widget in your TagoIO dashboard.
  7. Access the Copied URL to allow external access to access the local server.
    1. This will allow your TagoIO dashboard to communicate with your project folder.

Create the Custom Widget in your Dashboard

Once you have set up port forwarding, you can create the custom widget so that you can see what you're developing.
  1. Go to your TagoIO admin panel.
  2. Select a dashboard where you would like to add the custom widget.
  3. Create a new widget and in the URL & Parameters section, add your local development server URL.
  4. Click on "Configure Parameters" and add show_time as enabled. When this is enabled, it will display the last time the variable was received.
By following these steps, you will have your custom widget up and running in your TagoIO dashboard.

Key Components of Your Custom Widget: `widget.tsx` and `widget.view.tsx`


Now we can dive into what truly matters: the code! In this custom widget tutorial, our focus will be on two key files: `widget.tsx` and `widget.view.tsx`. While these aren't the only important files in our source folder, they will be our primary focus since they decide the key parts regarding how the custom widget works and what it does. 

`widget.view.tsx`: Telling your widget what to do

The `widget.view.tsx` file handles two main tasks. First, it manages the state of the custom widget and keeps this internal state in sync with TagoIO, both in the Admin and RUN environments. Second, it provides functions, known as callbacks, that the presentational component can use from the Custom Widget Library. The callbacks are used in order to tell the custom widget when to start working, display data, send data and more. 


The file contains 4 important callbacks: 
  1. window.TagoIO.ready();
    1. Allows the custom widget to start communications with TagoIO.
  1. window.TagoIO.onStart();
    1. Creates the widgets structure and gets it ready to receive data.
  1. window.TagoIO.onRealtime();
    1. Receives the device data to display on the widget.
  1. window.TagoIO.onSyncUserInformation();
    1. Receives the user data to format the device data accordingly.
  1. Finally, at the end of the useEffect function, it returns all the properties to the widget itself located within the `widget.tsx`

`widget.tsx`: Converting data so that your widget can display it

The `widget.tsx` file is in charge of showing the custom widget's interface. It uses the widget's configuration settings and data from variables and resources. Additionally, it employs handlers provided by the view component to interact with both the Custom Widget and TagoIO's APIs.

  1. Define Widget Properties
    1. Here you need define the properties that your widget will use. These properties include:
      1. data: The data fetched from the API.
      2. showTime: A parameter to determine if the time should be displayed.
      3. userSettings: User-specific settings such as date and time format.

  2. Create the Widget Component
    1. The main component of the widget is responsible for handling the rendering and logic. Here’s an overview of the tasks performed inside the component:
      1. Extract Data: Extract data, showTime, and userSettings from the properties.
      2. Reference for Chart: Use useRef to create a reference for the chart container.
      3. Memoize Data: Use useMemo to filter and memoize the data to be used in the chart.
      4. Effect Hook: Use useEffect to manage the chart's rendering logic. This includes:
        1. Formatting the data according to user settings.
        2. Initializing the chart and setting its options.
        3. Handling window resize events to adjust the chart size.

  3. Handle Loading State
    1. If the data is not available, display a "loading" message to inform the user. This will display a "loading" string on the upper left corner of the widget.

  4. Render the Widget
    1. Finally, render the widget with the gauge chart, ensuring it occupies the full available space.

Make sure to check out the ECharts documentation better learn how to modify this widget it to your advantage. 
Make sure to take a look at the snippets showing examples on how to send data via a custom widget, its available in commented form within the `widget.view.tsx`.

Deploying your Custom Widget Code to TagoIO Files

In this section, we will guide you through the steps of deploying your custom widget to TagoIO. Deployment is a key stage in your development process, ensuring that your finalized widget is accessible and functional within the TagoIO platform. By the end of this section, you will have created a dedicated folder for your custom widget, obtained your Profile ID, and modified the necessary configuration files. You will then run the build command to generate the built code, which will be placed in the designated folder, making your widget ready for deployment on TagoIO.

Creating the Custom Widget Folder and getting your Profile ID

Before deploying your custom widget on TagoIO, you need to set up a dedicated folder in your TagoIO Files and retrieve your profile ID. Follow these steps to ensure everything is in place:

Create a Folder in TagoIO Files
  1. Go to your TagoIO Admin panel.
  2. Navigate to the TagoIO Files module.
  3. Create a new folder and save it for future reference..
Retrieve Your Profile ID
  1. Click on your account image in the top right corner.
  2. Select "My Account."
  3. Click on the profile you are using.
  4. Click on "More" to find your profile ID and save it for future reference.

Modify the package.json file for your use case

In this section, we will be returning to the project folder to make essential modifications to the package.json file. These changes are crucial for ensuring that your custom widget functions correctly once deployed. To proceed, you will need access to the root folder where your custom widget is stored, as well as the profile ID obtained from the previous step.



Modifying the package.json file
  1. Go to your project folder and open the package.json file.
  2. Locate the build line.
  3. Replace the profile ID with your own profile ID.
  4. Replace the folder name with your folder name.

Building and Deploying your custom widget code

Now we can finally build the code. The built code is what you will deploy to TagoIO using the files module. To build the code, simply type "npm run build" in your terminal.



Finally, you can copy the built code and paste it into the folder you created earlier. To do this, open the `dist` folder and copy the `.js`, `.css`, and `.html` files, ignoring any files that end with `.map`. Then, paste the copied files into the folder you created.



All that remains is to paste the new URL into the custom widget, just as you did in the section "Create the Custom Widget" in your Dashboard. With this step, you have successfully deployed the custom widget and no longer need to keep your local development server port forwarded. 




    • Related Articles

    • Custom Widget Parameters

      Parameters allow you to send a list of keys and values to your custom widget. One use of these parameters is to change the way your code behaves. You can have two widgets pointing to the same link, but exhibiting different behaviors. Each parameter ...

    • Custom Widget

      Custom Widgets are very versatile, allowing you to build whatever you need to suit your application’s needs. The widget can be built with plain web technologies like HTML, CSS, and JavaScript, but keep in mind that at least some JavaScript is needed ...

    • Widget Cache system

      The caching system optimizes the performance of your dashboards by storing widget data and any computations performed using Data Analytics. This allows future requests to be served faster by utilizing results from earlier requests, thereby speeding ...

    • Keypad Widget

      Keypad allows the user to submit a pin code along with an optional action string. This widget is ideal to represent an alarm or to request a PIN code to unlock a resource. Creating your own To add it to your dashboard, choose the Keypad widget from ...

    • Image Widget

      The Image widget provides the ability to present custom images in your dashboard. You can use it to present the logo of your company or customer, or anything else that helps the user to better visualize your application. This widget works for both ...