Best Practices for Writing Custom JavaScript Code in Spotfire Text Areas

Introduction

This article contains best practices and recommendations for how to develop custom JavaScript code in Text Areas in TIBCO Spotfire® analysis files in a supportable and maintainable way so the analysis files will continue to work with future versions of TIBCO Spotfire.

JavaScripts can be inserted into a Text Area via the Edit HTML option and then clicking the "Insert JavaScript" button in the toolbar.

The intended use of JavaScripts in the Text Area is to decorate your own elements and make them more interactive, for example adding highlight effects on elements or creating an interactive layout.

3rd party JavaScript libraries

The first important thing to know is that the JavaScripts you add to the Text Area will execute in the same environment as the JavaScripts defined by Spotfire to implement all functionality in the Text Area and other Spotfire visualizations. This means that there are a lot of JavaScript libraries defined by Spotfire and third parties in scope, including JQuery ($) and JQueryUI. Spotfire provides no guarantee whatsoever of the correctness, usability or compatibility of the libraries in scope. Your use of any of those libraries is entirely at your own discretion and is not supported or warranted by Spotfire.

HTML elements

As a general rule the JavaScript should only modify elements in the HTML code that you have created and have control over yourself. This means that the JavaScript should only change parts of the HTML DOM that reside in the Text Area and that is defined in the the HTML of the Text Area. Thus if you add a div element in the Text Area that your JavaScript operates on, you are safe. This also means that you cannot assume how other elements outside your DOM are defined in order to be compatible with future versions of Spotfire. For example, it is possible that the layout and definition of a Table visualization in Spotfire could change in a future version.

Spotfire objects

You can add filters, calculated values, Spotfire property controls etc in a Text Area. These controls should be considered as Spotfire objects which are translated into HTML when they are rendered. It is not recommended to rely on the rendered HTML for these controls as it may change in future versions of Spotfire.

Order of scripts

The order of the JavaScripts in the Text Area is important. The order controls the loading and execution of the scripts, so if the scripts have dependencies between them you need to check that the order of the scripts are correct.

How to add scripts

The recommended way to add a JavaScript to the Text Area is to use the Insert JavaScript dialog.

It is possible to refer to JavaScript in a different location via for example a URL but you should then be aware of the risks with doing that. All users of the DXP file need to have access to that URL and it will not be possible to use the analysis file correctly without that access if you for example want to work offline.

Events

Since all JavaScripts share the same global context they also share global events. It is therefore not recommended to use global events such as listening to the document.ready event since those might change in future versions of Spotfire. The general rule mentioned above is applied here too - only use events that you have control over yourself, and only listen to events raised from elements that you have created. For example, it is not encouraged to listen to events from the Spotfire controls.

How to signal when the text area is ready to be rendered to PDF or image

If your script contains asynchronous calls, you need to use the SF.setBusy() API to make sure the text area will render nicely when exported to PDF or image.

By executing:

 SF.setBusy(true);

the export browser will not render a pdf/image until the script executes:

 SF.setBusy(false);

Sign In