We provide UCW IoT Cloud where you can run multiple instances of the UCW Platform for needs of your projects. You can start by registering here and get access to the IoT platform with unique functionality. To learn more check out the UCW Platform overview.

Tutorial overview

This is "Dashboard and Gadget" tutorial of a UCW portal add-on. Throughout the tutorial, you will build a dashboard. Since dashboard typically consists of few different types of gadgets, you will also implement them. Moreover, you will also learn how to store data in a data stream and create a scheduled job. You will also need knowledge from Hello World Tutorial. If you have not completed it yet, please see the tutorial pages. See source code.

In the tutorial, you will be working in "start" branch. However, at any moment of the tutorial, you can checkout into "master" branch to see correct solution.

Test downloaded files by building and running the sources. To do so, execute following commands

Unix / Linux based OS

./build.sh
./run-portal.sh

or

Windows

build.bat
run-portal.bat

The application should be up and running on http://localhost:9571. After clicking the link, you should see a login page.

Log into the application using default credentials (User: admin, Password: admin) and admin page should be displayed.

You just setted essential environment for developing your first dashboard and gadget.

As you can see, there is a lot of stuff that has been already created. All of it has been created using UCW Template Module. If you have not familiarised with it yet, please see its documentation for more information.

Step 02: Add dashboard

Adding dashboard to a system is pretty simple. We just need few steps:

Theoretically, the first step would be enough to add a dashboard, but you would have to change the URL manually or add a link somewhere to the application. Step 2 and Step 3 makes the application to redirect you to the dashboard right after the login. It just requires you to set same value to property PORTAL_REDIRECT_DEFAULT as the value of viewId used in Step 1.

That's it. You just added your very first dashboard to the UCW plugin. Unfortunately, this dashboard has almost zero value since it shows no data. So, let's explain how to create a gadget containing some data and how to add it to the dashboard. Before that practice a bit how to add links to the top navigation menu, header actions or header logo (See Hello World Tutorial in case you do not know how to do it and also check Dashboard Plugin Module to see all available attributes of dashboard component). If you do not want to practice you can skip to Step 03.

Following code shows what needs to be done to complete the previous task. All steps need to be done only in nsys-plugin.xml file:

That's it. You only need to extend AbstractGadget, set gadget template and implement the createVelocityParams function which has to return at least empty Map. When the gadget is created, add it to the dashboard. For more options of dashboard-gadget see its documentation. Resulting page should look as follows.

Similarly, as in case of empty dashboard empty gadget has almost zero value. If you have completed the Hello World Tutorial, you should have an idea how to add data to the gadget. You will need to use Apache velocity templates (see documentation) and append the data to Map returned from the createVelocityParams function. You can try it by yourself or follow the next steps which show few versions of gadgets.

Build and run the application. You should see a page similar to the one shown in the picture below

That's it. The gadget shows data which were generated randomly in the DataMeasurementGadget.

Step 05: Add sensor data gadget

In this step, you will create a gadget which displays some dynamically generated data. Before you dive into it, try to create Job which will generate data into a data stream (User data stream name: "ucw-dashboard", project name: "UCWD" and device name: "adafruit-feather-m0-wifi ", also see UCW Job Scheduler tutorial in case you do not know how to do it. Note that you can always checkout to master branch to see the final version). When the job is created you can follow next steps.

Build and run the application. The generator we have created for this tutorial generates data every 10 seconds, and so you should see pages similar to the ones shown in the pictures below

The gadget we have created shows sensor data for temperature and humidity stored in the data stream.

If you reach this part, you just created your first dashboard with multiple gadgets which can use another plugin and plugin functions

You should try to add few more gadgets to different positions, with different labels etc. to improve your understanding of gadget creation. Be aware of the key property you assign them (keys have to be unique). The result can look as follows.

Step 06: Add admin gadget

If you access http://localhost:9571/admin, you should see a lot of links to pages with general information about the application, list of users and so on. This is the place where all plugins should register their administration interfaces. Let's assume we have to be able to set some value for our gadget which will affect its behaviour (for example seed of generator of random data). This variable can set only someone with administrator privileges and so we will need to create admin-gadget.

To create an admin gadget, we need almost the same steps as in case of creating a regular gadget. We will need template and class which extends AbstractGadget. Let's create them (See template and gadget files created for this tutorial) and register the gadget by using the following snippet:

If you checked out into the master branch of the tutorial both links should be working. However, if you stayed in branch start, both link will not be functional because you did not implement necessary controllers. Refer to the code to see how to do so or simply check out to master branch.