Deployment Parameters

This section describes how to configure deployment for individual General Interface Builder applications and the JSX system, which is the General Interface runtime.

There are two areas to consider when deploying GI applications:

• Configuring Deployed Applications
• Configuring the Runtime

Configuring Deployed Applications

There are two possible ways to configure the deployment of a General Interface application:

• For each deployment, modify the HTML script element(s) on the web page that launches the application(s).
• For each application, modify the application configuration file (config.xml).

When the deployed application is launched, deployment parameters are passed to the General Interface runtime in the following order, with the first one taking precedence over the others:

1. Attributes of the HTML script element.
2. Query parameters of the src attribute of the script element.
3. Configuration parameters stored in the application configuration file, config.xml.

HTML Script Element

One mechanism for configuring an application is to modify the script element of the HTML launch page where the application is deployed. Deployment parameters can be included as attributes of the script element or as query parameters in the src attribute of the script element.

General Interface provides several built-in parameters, such as jsxappns, jsxapploader, and jsxapppath. Custom attributes or parameters can also be added to the script element. For example, this mechanism can be used to communicate session information from a web server to a General Interface application. However, all attributes beginning with jsx are reserved for General Interface.

All attributes of the script element are deployment parameters used to configure the application except these reserved HTML attributes — id, space, type, charset, defer, src, and language.

The following parameters are significant in the General Interface runtime:

• jsxappns. Application namespace. For example, jsxappns="myAPP". Because every application deployed on a single page must have a unique namespace, overriding the namespace can be useful when an application is multi-instantiated on the same page. However, the application must be written to never reference its namespace directly.
• jsxapploader. Specifies what type of progress bar to load when the application launches. For example, jsxapploader="0".
  
  • 0 = standard progress bar
    
  • 1 = portlet, subordinate progress bar
    

    To prevent General Interface progress bars from overlapping when deploying multiple applications in the same page, see Deployed Applications and the Progress Bar.

• jsxapppath. The path to the application. For example, jsxapppath="../workspace/JSXAPPS/samples/chart".

For examples of how to use these deployment parameters in the script element, see the following examples.

In this example, the jsxapppath attribute contains the application path.

<div style="width:100%;height:400px;">

  <script type"text/javascript" src="JSX/js/JSX30.js"
     jsxapppath="../workspace/JSXAPPS/samples/chart">
  </script>

</div>

In this example, the application path, jsxapppath, is passed as a parameter to the General Interface runtime file, JSX/js/JSX30.js.

<div style="width:100%;height:400px;">

  <script type="text/javascript"
     src="JSX/js/JSX30.js?jsxapppath=../workspace/JSXAPPS/samples/chart">
  </script>

</div>

To pass multiple parameters, use an ampersand (&). This example passes the application path and the progress bar loading as parameters.

<div style="width:100%;height:400px;">

  <script type="text/javascript"
     src="JSX/js/JSX30.js?jsxapppath=../workspace/JSXAPPS/MyProject&jsxapploader=0"
  </script>
</div>

Any application configuration parameter is available using the jsx3.app. Server.getEnv() method. For more information, see General Interface API Reference.

Application Configuration File

The other mechanism for configuring an application is to modify the application configuration file, config.xml. This file contains configuration parameters that affect deployment of the application. These parameters can be edited on the Deployment panel of the Project Settings dialog in General Interface Builder. To open the Deployment panel, choose Project > Project Settings > Deployment.

Deployment parameters include such settings as namespace, initial component to load, script to run when loading, and so on. For more information on the available parameters, see File Menu. Other deployment options, such as which add-ins to load, are automatically set in config.xml from settings in the IDE.

Custom attributes can also be manually added to config.xml, which is located at the root of the project. Simply open config.xml, add a new record element, and save the file. For example, you could add a record that externalizes a constant from JavaScript code as shown here:

<record jsxid="CONSTANT1" type="number">VALUE1</record>

This value can also be queried using the jsx3.app.Server.getEnv() method. For example,

myApp.getEnv("CONSTANT1");

Configuring the Runtime

The General Interface runtime or JSX system, which is required to run deployed General Interface applications, is configured at deployment with the same script element mechanism described in Configuring Deployed Applications. A runtime configuration parameter is any parameter beginning with jsx but not jsxapp. Any General Interface application in a multi-application deployment page may configure the runtime. However, it is an error if script elements provide conflicting values for a single runtime parameter.

JSX system parameters include but aren't limited to the following:

• jsx_logger_config. Specifies the name and location of the logging system configuration file to be used. You can create a custom logging system configuration file and specify its location using this attribute. This is useful for monitoring and testing a deployed application at runtime. See Creating a Custom Logging System Configuration File.
• jsx_no_messages. When set to 1 , prevents JSX/locale/messages.xml from loading with the system. This file is used for system messages and is probably not necessary for a production deployment.
• jsx_no_locale. When set to 1, prevents JSX/locale/locale.xml from loading with the system. This properties bundle file provides all localized data to the system, including information for NumberFormat, DateFormat, Locale, and DatePicker. This data may not be necessary for some smaller applications. For more information, see Internationalizing and Localizing Applications.
  

  An application that specifies the jsx_no_locale parameter must not use any locale data. A common result will be a null pointer exception in DatePicker or TimePicker or null painted in Table, Menu, Select, Matrix, or BlockX.

• jsx_browsers. Overrides the default set of supported browsers. The format of this parameter is bt={allow,warn}[,...]
  where bt is the browser type returned by the getType() method in the jsx3.lang.ClassLoader class. See jsx3.lang.ClassLoader in General Interface API Reference. For example, to show a warning in Internet Explorer 6, modify the application launch page as follows: <script src="JSX/js/JSX30.js" jsx_browsers="ie6=warn"/>
  • allow launches the application in the browser.
  • warn provides a warning for unsupported browsers and allows the user to proceed.
    
    
• The following Internet Explorer-specific parameters:
  
  • jsxxmlregkey The default ActiveX XML object key. Specifies the version of the XML Parser instance as referenced in the Microsoft Windows Registry. For example, jsxxmlregkey="Msxml2.FreeThreadedDOMDocument.4.0".
    
  • jsxxslregkey The default ActiveX XSL object key. Specifies the version of the XSL Parser instance as referenced in the Microsoft Windows Registry. For example, jsxxslregkey="Msxml2.XSLTemplate.4.0".
    
  • jsxhttpregkey The default ActiveX HTTP object key. Specifies the version of the HTTP control as referenced in the Microsoft Windows Registry. For example, httpregkey="Msxml2.XMLHTTP.4.0".
    
  • jsxxmlversion Specifies the version of the previous three keys---XML Parser, XSL Parser, and the HTTP control, such as version 3, 4, or 5. For example, jsxxmlversion="3".

By default, General Interface 3.5.1 and 3.6.0 load version 6 if available, then version 4 if available, then version 3. If you need to use a different version, use these system parameters to override the defaults.

General Interface runtime parameters are available using the jsx3.getEnv() method. For more information on the getEnv() method, see General Interface API Reference.

As an example of configuring the runtime, you might configure the General Interface runtime to print a value to the system log. The following example assigns a value of value1 to a General Interface runtime parameter named jsxprop1 :

<script type"text/javascript" src="JSX/js/JSX30.js"
   jsxprop1="value1">
</script>

Including the following log statement in a JavaScript file:

jsx3.log("The value of jsxprop1 is " + jsx3.getEnv("jsxprop1"));

would print the following output to the system log: The value of jsxprop1 is value1.