Skip to content

Dashboard JavaScript API


Row64 Studio allows users to customize JavaScript events on their dashboards, giving them the ability to fine-tune dashboard behaviors.

This guide provides instructions on customizing the JavaScript events on a dashboard and offers several practical example of implementing custom functionality that users might find useful. Users are not limited to the customizations displayed in the examples; many possibilities are available.



Setup

To get started, you must first have a dashboard project open in Row64 Studio.

If needed, you can download a sample project from the Studio Examples page. The examples in this guide will use the Urban Analytics project. For the easiest introduction, we recommend following along with the Urban Analytics example project, but custom JavaScript events can be used on any dashboard project.

If you're using a sample project, unzip it after downloading. After it is unzipped, open it in Studio.


Enable JavaScript Events


Redirection

When you enable JavaScript events in Row64 Studio, it redirects Studio from using the built-in, predefined events to a customizable file. This customizable file gives you full control of a dashboard pane's JavaScript events.

To use JavaScript events, you must first enable them in your project in Studio.


Enable JavaScript Events

In your project, double-click on a dashboard pane to pull up the Edit Dashboard Pane window.

Find the Layout tab.

If custom JavaScript events are available for the pane, you will see a Javascript Events section with a checkbox to enable JavaScript events.

Check the box to enable JavaScript events and to redirect your dashboard to use the customizable file.


JavaScript Options

Different dashboard panes support different JavaScript options.

Be sure to review all the available options in the Javascript Events section of the Layout tab before proceeding to edit the customizable JavaScript file.

For example, the map pane of the Urban Analytics example supports different JavaScript options (see next image) than the file pane as seen in the previous image.


Editing the JavaScript File

Tip

Before editing the JavaScript file, we recommend making a backup of the original file in case you need to restore the original configurations.

Warning

Be aware that the JavaScript file is overwritten with every new Row64 installation or build. If you wish to preserve your custom JavaScript file, you must make a backup and save it to a different location.


File Location

The customizable JavaScript is located at:

/var/www/html/api/dashEvents.js

Before editing, we recommend making a copy of this file in case you need to revert to the original configurations.

For example, the following image shows the /var/www/html/api directory with its original contents, in addition to a new dashEvents_BACKUP.js file that was made by copying and renaming the dashEvents.js file. The copying and renaming was performed manually by the user.


Edit JavaScript

The dashEvents.js file contains JavaScript functions that define the behavior of the dashboard.

You will need to explore this file to locate the JavaScript functions you want to customize.


Example #1: Open a Website

In this first example, suppose you want to be directed to a website when you click on a coordinate on the dashboard map. To accomplish this, you first need to enable the JavaScript redirection and then update the corresponding JavaScript function. In this case, this is the ClickGeoCoord function in the dashEvents.js file.

This example will update the behavior of the ClickGeoCoord function to have the Row64 Help site open in a new browser tab when a user clicks on a map coordinate in the dashboard.


Redirect Application Function

In the Urban Analytics sample project, double-click on the map pane to pull up the Edit Dashboard Pane window.

In this window, check the Coord Click box below the Javascript Events section in the Layout tab.


Edit JavaScript

Next, open the dashEvents.js file in a text editor of your choice, such as Sublime.

Find the JavaScript function that corresponds to the "Coord Click" option, which is ClickGeoCoord.

Add the following line to the bottom of the function:

window.open("https://app.row64.com/Help", '_blank').focus();

Save the file after making the changes.


Publish Dashboard

In Row64 Studio, in the Dashboard tab, select Publish to publish the dashboard to the browser to test the new functionality. (You'll need to publish the dashboard every time you want to see changes in the browser).


Test JavaScript in the Browser


Open Developer Tools

After publishing your dashboard and opening it in a browser, access the browser's developer tools.

Two easy shortcuts include Ctrl+Shift+I or F12.

The developer tools window will look slightly different between browsers, but they offer similar features. This example uses the Google Chrome browser.


Disable Cache

In the developer tools, select the Network tab and find the option to disable cache.

If cache is not disabled, changes made to the JavaScript file will not be reflected in the browser.


Open Console

When customizing JavaScript functions, it may be useful to print messages to the browser's console using the console.log("MY_MESSAGE") function to assist with troubleshooting.

You can open the developer tools console by selecting the Console tab. If any console.log() functions are present, they will output their messages to the console for the applicable event.


Test the Example

The earlier example added a JavaScript command to open the Row64 Help site when a map coordinate was selected.

Test this functionality by selecting a coordinate on the Urban Analytics map in the browser.


Example #2: Custom PPG

This example demonstrates how to open a custom pop-up window when a user clicks on a cell in the Type column of the file spreadsheet pane of the Urban Analytics project.


Dashboard Settings

In the Row64 Studio Urban Analytics project, double-click the file spreadsheet pane in the bottom right corner to pull up the Edit Dashboard Pane window. In the Layout tab, review the Javascript Events settings.

Your JavaScript events should be enabled from before.

Notice that there are two drop-down menus at the bottom of the window. By default, the left menu might say C: _File and the right ClickCell.

For now, leave these menus how they are.


Use Console Messaging

When editing JavaScript events, if you are unsure of which JavaScript event function to edit, it might be helpful to use console messages to test if your targeted event triggers the desired function.

As mentioned earlier, you will need to look through the dashEvents.js file to find a JavaScript event function that corresponds to the action you want to customize. If you have an action in mind, but don't know exactly which function to edit, you can input a custom console message line into a function to see if you trigger the correct event. This is a simple strategy to identify the correct function before committing time to editing the JavaScript.

In this example, since the goal is to open a pop-up window when you click on a cell, you may reasonably guess that the event function you need is ClickCell. To confirm this, add a console message line to this function.

In the dashEvents.js file, find the ClickCell function. Within this function, add the following line:

console.log("CUSTOM: Click cell");

Save the file.


First Test

In Studio, save your project and publish it to your browser.

In your browser, pull up the Console tab in the developer window.

Now, click on any cell in the Type column and watch the console.

Notice that nothing happens!

Although you added the console message to the correct event function, when you tried to trigger the event by clicking on a cell, the console message did not appear. This was not because the console message was added to the wrong function, but rather because Studio is not currently using the correct settings.


Studio Custom JavaScript Settings

Although the custom console message was written correctly and included in the right function, a console message did not appear because Row64 Studio was not using the right settings.

On your published dashboard in your browser, select an empty cell in the _File column. You should now see the custom message appear.

Notice

Clicking on a cell with an embedded item, such as a file, may trigger a different event, such as opening the embedded file, resulting in you not seeing the custom console message. If you don't see the console message, make sure you're selecting an empty cell.

This exercise highlights the importance of not only editing the JavaScript of the correct event function, but also ensuring that Studio is configured to apply the custom event. Before dedicating too much time to your custom JavaScript functionality, it may be beneficial to first use console messages to validate that your events are triggering the right functions and that Studio is set up to look for the right options.


Update Studio Settings

The goal of this example is to trigger a JavaScript event when a cell in the Type column is selected, not the _File column. To correct this, return to Studio and change the JavaScript options.

On this particular pane, the left drop-down menu applies JavaScript to the specified table column, whereas the right drop-down menu defines the JavaScript event to look for.

Set the left menu to Type, and keep the right at ClickCell.


Second Test

Now that you added a console message to the JavaScript event function and configured Studio to look for the correct trigger, it's time to test again. Save your dashboard project and publish it to your browser.

With the browser console open, click on a cell in the Type column. You should see your custom message appear.


OpenPPG Function

Now that you've verified that the targeted event is triggering the desirable function, you can proceed to create the custom pop-up.

In the dashEvents.js file, there is an existing OpenPPG function that opens a pop-up window when called by an event.

To use the OpenPPG function, you need to add it in a JavaScript event so that it can be called when the desired event is triggered.

Add the following code to the ClickCell function:

OpenPPG( function() {
    console.log("CUSTOM: Custom PPG triggered");
    ppgWin.SetTitle("CustomPPG");
});

Save the file.


Test for Pop-Up

Return to Studio and publish your project.

Click on a cell in the Type column, and a blank pop-up window should appear.


How to Edit the PPG

You can edit the layout and content of a pop-up window with the ppgWin and iframe variables.

ppgWin defines the basic window properties. By default, a new window will be blank and will have the download, fullscreen, and close buttons at the top right corner. Notice how ppgWin was used to set the window's name in the previous image.

iframe defines the content within the window and allows you to insert items like videos or files. iframe is a generic HTML function, so resources are available online that explain its full capabilities.


Example #3: PPG From Folder

Example #3 and #4 use a separate example project that is downloadable from Row64's Google Drive. If you were following along with Urban Analytics, you can close that project.


Load Example Files

Download the JavaScript API examples zip from Row64's Google Drive:

JS_API_Minimal_Examples.zip

Notice

Before proceeding through Example #3 and #4, back up your /var/www/html/api folder and replace it with the contents of the zip file.


Build Testing Dashboard in Studio

Open Studio and make a dashboard with a single dataframe.

Click the Data Tab > Get Data > From Server > City Locations.

Drag in the dataframe as a single pane dashboard. Right-click and select the Layout tab.

Enable JavaScript events. Set the following option in the drop-down list: A: Type to Clicked Cell.

Increase the Zoom Magnification.


Publish the Dashboard

Publish the dashboard and refresh your browser. (An easy shortcut for refreshing your browser is: <Ctrl><Shift><R>).

If you're following this example and using the API examples zip in Studio, you should see a pop-up with the text "clicked:" and the cell text.

Tip

Make sure you disabled cache, as shown earlier in this guide.


Study the Minimal JS and HTML

If you review your api folder, you'll see there's a sub-folder called minimal, which contains a single index.html file. That file is populating the iframe inside the PPG. It has a single inline function called Set(), which is filling the text in a <div>.


Study dashEvents.js

If you look inside dashEvents.js, you will see that the ClickCell() function is opening the PPG by setting the iframe to the HTML path inside your minimal folder. It is calling the Set() function and filling it with the cell string.


Example #4: Drill Into Details

This example demonstrates how you can use a button to pop up a video, and how to implement back-button returns.


Use the File from Example #3

In this example, use the API folder that was previously installed from Example #3 with the simple dataframe dashboard that was created.

Open your dashEvents.js file. Comment out the "Minimal HTML Folder" example and uncomment the "Button Inspects Video" example.

After making the changes, save the file.


PPG with Video Button

With your changes saved, refresh the browser to apply the changes. It should pop up another simple window with a button to watch a video.


Video Player with Back Button

The video player should pop up and you'll see a back button in the top left corner.


Return Back and Keep State

When you select the back button, it will remember what cell you had previously clicked when you selected "WATCH VIDEO."

This is a simple example of storing state; performing a task and then returning to your original state.


Study "menu" folder

This section provides guidance on the contents of the menu folder.


index.html

The index.html file is more standard and less minimal. It attaches a .js and .css file. It has a button with an onclick event to JavaScript.


Row64 dashboards use Open Sans for display, which is an open source font. You can match the font exactly as shown in this example, or just use Sans-serif, Arial, or Helvetica, which are faster and don't require custom fonts.


The JavaScript simply stores the handle of the dashEvents.js callback. It also stores a handle to the API. You can see what functions the API does in the file:

/var/www/html/api/apiCore.js

We do not recommend changing the apiCore since it directly bridges Row64 WebAssembly and simplifies scripting.


Study dashEvents.js

This section provides information on some of the functions within the dashEvents.js file.


dashEvents.js

The "Data" variable is used as JSON to store the state. In this case, it's a simple string.

We have a new “menu” folder with our PPG in it. We’re setting our Cell String the same as in Example #3. We’re setting the callback for our button to another function in dashEvents.js called OpenVideoLink().

Note that we also pass the “api” handle to demo how to make API calls within an iframe. We don’t do that in this example, but it shows you how.


When you click the "OPEN VIDEO" button, it calls the OpenVideoLink() function. You can load the bytes for a file if you know the:

  • Dataframe name
  • Video path
  • The column that contains the link to the video

We open the next PPG and make the Back Button visible, and set the callback in the ShowBackButton() function.


VideoBackButton()

When you select the back button, it calls the VideoBackButton() function.

We already have the PPG up, so we can recycle it with the iframe content with the index.html from the menu folder. We use our Data variable to get back the Cell String (i.e. prior menu state) that was visible before.


Note on the Back Button

The example files downloaded in Examples #3 and #4 include features beyond the V3.5 installer:

  • ShowBackButton() with callback
  • HideBackButton()

You can use these in your projects by copying the dashEvents.js from the example into your projects. Note these features will be integrated in V3.6, so don't replace the files in future versions as it will likely cause problems.


Conclusion

The examples in this guide demonstrated simple JavaScript modifications, but you can accomplish much more beyond this.

Remember to back up your api folder if you want to preserve your custom JavaScript. Otherwise, it will be overwritten the next time you build or install Row64.