Best Practices for Writing Custom JavaScript Code in Text Areas

Last updated:
9:58am Sep 25, 2019

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. 

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

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.  

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);

 

Feedback (2)

The SF object is injected into the global scope that is executed if the script is added via "Insert Javascript". If you shut down HTML sanitizer and write code inline, it will not work.

Magnus Rylander 7:35am May. 20, 2020

I get an error when trying to use 

SF.setBusy(true);  

SF.setBusy(false);

 

Execution of Javascript failed:
Type: ReferenceError
Message: SF is not defined
Stacktrace: ReferenceError: SF is not defined

 

 

 

 

tyger0951 9:08am May. 19, 2020