API Usage

When writing JavaScript code for your application, use the following best practices.

Minimize Repainting

The on-screen rendering of HTML is often the slowest aspect of browser-based applications. Using efficient repaints can make your application faster and more responsive to user input.

Follow these best practices for repainting:

• Look for unnecessary repaints in your JavaScript code and remove them.
  Use the General Interface debug build to identify multiple repaints. See Use the General Interface Debug Build.
• Repaint the smallest area of your application to obtain the desired effect.
• Understand how set methods may cause repaints and use them appropriately. See How Set Methods May Cause Repaints.
• Avoid redundant repaints on the same object.
  When calling any load APIs, such as the jsx3.app.Model.load(), jsx3.app.Model.loadAndCache(), and jsx3.app.Model.loadXML() methods, pass false as the second parameter to avoid a repaint if changes will be made to the component. Then repaint the component after changes are complete using the jsx3.gui.Painted.paintChild() method.
• Some methods, such as removeChild(), setChild(), and adoptChild(), can trigger repaints of the parent whose child is removed, set, or adopted. When possible, reuse components instead of removing and loading them.
• If removing multiple children at the same time, use the jsx3.app.Model.removeChildren() method to avoid multiple repaints.
• For Matrix components, call the repaintData() method if only the data has changed.
  The repaintData() method paints only the data rows and doesn't recalculate and re-profile the box profile and resulting XSLT. Therefore, the repaintData() method is more efficient than the repaint() method.

For more information, see General Interface API Reference.

How Set Methods May Cause Repaints

Note that there are two types of painting in General Interface:

• HTML DOM update: this is a fast, inexpensive paint, where a change to the General Interface DOM is transmitted directly to the browser DOM.
• Paint/repaint: this is a slower, more expensive paint, where the General Interface DOM is first serialized to an HTML string and then replaces part of the browser DOM.

Consider these basic rules when using set methods:

1. If the set method doesn't have a final boolean parameter (bRepaint), the component isn't repainted. For example, jsx3.gui.Block.setBackground(strBG). However, there are some exceptions.
2. If the set method has a final boolean parameter (bRepaint), you control the behavior. The default setting is false, meaning the component isn't repainted. For example, jsx3.gui.Block.setText(strText, bRepaint).
   If the final boolean parameter is set to true, the component is repainted, which is usually an inexpensive HTML DOM operation. However, in some cases a full repaint occurs.

If you're calling multiple set methods, follow these basic rules:

1. For methods that call inexpensive HTML DOM repaints, call each method with true.
2. If one of the methods calls a more expensive, full repaint, call that method last, while calling bRepaint=false to the preceding set methods.

For more information, see General Interface API Reference.

Search Components in the DOM Efficiently

There are many ways to access objects in General Interface. The most common methods are the getJSXByName() and getJSXById() methods. These methods search an application index to quickly find the specific object in the General Interface DOM. Other methods are available, such as getJSX(), but are less specific and less efficient at locating objects.

Don't use jsx3.GO() to search the General Interface DOM, because it has access to all loaded General Interface applications and searches all of them for a DOM node of the given name. Recommended usage is in the General Interface Builder JavaScript Console only.

The following APIs are generally fast and memory safe:

• jsx3.app.Server.getJSXByName()
• jsx3.app.Server.getJSXById()

The following APIs are slower but also memory safe:

• jsx3.app.Model.getAncestorOfType()
• jsx3.app.Model.getDescendantOfName()

For example, you could use the getAncestorOfType() method in a dialog button execute event to close a dialog:

this.getAncestorOfType(jsx3.gui.Dialog).doClose();

General Interface also provides DOM methods that use familial relationships to locate objects. Depending on the location of the object you're searching for, it may be faster to use these methods. For example, calling

object.getChild('myblock');

only checks its direct children, so it might be much faster than calling

object.getDescendantOfName('myblock');

which checks all children, grandchildren, and so on.

Apply the appropriate call for your particular use case.

For more information on General Interface APIs, see General Interface API Reference. For information on how to search the General Interface DOM safely when deploying multiple applications in the same web page, see Protecting Namespaces in Multiple Application Environments.

Exclude Logging Messages

To improve performance, don't build logging messages when logging is disabled. Only build logging messages when logging is enabled. When development is complete, configure the logger in your deployed application so fewer messages are generated by setting a more restrictive log level, such as WARN, ERROR, or OFF.

In this example, messages won't be generated if the com.tibco logger is configured as OFF:

var Logger = jsx3.util.Logger;
var log = Logger.getLogger("com.tibco");
if (log.isLoggable(Logger.ERROR))
    log.info(xmlDoc.toString()); // serializing XML may be
                                 // expensive

For more information, see Logging and Application Monitors and jsx3.util.Logger.isLoggable() in General Interface API Reference.