How Namespaces Affect Deployed Applications

Multiple General Interface applications running in a single web page share a common JavaScript memory space. Consequently, one application can have intended and unintended effects on another General Interface application running in the same web page. There is no way of designing an application such that it's completely protected from other applications. This chapter describes how to design an application so that unintended effects between it and from other applications are greatly reduced.

The namespace of a General Interface application is the name of the global JavaScript variable that is set to the instance of jsx3.app.Server representing the application. Custom application JavaScript code usually references this variable extensively since the server provides access to the General Interface DOM and local data cache, among other things.

The namespace of a General Interface application must be unique for each application deployed in a single web page. If a namespace collision occurs, the code of only one of the applications has access to its jsx3.app.Server instance. The other applications will likely break. Namespaces should always be checked for uniqueness before creating a deployment page with multiple General Interface applications.

A good way to ensure namespace uniqueness is to use the reverse domain naming convention when choosing your application namespace. For example, you could use com.tibco.gi.App1 and com.tibco.gi.App2. This ensures that your applications won't conflict with General Interface applications from other organizations.

Setting the Application Namespace in General Interface Builder

By default, the server namespace is the same as the project name, with any illegal characters removed. The value is displayed in the Namespace field on the Deployment panel of the Project Settings dialog (Project > Project Settings) and can be modified to any valid JavaScript variable name.

Using the Namespace in Application Code

The jsx3.app.Server instance, the name of which is specified by the application namespace, provides access to the General Interface DOM and local data cache.

Access to the DOM is provided by the methods getDOM(), getJSX(), getJSXByName(), getJSXById(), and getBodyBlock() of the jsx3.app.Server class. All DOM nodes, which are instances of jsx3.app.Model, are indexed by both ID and name. The following code retrieves the DOM node of name "textbox" in the application of namespace com.tibco.gi.App1:

com.tibco.gi.App1.getJSXByName("textbox");

The DOM index on name tracks only one node per name. Therefore, the getJSXByName() method only returns a predictable value for names that are unique over the entire application.

The jsx3.GO() method is a shortcut for fetching a DOM node by name or ID. The jsx3.GO() method has access to all loaded General Interface applications and searches all of them for a DOM node of the given name. The jsx3.GO() method is therefore slower than getJSXByName() and allows one application to affect another application. Only use jsx3.GO() in the General Interface Builder JavaScript Console where brevity is more important than accuracy. Application code should not use jsx3.GO.

jsx3.GO("textbox");

Access to the application local data cache is provided by the getCache() method in the jsx3.app.Server class. The following code fetches a cache document from the App1 application:

com.tibco.gi.App1.getCache().getDocument("docId");