5.4. Working with Javascript

Information and help on how to work with Javascript within GUI Composer’s context.

Javascript is not necessary to get started with GUI Composer. However, it may be necessary if you already have a target firmware that sends data using custom protocol or you need to perform some processing of data before it is displayed.

5.4.1. Introduction

This guide provides details about how to use Javascript to process/parse data, access, and work with the components in your GUI Composer v2 application.

Some initial resources that may be useful to familiarized with JS:

  • W3 Schools: A great resource that can be used for introduction to Javascript as well as reference when trying to find available language features and builtin in objects/functions.

  • Javascript.info: Another great resource with tutorials and reference materials on Javascript.

5.4.2. File Explorer in GUI Composer

You will need to open Project/File explorer in GUI Composer to start working with Javascript files. You may click on folder icon in main toolbar to open file explorer. You will see your current active project shown with bold font. Expanding the project folder will show you files that are currently part of the project.

  • You may use File Explorer to add files to your project from your PC (right click on a project and select Add Files). This may be useful when trying to add a custom Javascript library or images to your project.

  • Double clicking on a file will open that file in main editor area (supported for .gui and .js files). You may click on the X in the top right corner to close the file and return to GUI editor.

5.4.3. Adding Javascript files

You can add Javascript files from File → New → Javascript File to add .js files that may contain a useful starting point to add your own custom Javascript code.

New Javascript files contain commented out documentation that includes examples of how to pre or post process data while it is being streamed from/to device and vice-versa. This template may also be used any time some transformation on the data needs to take place or to update a graph or widget after its data has been processed.

File → New → Custom Codec File may be used with streaming data to enable custom parsing of the data. This is particularly useful when target device is sending data over UART using a custom protocol. In this case, Javascript code may be added to interpret the data and place it in a JSON object or code added to update widgets directly once data has been extracted.

5.4.4. Debugging Javascript

When you are developing your projects, debugging is a useful tool for diagnostics where you can set breakpoints, look at values, look at stack frames and more. GUI Composer 2 projects can be debugged using your browser’s built-in developer tools. We highly recommend using Chrome as your web browser as the Chrome Developer Tools are the most comprehensive.

  • To debug your code, first run your project by clicking on the preview to preview your application. A new browser window or tab will be opened to display the application.

  • Select the developer tools from your web browsers menu or hit F12.

The following animation shows how to open your projects Javascript file, set breakpoints and look at values in Chrome.

Chrome Debugger

Fig. 5.5 Chrome Debugger

Note that to make any changes to your code, you will need to open the file in GUI Composers Code Editor by double clicking on .js file in File Explorer. You are not able to save changes that you make in the browsers dev tools.

5.4.5. Processing of data with XDS target communication

It is relatively easy to process the data that is received by GUI Composer using JavaScript. The reverse technique may be used to adjust the data that is sent to the target device after user modifies it in the GUI.

  1. Create a simple application that displays a global variable. You will need to have a LaunchPad and firmware program that exposes a global variable. You can confirm that the application is working by clicking on preview to preview your application.

Then select New→File→Javascript File inside GUI Composer. Open theFile Explorer by clicking on folder icon on the left side column and double click on newfile_0.js.

  1. Locate the document.addEventListener(gc-databind-ready... function. Inside this function you will need to add your own gc.databind.registry.bind(... function calls. There are a number of examples provided inside the Javascript file.

  2. Add getter and setter functions that perform a random simple calculation on the data. Return value after the computation is automatically passed to the widget.

Please see this video below that explains how data processing is accomplished between two widgets. The idea for any data that is received from device is very similar.

Custom Data Processing in GUI Composer

The method above works well when received data needs to be processed and sent to the widget. However, if data needs to be processed and potentially sent to multiple widgets, then appropriate fields in the widget itself may need to be updated explicitly.

Furthermore, this approach may be necessary if a particular widget library does not expose all properties or a custom widget is used that is not integrated into GUI Composer pallette.

You may need to uncomment code that starts after Boilerplate code for working with components in the application gist. This code performs initialization at application load time to make it easier to work with widgets.

templateObj is an object that provides access to all widgets that have been added to your application.

The syntax is: templateObj.$.WidgetID.WidgetProperty e.g. a TextBox widget that has been added in designer might have a widget id of ti_widget_textbox.

WidgetID is easily obtained from designer by selecting a widget and then opening its property page, id fields contains WidgetID. Similarly looking at property page we can see that TextBox has a value field where text needs to be set.

Thus a complete line to set widgets value would be templateObj.$.ti_widget_textbox.value = teststring;

5.4.6. Processing of data with UART stream based data

Processing of streaming data may be accomplished by adding a bit of Javascript code. This method is necessary when using USB-UART target communication method with a Custom protocol option. In this scenario, the data received by GUI Composer on the UART will need to be parsed and placed in a JSON object or may be updated directly using templateObj as in the XDS option widgets example.

  1. You will need a LaunchPad and firmware that streams some data over UART. It is best to verify with a serial terminal program e.g. Putty that data is being sent over UART in expected format.

  2. Click on File→New→Custom Codec File menu to create a new file in your project. The new file should open automatically in the editor. Next find CustomCodec.prototype.decode function which contains a commented out section of code that parses JSON data.

  3. JSON encoded data is natively supported by GUI Composer. However, the CustomCodec file contains an example of how parsing of JSON objects is accomplished, so it serves as a good starting point for your own parsing logic. If the data being received is ASCII based data then it may make sense to add your own parsing code inside of while loop to look for patterns in received data.

You will need to create an object in Javascript with a number of fields that corresponds to individual fields in your data stream. That object is then passed to GUI Composer and fields of your object may be used to bind to widgets. If data that is received in data argument is binary then you will need to remove code that converts your data to strings and instead create a new Javascript code that interprets your binary data and converts to individual fields.

You may also use the same technique as described in last couple of paragraphs to processing data with XDS target communication to explicitly send received data to widgets.

5.4.7. Javascript tips and tricks

  • Variables used without the var keyword become global automatically.

  • Variables declared with the var keyword are scoped locally.

  • Be careful when using this objects as it belongs to calling scope. This is important for when callbacks are used. It may be avoided by declaring a _self object before the callback or explicitly adding .bind(this) after callback declarations.