Best Practices for Writing Custom JavaScript Code in Text Areas
Last updated:
8:11pm May 05, 2016

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 indended 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. 

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 TIBCO Spotfire to implement all functionality in the Text Area and other TIBCO Spotfire visualizations. This means that there are a lot of JavaScript libraries defined by TIBCO Spotfire and third parties in scope, including JQuery ($) and JQueryUI. You are strongly advised against using any of these libraries. If you still decide to use these libraries, you are taking a risk and you may need to manually update and edit your JavaScripts in the analysis files before upgrading to a newer version of TIBCO Spotfire.

TIBCO Spotfire provides no guarantee whatsoever of the correctness, usability or compatibility of the libraries in scope. Future versions of TIBCO Spotfire are likely to include other, upgraded and or incompatible libraries. Libraries may also be removed in future versions. Thus if you use JQuery in a JavaScript it might result in an erroneous Text Area when the dxp file is opened in a future version of TIBCO Spotfire. If you want to use another JavaScript library you need to import it yourself and make sure it does not conflict with the libraries TIBCO Spotfire use.

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 TIBCO Spotfire. For example, it is possible that the layout and definition of a Table visualization in TIBCO Spotfire could change in a future version.

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 TIBCO Spotfire. 

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.

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.

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 TIBCO 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.  

Changes between version 6.5 and 7.0 of TIBCO Spotfire

In TIBCO Spotfire Analyst 6.5, each Text Area and its corresponding scripts execute in its own separate browser window and has its own HTML DOM (Document Object Model). This is different from TIBCO Spotfire Web Player 6.5 where the complete analysis execute in one browser window.

From version 7.0, the TIBCO Spotfire Analyst client and the Web Player client work in the same way and the same scripts can therefore be used in both the web and installed clients.  All Text Areas and JavaScripts share the global context with the rest of the TIBCO Spotfire analysis. This means that if you have JavaScript code that for example triggered on the document.ready event, you will need to revise and edit your code.