Objectives

Upon completion of this tutorial, a developer will be able to create and use Client Components, which are reusable collections of widgets.

Tutorial Overview

This tutorial demonstrates how to author Client Components and how to use (or consume) those Components in Clients. A Client Component contains one or more widgets plus optional Data Streams and JavaScript code to provide reusable functionality in other Clients. For example, an author might build a Fahrenheit-to-Celsius conversion Client Component that has input and output display widgets plus a button to perform the conversion. These widgets are combined to form a single Client Component that is used in other Clients that need such conversion functionality.

This tutorial assumes the developer has a working knowledge of the Vantiq IDE. It is recommended that a new developer completes the lessons in the Introductory Tutorial and the Client Builder Tutorial before starting the lessons in this tutorial.

1: Creating a Client Component Project

Use the Projects button, select New Project, which displays the New Project Wizard. Either create a new Namespace (recommended) or add a new project to the current Namespace, select Empty as the Project type, and title the project “ProgressComponent”:

The next two lessons take place inside this Project.

2: Authoring the Progress Bar Component

This lesson creates a Client Component that implements a progress bar which can be reused in Clients. It uses a StaticHtml widget as a holder for the progress bar plus a little JavaScript code used to drive the progress bar. This lesson uses a simple open-source JavaScript progress bar as an example. However, the steps can easily be adapted to use other third-party JavaScript projects to create other Client Components.

a. Download the Progress Bar

Download the ProgressBar.js project. The only file necessary for the Client Component is progressbar.min.js.

b. Create the Client Component

To create a new Client Component, use the Add button, select Client, then use the New Component button to create the ProgressComponent Component:

c. Configure the StaticHtml Widget

Once the ProgressComponent Client Component pane appears, drag and drop a StaticHtml widget from the Add palette onto the Client Builder canvas. The StaticHtml widget is found in the Data Display section and is labeled HTML:

Click on the newly added StaticHtml widget to display its property sheet:

In the Specific properties section, click the Raw checkbox of the HTML property, then click the Click to Edit link. In the Edit Raw HTML dialog, replace the default text with the following:

<div id="progressDiv"></div>

This <div> is the HTML element that will contain the progress bar in the Client Component.

In the Layout properties section, set the following two property values:

• Height: 10
• Width: 150

These properties appropriately size the <div> to display the progress bar.

d. Configure the Client Component Properties

Configuring the Client Component properties is where the power of Client Components is exposed. First, add the downloaded progressbar.min.js file from Step (a) to the component. To do so, click the Edit tab of the Control Dock (on the left side of the Client Component pane), right-click the Component tree entry, then select Edit Component Properties to display the Edit Properties dialog:

• In the Basic tab, click the <None> link under the Custom Assets section. Use the Add an Asset button in the JavaScript Assets section to upload the progressbar.min.js file. Once uploaded, the component uses that code to create and update the actual progress bar.
• In the Configuration tab, use the Add Property button to add two Client Component configuration properties. Client Component configuration properties are those properties that the Consumer Client may use or change when using the Component.
  • progressBar: change to Type JSON and check its Hidden checkbox. progressBar is used internally by the Component to hold a reference to the actual progress bar so is marked Hidden to tell the Consumer Client to not show it as a configuration property.
  • setProgress: change to Type JavaScript Call-in Function.
    • Use the Add JavaScript function parameters button in the Actions section to add a single parameter, value, to be used in the setProgress function.
    • Use the Description button in the Actions section to provide documentation for the use of the setProgress function:
      Use setProgress(value) to update the progress bar's value. Value must be a number between 0 and 1.
    • Use the Click to Edit link to add the JavaScript code for the setProgress function. This code calls the ProgressBar.js API to change the value of the progress bar:

// the component runtime configuration contains a reference to the
// progress bar
configuration.progressBar.animate(value, {
    duration: 100
});

• In the Events tab, click the <None> link under the On Component Start section. In the Edit JavaScript dialog, enter the following code:

    // retrieve a reference to the StaticHtml widget that will contain the progress bar
    var progressWidget = client.getWidget("StaticHtml1");
    if (progressWidget) {
        // retrieve a reference to the div in the widget
        var progressDiv = progressWidget.find("#progressDiv");
        if (progressDiv) {
            // change the ID of the div so it will be unique, in case there are
            // multiple copies of the component
            var pbName = this.name + "_progressDiv";
            progressDiv.attr("id", pbName);

            // retrieve a reference to this component's runtime configuration
            var config = this.configuration;
            // create a progress bar and store its reference in the runtime configuration
            config.progressBar = new ProgressBar.Line("#"+pbName, {
                strokeWidth:5
            });
        }
    }

This code is run when the Client consuming the Component starts up. It remaps the <div> ID so that the Component can be used multiple times then creates the progress bar by calling the ProgressBar.js API new function. Note the call to client.getWidget. The identifier passed as a parameter (in the example this is “StaticHtml1”) will have to match the ID of the StaticHtml widget from Step c above. The ID for any widget is in quotes at the top of the property sheet shown when clicking on that widget in the Client Builder canvas.

Use the Save Changes button in the Client Component pane to save the ProgressComponent Component.

3: Consuming the Progress Bar Component

Now that the Progress Bar Component is complete, Clients may use the Component like any other widget. This lesson creates a new Client which contains the ProgressBar Component and a slider widget to show how to change the value of the progress bar.

a. Create the Client

To create a new Client, use the Add button, select Client, then use the New Client button to create the ProgressDemo Client.

b. Add Client Widgets

Once the ProgressDemo Client pane appears, drag and drop a ProgressComponent widget from the Add palette onto the Client Builder canvas. The ProgressComponent widget is found in the Components section and is labeled ProgressComponent. (Whenever a Client pane is displayed, all Client Components in the current Namespace are displayed in the Components section of the Add palette.)

Next, drag and drop an InputInteger widget from the Add palette onto the Client Builder canvas. The InputInteger widget is found in the Data Input section and is labeled Integer.

c. Configure the Client Widgets

Any non-hidden Component Configuration properties are always found in the Component’s property sheet Specific section when used in a Consumer Client.

There is nothing to configure for the ProgressComponent since there were only two Component Configuration properties defined during the authoring process:

• setProgress: is a read-only property for the Component and is the single JavaScript function that the Consumer Client may call to set the value of the progress bar.
• progressBar: is a hidden property used internally by the ProgressComponent so does not appear in the property sheet.

There are two properties to configure in the InputInteger widget:

• In the Specific section, the Input property should be changed to As Slider.
• In the Event section, click the <None> link for the On Change property. In the Edit JavaScript dialog, enter the following code:

// retrieve a reference to the progress bar component
var pb = client.getWidget("ProgressComponent");
if (pb) {
    // retrieve a reference to the component's runtime configuration
    var config = pb.configuration;
    config.setProgress(this.boundValue/100);
}

The On Change event function is called whenever the value of the slider changes. In this example, a reference to the ProgressComponent’s widget is retrieved then a reference to the setProgress exposed property is retrieved. Using that reference (the config variable), the value of the slider, this.boundValue, is converted from a 0 to 100 based value to a 0 to 1 based value (which is used by the progress bar) and passed to the setProgress function.

Use the Save Changes button in the Client pane to save the ProgressDemo Client.

d. Run the Client

Use the Run button at the top, right of the ProgressDemo Client pane to start running the Client:

When moving the slider widget left and right, the progress bar exactly tracks the value of the slider position. This is a simple example of how calls to the setProgress JavaScript function property of the ProgressComponent are used in other Clients that would like to display the progress of Client operations.

4: Authoring a Configurable Data Stream Component

This lesson creates a Client Component that implements a Gauge widget that can easily adapt to a new source of data to display sensor readings. The lesson also shows how to expose widget properties for use in the Consumer Client so that the Client may configure how the Component is used. To start, create a new project in a new or current Namespace, as explained in Lesson 1 above. Title this project “SensorComponent”.

a. Create the Client Component

To create a new Client Component, use the Add button, select Client, then use the New Component button to create the SensorComponent Component.

b. Create a Data Object to Test the Component

To initially run the Gauge widget, the Component uses a Client Data Object, which is a convenient place to define ‘global variables’. See the Data Objects section of the Client Builder User’s Guide for more details about Data Objects. To create a new Data Object, click the Edit tab of the Control Dock (on the left side of the Client Component pane), open the Data Objects tree entry, then click Client Data Object tree entry. This displays the Editing Data Object dialog:

Use the Add Property button to add a new Data Object. Enter sensor as the Name, select Typed Object as the Data Type, then click the Edit Typed Object icon from the Actions menu. This displays the client.data.sensor dialog. Click the Add Property button to add a single property, which will be used to store the value of a simulated sensor. Enter n as the Name and select Real as the Data Type, then click the OK button. The value n will be referenced in the next section as the sensor value. Use the Save and Exit button to save the Data Object.

c. Create a Data Stream

Data Streams are used to feed data to Data Display widgets, such as the Gauge. See the Data Streams section of the Client Builder User’s Guide for more details about Data Streams. To create a new Data Stream, in the Edit tab of the Control Dock right-click the Data Streams tree entry, then select Add ‘On Client Event’ to display the Edit Data Stream dialog:

This Data Stream uses the Data Object, client.data.sensor, created in the previous section. Enter SampleSensor as the Data Stream Name, select Get schema from client.data.object as the Client Event, and select client.data.sensor as the Data Object. Use the Save button to save the new SampleSensor Data Stream.

d. Add and Configure the Gauge Widget

Drag and drop a Gauge widget from the Add palette onto the Client Builder canvas. The Gauge widget is found in the Data Display section and is labeled Gauge. Click on the newly added Gauge widget to display its property sheet:

• In the Specific properties section, click the Expose Property (small + icon) button to the right of the Minimum property and do the same for all properties through the Title property. The Expose Property button adds Component Configuration properties to the Component, which allow the Consumer Client to change each of those properties. In addition, enter Sensor Readings for the Title property to change the title of the Gauge.
• In the Data properties section, click the Expose Property button for each of the Data Stream and Data Stream Property properties. These two Component Configuration properties allow the Consumer Client to use a different Data Stream, which is the objective of this section. In addition, select SampleSensor for the Data Stream property and n for the Data Stream Property property. These two values use the Data Stream and Data Objects from the previous two sections to display data in the Gauge widget.

Use the Save Changes button in the Client Component pane to save the SensorComponent Client Component.

5: Consuming the Sensor Component

Now that the Sensor Component is complete, Clients may use the Component like any other widget. This lesson creates a new Client which contains the Sensor Component, a button to test the sensor gauge, and substitutes a new Data Stream to drive the gauge.

a. Create the Client

To create a new Client, use the Add button, select Client, then use the New Client button to create the SensorDemo Client.

b. Create a Data Object

Follow the instructions from Lesson 4, section b (Create a Data Object to Test the Component) above. This Data Object is necessary in this Consumer Client to match that found in the SensorComponent so the Gauge widget can be tested.

c. Add Client Widgets

Drag and drop a SensorComponent widget from the Add palette onto the Client Builder canvas. The SensorComponent widget is found in the Components section and is labeled SensorComponent.

Next, drag and drop an Inline Button widget from the Add palette onto the Client Builder canvas. The Inline Button widget is found in the Buttons section and is labeled Inline.

d. Configure the Client Widgets

Click on the SensorComponent widget to configure its properties.

• In the Specific section:
  • Title: enter My Sensor.
  • Data Stream Property: enter n, which is the sensor value configured in the Data Object.

Click on the Inline Button widget to configure its properties.

• In the Specific section:
  • Button Label: enter Sensor Sample.
• In the Event section:
  • On Click: enter the following code:

    // set the Data Object sensor data
    client.data.sensor.n = 50.0;

    // retrieve a reference to the Sensor Component
    var gauge = client.getWidget("SensorComponent");
    if (gauge) {
        // find the Data Stream property of the Component's configuration
        var dataStream = gauge.configuration["Data Stream"];
        if (dataStream) {
            // send a Client Event to the Data Stream to set its value
            client.sendClientEvent(dataStream, client.data.sensor);
        }
    }

Use the Save Changes button in the Client pane to save the SensorDemo Client.

e. Run the Client

Use the Run button at the top, right of the SensorDemo Client pane to start running the Client:

Click the Sensor Sample button. The Sensor Readings gauge will change to display a value of 50, which is the value entered in the Client Data Object code. This is a simple example to test that the SensorComponent works with the default Data Stream.

Use the Stop Running button at the top, right of the SensorDemo Client pane to stop running the Client.

f. Create an MQTT Source

This section creates an MQTT Source which will be used to drive the SensorComponent Component in the SensorDemo Client. Use the Add button, select Source, then use the New Source button to create the New Source pane.

• In the General tab, name the Source Sensor and select MQTT as the Source Type.
• In the Server URI tab, use the Add Server URI button to add a new server URI with the value of tcp://public.vantiq.com:1883. This references a publicly available Vantiq MQTT server which generates sample data.
• In the Topic tab, use the Add Topic button to add a new MQTT topic with a value of com.vantiq.sensor.sample.

Save the new source, then click the Test Data Receipt button in the pane to display realtime data from the MQTT server. A Subscription pane will appear and data of the form shown below will be displayed:

Notice there are three property values returned by the MQTT topic. The last property is vl, which represents a voltage between 0 and 2.5 volts. Notice also data is delivered at one second intervals. Close the Subscription pane after seeing the source data displayed.

g. Create a New Client Data Stream

Now that the Sensor MQTT Source is active, it can be used in the SensorDemo Client. In the Edit tab of the Control Dock, right-click the Data Streams tree entry, then select Add ‘On Source Event’ to display the Edit Data Stream dialog:

Enter SensorSource as the Data Stream Name and select Sensor as the Source. Use the Save button to save the new SensorSource Data Stream.

h. Reconfigure the SensorComponent Widget

The SensorComponent widget can now use the SensorSource source sample voltage values to drive its gauge. Click on the SensorComponent widget to display its property sheet:

In the Specifics section, configure the following Component properties:

• Low Range Zones: 0:1.5
• Medium Range Zones: 1.5:2.0
• High Range Zones: 2.0:3.0
• Maximum: 3.0
• Data Stream: SensorSource
• Data Stream Property: vl, which is the voltage property value seen in the sample MQTT data

Use the Save Changes button in the Client pane to save the SensorDemo Client.

i. Run the Client Using MQTT Data

Use the Run button to start running the Client:

The Sensor Readings gauge changes to display values between 0 and 2.5 volts at one second intervals, as retrieved by the Sensor MQTT source.

So, by creating new Sources which retrieve at least one numeric value, the SensorComponent can easily be reconfigured to display the data from those new Sources.

Now that this lesson is complete, please disable the Sensor source by clicking the Toggle Keep Active Off button at the top, right of the Sensor Source pane, then save the Source. Disabling the source will reduce the load on the publicly available Vantiq MQTT server.