tibco® general interface - enterprise edition · multiple components that work together using...

TIBCO® General Interface - Enterprise Edition

Developer Guide

Software Release 3.9.1April 2012

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN TIBCO GENERAL INTERFACE INSTALLATION) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE "LICENSE" FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIB, TIBCO, TIBCO Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO General Interface, TIBCO General Interface Framework, TIBCO General Interface Builder, TIBCO General Interface Performance Profiler, and TIBCO General Interface Test Automation Kit are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.

U.S. Patent No. 8,136,109

Copyright © 2001-2012 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

1

Copyright © TIBCO Software Inc. All Rights Reserved.

General Interface Developer GuideGeneral Interface Developer Guide

Software Release 3.9

March 2010

Chapter 1 Introduction to General InterfaceChapter 2 General Interface Builder BasicsChapter 3 General Interface Framework BasicsChapter 4 Handling Application DataChapter 5 Communicating with Data ServicesChapter 6 Communicating with a Web Service TutorialChapter 7 Using CDF Form Mapping TutorialChapter 8 Optimizing Application PerformanceChapter 9 Accessing Data Across SubdomainsChapter 10 Adding and Debugging JavaScript CodeChapter 11 Class Inheritance and IntrospectionChapter 12 Extensions to JavaScript Exception HandlingChapter 13 General Interface JavaScript Documentation CompilerChapter 14 Protecting Namespaces in Multiple Application EnvironmentsChapter 15 Implementing Context-Sensitive HelpChapter 16 Logging and Application MonitorsChapter 17 Internationalizing and Localizing ApplicationsChapter 18 Deploying ApplicationsChapter 19 Optimizing Load PerformanceChapter 20 Asynchronous Modular PlatformChapter 21 Asynchronous Programming UtilitiesChapter 22 Using the Test RecorderAppendix A General Interface Builder Menus, Toolbars, Dialogs, and Tools

2


Chapter 1 Introduction to General Interface

This chapter provides an introduction to General Interface software, which includes GeneralInterface Framework and General Interface Builder.

General Interface Files and FoldersFurther Information on General Interface Topics

General Interface Files and Folders

General Interface consists of two components:

General Interface Framework The distributable runtime framework for runningbrowser-based General Interface applications. The framework is located in the JSXdirectory.General Interface Builder A browser-based, visual development environment fordeveloping General Interface applications that use the General Interface Framework.General Interface Builder is itself a General Interface application. General InterfaceBuilder is located in the directory.GI_Builder

Although the installation directory is different for Enterprise Edition and Professional Edition,the contents of the directories are the same. The figure shows the directory structure and itscontents.

3


Further Information on General Interface Topics

For more information, see the following topics:

Workspace and projects: Managing ProjectsGeneral Interface Builder preferences: Customizing the IDELogging system configuration file: Logging and Application MonitorsParameterized launch pages: Deploying as a Full Console Application

4


Chapter 2 General Interface Builder Basics

This chapter provides an overview of General Interface Builder features and the user interface.

Using PalettesCustomizing the IDEManaging ProjectsWork Area EditorsComponent Libraries Palette and the Online RepositoryData and Cache ManagementData Connection and MappingJabber SupportGeneral Interface DocumentationFurther Information on General Interface Basics

Using Palettes

This section describes the General Interface Builder palettes that you use as you work with yourapplication.

Project Files Palette

A list of all files referenced by an application are displayed in the Project Files palette. Files caninclude GUI components, XML and XSL documents, JavaScript files, CSS files, dynamicproperties files, properties bundle files, mapping rules files, and other files, such as text files.The file and folder hierarchy reflects where the files are located in relation to the projectdirectory.

For more information on projects, see . For definitions of toolbar buttons, see Managing Projects.Project Files Palette Toolbar

5


Component Libraries Palette

The Component Libraries palette, shown in the next figure, provides predefined GUI prototypeobjects for adding functionality to your application. Components are organized in foldersaccording to function. For example, objects in the folder such as Dialog, Layout, andContainers

Tabbed Pane, act as containers for other objects. Form Elements objects, such as Text Area,Button, and Select, collect user input.

These object libraries not only reduce the time required to build applications, they also allowobject behavior and look-and-feel to be easily customized.

Prototype objects can be dragged from the Component Libraries palette to any object in thework area or to the Component Hierarchy palette. A new object of the selected type is createdas a child of the object where it's dropped if the parent object accepts children.

You can also create, manage, and share your own libraries of components. Saving a componentdefinition to the workspace directory adds it to the folder in the Component/prototypes User

Libraries palette. The custom component can then be reused like any other prototypecomponent.

The folder contains any prototypes defined in an add-in, such as Charting. You can alsoAddins

create your own custom add-ins. Add-ins must be enabled on the Add-Ins panel before theydisplay in the folder. For more information, see General Interface Component Guide.Addins

For more information on components and tutorial on custom add-ins, see the General InterfaceComponent Guide.

6


Component Hierarchy Palette

The Component Hierarchy palette, shown in the next figure, lets you view and manage thehierarchical model of objects in your application.

Objects can contain other objects. For example, a LayoutGrid component could include TextBox, Label, and Button objects, as well as other components. Applications usually consist ofmultiple components that work together using JavaScript logic.

Using the Component Hierarchy palette, you can select objects and then modify them usingother palettes, such as Properties Editor palette, Events Editor palette, and so on. Once you'vedefined a component or object, you can also clone it to quickly make multiple copies. Objectscan also be exported to reuse in other applications or imported from another project into thecurrent one. For more information about working with components, see General InterfaceComponent Guide.

Use to select multiple components. Use to choose a range ofCtrl+click Shift+clickcomponents.

For definitions of toolbar buttons, see .Component Hierarchy Palette Toolbar

Properties Editor Palette

Each object has a predefined set of properties that define look-and-feel, on-screen position, andother characteristics. When a component is selected, its properties display in the PropertiesEditor palette. As you can see in the next figure, properties are name-value pairs.

7


To modify a property, do one of the following in the Properties Editor palette:

Type a value in the Value column.Right-click and choose a dynamic property value from the menu, if available. For moreinformation, see .Dynamic Properties FilesType a dynamic property key or a properties bundle key in the Value column. See

and .Dynamic Properties Files Properties Bundle FilesClick the down arrow in the Value column and select a value from the list, if available.

To learn more about properties in the Properties Editor palette, hover themouse over the property name or see General Interface GUI PropertyReference (Help > API Documentation > GUI Property Reference).

To modify a common property for multiple components, select multiple components in theComponent Hierarchy palette using Ctrl+click or Shift+click and set the property value. In thefollowing example, the three selected components have a common width property of 120. Ifproperty values are different, displays in the value field.[multiple values]

8


For more information on properties, see General Interface Component Guide.

Events Editor Palette

In addition to properties, objects can have model events. Model events are published inresponse to user actions, allowing your application to respond to user input. For example,when a user clicks a Cancel button in a dialog, an event specifies that the dialog closes and datais discarded

The Events Editor palette, as shown in the next figure, provides a set of model events for eachobject. Events are name-value pairs, where the value is a JavaScript statement.

To learn more about events in the Events Editor palette, hover the mouse over theevent name or see General Interface GUI Event Reference (Help > APIDocumentation > GUI Event Reference).

For more information, see General Interface Component Guide and Associating Code with an.Event

9


1.

2. 3.

4.

Attributes Editor Palette

You can use the Attributes Editor palette to add and edit HTML attributes for the componentselected in the Component Hierarchy palette.

HTML attributes change how the component is rendered when it's displayed in the browser.After using the Attributes Editor palette, you can view your changes in the Rendered HTML(Read Only) view of the work area.

If, for example, you add an attribute of name and value to a block, this HTML markupfoo bar

is added to the rendered HTML markup for the component selected in the ComponentHierarchy palette:

<div id= label= class= *foo= *"_jsx_1_3" "block" "jsx30block" "bar" style="position:relative;width:490px;height:516px; font-size:10px;;overflow:auto;font-family:Verdana;z-index:1; text-align:left;display:block;"/></div>

XSL Parameters Palette

The XSL Parameters palette is only available for components that implement , such as Menu, Tree, and Matrix components. The XSL Parameters palettejsx3.xml.Cacheable

allows you to add and edit XSL parameters that are passed to the XSL template, which rendersthe component as HTML.

To add an XSL parameter, complete these steps:

Select a component that implements in the Component Hierarchyjsx3.xml.Cacheable

palette or in the work area.Choose to open the palette.Palettes > XSL Parameters PaletteChoose a predefined parameter from the drop-down list or type the name of a newparameter in the Name field.

Type a value in the Value field.

10


4. 5.

Type a value in the Value field.Click the button .Add Attribute

To change an existing XSL parameter, select the Value field, change the value, and press Enter.

To remove a parameter, right-click a row and choose .Remove Parameter

For example, the XSL for the Matrix List prototype defines two parameters: and jsx_rowbg1

These parameters control the background color of odd and even numbered rowsjsx_rowbg2.

respectively.

To learn more about XSL parameters, see General Interface XSL Parameter Reference(Help > API Documentation > XSL Parameter Reference).

Recycle Bin palette

When you delete components from the work area or the Component Hierarchy palette, they'resent to the Recycle Bin and held in memory until the project is closed or the Recycle Bin isemptied. You can open the Recycle Bin from the Palettes menu and recover the components atany time during the project session.

Each open component editor maintains its own Recycle Bin, which is only visible when thecomponent is active. Whenever you close a component editor, close a project, choose Save andReload, Revert, Revert All, or navigate to another project in General Interface Builder, theRecycle Bin is emptied and the components can't be recovered.

To delete a single component, select a component in the Live Component view or theComponent Hierarchy palette. Press or use the button on theCtrl+Delete RecycleComponent Hierarchy palette toolbar.

To recover components from the Recycle Bin palette, choose select thePalettes > Recycle Bin,component to recover, and click the button on the toolbar. TheRestore Recycled Objectcomponents are restored to the Component Hierarchy palette and the Live Component view.

11


Local Data Cache Palette

The Local Data Cache palette provides access to all cached XML and XSL files for inspectionand updates. The Local Data Cache palette allows you to view and edit cached files. Modifiedfiles can be saved and reloaded with a single command.

For more information on caching, see .Handling Application Data

For definitions of toolbar buttons, see .Local Data Cache Palette Toolbar

System Log Palette

General Interface Builder uses the System Log palette to display system out messages from thesystem, as well as any logging messages in your JavaScript code. The system log handler,defined in the logging system configuration file, prints logging messages to the GeneralInterface Builder System Log palette in the IDE. For more information, see Understanding the

.Logging System Configuration File

12


1. 2.

3.

The System Log palette has the following features:

Docking optionsAdjustable log levels, such as , , , , , , or OFF FATAL ERROR WARN INFO DEBUG TRACE

Support for sound for messagesColor coding of messages, such as red for error messages

For definitions of toolbar buttons, see .System Log Palette Toolbar

For more information about logging, see .Logging and Application Monitors

Enabling Sound for Messages

The System Log palette supports sound for messages. This is turned off by default but can beenabled in the logging system configuration file, ./logger.xmlGI_HOME

To enable sound for messages,

Open located in the directory.logger.xml , GI_HOME

Change the property for the handler from to abeepLevel ide jsx3.util.Logger.OFF

logging level, such as . Sound is played for the specified loggingjsx3.util.Logger.ERROR

level and higher.For example, if the property is a sound playsbeepLevel jsx3.util.Logger.ERROR,

whenever error and fatal messages are reported. See .Log Levels

<property name= eval="beepLevel" "true" value= />"*jsx3.util.Logger.ERROR*"

Firefox requires a plug-in that can play .wav files.

Save .logger.xml

Customizing the IDE

General Interface Builder offers a fully customizable integrated development environment(IDE). You can modify IDE settings in the IDE Settings dialog. You can also customize theposition of the General Interface Builder palettes.

13


Specifying IDE Settings

In the IDE Settings dialog, you can modify General Interface Builder IDE preferences for thevisual authoring environment. The options in this dialog allow you to customize the IDE,modify and add keyboard shortcuts for menus, and set paths. Settings in this dialog are savedto ./settings/builder.xmlworkspace

To open the IDE Settings dialog, choose .Tools > IDE Settings

The IDE Settings dialog has several panels:

IDE Settings PanelIDE Hot Keys PanelPaths PanelGIPP and GITAK Panel

This section discusses some but not all of the available options. For more information, see IDE.Settings Dialog

IDE Settings Panel

On the IDE Settings panel, you can modify options for character encoding, set warnings,modify the snap-to spacing, and so on.

Character Encoding

General Interface Builder provides support for writing files in a specified character encoding,such as UTF-8 or UTF-16. The ability to choose a character encoding is particularly useful fordeveloping and localizing applications for multilingual environments.

General Interface Builder allows you to specify an encoding for all project files, as well asseparately specify an encoding for XML files.

14


1.

2.

3.

4.

5.

1.

General Interface Builder settings in the IDE Settings dialog allow you to:

Specify character encoding for all project filesSpecify character encoding for XML filesSpecify whether to add character encodings to XML declarationsSpecify the output line separatorTest the specified encodings to verify they can be written

For applications loaded from the local disk, such as General InterfaceBuilder, Firefox reads non-XML files that are encoded in a standard 8-bitencoding. Firefox can read local XML files in any encoding supported bythe host system only if the encoding is included in the XML declaration.

Modifying encoding options

To modify encoding options, complete the following steps:

Enter an encoding in the field. Click the button to verifyOutput character encoding Testthat the specified encoding is available on the system and can be written. If this field isempty, the default is used. This default is system-dependent.Select an output line separator. If this field is empty, the default is used. This default issystem-dependent.Check the checkbox if you want to use a different encodingInstead encode XML file asfor XML files. Enter an encoding. Click the button to verify that the specifiedTestencoding can be written and that it's available on the system.If this option is unchecked, XML files are written in the same encoding as specified in the

field or the default system encoding if that field is empty.Output character encodingCheck the if you want the encoding in theAdd character encoding to XML declarationXML declaration.Click or to save your changes.Save Apply

For Internet Explorer, encoding behavior varies according to MicrosoftWindows updates and security settings, which might need to be modified.UTF-16 and the default system encoding should be supported regardless.If the test fails for other encodings, you might need to enable the

object. See "How to disable the ADODB.Stream object fromADODB.Stream

Internet Explorer" at and reverse thehttp://support.microsoft.com/default.aspx?kbid=870669

instructions to enable it.

For descriptions of options on this panel, see .IDE Settings Panel

IDE Hot Keys Panel

On the IDE Hot Keys panel, you can add new hot keys and modify existing hot keys forGeneral Interface Builder menus. Hot keys are keyboard shortcut commands that activatemenus. For example, pressing Ctrl+N executes this menu command, File > New > GUIComponent.

To add or modify a hot key,

Double-click a row in the Menu list.

http://support.microsoft.com/default.aspx?kbid=870669

15


1. 2. 3. 4. 5.

1. 2.

3.

4. 5.

Double-click a row in the Menu list.Press the keys you want for the hot key, such as Ctrl+Alt+m.Click .SetClick to save the changes and close the dialog or click .Save ApplyUse the browser reload button to restart General Interface Builder for the changes to takeeffect.

To revert to the default hot key, double-click a row and choose .Use Default

Paths Panel

On the Paths panel, you can set the workspace path for your projects and the HTTP base pathfor running applications from a local HTTP server.

Workspace

The workspace is the directory that contains your projects, custom add-ins and prototypes, andyour user settings for General Interface Builder.

To modify the workspace path,

Open the IDE Settings dialog and click the Paths button.Click the Browse button next to the Workspace field to open the Choose Folderdialog.Navigate to a folder, select it, and click Click again to close the ChooseChoose. ChooseFolder dialog. You can also use the New Folder button to create a new folder.Click to save the changes and close the IDE Settings dialog or click .Save ApplyClick at the Restart Required prompt and use the browser reload button to restartOKGeneral Interface Builder.

HTTP Base

The path in the HTTP Base field is used when you select . ToProject > Run Project From HTTPuse this feature, you must have an HTTP web server, such as Apache, hosting both the GeneralInterface installation directory and your workspace directory.

To add an HTTP base, enter the base URI for the General Interface directory on a local HTTPserver. If this field is empty and you choose , you areProject > Run Project From HTTPprompted to enter a path.

If the relative path between the workspace directory and the General Interface directory isn'tthe same on the HTTP server as on disk, you must enter the relative path to the workspacedirectory in the WS Path field.

GIPP and GITAK Panel

On the GIPP and GITAK panel, you can specify the installation paths for the General InterfacePerformance Profiler (GIPP) and General Interface Test Automation Kit (GITAK). GIPP is aJavaScript profiling tool for benchmarking the performance of General Interface applications,and GITAK is a functional testing tool for testing General Interface applications. For moreinformation, see the General Interface Performance Profiler Guide and the General InterfaceTest Automation Kit User Guide.

16


Chat Panel

On the Chat panel, you can specify server and login settings for the Jabber client in GeneralInterface Builder. See .Jabber Support

Setting Palette Docking Options

Most palettes have a Docking Options button for customizing the palette. The optionsinclude moving the palette to a different quadrant of the General Interface Builder userinterface, floating the palette, and closing the palette. The System Log palette, which hasslightly different docking options, can be displayed at the bottom of the IDE, floated, opened ina separate browser window, or closed.

Docking settings are saved in your user settings and reloaded each time you open GeneralInterface Builder.

To access docking options, click the down arrow next to the Docking Options button .

To hide all the palettes, click the Show Edit Pane button on the General InterfaceBuilder taskbar.

Managing Projects

All development work in General Interface Builder is done in a project in the workspace.Projects are collections of files you create and edit in General Interface Builder. Project files aredisplayed in the Project Files palette and stored in the workspace.

Choosing a Workspace

The workspace is the directory that contains your projects, custom add-ins, custom prototypes,and your user settings for General Interface Builder.

The first time General Interface Builder launches after installation, a dialog prompts you tocreate or select a workspace directory. You can create a new directory, select an existingdirectory, or choose the default workspace directory. The default workspace location is

. You can use multipleC:\Documents and Settings\username\My Documents\TibcoGI

workspaces for your projects, as well as change workspaces.

For more information, see General Interface Getting Started.

Changing a Workspace

You can keep all of your projects in one workspace or use multiple workspaces. You canmodify the workspace location in the IDE Settings dialog. See .Workspace

17


1.

2.

3.

4.

Creating Projects

When you create a project, default files are created and opened in the work area: and logic.js

. The JavaScript file, is an empty file that you can add JavaScript codeappCanvas.xml logic.js,

to. The default GUI component file, , is where you can begin designing yourappCanvas.xml

application user interface.

To create a project, complete these steps:

Choose or click the link in the WelcomeProject > New Project Create a New Projectscreen (Help > Welcome Screen) to open the new project wizard.Choose General Interface Application as the project type, and click .Next

Choose the project template and click .Next

Specify a project path and click .Finish

18


3.

4. Specify a project path and click .Finish

A new project is loaded in the browser window. Two default, empty files are open in thecentral work area.

While building this sample application, all project data is stored locally inbrowser memory. The application is automatically saved to the filenotsystem. Save the project before you close or refresh the browser window.If you don't save the project, the data is lost.

Project Files and Folders

When you create a project, a project folder is created in the folder./JSXAPPSworkspace

The top-level project folder has the same name as your project. All project folders include thedefault subdirectories and files listed in the following table. This default structure can bemodified and additional folders can be created as needed. For example, you might createfolders for image, WSDL, and CSS files.

19


Project Files Description

config.xml Contains application configuration data, such as project settings and filelocations. See .Modifying Project Settings

launch.html Launches the application in the web browser. Use this file only duringdevelopment, not at runtime.

launch_in_ide.html Launches the application in General Interface Builder. Use this file onlyduring development, not at runtime.

To access project files and folders, click the link in the GeneralJSXAPPS/project_name

Interface Builder taskbar, located in the lower left area of the IDE.

ProjectFolders

Description

components Contains the XML files for application components. Each component has anassociated XML file with object definitions. For component files, use the .xmlextension. When you create a new project, a default component named

is created in this folder. See General Interface Component Guide.appCanvas.xml

js Contains included JavaScript files for your application. For JavaScript files, usethe .js extension. When you create a new project, a default file named logic.jsis created in this folder. See .Adding and Debugging JavaScript Code

jss Contains dynamic properties XML files. For dynamic properties files, use the.xml extension. See .Dynamic Properties Files

rules Contains mapping rules XML files for connecting to web services. Rules filesdefine the mappings between GUI components and SOAP message elements.For mapping rules files, use the .xml extension. See Basic Steps for

.Communicating with Data Services

xml Contains any XML files with content data, such as default values, for theapplication. For XML files, use the .xml extension.

xsl Contains any XSL files used for transforming application data. For XSL files,use the .xsl extension.

These project folder names are conventions only and not mandatory.

Saving Projects

When you save project files, General Interface Builder saves them to a project directory in the directory in the specified workspace directory. For example, JSXAPPS workspace

For more information on workspaces, see General Interface Getting/JSXAPPS/project_name.

Started.

There are several ways to save files in a project:

Right-click a file tab in the work area and choose , or .Save Save and Reload, Save As

Choose , , or .File > Save Save and Reload, Save As Save All

20


Choose , , or .File > Save Save and Reload, Save As Save AllFor a local data cache XML file, right-click a file tab in the work area and choose Save to

or .Cache Save a Copy to Disk

For menu definitions, see .File Menu

Running Projects

There are several ways to run a project:

Choose .Project > Run ProjectChoose .Project > Run Project from HTTPDouble-click the default launch file, , which is/launch.htmlworkspace/project_dir

generated when you create the project. Use this file only during development, not duringdeployment.

To run deployed applications, see .Deploying Applications

Running Projects from HTTP

To use this menu command, you must have an HTTP server, such as Apache, running locallyand hosting both the General Interface installation directory and your workspace directory. Formore information, see .HTTP Base

To run a project in a new browser window on a local HTTP server, choose Project > Run. If the HTTP server isn't configured, you are prompted to configure it.Project From HTTP

Opening Projects

There are several ways to open a project:

Choose the link in the Welcome screen (Help > WelcomeOpen an Existing ProjectScreen) and choose a project from the list.Choose and choose a project from the list. To open a GeneralProject > User ProjectsInterface sample project, choose and choose a sampleProject > User Projects > Samplesproject from the list.Choose and choose a recently opened project from the list.Project > Recent ProjectsDouble-click the default General Interface Builder launch file, workspace/ project_dir/launch_in_ide.html, which is generated when you create the project. Use this file tolaunch the project only during development, not at runtime.

You can also open multiple instances of the same project in different browsers, such as InternetExplorer and Firefox. However, because each instance is sharing the same preferences andsettings files, competing changes to General Interface Builder preferences may not be persisted.

Closing Projects

To close a project, simply close the browser.

21


Deploying Projects

To deploy a project, set deployment options on the Deployment panel of the Project Settingsdialog. Use the Deployment Utility to create a hyperlink to the deployed application. Then copyyour application files and General Interface software to an HTTP or HTTPS web server.

For more information, see the following:

Deployment PanelDeploying Applications

Modifying Project Settings

When you create a new project in General Interface Builder, a default configuration file isautomatically created as part of the project in the project directory: workspace

. The configuration file contains application configuration/JSXAPPS/project_dir/config.xml

data, such as project settings and file locations. Project settings include deployment, add-ins,class path, and legacy settings.

You can modify the project settings in the Project Settings dialog. Any changes you make in theProject Settings dialog are saved to the configuration file.

If you edit this file manually, close General Interface Builder before editing.

To open the Project Settings dialog, choose . To save your changes inProject > Project Settingsthe Project Settings dialog, click the or button.Apply Save

22


1.

2.

The Project Settings dialog has several panels:

Deployment PanelAdd-Ins PanelClasspath PanelLegacy Settings Panel

For more information on available options in the Project Settings dialog, see Project Settings.Dialog

Deployment Panel

Settings on this panel control the behavior of the deployed application. For definitions ofoptions not discussed here, see . For more information on deployment,Project Settings Dialogsee .Deploying Applications

Namespace

The General Interface runtime creates a single instance of a for each loadedjsx3.app.Server

application. The application namespace, which is a unique JavaScript identifier for the instance, provides access to the instance.jsx3.app.Server jsx3.app.Server

When specifying a namespace, it's recommended that you use the reverse-domain namingconvention with the dot symbol (.). For example . Using the reverse-domaincom.tibco.APP

naming convention reduces the likelihood that other JavaScript code will interfere with yourapplication.

To specify the namespace, complete these steps:

Choose to open the Deployment panel of theProject > Project Settings >DeploymentProject Settings dialog.Type the namespace in the Namespace field. For example, set the namespace to eg.chart.APP.

You can also override the namespace per deployment using the deploymentjsxappns

parameter. See .Deployment Parameters

Mode

The deployment mode for the deployed application can be set to Live or Static mode. SelectLive mode if the application needs to be online and is connected over HTTP/S to a server foronline data access.

Select Static mode when working offline. When in offline mode, the application can't access aserver. Data is static and is referenced using static URLs stored in rules files. Choose Staticwhen developing and testing an application offline or when a back-end web service isn'tavailable.

The Mode setting is used by the j class.sx3.net.Service

Body Hot Keys

Hot keys are keyboard shortcuts that an end user can use to interact with a GUI component,such as a button or menu, in a running application.

When the Body Hot Keys option is checked on the Deployment panel, any hot key event thatbubbles up to the HTML element is sent to the application. Even if the focus is in thebody

23


1. 2. 3. 4.

bubbles up to the HTML element is sent to the application. Even if the focus is in thebody

browser window and not in the General Interface application, the application receives the hotkey and responds to it. Choose this option for deployment of standalone console applications.See .Deploying as a Full Console Application

When the Body Hot Keys option is unchecked, hot keys only function if the focus is in theGeneral Interface application. This deployment choice prevents your application fromresponding to hot keys initiated in other General Interface applications on the page. Choose thisoption for deployment of non-console applications that are a portion of a web page. See

.Deploying as a Non-Console Application

onLoad Script

Enter one or more JavaScript statements that you want executed when the applicationinitializes. For example, you might want to execute a main method, communicate with a server,create controller objects by instantiating a controller class, or create the state of the application.For more information, see and .Executing Code When the Application Loads Deployment Panel

onUnload Script

Enter one or more JavaScript statements that you want executed when the browser window isunloaded. The onUnload event allows you to save user state and do any final cleanup beforeexiting. For more information, see and Executing Code When the Application Unloads

.Deployment Panel

For descriptions of other options on this panel, see .Deployment Panel

For more information on deployment, see .Deploying Applications

Add-Ins Panel

Use the Add-Ins panel to enable the Charting add-in or custom add-ins for a project. Add-insare disabled by default to accelerate load time of General Interface Builder and GeneralInterface applications.

Enabling Add-ins

To enable add-ins,

Choose to open the Project Settings dialog and click .Project > Project Settings Add-InsCheck the add-in you'd like to enable on the Add-Ins panel.Click to save the changes and close the dialog or click .Save ApplyClick at the Restart Required prompt and use the browser reload button to restartOKGeneral Interface Builder.

After add-ins are enabled, their prototypes are available in the Component Libraries palette inGeneral Interface Builder.

For more information on the Charting add-in, see General Interface Component Guide.

Custom Add-ins

For custom add-ins to display on the Add-Ins panel, they must be saved to the or JSX/addins

directory. Typically, add-ins to be used by a team of developers would be/addinsworkspace

saved to the directory and posted by an administrator to a location accessible to theJSX/addins

team. Add-ins for individual use can be saved to the directory./addinsworkspace

24


1.

2.

3. 4. 5.

For a tutorial on custom add-ins, see General Interface Component Guide.

Classpath Panel

The project class path is used by General Interface to find custom classes that are dynamicallyloaded by your application.

To add a class path, complete the following steps:

Click in the Path field and type the path to the classes.

The class path is relative to the project directory. For example, entering js/as the path would load the specified classes in the workspace

directory./JSXAPPS/project_dir/js

Press the Tab key and type the packages to load in the Packages field. For example, .com.tibco.*

Press Enter to commit the class path.Click to save the changes and close the dialog or click .Save ApplyUse the browser reload button to restart General Interface Builder for the changes to takeeffect.

To delete a class path, click the button next to the row.Delete

Path Packages Description

js/ com.tibco.* Loads classes with three words beginning with fromcom.tibco

the directory . For example,/JSXAPPS/project_dir/jsworkspace

this would load the class file workspace./JSXAPPS/project_dir/js/com/tibco/Object.js

js-ext/ com.tibco.ext.* Loads classes with four words beginning with com.tibco.extfrom the directory . For/JSXAPPS/project_dir/js-extworkspace

example, this would load the class file workspace./JSXAPPS/project_dir/js-ext/com/tibco/ext/Object.js

js-foo/ com.foo.** Loads all nested classes of from the directory com.foo workspace

./JSXAPPS/project_dir/js-foo/

js-foo2/ com.foo.*.* Loads classes with four words beginning with from thecom.foo

directory ./JSXAPPS/project_dir/js-foo2workspace

Work Area Editors

General Interface Builder has built-in editors for creating and editing files. Editors are availablefor the following file types:

GUI componentsXMLXSLJavaScript

CSS (Cascading Style Sheets)

25


1.

2.

3.

4.

CSS (Cascading Style Sheets)Dynamic propertiesProperties bundleMapping rules filesGIPP test casesGITAK test cases

Working with Files

To create a file, choose and select the file type you'd like to create. A new untitledFile > Newfile tab opens in the work area.

To save the file,

Choose or or right-click the file tab at the top of the work area andFile > Save Save Aschoose or .Save Save AsOptionally, browse to the recommended directory in the project. Choose forcomponents

GUI components, for JavaScript, for dynamic properties files, for propertiesjs jss xml

bundle files, for mapping rules files, for XML documents, and for XSLrules xml xsl

documents.Enter a file name and extension. Enter the extension for GUI components, XML,.xml

dynamic properties, and mapping rules files. Enter the extension for XSL files. Enter.xsl

the extension for JavaScript files and the extension for CSS files..js .css

Choose to close the Save File dialog.Save

Work Area View Support

The work area provides several views. The available views depend on what type of file is activein the work area.

The views include:

Live Component ViewGrid ViewSource ViewFormatted Source XML (Read Only) ViewRendered HTML (Read Only) ViewComponent Profile View

These views are available from the work area toolbar to the lower right of the work area asshown in the following figure.

26


Live Component View

The Live Component view is available for GUI components and is the graphical view of thecomponents in one component file of your application. You can drag and drop componentsfrom the Component Libraries palette into this view. You can also modify componentproperties in the Properties Editor palette and add event handlers in the Events Editor palette.The Component Hierarchy palette displays the hierarchical structure of the component file. Foran example of how to work with components, see General Interface Getting Started.

Grid View

The Grid view is available for dynamic properties files and properties bundle files. You canuse dynamic properties files, which are XML resource files, to create custom properties forcomponents. Properties bundle files are XML resource files used to localize your application fora specific language and country.

For more information, see . See and Dynamic Properties Files Properties Bundle Files.Internationalizing and Localizing Applications

Source View

The Source view is available for all file types and displays the editable source for XML filesand text files, such as JavaScript and CSS files. For components, the Source view displays theXML source of the component serialization file.

Formatted Source XML (Read Only) View

The Formatted Source XML view displays XML source in an easy-to-read format withsyntax highlighting. For example, attributes and values are in different colors than elementnames. This view is read-only and is available for all component files and XML files, includingXSL, dynamic properties files, and properties bundle files.

Rendered HTML (Read Only) View

The Rendered HTML view displays the HTML that will be used to render the component(s)in the browser. This view is read-only and is available only for GUI components.

When running General Interface Builder in HTML and XHTML mode, well-formed HTML,

27


When running General Interface Builder in HTML and XHTML mode, well-formed HTML,which is XHTML, is pretty-printed in the Rendered HTML (Read Only) view. If the markupisn't well-formed, pretty printing isn't used and a parsing error displays in the System Logpalette.

For example, if you entered HTML without a closing element in the Text/HTML property for alabel, such as , a mismatched tag error message displays in the System Log palette<b>My Label

and the Rendered HTML (Read Only) view isn't pretty-printed. If you entered valid XHTMLwith open and close elements, such as no error is reported and the Rendered<b>My Label</b>,

HTML (Read Only) view is pretty-printed.

Component Profile View

The Component Profile view allows you to define the profile of a component. This view isavailable only for GUI components.

Here you can assign a name, description, and icon URL for the component. This is useful ifyou're creating custom components and exporting them to the Component Libraries palette (

/ ). The icon displays next to the name of the component in theworkspace prototypes

Component Libraries palette and the description displays as a tooltip.

Modifying a Component at Runtime

The onBeforeDeserialization and onAfterDeserialization text areas can be used to specifyJavaScript to execute before or after the object is deserialized. If the component is loaded atruntime, the code is executed immediately before the XML is converted into JavaScript objectsor after the JavaScript objects are instantiated and bound to the GUI model.

Executing JavaScript code before an object is deserialized is useful when the runtime needs tobe prepared before the component is loaded, such as preloading data for the component.Executing JavaScript code after an object is deserialized is useful when the component needs tobe initialized with information only available at runtime. For example, you might want tomodify the CDF for a Matrix list component and then re-populate the list after it displayson-screen.

JavaScript code entered in the onBeforeDeserialization text area has access to the contextobjXML

variable, which is an instance of . The context variable represents thejsx3.xml.Document objXML

serialization file in-memory and the namespace prefix resolves to the namespace for thejsx1

file (in this case, urn:tibco.com/v3.0).

For example, if you have a Block in your serialization file named and you want to changefoo

the background color to red, you could put the following code in the onBeforeDeserializeevent:

objXML.setSelectionNamespaces("xmlns:jsx1='" + jsx3.app.Model.CURRENT_VERSION + "'");

objNode =var objXML.selectSingleNode("//jsx1:object\[@type='jsx3.gui.Block']/ jsx1:strings\[@name='foo']");

(objNode) {if objNode.setAttribute("jsxbgcolor","red");}

The event provides direct access to the actual model objects, after they areonAfterDeserialize

deserialized but before they are rendered on-screen. In this example code, the background of

Block is rendered in red after the object is created:foo

28


Block is rendered in red after the object is created:foo

var objBlock = objJSX.getDescendantOfName("foo");(objBlock) {if

objBlock.setBackgroundColor("red");}

Note that the variable, which is an instance of , points to theobjJSX jsx3.app.Model

root object in the serialization file.

For more examples, see .Executing Code Before or After Deserialization

Dynamic Properties Files

Dynamic properties are XML resource files that contain externalized strings as name-valuepairs. This feature enables you to organize the styles and text used by the application in acentralized location for easier application maintenance. Dynamic properties can be used forlocalization and for IDE lookup values. Properties bundle files are also used for localization. Formore information, see .Properties Bundle Files

When authoring dynamic properties and properties bundle files using non-ASCIIcharacters and non-western languages, save the file in a format that supports suchcharacters, such as UTF-8 or UTF-16. See .Character Encoding

General Interface has built-in dynamic properties that you can use. These built-in dynamicproperties begin with an @ symbol. You can also create your own custom dynamic propertiesfiles using the Dynamic Properties editor.

General Interface and custom dynamic properties are available on the context menu in theProperties Editor palette as shown in the following figure. To assign a dynamic property,right-click in the Properties Editor palette and select a dynamic property. You can also type theproperty key (ID) in the Value cell, such as @Dialog BG for the BG Color property. After adynamic property is selected, the explicit value displays in the Value field next to the name ofthe dynamic property.

29


1. 2. 3.

Creating Dynamic Properties Files

To create a dynamic properties file in General Interface Builder,

Choose . A visual editor displays in the work area.File > New > Dynamic Properties FileEnter a name for the property in the ID field.To select a type, click in the Type column and choose a type from the drop-down list orbegin typing the name, such as , to see the list of matches.jsxb

30


3.

4.

5.

6.

7.

8.

1.

Enter a value for the type in the Value field. If the value is JavaScript code, check theEval checkbox.Values can be text or JavaScript code. For more information on entering JavaScript code,see . For information on CSS values, see GeneralSpecifying Code in Dynamic PropertiesInterface Component Guide.For example, you might want to add a custom color for the BG Color property. Enter aname for the property, such as . Select as the type and enter abluebgcolor jsxbgcolor

color value, such as .#6E6CEF

You can use the Color Picker to choose a color. Choose or click the Tools > Color Picker button in the Properties Editor palette.Color Picker

Continue to edit values and do the following as needed to set up the list of properties: To add a new row, press Enter, click the Add button , or right-click a row andchoose . Insert New RecordTo delete a row, select a row and click the button .Delete

Choose or right-click the work area tab and choose File > Save and Reload Save and.Reload

Browse to the folder of your project and enter a file name with the .xml extension.jss

For dynamic properties files, be sure to use the .xml extension as someservers won't recognize the .jss extension used in previous releases. Bydefault, General Interface, version 3.2 and higher, supports the .xmlextension, which is the recommended file extension.

Click in the Save File dialog.Save

Loading and Using the Dynamic Properties File

To load the dynamic properties file and apply properties to a component, complete thefollowing steps:

Set the dynamic properties file to automatically load with the application, so the new

31


1.

2.

3.

Set the dynamic properties file to automatically load with the application, so the newproperties are always available. Right-click the dynamic properties file in the ProjectFiles palette and choose .Auto LoadReturn to the Live Component View and select the component you want to apply theproperty to in the Component Hierarchy palette or in the work area.Find the property you added in the Properties Editor palette, such as BG Color, andright-click the Value cell to invoke the lookup list of property values. The property valueyou added displays on the list.

Properties Bundle Files

The Properties Bundle editor is used to create and edit properties bundle files, which are usedto localize your application for a specific language and country. A locale is a region of the worldthat shares a common language, writing, calendar, and so on.

When authoring dynamic properties and properties bundle files using non-ASCIIcharacters and non-western languages, save the file in a format that supports suchcharacters, such as UTF-8 or UTF-16. See .Character Encoding

Properties bundle files, also known as resource bundles, contain locale-specific objects, such asmenu and button labels in the application user interface. When these strings are externalized inthe properties bundle files, it's easier to translate applications into other languages. Theapplication simply loads the locale-specific resource appropriate for the user's locale.For more information on localizing, see .Internationalizing and Localizing Applications

Mapping Rules Files

Mapping rules files are XML files that define mappings between application objects and dataelements or CDF documents and data elements. Mapping rules files are created with the XMLMapping Utility. For more information, see .Communicating with Data Services

GIPP Test Cases

GIPP test cases are used with the General Interface Test Recorder. For more information, see .Using the Test Recorder

GITAK Test Cases

GITAK test cases are used with the General Interface Test Recorder. For more information, see .Using the Test Recorder

Component Libraries Palette and the Online Repository

General Interface Builder provides an interface for the online component repository hosted onGeneralInterface.org. This repository allows you to share components with theGeneralInterface.org community. You can upload components to the repository for subsequentdownload and use by other developers and you can browse and download componentsuploaded by other developers from around the world.

The interface to the component repository is in the Component Libraries palette in Builder. The

Component Libraries palette includes the following tabs:

32


1. 2. 3.

4.

Component Libraries palette includes the following tabs:

System tab: A tree that shows all of the built-in system components. These files arestored at the path .GI_HOME/GI_Builder/prototypes

User tab: A tree that shows the components that the current user has created in theirlocal GI workspace. Components downloaded from GeneralInterface.org are also savedhere. These files are stored at the path . GI_WORKSPACE/prototypes

Online tab: List of the shared components that have been previously uploaded toGeneralInterface.org.

Saving a Component to the Workspace

A component must exist in the GI workspace before you can upload it to the online repository.To save a component to the GI workspace:

Open an existing component or create a new component in General Interface Builder.Choose .File > Save a Copy to LibraryEnter a name for the file and save it in the directory. You can save it to anyprototypes

nested folder as long as it is contained within .prototypes

To display the component in the Users tab of the Component Libraries palette, click the icon.Reload

The component is now available for upload.

To create new component folders in your workspace, click the icon and enterNew Folder

the folder name. To remove components, select the components and click the icon.Delete

33


1.

2. 3. 4.

5. 6.

1.

2. 3.

Uploading a Component to the Online Repository

For each component that you upload, you must agree to the General Interface termsof service .http://www.generalinterface.org/terms.html

To upload a component to the GeneralInterface.org online repository

Select the component on the User tab in the Component Libraries palette.

Click the icon.Upload ComponentEnter a name and description.Select the check box to agree to the General Interface terms of service. To review theterms of service, click the underlined link.Click .UploadIf you are not already logged in, you will be prompted to enter your user name andpassword. Log in, then click again.Upload

The component is uploaded and summary infomation is presented. If you have any customcode in the application, Dojo Foundation staff will review the code before making it available toothers.

To view an uploaded component, open the Online tab. Click the icon and chooseFiltersfiltering option as needed to display the component.

Downloading Components from the Online Repository

To download previously uploaded components:

Open the Online tab in the Component Libraries palette.

Click the icon and to choose how to filter the list of components.FiltersDrag and drop the component to the canvas or to the desired level in the ComponentHierarchy.

Using the Online Tab

The Online tab of the Prototype Libraries palette supports the options described in this section.

Refreshing the Display

Clickt the icon on the User or Online tab to reload the current list of components.Refresh

Displaying Component Details

On the Online tab, you can display component details by double-clicking the component entry.

To return to the component list, click the icon.List

Using Filters

The following filter options are available by clicking the icon.Filters

Function Description

http://www.generalinterface.org/terms.html

34


All Show all available components.

Featured Show the components that the Dojo Foundation is currently featuring.

Rating Show the user ratings along with the component name.

Downloads Show the number of times that the component has been downloaded.

User Show the login name of the user who uploaded the component.

Date Show the date that the component was uploaded.

Using Feeds

The following options are available by clicking the icon. To view these options, youFeedsmust be subscribe to Live Bookmarks. If you are not subscribed, you are prompted to do sowhen you first choose a Feeds option on the Online tab.

Function Description

Top Rated Show the components with the highest user ratings.

Most Popular Show the components that have been downloaded most frequently

Most Recent Show the components that were uploaded most recently

Data and Cache Management

At the most basic level, a General Interface application consists of files stored on the file system.The formats of application files are industry-standard, such as XML, XSL, and CSS. You can useviewing and editing features built into General Interface Builder or you can use externaleditors.

General Interface Builder provides the following XML editing and management features:

Access to all component XML files for inspection and updates. Buttons to the lower rightof the work area provide multiple views of each component, including an editable XMLview. Component definitions can be refreshed using the toolbar on the ComponentHierarchy palette.Access to all cached XML and XSL files for inspection and updates. The Local DataCache palette allows you to view and open cached files for editing. Modified files can besaved and reloaded with a single command.

35


XML/XSL Merge Tool is used for testing the text, HTML, or XML output from a mergeoperation. You can view both the parsed output and its source. If parsing errors occur,error notification is provided. You can open multiple instances of this tool.

Character-level debugging that helps you identify the location of any XML parsingerrors.

Data Connection and Mapping

General Interface software is designed to interface with industry-standard web protocols.

XML Mapping Utility

The XML Mapping Utility provides a visual environment for configuring and testing dataservices including data mapping, testing, and off-line development.

To open the XML Mapping Utility, choose .Tools > XML Mapping Utility

36


To open the XML Mapping Utility, choose .Tools > XML Mapping Utility

For more information on the XML Mapping Utility, see andCommunicating with Data Services.Communicating with a Web Service Tutorial

Visual Bindings

The XML Mapping Utility provides a visual interface for mapping GUI components to dataservices. You can use drag-and-drop to create bindings for inbound and outbound SOAPmessages and XML documents. XML elements can be bound to the values of GUI objects, nodesin XML documents, and JavaScript variables. All mapping information is stored in an XML filereferenced in the project. If modifications are needed, you reopen this file in the XML MappingUtility.

Testing

When mappings are complete, the interaction with the data service can be tested. You canpreview the outbound message before it is sent, test the message against the live service,preview the response message, and enter a callback script to execute when the response isreceived.

Decoupled Web Service Development

For tight project timelines, avoiding sequential dependencies is critical to project success.General Interface Builder is designed to allow parallel development of back-end and front-endapplications. Back-end data services do not need to be complete or accessible for applicationdevelopment to begin. You can save a representative snapshot of server data on the local filesystem. During testing, the live web service environment can be simulated using this storeddata. An application can even be deployed using static data, then reconfigured when theback-end service becomes available.

37


Additional Visual Tools

Additional protocols and interactions are supported using the General Interface APIs. For moreinformation on designing interactions, see the online API documentation in General InterfaceBuilder.

For General Interface feature updates and examples to assist the application developmentprocess, visit Developer Network at .http://www.generalinterface.org

Jabber Support

General Interface Builder includes a Jabber client, allowing you to participate in chats fromwithin Builder. The client is implemented on top of the Dojo XMPP library. It works with Jabberservers that support the Jabber HTTP Bind protocol, such as .OpenFire

An OpenFire server is available for use at http://chat.generalinterface.org. Sign in with yourDojo Foundation .account credentials

The Jabber client in Builder feature supports the following actions:

Adding and removing buddies

Assigning nicknames to buddies

One-to-one conversations

Online/away/offline buddy statuses

To configure your Jabber settings, open the IDE Settings window, as described in Customizing.the IDE

When Jabber is configured, you can open the Chat palette from the Palettes menu.

General Interface Documentation

General Interface provides the following documentation to assist you as you develop yourGeneral Interface applications:

Product documentation

Context-sensitive help

Spyglass help

API documentation

Online documentation, forums, samples, and other resources at .http://www.generalinterface.org

http://www.generalinterface.org

http://www.igniterealtime.org/projects/openfire/

http://www.generalinterface.org/docs/display/DOC/Accounts+and+Registration


38


Product Documentation

Product documentation is available online at .http://www.generalinterface.org/docs/display/DOC/Learning+Center

Context-sensitive Help

To access context-sensitive help in General Interface Builder, move focus to an area of the IDE,such as a dialog, editor, or palette, and press or click the Help button .Alt+F1

To implement context-sensitive help in your applications, see Implementing Context-Sensitive.Help

Spyglass Help

Documentation is also available in a spyglass in various areas of General Interface Builder. Aspyglass contains descriptive text in HTML and can contain more information than a tooltip. Toinvoke a spyglass, hover the mouse over the following areas in the IDE:

Property names in the Properties Editor palette

Model event names in the Events Editor palette

APIs icon in the Settings panel of the XML Mapping Utility

You can also add spyglass documentation to your own applications using the Spyglass event and the spy methods in the interface. For more information, see(jsxspy) jsx3.gui.Interactive

General Interface API Reference.

API Documentation

Online API documentation is available online at .http://www.generalinterface.org/docs/display/DOC/API+Documentation

Further Information on General Interface Basics

For more tutorials and sample applications, see:

General Interface samples — /JSXAPPS/samplesworkspace

Developer Network at http://www.generalinterface.orgSample Projects Video Tutorials

http://www.generalinterface.org/docs/display/DOC/Learning+Center

http://www.generalinterface.org/docs/display/DOC/API+Documentation


39


Chapter 3 General Interface Framework Basics

This chapter discusses the basics of General Interface Framework, which is the runtime forGeneral Interface applications.

Class Loading in General InterfaceURI ResolutionCustom Document FormatsCommon Data Format (CDF)Flexible CDF SchemaCommon Interface Format (CIF)Common Exchange Format (CXF)

Class Loading in General Interface

General Interface Builder uses dynamic class loading for increased performance and acceleratedload time. Dynamic class loading causes classes to be loaded as they're needed at the lastpossible moment. Since only statically loaded classes are loaded at application startup, theapplication loads much faster.

The classes distributed with General Interface are partitioned into two categories:

Statically loaded classes that are always loaded by General Interface at applicationstartupDynamically loaded classes

For a list of statically loaded system classes, see .General Interface Framework Classes

How Classes are Loaded

As a General Interface application loads, General Interface Framework statically loads a subsetof the system classes. Next, application classes and application code using the Auto Loadoption are statically loaded. Finally, all other classes are loaded using the dynamic class loadingmechanism. The following table provides an overview of how classes are loaded.

40


ClassLoadingType

General InterfaceClasses

Application Classes Application Code

Staticallyloaded

Classes automaticallyloaded by GeneralInterface. See the nexttable.

Auto Load enabled. Auto Load enabled.

Dynamicallyloaded

Load other GeneralInterface classes using

orjsx3.require()

automatically withdeserialization.

Auto Load disabled. Addcustom classes to class path.Load class using

orjsx3.require()

automatically withdeserialization.

Auto Load disabled.Load code using Server.loadResource().

General Interface Framework Classes

The General Interface runtime system, General Interface Framework, always statically loads theclasses listed in the following table as the application initializes.

All other system classes, such as Matrix, must be loaded dynamically using the require()method or through deserialization. See .jsx3.require() Method

jsx3.app.AddIn jsx3.app.Cache jsx3.app.DOM

jsx3.app.Model jsx3.app.Properties jsx3.app.PropsBundle

jsx3.app.Server jsx3.app.Settings jsx3.gui.Alerts

jsx3.gui.Alerts jsx3.gui.Block jsx3.gui.Event

jsx3.gui.Heavyweight jsx3.gui.HotKey jsx3.gui.Interactive

jsx3.gui.Painted jsx3.lang.Class jsx3.lang.Exception

jsx3.lang.Method jsx3.lang.NativeError jsx3.lang.Object

jsx3.lang.Package jsx3.net.Request jsx3.net.URI

jsx3.net.URIResolver jsx3.util.DateFormat jsx3.util.EventDispatcher

jsx3.util.List jsx3.util.Locale jsx3.util.Logger

jsx3.util.MessageFormat jsx3.util.NumberFormat jsx3.xml.CDF

jsx3.xml.Document jsx3.xml.Entity jsx3.xml.Template

Application Classes

To statically load your application class files as the application loads, enable the Auto Loadoption for the JavaScript files in the Project Files palette. For more information, see Enabling the

.Auto Load Option

To dynamically load custom application classes when the Auto Load option is off, classes must

meet the following requirements:

41


1. 2.

meet the following requirements:

The classes must be on the class path, so the system class loader can find the classes. See .Specifying Class Paths

The method must be used to load classes explicitly that are not loadedjsx3.require()

automatically by the component through deserialization. See .jsx3.require() Method

Application Code

To statically load your application code as the application initializes, enable Auto Load for theJavaScript files in the Project Files palette. For more information, see Enabling the Auto Load

.Option

If you don't want the application code statically loaded, you can load it dynamically using the method. This method looks up a resource registered with theServer.loadResource()

application by its id. The resource must be registered in the file of the application.config.xml

For more information, see General Interface API Reference.

Enabling the Auto Load Option

To statically load JavaScript files as the application initializes, you can enable the Auto Loadoption for individual JavaScript files in your project. When a JavaScript file is set to auto load,the file is statically loaded after the Framework classes are loaded.

To enable the Auto Load option for one or more JavaScript files in your project, complete thesesteps:

Right-click a JavaScript file in the Project Files palette.Choose Auto Load from the context menu. The file name now displays in bold in theProject Files palette.

When you enable the Auto Load option, the attribute for the JavaScript file is set to onLoad true

in the application configuration file ( ).config.xml

42


<record jsxid= type= >"1" "map" main_js<record jsxid= type= >"id" "string" </record> script<record jsxid= type= >"type" "string" </record> true<record jsxid= type= >"onLoad" "boolean" </record> js/logic.js<record jsxid= type= >"src" "string" </record></record>

jsx3.require() Method

The method can be used to load classes explicitly. Use the fully qualified classjsx3.require()

name when using the method. For example,jsx3.require()

jsx3.require("jsx3.net.Form");

Only classes that can be found by the system class loader are loaded. Custom classes can beadded on the Classpath panel of the Project Settings dialog. See .Specifying Class Paths

When a component file is deserialized, the class of each object encountered in the file isdynamically loaded if it's not already loaded. Therefore, it's often not necessary to use the

method with classes that descend from jsx3.app.Model. However, if JavaScriptjsx3.require()

code references these classes and if the code executes before a deserialization automaticallyloads the class, you must use the method to explicitly load the class.jsx3.require()

The method must be called at least once before making these types ofjsx3.require()

references:

A static reference to a class descending from (typically ).jsx3.gui.Model jsx3.gui.**

Any references to subclasses of that execute before the class is loaded throughModel

object deserialization.

Specifying Class Paths

If you've created custom classes, you need to specify the class paths, so the system class loadercan find the classes. Class paths are set on the Classpath panel of the Project Settings dialog.Class paths are saved as settings in the application configuration file, , and areconfig.xml

deployed with the project.

For specifics on setting class paths, see .Classpath Panel

Classes must be located in the same directory structure as the package name. See .Class Naming Conventions

43


Class Naming Conventions

The following file and directory naming conventions for classes are required only for dynamicclass loading. For classes that aren't dynamically loaded, these naming conventions are arecommendation only.

The JavaScript class file name should be identical to the class name with a .js extension. Forexample, a class named would be saved as . The directory structure ofSomeClass SomeClass.js

the class file must match the package name that the class is in. For example, if SomeClass.js isin a package and is saved to a directory in the project, the class file location shouldcom.tibco js

be .js/com/tibco/SomeClass.js

URI Resolution

This section describes how URIs are resolved in General Interface. A Uniform ResourceIdentifier (URI) identifies or names a resource required by the application.

The URI functionality of General Interface has been updated to provide additional functionalityand to simplify development. Project resources are now referenced by the project configurationfile ( relative to the base directory of the project. Referencing resources in theconfig.xml)

configuration file allows you to rename and move project directories more easily.

Any relative URI that isn't of a legacy 3.1 format (beginning with or ) is resolvedJSX/ JSXAPPS/

relative to a base URI that depends on the context of the URI. General Interface 3.1 applicationsperform as expected in version 3.2 and higher. However, it is strongly recommended that youupdate your applications to take advantage of the relative URI functionality.

44


1.

2.

Using URIs in General Interface Builder

In General Interface, version 3.1, URIs that referenced resources contained in a project directorywere of the following form:

JSXAPPS/appname/subfolders/filename.xml

The version 3.1 format is still valid in version 3.2 and higher, because URIs beginning with are handled in a special manner. As of version 3.2, these URIs can be written relativeJSXAPPS/

to the base directory of the project. The previous example can now be written as follows to takeadvantage of relative paths:

subfolders/filename.xml

In General Interface Builder, version 3.2 and higher, any property editable in the PropertiesEditor palette can accept a relative URI, which is resolved relative to the project directory. Forexample, these properties accept relative URIs: the Image property for ToolbarButton and theXML URL property for List. URIs that appear in free form properties, such as Text/HTML forBlock, are never resolved. URIs set as values of attributes in the Attributes Editor are also notresolved.

In summary, the URI requirements in General Interface Builder, version 3.2 and higher, includethe following:

All properties editable in the Properties Editor palette that expect a path (XML URL,Image URL, and so on) can take an absolute path or a path relative to the projectdirectory.All other inputs (HTML attributes, free-form HTML) have to be pre- resolved staticallyor using the URIResolver API. See .URI Resolvers

Using dynamic properties is one way of externalizing these paths. Be certain that values storedin the dynamic property agree with the requirements described above, depending on how theyare used.

To reference a resource that is located outside of the project directory, use a relative URIstarting with one or more "../" tokens or one of the supported absolute URI formats. See URI

.Format Support

Using URIs with the General Interface API

When using URIs in JavaScript with the General Interface APIs, it's important to understandhow each API resolves any URIs sent to it. For example, the methodjsx3.app.Model.load()

resolves URIs relative to the project directory of the application that the Model instance isowned by. For more information, see General Interface API Reference.

URI Format Support

The following URI formats are considered to be absolute in General Interface. They alwaysresolve to the same location regardless of what they are resolved against.

For more information on the element, query parameters, and deployment parameters,script

see .Deployment Parameters

45


URI Format Description

JSX/... Legacy format for General Interface 3.1. Resolves relative to theparent of the directory as determined by the location of the JSX

script. If multiple elements are used in one HTMLJSX30.js script

page, the URL for the script file be the same.JSX30.js must

JSXAPPS/... Legacy format for General Interface 3.1. Resolves relative to theparent of the directory, as determined by the JSXAPPS jsxapppath

query parameter of the attribute of the elementsrc script

referencing the . If multiple elements are usedJSX30.js script script

in one HTML page, the applications be located in the same must directory.JSXAPPS

GI_Builder/... Legacy format for General Interface 3.1. Resolves as whenJSX/...

General Interface Builder is running. Applications should notreference any URIs of this format, because the directoryGI_Builder

can't be deployed under the standard licensing terms.

jsx:///... Format for General Interface 3.2 and higher. Resolves relative to the directory as determined by the location of the script.JSX JSX30.js

jsxaddin://addin/... Format for General Interface 3.2 and higher. Resolves relative to thebase directory of the add-in specified by the host portion ( of)addin

the URI. The host portion of the URI follows the double forwardslashes (//). The host of the URI should be the add-in key (

) with any colon characters (:) replaced with anAddIn.getKey()

exclamation point (!). The add-in must be loaded for the URI toresolve correctly.

jsxuser:///... Format for General Interface 3.2 and higher. Resolves relative to theparent of the directory (workspace). When General InterfaceJSXAPPS

Builder is running, this URI resolves relative to the workspacedirectory.

jsxapp://app/... General Interface 3.2 and higher format. If the Server instancecorresponding to the host portion of the URI is loaded into memory,the URI is resolved relative to the application base directory (

). The host portion ( of the URI is the relative pathjsxappbase )app

from the directory to the application base directoryJSXAPPS

containing the file with any forward slashes (\/) replacedconfig.xml

with exclamation points (!). If the Server instance isn't loaded intomemory, the URI resolves relative to the directory containing the

of the application. You can override the applicationconfig.xml Note:base directory ( ). See jsxappbase Overriding the Application Base

.Directory

Additionally, any URIs specifying a scheme or an absolute path (beginning with a forwardslash) are also considered absolute and will not be modified.

Any other URI is considered relative and will be resolved by a URI resolver depending on thecontext in which it is encountered.

46


URI Resolvers

General Interface, version 3.2, introduces a new interface, . An object thatjsx3.net.URIResolver

uses relative URIs must implement methods in the interface to define a contextURIResolver

against which those URIs are resolved. Two classes, and ,jsx3.app.Server jsx3.app.AddIn

implement this interface. The class uses the URI scheme and the class usesServer jsxapp: AddIn

the URI scheme described previously. Additionally, static resolvers are provided forjsxaddin:

the and schemes. For more information, see General Interface API Reference.jsx: jsxuser:

Custom Document Formats

General Interface applications use custom document formats to store and process data, storemapping rules, and to define GUI components.

Common Data Format

Common Data Format (CDF) is used by General Interface to store data. A CDF documentprovides a common format for sharing data among components, transferring data betweenclient controls, and performing data mapping. See . Support is alsoCommon Data Format (CDF)provided for flexible CDF schema. See .Flexible CDF Schema

Common Exchange Format

Common Exchange Format (CXF), which is based on CDF, is used to store mapping rules toand from CDF and GUI components. CXF documents are created at design time by the XMLMapping Utility from source documents, such as WSDL, Schema, XML, and XHTML. CXFprovides a common format for connecting to and exchanging data with disparate systems andservices. At runtime, CXF is used to perform the actual interactions. See Common Exchange

.Format (CXF)

Common Interface Format

Common Interface Format (CIF) is a serialization format used to define components.jsx3.gui

The CIF format provides improved readability and smaller file size. See Common Interface.Format (CIF)

Common Data Format (CDF)

Common Data Format (CDF)

The Common Data Format (CDF) is an XML Schema that provides an abstraction layer forclient data. It allows components of an application to use a single data format. Benefits includethe ability to share data among components, reliably transfer data between client controls usingdrag-and-drop, and perform data mapping. Component data can be inserted or updatedwithout using XSLT. The interface also defines a common set of methods forjsx3.xml.CDF

manipulating data. The class, which implements the CDF interface, canjsx3.xml.CDF.Document

also be used to expose the CDF convenience methods on an XML document.

Components that consume structured data require CDF. These components include:

Menu

47


MenuTreeSelect and ComboMatrixCharting

There are two ways to work with CDF documents:

Through a CDF component, such as Matrix and TreeDirectly with the API. See the class in the online API help injsx3.xml.CDF.Document

General Interface Builder.

CDF Schema

The CDF schema is described by the following XSD:

48


<?xml version= ?>"1.0"<xsd:schema = >xmlns:xsd "http://www.w3.org/2001/XMLSchema" <xsd:element name= >"data" <xsd:complexType> <xsd:sequence> <xsd:element type= name="cdfrecord" "record" maxOccurs= minOccurs= />"unbounded" "0" </xsd:sequence> <xsd:attribute name= >"jsxid" <xsd:simpleType> <xsd:restriction base= >"xsd:string" <xsd:enumeration value= />"jsxroot" </xsd:restriction> </xsd:simpleType> </xsd:attribute> </xsd:complexType> </xsd:element>

<xsd:complexType name= >"cdfrecord" <xsd:sequence> <xsd:element type= name="cdfrecord" "record" maxOccurs= minOccurs= />"unbounded" "0" </xsd:sequence> <xsd:attribute name= type= />"jsxtip" "xsd:string" <xsd:attribute name= type= />"jsxvalue" "xsd:string" <xsd:attribute name= type= />"jsxdivider" "xsd:string" <xsd:attribute name= type= />"jsxtext" "xsd:string" <xsd:attribute name= type= />"jsxstyle" "xsd:string" <xsd:attribute name= type= />"jsxkeycode" "xsd:string" <xsd:attribute name= type= />"jsxunselectable" "xsd:string" <xsd:attribute name= type= />"jsxexecute" "xsd:string" <xsd:attribute name= type= />"jsxgroupname" "xsd:string" <xsd:attribute name= type= />"jsximg" "xsd:string" <xsd:attribute name= type= />"jsxselected" "xsd:string" <xsd:attribute name= use= type= />"jsxid" "required" "xsd:string" </xsd:complexType>

</xsd:schema>

The CDF schema is an open schema that can be extended using custom entities and attributes.In the following example, the and attributes are system attributes with specialjsxtext jsxid

meaning. The attribute is required for a record in the CDF. This attribute acts as a key andjsxid

should be a unique value. The and attributes are custom, developer-definednumber name

attributes.

49


<?xml version= ?>"1.0"<data name= jsxroot">"" number="" jsxid=" <record name= number= jsxid= jsxtext="Select a"a" "0" "null" State"/> <record name= number= jsxid= jsxtext= />"b" "1" "AL" "ALABAMA" <record name= number= jsxid= jsxtext= />"c" "2" "AK" "ALASKA" <record name= number= jsxid= jsxtext= />"d" "3" "AZ" "ARIZONA" <record name= number= jsxid= jsxtext= />"e" "4" "AR" "ARKANSAS" <record name= number= jsxid= jsxtext= />"f" "5" "CA" "CALIFORNIA" <record name= number= jsxid= jsxtext= />"g" "6" "CO" "COLORADO" <record name= number= jsxid= jsxtext= />"h" "7" "CT" "CONNECTICUT" <record name= number= jsxid= jsxtext= />"i" "8" "DE" "DELAWARE" ... <record name= number= jsxid= jsxtext= />"Y" "50" "WI" "WISCONSIN" <record name= number= jsxid= jsxtext= />"Z" "51" "WY" "WYOMING"</data>

CDF Structural Elements

CDF documents consist of an XML declaration and a element that contains all records.data

Usually, the element also contains at least one element with attributes.data record

Depending on the component, a record can represent a table row, a node in a tree, a menu item,and so on. Although the element isn't required, at least one record is required for a CDFrecord

component to display data.

Hierarchical structures, such as submenus, can also be defined by nesting records withinrecords. Entities by any other name, such as a node named as opposed to , are notlookup record

displayed on-screen, but can be useful for organizing information within the CDF model. Ifadditional hierarchies are described by nesting records, the view displays these where relevant.Currently, the Matrix, Menu, and Tree controls visualize hierarchical relationships, while theother controls flatten these out. Consider the following CDF structures and their visualrepresentations as defined by the Menu class.

50


Underlying CDF Model On-screen View

<data jsxid="jsxroot"/>rOj

<data jsxid= >"jsxroot" <record jsxid="1"jsxtext= />"New" <record jsxid="2"jsxtext= />"Open" <record jsxid="3"jsxtext= />"Save"</data>

<data jsxid= >"jsxroot" <record jsxid="1"jsxtext= />"New" <record jsxid="2"jsxtext= >"Open" <record jsxid="2a"jsxtext= />"Image..." <record jsxid="2b"jsxtext="Document..."/> </record> <record jsxid="3"jsxtext= />"Save"</data>

<data jsxid= >"jsxroot" <record jsxid="2"jsxtext= >"Font" <record jsxid="2a"jsxtext="Bold" jsxgroupname=

jsxselected="font" "1"/> <record jsxid="2b"jsxtext="Underline" jsxgroupname=

/>"font" <record jsxid="2c"jsxtext="Italic" jsxgroupname=

/>"font" </record> <record jsxid="3"jsxtext= />"Color"</data>

51


<data jsxid= >"jsxroot" <record jsxid="1a"jsxtext= />"Bold" <record jsxid="1b"jsxtext="Underline" jsxdivider= />"1" <record jsxid="1c"jsxtext="Italic" jsximg= />"x.gif" <lookups jsxid= >"2" <record jsxid="3"jsxtext= />"IL" <record jsxid="4"jsxtext= />"MA" <record jsxid="5"jsxtext= />"NV" <record jsxid="6"jsxtext= />"WI" </lookups></data>

CDF System Attributes

System attributes are reserved attributes used by General Interface to render CDF components.Each component has an associated XSL file for transforming CDF code into HTML for displayin your application. The system attributes listed in are referenced in the component XSL.

The attribute is required for all CDF components and must be a unique value. Support forjsxid

optional attributes varies according to component. The and attributes arejsxtext jsximg

commonly used and apply to most CDF components.

52


Attribute Component Description

jsxdisabled Button, Checkbox,ImageButton, Menu,RadioButton,ToolbarButton

Disables the record so that a user cannot select it.The record text is displayed in a grey color. Specify avalue of to disable the record.1

jsxdivider Menu Creates a linear divider between the current recordand the preceding record. Specify a value of to1

display the divider.

jsxexecute Matrix, Menu, Tree,Table

Allows an event to run a program function when theevent fires. A function name or a string of JavaScriptstatements can be specified. Separate multiplestatements with a semicolon (;) character. Forexample, jsxexecute="var a=12;var b='5';"

jsxgroupname Matrix, Menu Adds the record to a group that can be used bymultiple CDF records or components. Records in agroup are mutually exclusive options. For example,a menu for selecting fonts allows only one fontoption to be chosen.

jsxid all Uniquely identifies the CDF record. This value canbe user-defined or automatically generated using the

method ( . This attribute is getKey() jsx3.xml.CDF)

.required

jsximg Matrix, Menu, Tree,Table

References a graphic file to use as an icon. Specifythe file path relative to the project directory, forexample, . Image position dependsimages/icon.gif

on the component. For best results, use a 16x16transparent GIF file.

jsxkeycode Menu Defines a keyboard shortcut for calling the record.Specify any named key, such as Tab, Alt, Shift, orCtrl, and use the plus character (+) as a delimiter. Forexample, .jsxkeycode="ctrl+e"

jsxnomask Button, Checkbox,ImageButton, Menu,RadioButton,ToolbarButton(when used as aMatrix mask)

Disables a visible mask (checkbox, radio button,menu, and so on) so it's hidden and a user can'tselect it. Specify a value of to hide the mask for1

that row.

jsxselected Matrix, Menu, Tree,Table

Specifies whether the record is selected or notselected by default. Specify a value of to define the1

record as selected.

jsxstyle Matrix, Menu, Tree,Select, Table

Applies a CSS style to this record. Specify any CSScode. For example, jsxstyle="font-weight:bold;".

53


1. 2. 3.

jsxtext Matrix, Tree, Select,Menu, Table

Defines the visible text for the record. For example,in a menu component, the value of this attribute isthe name of the menu item as displayed in theapplication.

jsxtip Matrix, Tree, Select,Menu, Table

Defines the tooltip text to display when the cursorhovers over the record. For example, jsxtip="Type

.your address here"

jsxunselectable Matrix, Tree, Table Specifies whether a tree node or list item can beselected by end users. Specify a value of to prevent1

the record from being selected. When the value ofthis attribute is , the execute method for the record1

cannot be called.

Any CDF attribute value of , , , , , or jsxtext jsxtip jsximg jsxkeyode jsxstyle

in the form of { } is replaced with the dynamic property if it exists. Ifjsxclass xxx xxx

the property doesn't exist, then the value isn't changed. Dynamic properties comefrom the server owning the CDF control. The conversion occurs when the XMLdocument is retrieved from source and before it's placed in the cache. For moreinformation, see the API for .CDF.convertProperties()

CDF records can also include custom attributes. Custom attribute names can be any stringexcept names of system attributes. To add attributes to a CDF record, call the

method. You can also manually edit the CDF document on the fileinsertRecordProperty()

system, or open the cached file in General Interface Builder.

Creating CDF Documents

CDF documents are created both at design time and at runtime.

There are several ways to create CDF documents:

Create a new XML file that conforms to the CDF schemaCreate a new instance of a CDF componentInstantiate a CDF using the APIMap a parent element to a CDF in the XML Mapping UtilityTransform an existing XML document using the API

Creating an XML File

To create a new CDF document in your project,

Choose File > New > XML Document.Select from the list to add the basic template for a CDF document.CDF DocumentPress again to add templates for attributes, additional records, or an XMLCtrl+Spacebarheader declaration.

54


Creating a new CDF Component

When you drag a CDF component, such as Matrix or any other component that implements the interface, to the work area in General Interface Builder, a CDF document isjsx3.xml.Cacheable

automatically created in the Local Data Cache palette. This document, which contains defaultdata, is associated with the component for the length of the browser session.

If you do not explicitly set an XML Cache ID for a CDF-type control, such as matrix, menu, andselect, an ID is automatically generated by the system. The naming convention is aconcatenation of the control ID. For example, plus an _XML suffix. An ID looksobject.getId()

similar to the following: ._jsx_1_5_XML

Instantiating a CDF Document Using the API

A CDF component isn't required for creating a CDF. Instead, you can instantiate a CDF directlyusing the factory method, .jsx3.xml.CDF.Document.newDocument

In this code example, a new XML document that represents an empty CDF document is created:

var oDoc = jsx3.xml.CDF.Document.newDocument(); o = ();var new Object

o.jsxid = jsx3.xml.CDF.getKey();o.jsxtext = "hello";oDoc.insertRecord(o);oDoc;sampleWSDLMapping1.getCache().setDocument("foo",oDoc);

This is a good choice if a CDF component isn't required. For example, the Properties Editorpalette in General Interface Builder uses the API to create the CDF on the fly at runtime andgenerate the list of available properties for the selected component in the work area.

For method details for the class, see the online API help in Generaljsx3.xml.CDF.Document

Interface Builder.

Mapping a Parent Element to a CDF Document

For outbound requests, map an element to the CDF Document option in the Type drop-downlist in the Mappings table of the XML Mapping Utility. A new CDF document is automaticallycreated when the response is received.

Transforming an existing XML Document

You can use method calls to the class to transform an existing XMLjsx3.xml.Template

document. Using these methods, you can apply XSLT to an existing XML document totransform the XML into the CDF format. The following sample JavaScript code illustrates howto load and transform an XML file into CDF.

var myXML = jsx3.xml.Document();newmyXML.load("JSXAPPS/myProjectDir/xml/nonCDF.xml");

myXSL = jsx3.xml.XslDocument();var newmyXSL.load("JSXAPPS/myProjectDir/xsl/CDF.xsl");myXSL.transform();

For method details, see the online API help in General Interface Builder.

55


Accessing CDF Data

Data in CDF documents can be accessed using JavaScript object notation or XML record format.

Accessing a CDF Document Directly

If you want to access the CDF document that belongs to a control, you simply call the{{getXML()}}method. The XML source document and the CDF source document aresynonymous for the CDF controls, such as matrix, menu, select and so on. For example.

// get a handle to the matrix objMatrix = myServer.getJSXByName("myMatrix");var objCDF = objMatrix.getXML();var

Getting a Handle to a CDF Document

To access data in a CDF document of a CDF component, first get a handle to the document inone of the following ways:

From cache, by calling the method ( ). This method takesgetDocument() jsx3.app.Cache

the name of the cached CDF document as input, which is system-defined by default. Forexample,

myserver.getCache().getDocument("myDocument");

To avoid working with the system-defined name, use the XML Cache ID property tospecify a name for the CDF document or access the CDF document through the object.

From an object, by calling the method ( ). All CDFgetXML() jsx3.xml.Cacheable

components implement the interface, which provides this method.jsx3.xml.Cacheable

For example,

var objXML = myCdfControl.getXML();

The result of this method call is a instance.jsx3.xml.Document

If you've instantiated a CDF directly and aren't using a CDF component,you don't need to get a handle to the CDF document.

Accessing a Node

You can access a record node within a CDF document in one of the following ways:

By calling the method ( ) for the CDF document andselectSingleNode() jsx3.xml.Entity

passing the appropriate XSL query. The following code example returns the node withelement name and value of .record jsxid 12

myCdfDocument.selectSingleNode(//record\[@jsxid='12']);

* From an object that implements the CDF interface, by calling the getRecordNode()method ( ). For example,jsx3.xml.CDF

myObject.getRecordNode(12);

56


Using CDF Methods

This section gives an overview of CDF methods and describes how to use the methods tointeract with a CDF document.

CDF Methods Overview

The following table provides an overview of available methods defined by the jsx3.xml.CDFinterface. For detailed method descriptions, including input and output information, see theonline API help in General Interface Builder.

57


Method Summary

getKey Generates a unique identifier for use as the attribute for a CDFjsxid

record. This value persists only for the length of the browser session.Unique values that persist across browser sessions must be generatedby the developer.

newDocument A factory method for creating a new CDF document containing thefollowing XML: <data jsxid="jsxroot"/>

adoptRecord Transfers a CDF record between components. The record must have aunique value to be transferred. If no CDF document exists forjsxid

the adopting parent, a document is created and added to the cache. Ifsuccessful, this method returns a instance, which isjsx3.xml.Entity

an object handle to the transferred record. The view for the record isautomatically updated.

adoptRecordBefore Equivalent to , except that the to-be relationship is as aadoptRecord

previousSibling to the CDF record identified by the parameter, .strSiblingRecordId

deleteRecord Deletes a CDF record from the component CDF document. Ifsuccessful, this method returns a instance, which isjsx3.xml.Entity

an object handle to the deleted record node. Updating the view forthe record is optional.

deleteRecordProperty Deletes a specific property from a CDF record. The record must havea unique value. Do not call this method to delete the jsxid jsxid

property.

getRecord Returns a JavaScript object that is a clone of the specified CDF record.Any updates to this clone doesn't affect the original record unless youcall and pass the modified clone as the input.insertRecord()object

parameter.

getRecordNode Returns a instance representing the actual objectjsx3.xml.Entity

handle to the CDF record. Updating this object also directly updatesthe model. To synchronize the view after an update, call thefollowing: object.redrawRecord(strRecordId,jsx3.xml.CDF.UPDATE);

insertRecord Inserts a new record into the CDF document for the component. If noCDF document exists for the component, a document is created andadded to the cache. If a record with the same value alreadyjsxid

exists, the existing record is updated.

insertRecordBefore Creates a new CDF record and inserts it into the CDF data source ofthis object, before the record identified by the parameter,

.strSiblingRecordId

insertRecordNode Inserts a new record node into the control's XML-formatted datasource. If no CDF document exists for the component, a document iscreated and added to the cache. If a record with the same valuejsxid

already exists, the existing record is updated. This function is forinserting records as XML node entities rather than JavaScript objects.

58


insertRecordProperty Inserts a new CDF attribute and corresponding value for the specifiedCDF record. The attribute can be one of the system attributes definedin or a custom attribute. Updating the viewCDF System Attributesfor the record is optional.

Adding Records

Use the and methods to add records to a CDF document.insertRecord() insertRecordNode()

The two methods are functionally equivalent, but takes a JavaScript object asinsertRecord()

input, while takes an XML entity. With , you specify the insertRecordNode() insertRecord()

attribute, along with any other CDF attributes for the record, as properties of the object.jsxid

insertRecord Example

The following sample JavaScript code illustrates how to add records to a Matrix componentusing :insertRecord()

// get a handle to the matrix objMatrix = myServer.getJSXByName("myMatrix");var

// CDF recordnew objRecord = ();var new Object

objRecord.jsxid = jsx3.CDF.getKey();objRecord.Date = myServer.getJSXByName("dateEntry").getValue();objRecord.Security = myServer.getJSXByName("securityEntry").getValue();objRecord.Open = myServer.getJSXByName("openEntry").getValue();objRecord.High = myServer.getJSXByName("highEntry").getValue();

// insert the record and pass so it is redrawn without repainttrueobjMatrix.insertRecord(objRecord, , );null true

In this example, the new CDF record object is . The first property defined for thisobjRecord

object, , is a required system attribute that must be unique. The method is usedjsxid getKey()

to generate a unique value for this record. Other properties, , , , and jsxid Date Security Open

, become custom attributes of the CDF record. Values for these properties are provided byHigh

components in the application.

In addition to a JavaScript object, the call takes two parameters — the numericinsertRecord()

identifier ( value of a parent object) and an optional Boolean parameter for a redrawjsxid

operation. When null is specified for the second parameter, as in this example, the record isadded to the root element of the CDF document.

Since this example adds a single record, the overhead associated with redrawing the record isinsignificant. When adding multiple records, such as in a loop, consider passing a value of falsefor this parameter and repainting the entire component after all records are added. For details,see .Redrawing and Repainting Records

Creating Record Hierarchies

By default, the structure of a CDF document is flat without hierarchical relationships betweenrecords. To create an hierarchical CDF document, specify the optional strParentRecordIdparameter when calling either or . This parameter takes the insertRecord() insertRecordNode()

value of a parent record, and when a value is specified, the record is added as a child ofjsxid

the parent record.

59


Updating Records

When you add a record that has the same value as an existing record in the CDFjsxid

document, the existing record is replaced. Make sure values are unique before addingjsxid

records. For details, see .Generating Unique Identifiers

You can use the method to add attributes to an existing record in ainsertRecordProperty()

CDF document. Specify the value of the record to modify, along with the attribute namejsxid

and attribute value. The following sample illustrates how to add an attribute to an existingrecord within an ID ( ) of 58:jsxid

objList.insertRecordProperty("58","mypropname","mypropvalue");

The process of removing attributes is similar. Using , specify the deleteRecordProperty() jsxid

value of the record to modify and the name of the attribute to remove. Although not specificallyrestricted by the API, do not remove the attribute from a record. The following samplejsxid

JavaScript code illustrates how to remove an attribute from an existing record:

objList.deleteRecordProperty("11","jsximg");

In both of the preceding examples, the record is automatically refreshed to reflect the change inthe application. You could also pass a value of for the optional parameter tofalse bRedraw

prevent the redraw operation. For details on optimizing redraw and repaint operations, see .Redrawing and Repainting Records

Deleting Records

Use the method to delete a record from a CDF document. This method returnsdeleteRecord()

an object handle to the XML entity instance that was removed. The following sample JavaScriptcode illustrates how to delete an existing record:

var objMatrix = myServer.getJSXByName("myMatrix");objMatrix.deleteRecord(strRecordId);

Generating Unique Identifiers

The attribute must be unique among all records for the component. If users need to dragjsxid

records from one component to another, the attribute must be unique across multiplejsxid

components. There are several ways to ensure uniqueness.

If the content of the CDF document is built programmatically by your application, you can usethe method to generate a unique value for the attribute. Thejsx3.xml.CDF.getKey() jsxid

generated value is guaranteed unique across multiple components for the browser session. Foran example, see .Adding Records

If the content of the CDF document is built outside of your application, you can use any keyvalue in an XML attribute as the value. If no key value exists in the original XML whenjsxid

transforming the XML into CDF, use the XPath generate-id function to generate a unique value.

Redrawing and Repainting Records

After adding, modifying, or deleting records, the on-screen representation for the record willneed to be synchronized. A changed record can be redrawn or the entire component can berepainted. Context and the impact on application performance determine which operation ismore appropriate.

In general, repainting the component affects all records and is resource-intensive. Repainting

60


In general, repainting the component affects all records and is resource-intensive. Repaintingthe component should be avoided unless a sizable number of records are modified. Forexample, if many records are added in an iterative manner, it can be more efficient to repaintthe component once, after all additions have been made. To repaint a component, call the

method for the specific component.repaint()

CDF methods, with the exception of the adoptRecord()}}method, accept an optional Booleanparameter that signifies whether the on-screen view should be immediately updated to

, which is the default value,reflect the update to the in-memory model. A value of {{true

redraws the record after modification. For the method, both controls (the formeradoptRecord()

and new parent) are redrawn.

Counting Records

You can count the number of records in a CDF document by querying for all records andcalling the method on the object that is returned. The following sample illustratesgetLength()

this for the List control.

var objXML = myList.getXML(); objNodes = objXML.selectNodes("//record");var

alert("The number of records is: " + objNodes.size());

First, call the method for the object, then the method ( )getXML() selectNodes() jsx3.xml.Entity

for the XML entity, passing the path for the nodes to select. This method returns a handle to the object containing all record nodes in the CDF document. Calling the jsx3.util.List

method on this object returns the number of CDF records.getLength()

Flexible CDF Schema

The Common Data Format (CDF), enforces a standard XML data schema with a root elementcalled , nested elements called and record attributes such as , and data record jsxid jsxtext

. This schema applies to the classes that implement the interface: Select,jsximg jsx3.xml.CDF

Tree, Menu, Table and Matrix (and previously List and Grid).

Standard CDF schema example<data jsxid= >"jsxroot" <record jsxid= jsxtext= jsximg= />"1" "One" "one.gif" <record jsxid= jsxtext= jsximg= />"2" "Two" "two.gif" ...</data>

The flexible CDF schema feature allows these same classes to consume datasources that do notstrictly follow CDF. This feature is particularly useful for consuming pre-existing XMLdatasources that were created without knowledge of CDF.

With the flexible CDF schema feature,

The core CDF schema elements and attributes , and can be renamed todata record jsxid

anythingA single data source can drive multiple CDF controls, each with its own view of the data

61


1. 2.

3.

An alternative way of converting data sources to CDF is to use XSL Transformers.XSL Transformers allow you to define one or more XSL transformations to convertthe source data to CDF before it is stored in the XML application cache and is used torender a CDF control. Whereas the flexible CDF schema feature supports only XMLschemas that have a similar structure to CDF, the XSL transformers approachsupports any arbitrary XML schema. Knowledge of XSL is required to use thisapproach. See the API documentation for for more informationjsx3.xml.Cacheable

on XML Transformers.

How Flexible CDF Schema Works

Each CDF control has a property of type . The value of this propertyschema jsx3.xml.CDFSchema

defines how the control views its CDF datasource. If the property is not set then theschema

control uses the default CDF schema.

Each CDF control first queries its schema for the name of the attribute and then queries itstext

datasource for that attribute of a record. For example, the implementation of jsx3.gui.Treeincludes expressions such as

this.getRecordNode(id).getAttribute( .getSchema().getProp( ))this "text"

This additional level of indirection ( instead of )this.getSchema().getProp("text") "jsxtext"

allows the object to control how each CDF control views its datasource. The default CDFSchema

object returns from a call to . However, you can modifyCDFSchema "jsxtext" getProp("text")

the schema so that it returns instead. This change would allow you to have a CDF"label"

datasource such as

<data jsxid= >"jsxroot" <record jsxid= label= />"1" "One" ...</data>

Controlling Flexible CDF Schema in General Interface Builder

You can control flexible CDF schema from within General Interface Builder. To do so,

Open or create a component with a CDF control in it, such as Matrix, Tree or Menu.Find the CDF Schema component in the Component Libraries palette and drag it ontothe CDF control. It may be easier to drag it onto the corresponding node in theComponent Hierarchy palette.Modify the properties of the schema object in the Properties Editor.

The Properties Editor contains an editable property for each attribute in the default CDFschema. In general, the default value of property is . also has a propertyabc jsxabc CDFSchema

called . This property allows you to change the element name of the records in therecord

datasource. You can choose another name, such as or you can use set it to to indicateitem *

than any XML element should be interpreted as a data record.

62


For the CDF schema shown in the screenshot, the datasource is

<items id= >"jsxroot" <item id= label= />"1" "One" <thing id= label= />"2" "Two" <object id= label= />"3" "Three" ...</items>

Using the same datasource for two different controls is simply a matter of defining a uniqueCDF schema for each control.

Click to download a sample project that uses the flexible CDF schema feature: .GI-702.zip

Common Interface Format (CIF)

Common Interface Format (CIF)

The Common Interface Format (CIF) is a serialization format for storing General Interfacecomponent definitions. In the future, this format will replace the current serialization fileformat, which has the following namespace — . The CIF formatxmlns="urn:tibco.com/v3.0"

provides improved readability and smaller file size.

The CIF format uses several new namespaces, the root of which is . The new format is 100% compatible with the v3.0http://xsd.tns.tibco.com/gi/cif/2006

serialization format. An XSLT is used for the conversion between CIF and v3.0 formats.

Currently, General Interface Builder can read but save CIF files. Any edits made to a CIFnotfile are saved in the old serialization format.

http://www.generalinterface.org/docs/download/attachments/6685683/GI-702.zip?version=1&modificationDate=1261075096000

http://xsd.tns.tibco.com/gi/cif/2006

63


CIF Document Example

Here is an example of a CIF document that represents a dialog component. The dialog containsa window bar with buttons, a splitter with a grid layout, and so on. Some of the key aspects ofthe CIF are indicated in bold. For definitions, see .CIF Definitions

<component xmlns="http://xsd.tns.tibco.com/gi/cif/2006" *classpath*="jsx3.gui" =xmlns:e "http://xsd.tns.tibco.com/gi/cif/2006/events" =xmlns:\d "http://xsd.tns.tibco.com/gi/cif/2006/v3.2/dynamics" =xmlns:\p "http://xsd.tns.tibco.com/gi/cif/2006/property" =xmlns:\pe "http://xsd.tns.tibco.com/gi/cif/2006/property.eval" =xmlns:x "http://xsd.tns.tibco.com/gi/cif/2006/xslparameters" =xmlns:v "http://xsd.tns.tibco.com/gi/cif/2006/view" =xmlns:id "http://xsd.tns.tibco.com/gi/cif/2006/inlinedata" =xmlns:u "http://xsd.tns.tibco.com/gi/cif/2006/userdefined" =xmlns:ue "http://xsd.tns.tibco.com/gi/cif/2006/userdefined.eval" >

<![CDATA[ jsx3.log("Here is an<meta name= >"onAfterDeserialize" unescaped entity: >"); ]]></meta> <Dialog d:bgcolor= pe:width= pe:height="@Solid Medium" "400" "200" p:name= >"dlg1"

<WindowBar p:name= p:text= u:custom="this is"cbar1" "My Dialog" custom"> <ToolbarButton d:image= p:name="@Min Icon" "tbbMin" e:execute= />"x();" <ToolbarButton d:image= p:name="@Close Icon" "tbbClose" e:execute= />"y();" </WindowBar>

<Splitter d:bgcolor= p:name= >"@Solid Shadow" "splt1"

<LayoutGrid d:bgcolor= p:name="@Solid Light" "lg1" id:sizearray= >"AX1" <DatePicker pe:width= p:name= />"100" "dp1" <Button p:name= p:text="btn1" "Click Me" e:execute= />"alert('hello');" <Slider pe:length= p:value= p:name= />"100" "100" "sld1"

<id:\data href="AX1" handler-for= >"jsx3.lang.Serializeable.Array" <object> 38<item> </item> *<item> </item> 26<item> </item> </object> </id:\data>

</LayoutGrid>

<Block d:bgcolor= p:name="@Solid Light" "pane2"

64


p:\padding= >"8" <Select p:name= id:xml= >"sel1" "HRTL129Q"

<id:\data href= >"HRTL129Q" <![CDATA[ <data jsxid= >"jsxroot" <record jsxid= jsxtext= />"TIBX" "TIBCO" <record jsxid= jsxtext= />"MSFT" "Microsoft" <record jsxid= jsxtext= />"YHOO" "Yahoo!" <record jsxid= jsxtext= />"EBAY" "Ebay" <record jsxid= jsxtext= />"GOOG" "Google" <record jsxid= jsxtext= />"IBM" "IBM" </data> ]]> </id:\data>

</Select> </Block>

</Splitter>

65


</Dialog>

</component>

66


CIF Definitions

Node Name Namespace Description

component http://xsd.tns.tibco.com/gi/cif/2006 Root level node. Supports child elements belonging tothe same namespace. Any child element (excludingthose named , which is a reserved name) ismeta

understood to be an instance of and isjsx3.app.Model

deserialized as part of the standard General InterfaceDOM. In other words, any object hierarchycommunicated by the XML serialization format wouldbe a true reflection of the General Interface DOM oncethe XML is deserialized.

@classpath http://xsd.tns.tibco.com/gi/cif/2006 This attribute can belong to any node belonging to the namespace excepthttp://xsd.tns.tibco.com/gi/cif/2006

for nodes. If bound to the root node, ,meta component

this is the default class path for all GUI controlsdefined in the serialization file. Any GUI control thatimplements this attribute can override the root nodesetting.

meta Immediate child of the root node, .component

Describes meta-related information about thecomponent, including the following — name, icon,description, onAfterDeserailze,

.onBeforeDeserailize

@name Attribute of the node. Defines the name of the meta

attribute. For example, meta onAfterDeserialize.

data http://xsd.tns.tibco.com/gi/cif/2006 Inline node. Allows for the serialization of datadata

according to an open format. The defaultimplementation of this node assumes that it containsCDATA content. However, this node could provide a

attribute as a means for serializing andhandler-for

deserialization custom data types.

@href Provides the unique ID for the inline nodedata

among all inline nodes in the document.data

@handler-for Provides the name of the JavaScript object thathandles the deserialization of either the component orthe data. Applies only to the node that belongs todata

the namespace, .http://xsd.tns.tibco.com/gi/cif/2006/inlinedata





http://xsd.tns.tibco.com/gi/cif/2006/inlinedata

67


namespace-qualifiedattributes

xmlns:e=

"http://xsd.tns.tibco.com/

gi/cif/2006/events"

xmlns:d=


gi/cif/2006/dynamics"

xmlns:p=


gi/cif/2006/property"

xmlns:pe=


gi/cif/2006/property.eval"

xmlns:x=


gi/cif/2006/xslparameters"

xmlns:v=


gi/cif/2006/view"

xmlns:u=


gi/cif/2006/userdefined"

xmlns:ue=


gi/cif/2006/userdefined.eval"

In order to ensure proper compatibility with theexisting serialization format and provide for goodruntime deserialization performance, XMLnamespaces are used to uniquely identify how todeserialize a given property on a standard GeneralInterface object definition. The use of namespacesallows the deserialized to quickly categorize the objectproperties. This prevents the need for expensiveruntime lookups and the possibility of namespacecollisions. For example, the drag property on a Listdefinition may belong to the property namespace ([http://xsd.tns.tibco.com/gi/cif/2006/property]),specifying whether or not the given List supportsdrag-and-drop. It could also belong to the eventnamespace([http://xsd.tns.tibco.com/gi/cif/2006/events]) andrelate to the handler code to fire when a drag eventfires on the List. It could also be a user-definedproperty ([http://xsd.tns.tibco.com/gi/cif/2006]

or/userdefined

[http://xsd.tns.tibco.com/gi/cif/2006/userdefined.eval]).The drag property could also be a dynamic property.

Common Exchange Format (CXF)

Common Exchange Format (CXF)

The Common Exchange Format (CXF) is an interface definition schema that describes how tointeract with XML data within General Interface. By using CXF, General Interface is able toconnect to disparate systems and services without being tied to a specific exchange format. Atruntime, CXF is used by the class to perform the actual interactions.jsx3.net.Service

In much the same way that WSDL (an XML document format) defines SOAP transactions,General Interface employs a tree-like definition language of its own referred to as the CommonExchange Format (CXF). Using a common format for defining transactions allows GeneralInterface to communicate with a myriad of systems without being tied to a particular interfacedefinition. CXF documents are created at design time by the XML Mapping Utility using anynumber of formats as a starting point for creating the definition. Supported formats includeWSDL, schema, XML, and XHTML. CXF documents are referred to as mapping rules files orrules files throughout the documentation.

Once parsed by the XML Mapping Utility, XML documents are persisted in CXF format. A CXF

68


Once parsed by the XML Mapping Utility, XML documents are persisted in CXF format. A CXFrules document can then be mapped to application objects, such as CDF documents, text boxes,and nodes in the Local Data Cache palette.

Regardless of whether WSDL, Schema, or XML is used, all input formats result in the sametransactional format. In practice, this means that the interactions with a SOAP service can bedefined by using WSDL or a sample SOAP message, such as an Envelope, as a starting point.Ultimately, the source type (WSDL, Schema, or XML) used to create a CXF rules document isirrelevant once the CXF document has been created, as all formats are persisted using CXF.

Another way to think about CXF is to think of it as an interpretive language that is able tointerface between the XML document formats used by a given web service and the native CDFand JavaScript formats used by General Interface. Just as it is important to be versed in CDF inorder to know how data is used within General Interface, an understanding of CXF providesinsight into how data is shared between General Interface and data services. While CDFprovides the format for data while it is within the control of General Interface, CXF providesthe bridge to convert this information to the format required by the given web service.

CXF Document Example

The following CXF document was created by the XML Mapping Utility. The input document isGoogle's WSDL located at . After the XML Mappinghttp://api.google.com/GoogleSearch.wsdlUtility converts Google's WSDL to CXF, a few operations are removed for readability. Whatremains is a shortened description of the doGoogleSearch operation, with a sampling of themajor CXF entities and attributes. If you're familiar with WSDL and Google's in particular, youshould see similarities and differences between CXF and WSDL. CXF is more transactional andis designed to read more literally with less indirection. Therefore, it contains only a subset ofthe data contained in the original WSDL.

http://api.google.com/GoogleSearch.wsdl

69


<data jsxid= jsxnamespace="jsxroot" "jsx3.xml.Mapper" jsxversion= >"1.0" <record jsxid= jsxtext="13" "WSDL (/GoogleSearch.wsdl)" src= type="http://api.google.com/GoogleSearch.wsdl" "W" path=""> <record jsxid= jsxtext= path= type="12" "Service" "/" "S" soapstyle= >"rpc" <record jsxid= jsxtext="74321" "doGoogleSearch" opname= endpoint= type= path= >"doGoogleSearch" "beta2" "P" "/" <headers jsxid= >"7" <record jsxid= name="3" "SOAPAction" value= />"urn:GoogleSearchAction" <record jsxid= name= value= />"4" "Content-Type" "text/xml" </headers> <record jsxid= jsxtext= type="5" "Input (request)" "I" stubsrc= stubpath= onbeforesend="soap.xml" "/" "some code" soapuse= soaprpcns="encoded" "urn:GoogleSearch" soapencstyle= >"http://schemas.xmlsoap.org/soap/encoding/" <record jsxtext= jsxid= type="doGoogleSearch" "41037" "C" tns= path= >"urn:GoogleSearch" "/" <record jsxtext= jsxid= type="key" "1" "E" datatype= simple= path= repeat= >"xsd:string" "1" "/" "false" <mappings jsxid= >"11" <record jsxid= name= value= />"10" "Script" "setValue(true);" </mappings> </record> </record> </record> <record jsxid= jsxtext= type="9" "Output (response)" "O" soapuse= soaprpcns="encoded" "urn:GoogleSearch" soapencstyle="http://schemas.xmlsoap.org/soap/encoding/" stubsrc= onafterreceive= >"/" "some code" <record jsxtext= jsxid="doGoogleSearchResponse" "20020" type= tns= path= >"C" "urn:GoogleSearch" "/message[5]" <record jsxid= jsxtext= type= path="8" "return" "C" "/" datatype= >"typens:GoogleSearchResult" <record jsxid= jsxtext= type="5" "documentFiltering" "E" path= datatype= simple="/" "xsd:boolean" "1" jsxselected= >"1" <restrictions jsxid= >"16" <record jsxid= name= value= />"14" "enumeration" "true" <record jsxid= name= value= />"15" "enumeration" "false" </restrictions> </record> </record> </record> </record> </record>

</record> </record></data>

70


CXF Attribute Definitions

CXF is an extension of CDF, meaning it adheres to the CDF format, while adding additionalattributes and entities of its own. For more information on CDF, see Common Data Format

.(CDF)

The following table provides attribute definitions. Each of these attributes exists in one or morerule types, which are described in .CXF Rule Types

71


Attribute Description

datatype Data type for the node. For example, . This is relevant to RPCxsd:string

Encoded WSDL inputs. When the final message is generated and sent to theremote service, this value is used to specify the encoding for a node in themessage.

endpoint URL for the remote service to contact. Although WSDL binds the endpointto the service (which can encapsulate one or more operations), CXF bindsthe endpoint to each individual operation.

groupref If equal to 1, the node is flagged as structural, which means that it isn't partof the generated message. The node appears in the rules tree as anorganizing element but isn't generated and sent with the request, essentiallyremoving the abstract node and appending its descendant structures to thestructural node's immediate parent.

jsxid System ID for the record. This is assigned by the system and is unique foreach node in the CXF document. This attribute is only relevant at designtime.

jsxtext System text for the record. More importantly, this is the node name (forattributes and entities) in the message.

method The HTTP transport method: GET, POST, PUT, DELETE.

name Applies to records in the CXF that define mappings, HTTP headers, andrestrictions. In the case of mappings, this is the map type (i.e., DOM, Script,CDF Document, and so on). For HTTP headers, this is the header name. Forrestrictions, this is the type of the restriction (enumeration, nillable, pattern,and so on).

onafterreceive JavaScript code to execute immediately after receiving the responsemessage.

onbeforesend JavaScript code to execute immediately before sending the request message.

opname The name of the operation. This value is unique among all other operationnodes in the CXF document. In the case of a CXF that was created without aWSDL, there is only one operation for the CXF named .jsxtransaction

path The node path to find this item in the original source Schema used to createthe CXF. This attribute is only used by WSDL and Schema input types andis only relevant at design time.

ref If equal to 1, this node will be flagged by the XML Mapping Utility as areferential node, pointing to a group or element in theattributeGroup

source WSDL/Schema. This attribute is only relevant at design time and isused to convert the indirection used by Schema to the concrete structuresused by CXF.

repeat If this attribute exists, its value will be evaluated as JavaScript within thecontext of the instance that is processing the given CXF. Ifjsx3.net.Service

the result evaluates to , the given branch in the CXF will be processedtrue

again. This only applies to XML documents generated on the client. Thisvalue is ignored when processing a service response.

72


simple If equal to 1, the data type for this node is one of the simple types defined bySchema ( ).http://www.w3.org/2001/XMLSchema-instance

soapencstyle If equal to , the operation ishttp://schemas.xmlsoap.org/soap/encoding/designated as encoded, meaning each node will be tagged with its data type.This applies only to WSDL input types that use RPC encoding.

soaprpcns If an RPC Encoded message, the namespace for the remote procedure (themessage).

soapstyle The SOAP style — document or rpc.

soapuse The SOAP use — encoded or literal.

src URL for the source document that is serving as the pattern master forgenerating the CXF. The pattern master is the input document that was usedby the XML Mapping Utility to create the CXF (typically a WSDL). Thisattribute is only relevant at design time.

stubsrc URL for the base shell document. Also used for inbound messages (responsenodes) when running in static mode.

stubpath The XSL Query for the node in the base shell document ( ) to whichstubsrc

the generated document will be appended.

tns If this value exists on a Rule node contained by an Input node, the Rule willbe qualified and the value of the will be appended to the root node in thetns

response document. If it exists on a rule contained by the output or faultnodes, it defines a qualified namespace, meaning that it isn't enough for thenode names to match for the rule to be applied; rather, the node'snamespace must also match.

ttns Represents the target namespace for the data type and applies torpc-encoded messages. For example, if the target namespace is tns abc.com

and is , you would see something similar to the following in attns def.com

message:

<jsx1:myNode xsi:type= ="jsx2:myType" xmlns:jsx1 "abc" =xmlns:jsx2 "def" = />xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance"

type The type of rule. For example, A, C, E, and so on. The most common type isE, which represents a mapping rule to an Entity node type in the CXF.

value Applies to records in the CXF that define mappings, HTTP headers, andrestrictions. In the case of mappings, this is the map path/value. For HTTPheaders, this is the header value. For restrictions, this is the value of therestriction.

CXF Rule Types

Each node in the CXF document is known as a rule, each of which describes a specific step inthe transaction. For example, an operation rule defines the location of the Service, while aMapping rule defines what values will be sent to the Service. The following table describes eachrule and the CXF attributes it implements.

http://www.w3.org/2001/XMLSchema-instance

http://schemas.xmlsoap.org/soap/encoding/

73


CXF Rule Type Attribute Description

WSDL

//record[@type='W']

jsxid, jsxtext,

type, src, type

This is the top-level node in a CXF document thatresulted from a WSDL input. The most relevantattribute is , which describes the location ofsrc

the original WSDL in case the CXF document isin-edit and still needs a back-reference to theoriginal WSDL.

Service

//record[@type='S']

jsxid, jsxtext,

type, path,

soapstyle

This is a second-level node in a CXF documentthat resulted from a WSDL input. It is animmediate child of the WSDL-type node. Itdescribes a service to which one or moreoperations belong. Although the service doesdefine an endpoint in the original WSDL, thisinformation is saved to the Operation nodes forimproved flexibility.

Operation

//record[@type='O']

jsxid, jsxtext,

type, endpoint,

method,

opname, path

This is a third-level node in a CXF document thatresulted from a WSDL input. It is an immediatechild of the Service node. The operation describesthe type of messages involved, including input,output, and fault.

Transaction

//record[@type='T']

jsxid, jsxtext,

type, endpoint,

method, opname

This is the top-level node in a CXF that resultedfrom a non-WSDL input. It is equivalent to thethird-level Operation node that results from aWSDL input, except that it does not define a path.Instead, its child input and output rules definethe path to their respective source documents.

Input

//record[@type='I']

jsxid, jsxtext,

type,

onbeforesend,

path,

soapencstyle,

soaprpcns,

soapuse, src,

stubpath,

stubsrc

This node is the child of either an Operation orTransaction node. It contains the rules necessaryto create the input (the document that will be sentas part of the request). When the immediateparent is a Transaction node, the input will definea attribute, if relevant.src

Output

//record[@type='O']

jsxid, jsxtext,

type,

onafterreceive,

path,

soapencstyle,

soaprpcns,

soapuse, src,

stubsrc

This node is the child of either an Operation orTransaction node. It contains the rules necessaryto create the output (the response that will beprocessed). When the immediate parent is aTransaction node, the output will define a srcattribute, if relevant.

74


Fault

//record[@type='F']

jsxid, jsxtext,

type, path,

soapencstyle,

soaprpcns,

soapuse

This node is a child of an Operation node. Itdefines an alternative ruleset for processing afault document returned from the Service. It isexecuted only when the service responds with anon-202, 200, or -0 HTTP status code. It does notsupport the extra attributes that the Output nodesupports.

Rule

//record[@type='A'

or @type='C' or

@type='D' or

@type='E']

jsxid, jsxtext,

type, datatype,

groupref, path,

ref, repeat,

simple,tns,ttns

Rule nodes define the mappings and restrictionsand are used to either generate a node in theinput message or process a node in the output.Note the following definitions: A: attribute nodeE: entity node D: CDATA node C: complex node(contains E, C, D, or A nodes)

Mapping

//mappings/record

jsxid, name,

value

Mapping nodes are bound to an entity calledmappings, which, in turn, is bound to a givenRule node. There can be zero or more mappingsfor a given rule.

Restriction

//restrictions/record

jsxid, name,

value

Restriction nodes are bound to an entity calledrestrictions, which, in turn, is bound to a givenRule node. There can be zero or more restrictionsfor a given rule. The restrictions can be used tovalidate mapped input.

Header

//headers/record

jsxid, name,

value

Header nodes are bound to an entity calledheaders, which, in turn, is bound to a givenOperation or Transaction node. There can be zeroor more HTTP headers for a given operation.

75


1. 2. 3.

Chapter 4 Handling Application Data

This chapter describes how to send, receive, and cache application data.

About Handling Application DataSending DataReceiving DataCaching Data

About Handling Application Data

General Interface provides an in-memory local data cache where developers can store XML/XSLdocuments needed by the application. Some documents in the local data cache are placed thereautomatically by the system. Developers can also set their own documents in the local datacache. Having a centralized cache provides easier object cleanup, as well as a standardizedmethod for sharing data across multiple components. The local data cache is a critical aspect ofa stateful rich client experience when used in conjunction with asynchronous data access.

General Interface applications can send and receive any type of text data sent using HTTP/S.The class is used for this exchange, providing a generic transport mechanismjsx3.net.Request

for text content, regardless of format. Data that is in XML format can be stored in the local datacache for repeated use by various objects within the application.

Sending Data

You can send data from an application using the methods: GET or POST. Depending upon thecapabilities of the server being called, other methods like DELETE, PUT, and HEAD may alsobe called.

The following describes the general pattern for sending data:

Create a new instance.jsx3.net.Request

Call the method and specify the interaction type (GET, POST, and so on).open()

Call the method.send()

For a POST interaction, pass the string content as the only parameter to the method. Forsend()

GET, use another content mechanism, such as an overloaded URL, as in this example:

76


//initialize and open

req = jsx3.net.Request.open("GET","http://www.tibco.com?myQuery=1", );var true

//create response callback and subscribe

onResponse(objEvent) {function

req = objEvent.target;var

alert(req.getResponseText());

};

req.subscribe(jsx3.net.Request.EVENT_ON_RESPONSE,onResponse);

//send

req.send();

General Interface applications perform best when they use asynchronous data access. However,there are times when you might want to synchronously access data. The above call madesynchronously is shown in the following example:


req = jsx3.net.Request.open("GET","http://www.tibco.com?myQuery=1", );var false

//send

req.send();

alert(req.getResponseText());

Receiving Data

The process for receiving data depends on whether the data is valid XML or another format.

Receiving XML Data

To receive XML data, call the method on the instance. This methodgetResponseXML() Request

returns a object, which is an XML document in a format that Generaljsx3.xml.Document

Interface can use, as shown in the following example:

77



reqSocket = jsx3.net.Request.open("GET",jsx3.GO('myURLComponent').getValue(), var);false

//send the request

reqSocket.send();

//get the XML response

repXML = reqSocket.getResponseXML();var

To save the response document for repeated access, use the function to load it intosetDocument

the local data cache as follows:

myApp.getCache().setDocument("MyCacheDocument", repXML);

Also note that the class has different methods for accessing data. The example shownRequest

above is the simplest of all data calls: a synchronous HTTP GET. In fact, requesting and cachingdata in this manner can be done with only one API call, as shown in the followingopenDocument

example:

var repXML = someApp.getCache().openDocument(someURL,someCacheId);

The Cache class has different methods accessing data more efficiently than thefor{{openDocument}} method just described. For example, the method{{getOrOpenDocument}} will first check the cache the document before attemptingforto load it.

If the document is large or the server will respond a known latency, fetch thewithdocument asynchronously, using {{getOrOpenAsync}}. This method returns thecorresponding document synchronously it already exists the cache. If theif indocument does not exist the cache, then it is loaded asynchronously and the methodinreturns a placeholder document. The namespace URI of placeholder document isthis{{jsx3.xml.Cache.XSDNS}} and its root node name is {{loading}}.

Because the cache stores placeholder document until the document finishesthis

78


loading, subsequent calls to synchronous APIs (such as {{getDocument() andgetOrOpenDocument()}}) may also the placeholder document. It is thereforereturnimportant to check the namespace of the returned document when any code uses theasynchronous APIs.

Once a document finishes loading asynchronously the placeholder document is replaced the loaded document. This change value causes the cache to publish a pair ofwith in

events of action {{Cache.CHANGE}}. If loading the document fails or times out, theplaceholder document is instead replaced another placeholder document. Thiswithdocument also has a URI namespace of {{Cache.XSDNS}}. Its root node name may beeither {{error}} or {{timeout}}. If the root node name is {{error}} then the rootnode has an attribute, also named {{error}}, which contains the XML error message.

h4. Handling Failures

If the incoming XML can't be parsed by the {{Request}} instance, the{{getResponseXML}} call fails. One possible cause of failure is invalid XML, whileanother is an unrecognized content type specified the HTTP header. The server mustinset field the HTTP header to {{text/xml}} or similar.this in

If the {{getResponseXML}} call fails but the content is valid XML, you can stillparse it by calling the {{getResponseText()}} method and passing the XML string intoa {{jsx3.xml.Document}} instance as follows:{code:lang=javascript} objXML = var newjsx3.xml.Document();

79


objXML.loadXML(XML_string);

(!objXML.hasError()) alert("success:\n\n" + objXML.getXML());if

For more details on the method, see .getResponseText() Receiving Non-XML Data

Receiving Non-XML Data

To receive non-XML data, call the method for the instance. ThisgetResponseText() Request

method returns the body of the response as a string value, as shown in the following example:

var strText = objRequest.getResponseText();

window.alert(strText);

Non-XML data is useful in many situations. For example, non-XML data can be displayed inthe application by setting it as the text property of a object, or it can bejsx3.gui.Block

reformatted into CDF for use by a Matrix component. Also, if the data is converted to XML, itcan be stored in the local data cache to facilitate data access and management.

Caching Data

Each General Interface application maintains a separate local data cache. If two applications areembedded on a single web page, each has its own cache. This local data cache should not beconfused with the browser file cache for temporary Internet files. The General Interface localdata cache is an in-memory, JavaScript hash of parsed XML documents that disappears whenthe browser window is closed. Any XML document, including XML, CDF, and XSL files, can bestored in the local data cache.

Controls that display XML data interface with the local data cache by way of the interface. This class provides methods that link a GUI object and the localjsx3.xml.Cacheable

data cache data it needs. The GUI object never refers to the data by reference. Only the localdata cache references the XML document object, facilitating improved dereferencing and objectcleanup.

The Share Resources property is an important property of GUI classes that extend Cacheable(Menu, Tree, Matrix, and so on). When the Share Resources property is set to (defaultfalse

setting) and the GUI object is removed from the General Interface DOM, the associated XMLand XSL documents are also removed from the local data cache. Set this property to if twotrue

GUI objects refer to the same document or if the document should remain in the local datacache after the GUI object is removed.

Accessing the Correct Cache

To load files into the local data cache for use at runtime, call methods of the jsx3.app.Cacheclass. All cache method calls must be qualified with application namespace information. If thenamespace for your application is app1, use the following syntax when storing and retrievingdocuments:

app1.getCache().method_name

You can cache any XML, CDF, or XSL document using the method. The openDocument()

method allows you to specify the URL of a file to load and parses the file into a openDocument()

instance. To cache the document, provide a second parameter to use as thejsx3.xml.Document

80


instance. To cache the document, provide a second parameter to use as thejsx3.xml.Document

cache ID as follows:

app1.getCache().openDocument ("http://ibiblio.org/bosak/coriolan.xml","someCacheId");

Because this method call is always synchronous, browser performance can beaffected if the document is large.

To explicitly load a file into cache independently of the method, use the openDocument()

method.setDocument()

To retrieve a file from cache, use the method as follows:getDocument()

app1.getCache().getDocument("myDocument");

Shared Global Cache

If you need to share a cache document with other applications running in the same page, usethe shared global cache that is provided by the General Interface system as follows:

var objSharedXML = jsx3.getSharedCache().getDocument("abc");

When a document is requested from the local data cache and the document isn't found, theGeneral Interface system queries the shared global cache. For example, if the local data cachedoesn't have a document named , each of the following calls is equivalent, assuming that theabc

application namespace is app1:

var objXML = jsx3.getSharedCache().getDocument("abc");

or

var objXML = app1.getCache().getDocument("abc")';

Pre-caching XML Documents

General Interface controls that implement the interface will automaticallyjsx3.xml.Cacheable

load their associated XML document into the local data cache when first painted. Otherwise,loading XML data into the local data cache is typically the domain of the developer.

In General Interface Builder, project files can be configured to load automatically when theapplication loads. To manually specify which project files are automatically loaded into cache,right-click the file name in the Project Files palette and select . Any type of projectAuto Loadfile except a GUI component and a mapping rule can be configured to automatically load. Formore information on Auto Load options, see .File Profile Dialog

When you're working in General Interface Builder, XML and XSL project files can be manuallyloaded or reloaded into the local data cache by doing the following:

In the Project Files palette, right-click the file name and select .Load/ReloadIn the work area, right-click the associated tab and select afterSave and Reloadmodifying an XML or XSL document.

To view the contents of the local data cache in General Interface Builder, choose Palettes > Local

81


To view the contents of the local data cache in General Interface Builder, choose Palettes > Local.Data Cache

82


Chapter 5 Communicating with Data Services

This chapter describes how to communicate with data services in a General Interfaceapplication.

About Communicating with Data ServicesBasic Steps for Communicating with Data ServicesXML Mapping Utility User InterfaceCreating Mapping Rules FilesModifying Mapping Rules FilesMapping GUI Components to Mapping RulesCalling a Data ServiceMapping Response Data to CDF GUI ComponentsTesting Outbound and Inbound MessagesHandling Errors and Timeouts

About Communicating with Data Services

General Interface applications are able to communicate with XML data services, such as SOAP,REST, or RSS, using the HTTP protocol. To simplify the exchange of information, GeneralInterface provides an XML Mapping Utility that allows developers to visually bind nodes in theexchanged messages to objects in the application. The output from the XML Mapping Utility isan XML document format called the Common Exchange Format (CXF). CXF is analogous toXSLT in that it is an XML-based structure that is capable of transforming, creating, andprocessing XML documents.

For information on General Interface document formats, see .Custom Document Formats

CXF documents can also be used for internal transformations and mappings, making themuseful even when a remote service isn't involved. The following figure depicts how CXF can beused to process and transform the messages exchanged with a remote service. The next figureshows how CXF can be used for internal mappings and transformations.

Processing External Data

83


1.

2.

3.

4.

5.

Processing Internal Data

Because CXF is used to define how information is processed, CXF documents are commonlyreferred to as rules files. The XML Mapping Utility is the design-time tool that creates a rulesfile, and the class is the runtime engine that executes a rules file. If the rulesjsx3.net.Service

file specifies that a remote service is involved, the class manages alljsx3.net.Service

communications, using its own instance of for the HTTP communications.jsx3.net.Request

Basic Steps for Communicating with Data Services

Communicating with data services in your application involves these basic steps:

Create mapping rules.See .Creating Mapping Rules FilesMap application GUI components to the rules file:

Manual mapping. See .Manually Mapping GUI Components and Input Mappings

Automatic mapping. See Automatically Generating GUI Components and Input. For CDF mapping, see .Mappings Map Response Elements to CDF Equivalents

Test messages.See .Testing Outbound and Inbound MessagesGenerate function code to run the rules file and invoke the service.See .Generating Function CodeAdd events that will invoke function code in your application.See .Invoking Function Code

XML Mapping Utility User Interface

This section explains the XML Mapping Utility user interface.

To open the XML Mapping Utility, do one of the following:

Choose .File > New > Mapping RuleChoose XML Mapping Utility.Tools >Click the button on the Project Files palette toolbar and choose .New Mapping RuleDouble-click an existing rules file in the Project Files palette.

The XML Mapping Utility prompts you to select one or more source documents to use as thestarting point for the mapping rules file. After the source documents are parsed, the XMLMapping Utility user interface is displayed.

84


Mapping Utility user interface is displayed.

The XML Mapping Utility has several panels and toolbars:

XML Mapping Utility ToolbarRules Tree PanelRules Tree Panel ToolbarRule Profile PanelSettings PanelMapper Log

For definitions of fields in the XML Mapping Utility, see .XML Mapping Utility

XML Mapping Utility Toolbar

The XML Mapping Utility toolbar has buttons for creating, opening, and saving mapping rules.

For more information on toolbar buttons, see .XML Mapping Utility Toolbar

Rules Tree Panel

After the source documents are parsed, the mapping rules file displays as a tree consisting ofmultiple rules in the Rules Tree panel. The rules tree contains a collection of input (request) andoutput (response) rules, which are executed in the order they appear in the tree.

The rules in the rules file can be edited independently of the source document. After the initialparse, you can add rules to and remove rules from the file as needed. For example, unmappedrules can be removed to minimize the size of the rules file. Additional rules can be defined tocustomize the service interaction or account for changes to the service over time.

85


Icon Rule Type Description

(smallpencil)

Attribute A rule that maps to an attribute node.

CDATA A rule that maps to a CDATA (character data) node.

A rule that maps to an element node and which has descendantelement, attribute, or CDATA rules. Double-clicking the iconreveals additional rules that are defined by the source WSDL orSchema.

ComplexType

A rule that maps to an element node and which has descendantelement, attribute, or CDATA rules.

Data Type The XSD data type of the selected rule, such as string, boolean,decimal, and so on.

(largepencil)

Element A rule that maps to an element node.

Input(request)

An input or request rule.

Mapping A rule that has a mapping assigned to it.

Operation An operation or transaction rule.

Output(response)

An output or response rule.

RepeatWhen

An input rule that repeats. See .Repeat When

Restriction A rule that has a restriction assigned to it. Restrictions are usedto validate and restrict user input. See .Restrictions

Schema orWSDL

The root rule in the rules file.

Service The service, which is a collection of operations.

(1), (0 - 1),(1-unbounded)

Inclusive minimum and maximum number of times this rulecan appear in the XML message.

Rules Tree Panel Toolbar

The Rules Tree panel offers a number of tools on the toolbar to edit and exercise mappings:

Test Invokes a tool to test the mappings. For more information, see Testing Outbound.and Inbound Messages

Map Automatically maps the selected rules to GUI components and CDF elements. Formore information, see Automatically Generating GUI Components and Input Mappingsand .Mapping Response Data to CDF GUI ComponentsDetach Removes mappings, restrictions, or HTTP headers for the selected rules.Delete Deletes the selected rules or all unselected sibling rules.Generate Generates the JavaScript code that will be needed to execute the rules file in the

running application. See .Calling a Data Service

86


running application. See .Calling a Data Service

For more information on toolbar buttons, see .Rules Tree Panel Toolbar

Rule Profile Panel

The Rule Profile panel, which is below the Rules Tree panel, has two buttons:

Original Schema Source Displays the read-only Schema source for the selected rule. Thisbinding can be updated by modifying the Source Path field in the Rule Profile panel.Maintaining this binding is only important at design time, particularly if the rule nodemay need to be reparsed from source.Rule Node Profile Displays profile information for the selected rule, such as targetnamespace, data type, and rule name. Some of these fields are editable. For moreinformation on these fields and how to modify profiles, see Working in the Rule Profile

and .Panel Rule Profile Panel

Settings Panel

The Settings panel, to the right of the Rules Tree panel, displays fields pertinent to the type ofrule selected in the rules tree. If no rule is selected in the rules tree or if multiple rules areselected, the Settings panel is blank. You can use the Settings panel to define how the rule isprocessed, such as add restrictions, mappings, JavaScript code, and so on.

For more information about fields in the Settings panel, see . For moreSettings Panelinformation on using the Settings panel, see .Working in the Settings Panel

For additional information and API documentation, hover the mouse over the question markicon and the APIs icon in the Settings panel.

87


APIs

CDFCONTEXT (Direction: input, output)*---CDF record node being acted uponCDFRECORDS (Direction: input, output)* - CDF records collection being iteratedRULENODE (Direction: input, output)* - Current node in the rules tree being processedMESSAGENODE (Direction: input, output)* - Node in the message being processedOBJECTTYPE (Direction: input, output)* - Deprecated. Now evaluates to 'Script'OBJECTNAME (Direction: input, output)* - Deprecated. Will always evaluate to whatFILTER once evaluated to--namely the Script being evaluatedFILTER (Direction: input, output)* - Deprecated. Do not use.setValue(strValue) (Direction: input)* - Equivalent to MESSAGENODE.setValue(strValue)setCDFContext(strXSLQuery) (Direction: input)* - Valid selection query to update

. Must return an object reference to a CDF Record node.CDFCONTEXT

setCDFRecords(strXSLQuery) (Direction: input)* - Updates record collection to beiterated. Must return a valid instance containing one or more CDFjsx3.util.Collection

record nodes.disableNamedRule(strNodeName) (Direction: input)* - Disables the named child rule, sothat it does not execute until is called.enableNamedRule

enableNamedRule(strNodeName) (Direction: input)* - Re-enables the named child rule.disableReferencedRule(objRuleChild) (Direction: input)* - Disables the child rule, sothat it does not execute until is called.enableReferencedRule

enableReferencedRule(objRuleChild) (Direction: input)* - Re-enables the child rule.

*Contextual variables listed as inputs are available when creating input messages. Outputs areavailable when processing output messages.

Mapper Log

The Mapper Log displays information about the outcome of parsing the starting sourcedocument(s). Different log levels can be selected by clicking on the Adjust Log Level button in the Mapper Log panel. Possible levels, from most detailed to least detailed, include Trace,Debug, Info, Warn, Error, and Fatal. The default level is Info and the XML Mapping Utilityresets to this value when closed.

The Mapper Log can also be used to view the message exchange when using the Test InterfaceTool.

For more information, see .Mapper Log

Mapper Log Toolbar

The Mapper Log toolbar has buttons for selecting log levels and clearing the log. For moreinformation, see .Mapper Log Toolbar

XML Mapping Utility Field Descriptions

For more information about fields in the XML Mapping Utility, see .XML Mapping Utility

88


Creating Mapping Rules Files

Mapping rules files are XML files authored in Common Exchange Format (CXF). CXF defineshow data is exchanged between objects, as well as how data is converted from one XML formatto another. CXF can be viewed as a visual form of XSLT with additional support forHTTP-based communication to transport the XML. In fact, a rules file can be compiled intoXSLT for faster performance. For information about CXF, see .Common Exchange Format (CXF)

Mapping rules are individual rules within the mapping rules file. There are many types ofmapping rules, each of which defines a particular aspect of the mapping process. For example,rules that descend from the output rule define how to process (read) a document in the localcache or returned from a remote service, while mapping rules that descend from an input ruledefine how to create (write) a node in an XML document.

Rules files created in an earlier version of General Interface are automaticallyupdated to the latest CXF version when opened in the XML Mapping Utility.

The first step in mapping GUI components or CDF documents to a mapping rule is to create amapping rules file.

The XML Mapping Utility accepts many types of source document formats to begin definingthe mapping rules file, including WSDL, XML, XSD, XHTML, JSON, and well-formed HTML.Data in any of these formats can be parsed and used as a starting point for defining mappings.When the mapping rule will be used to not only read and write XML, but also communicatewith a remote service, the HTTP methods, PUT, GET, POST, and DELETE are supported.

This section uses the General Interface WSDL Mapping 2 sample located in By default, this sample runs in Static/JSXAPPS/samples/WSDL_Mapping_2.workspace

Mode, rendering the results of a sample message on screen. To run against theXignite web service in Live Mode, register for a license key at

. Then set the project to Livehttp://www.xignite.com/xhistorical.asmx?op=xRegisterMode on the Deployment panel of the Project Settings dialog (Project > ProjectSettings > Deployment) and reload your browser.

Choosing the File for the Rules File Starting Point

The files you can use as the starting point for generating the mapping rules file in the XMLMapping Utility are WSDL Files; XML, XHTML, and Schema Files; and JSON Files.

WSDL Files

Select if your source document is a WSDL that defines a Doc Literal or RPC EncodedWSDLSOAP service. Specify the location of the WSDL file in the URL field. See Specifying Paths in the

.XML Mapping Utility

http://www.xignite.com/xhistorical.asmx?op=xRegister

89


XML, XHTML, and Schema Files

Select if your source document is a data format other than WSDL orXML/XHTML/SchemaJSON.

Specify the location of source document(s) in the URL fields. See Specifying Paths in the XML.Mapping Utility

JSON Files

Select if your source document is in JavaScript Object Notation data interchange format.JSONSpecify the location of the source document in the URL field. See Specifying Paths in the XML

.Mapping Utility

90


1.

2.

3.

4. a.

b.

5.

Specifying Paths in the XML Mapping Utility

The XML Mapping Utility resolves paths to files relative to the project. It's recommended thatyou copy WSDLs and other source document(s) for rules files to a directory in your project. Forexample, create a folder in your project and copy the WSDL into the folder. Thenwsdl wsdlenter wsdl_file.xml in the URL field of the XML Mapping Utility.wsdl/

If you need to resolve a path to a source document outside of your project, use an absoluteresolver, such as and .jsxuser:/// jsxapp:///

jsxuser:///... Resolves relative to the parent of the directory, which is theJSXAPPS

workspace. When General Interface Builder is running, this URI resolves relative to theworkspace directory.

jsxapp:// /...app If the Server instance corresponding to the host portion of the URI isloaded into memory, the URI is resolved relative to the application base directory (

).jsxappbase

Creating a Rules File

To create a new rules file:

Copy the file(s) to be used as the starting point for the mapping rules file to yourproject---a WSDL file, XML/HTML/Schema files, or a JSON file. This example uses

in .Historicals.wsdl workspace/JSXAPPS/samples/WSDL_Mapping_2/wsdl

Open the XML Mapping Utility using one of these methods: Select . File > New > Mapping RuleChoose XML Mapping Utility.Tools >

Select the file type you are using as the starting point for the mapping rules file: WSDL,XML/XHTML/Schema, or JSON. See .Choosing the File for the Rules File Starting PointEnter a URL and parse the document:

Type the URL for a source document(s) to be used as the starting point for therules file or click the Browse button to locate the file. See Specifying Paths in the

. XML Mapping UtilityFor example, if the is saved in a folder in your currentHistoricals.wsdl wsdl

project, type as the starting point for the rules file. wsdl/Historicals.wsdl

Click the button to generate the mapping rules file. Parse DocumentAfter you click Parse Document, a new rules file is created. The XML MappingUtility looks similar to the following:

Modify the mapping rules file as desired. For example, remove any extraneous rules as

http://www.generalinterface.org/docs/download/attachments/6685500/Creating_Mapping_Rules_Files-input_type_wsdl.gif

http://www.generalinterface.org/docs/download/attachments/6685500/Creating_Mapping_Rules_Files-mapper_ui.gif

91


4.

b.

5.

a.

b.

6.

Modify the mapping rules file as desired. For example, remove any extraneous rules asfollows:

Select a rule or rules in the rules tree. Use or to selectShift+click Ctrl+clickmultiple rules. Choose to delete the rules you've selected. OrDelete > Delete Selected Ruleschoose to delete the unselected rules. Delete > Unselected Sibling RulesFor example, select (not the singular GetHistoricalQuote) inGetHistoricalQuotesthe Rules Tree panel and choose from theDelete > Unselected Sibling RulesRules Tree panel menu to remove the other operation rules that were defined bythe source WSDL. This helps to reduce the size of your mapping rules file so thatit only defines those operations that will be run. For more information, see . Modifying Mapping Rules Files

Save the rules file with the extension..xml

Modifying Mapping Rules Files

The rules file is automatically created when the XML Mapping Utility first parses the sourcedocument(s). However, you can manually modify any individual rule to reflect structures notaccurately reflected in the source documents.You can add rules, add mappings, delete rules,view sample messages, and so on.

There are several ways to modify the mapping rules file:

Choose menu commands in the Rules Tree panel. See .Working in the Rules Tree PanelSet rule profile values in the Rule Profile panel. See .Working in the Rule Profile PanelSet fields in the Settings panel. See .Working in the Settings PanelUse drag-and-drop to map application GUI components to rules in the Rules Tree panel.See .Manually Mapping GUI Components and Input Mappings

Working in the Rules Tree Panel

The rules tree in the Rules Tree panel reflects the structure and order of the information beingtransformed---inputs that are being created to send to a remote service and outputs that will beprocessed to update information in General Interface applications. The source documents usedto generate the rules tree, which are typically WSDLs and Schemas, define the structure of therules tree. However, requirements do change and some interactions simply don't involveWSDL/SOAP.

In these situations, the tools in the Rules Tree panel help you manage the structure andrelationship for each rule, including reordering rules using drag-and-drop, adding new rules,cloning existing rules, and removing existing rules.

Reordering Rules

Because the rules tree is an execution tree, the order of the rules defines the order of execution.More specifically, the rules are traversed by depth and then breadth.

To reorder a rule, simply drag and drop it to a new location in the tree.

92


Adding Rules

To add a rule to the rules file, right-click a rule in the rules tree and choose .Add New RuleThen choose a command from the submenu, such as , , or . OnceElement Attribute CDATAyou've created a rule, you can modify the profile in the Rule Profile panel. See Working in the

.Rule Profile Panel

Cloning Rules

It's also possible to clone any node in the rules tree, including its descendant content. To clone arule, right-click a rule in the rules tree and choose Clone.

Deleting Rules

If you only need to work with some of the rules that were automatically generated when thesource document(s) were parsed, you can delete the unnecessary rules to reduce the clutter inthe Rules Tree panel. Reducing the rules in the tree also optimizes the rules file for the web as itonly contains necessary rules. This optimized rules file is a key advantage to using the XMLMapping Utility instead of the more verbose WSDL file. Note that deleting rules doesn't affectthe source document.

To delete a rule and all of its children from the rules tree, select the rule(s) you want to deleteand choose .Delete > Selected Rules

To delete all unselected sibling rules from the rules tree, select the rule(s) you want todon'tdelete and choose .Delete > Unselected Sibling Rules

Use or to select multiple rules.Ctrl+click Shift+click

Regenerating Rules

The ability to reparse rules is helpful if you've deleted a rule by mistake or you want to removethe rule settings. Often, minor changes to the source WSDL can be handled by downloading acopy of the updated WSDL and replacing the local copy that you used to create the originalrules file. Then, right-click the parent rule in the rules tree. Choose to re-parse fromReparsethat rule down. When the Reparse Selected Branch dialog displays, click the button toReparsereparse the rule. The rule is returned to its original state and all mappings are lost.

In some situations the reparse will fail. If that occurs, select the rule in the rules tree, choose theRule Node Profile radio button, and write your own XPath in the Source Path field to recreatethe binding between the rule in the rules tree and the Schema definition in the source documentfrom which it originates.

For example, if you parse the default WSDL , the ReturnCityState element maps toAddress.wsdl

the Schema node at this address:

//jsx3:schema[@targetNamespace='http://ws.cdyne.com/']//jsx3:element[@name='ReturnCityState']

The above address is brittle, because if an additional element is added to the Schema, it cancorrupt the absolute addressing. In such a case, simply edit the XPath to use an XPath addressthat is less brittle. For example,

//jsx3:element[@name='ReturnCityState']

93


When authoring your own XPath for a WSDL document, use the jsx1 prefix to pointto any node in the source document belonging to the namespace,

. Use jsx3 to resolve to the namespace, http://schemas.xmlsoap.org/wsdl/. For all other source document typeshttp://www.w3.org/2001/XMLSchema

(XHTML, Schema, XML, etc), the prefix is an incremented value (jsx1, jsx2, jsx3, etc)that reflects the order in which the namespace was first declared in the sourcedocument.

Adding Mappings

Rules that descend from input or output rules can be mapped to GUI components, as well as toCDF documents, records, and attributes. For example, you can map user input in a text field toa rule in your rules file and then send this data to a web service in the outgoing message.Incoming data from the web service can then be mapped to a CDF document, allowing theserver's response to be displayed in the user interface.

There are several ways to add mappings:

Drag and drop a GUI component from the Component Hierarchy palette to a rule in theRules Tree panel. See .Mapping GUI Components to Mapping RulesSelect a rule and create a mapping using the Map menu. See Mapping Response Data to

.CDF GUI ComponentsSelect a rule and set the mapping in the Mapping table in the Settings panel. See Adding

.a Mapping to the Mappings Table

For more information on mapping types, see .Message Rules

Detaching Mappings, Restrictions, and Headers

You can remove existing mappings, restrictions, and headers from a rule in the Rules Treepanel. This is useful if you've made an error or you want to reduce the size of your rules file.

To remove mappings from a rule, select one or more rules that have a mapping and choose . Rules that have mappings are indicated with a Mapping icon .Detach > Mappings

Mappings are displayed in the Settings panel on the right.

To remove restrictions from a rule, select one or more rules that have restrictions and choose . Rules that only have and restrictions don't have anDetach > Restrictions maxoccur minoccur

icon in the rules tree. Rules that have additional restrictions are indicated with a Restrictionicon . Restrictions are displayed in the Settings panel on the right.

Use or to select multiple rules.Ctrl+click Shift+click

To remove HTTP headers from a rule, select an operation rule that has HTTP headers andchoose . HTTP headers are displayed in the Settings panel on the right.Detach > Headers

Working in the Rule Profile Panel

After the physical structure of the rules tree is defined, you can use the Rule Profile panel todefine attributes for a rule, such as the node name and target namespace.

To modify the rule profile in the rules tree, do the following:

http://schemas.xmlsoap.org/wsdl/

http://www.w3.org/2001/XMLSchema

94


1. 2. 3. 4. 5.

To modify the rule profile in the rules tree, do the following:

Select the rule you want to modify in the Rules Tree panel.Select the radio button below the Rules Tree panel.Rule Node ProfileClick in the Value field next to the name you want to modify.Type in a value.Generate a test message to test the impact of changes to the rule profile. To generate atest message, right-click an input or output rule in the Rules Tree panel and choose

.Generate Sample Message

For field definitions, see .Rule Node Profile

Working in the Settings Panel

The most significant step in the mapping process is to create the actual mappings for each rule.To add and remove mappings, use the Settings panel, which provides a unique set of settingsappropriate to the type of rule. For example, operation rules allow you to define the endpointURL where an outbound request will be sent. Some of the most common settings can be setusing shortcut methods in the Rules Tree panel. For more information, see Adding Mappingsand .Detaching Mappings, Restrictions, and Headers

The Settings panel only displays fields pertinent to the selected rule. These four types of rulesdisplay fields in the Settings panel:

Operation or transaction rulesInput rulesOutput rulesMessage rules

Modifying Operation Rules

When you select an operation rule in the Rules Tree panel, the Settings panel displays the fieldsEndpoint URL, Method, and HTTP Headers.

95


For more information on these fields, see .Operation Rules

Using the SCRIPT Transport Method for JSON

The default transport method for the XML Mapping Utility is . Other transport methodsPOST

are supported, however, including a JSON-specific transport named .SCRIPT

When you use the method, the XML Mapping Utility uses a tag for the transportSCRIPT SCRIPT

instead of the standard XMLHTTP control.

With the method, you can set an additional field to specify that the service uses JSONPSCRIPT

(JSON with padding). When this field is set, the service class appends an additional parameterto the URL in the form

callback={method}

where { } is a temporary callback function managed by the Service instance.method

This allows for flexibility when using JSON Services that are also available as JSONP

96


This allows for flexibility when using JSON Services that are also available as JSONPServices---you can use the same endpoint URL, but implement different behaviors. If the givenJSONP Service expects the name of the callback parameter to be something different than

, use the runtime API call, , to pass the parameter name that is expected bycallback setJSONP

the given JSON Service.

For example, Yahoo! Pipes supports the parameter name for its implementation of"_callback"

JSONP. Therefore, when calling Pipes, make sure to set the true name of the callback beforesending the request:

objService.setJSONP("_callback");objService.doCall();

Note that the following two statements are equivalent, because the default JSONP name usedby the system is " ":callback

objService.setJSONP( );trueobjService.setJSONP("callback");

You can also implement a callback of your own by directly modifying the endpoint URL to callthe named function. In such situations, pass to this method, so that the transport will notfalse

attempt any form of automated callback.

If you implement your own callback handlers, you must manually conclude theservice call with a call to the Service method , by passing the JSON objectdoRespond

returned from the Service back to the mapper.

Modifying Input Rules

Input rules, also known as requests, can be modified in the Settings panel. To modify inputrules, select an rule in the Rules Tree panel. The Settings panel displays theInput (request)following fields: Stub URL, Stub Path, and onBeforeSend.

97


For more information on fields in the Settings panel, see .Input Rules

Stub URL

To enable the Stub URL field, click the button next to the field.Enable

The Stub URL field is typically used in conjunction with the Stub Path field to supportSOAP-based web services. When SOAP is used, each request document is encapsulated by aSOAP Envelope. The XML Mapping Utility treats the Envelope as a static document into whichthe actual request is placed. For example, the default stub used by the XML Mapping Utility isas follows:

<SOAP-ENV:Envelope =xmlns:SOAP-ENV "http://schemas.xmlsoap.org/soap/envelope/" =xmlns:SOAP-ENC "http://schemas.xmlsoap.org/soap/encoding/" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" = >xmlns:xsd "http://www.w3.org/2001/XMLSchema" <SOAP-ENV:Body> </SOAP-ENV:Body></SOAP-ENV:Envelope>

This document is generic enough to encapsulate the majority of SOAP messages and it'srecommended that you use it.

However, if this default document does not contain enough information, you can specify theURL for a static stub of your own. For example, you might also need to include a SOAP Headerin addition to a SOAP Body element in the Envelope.

98


The Stub URL value can be updated at runtime using the API call, . If more control is needed over the stub document and itssetOutboundStubURL

structures, you can provide a parsed instance of your own byjsx3.xml.Document

calling the method.setOutboundStubDocument()

Stub Path

When the stub document changes, it is often necessary to update the Stub Path to reflect theXPath address for the node in the Stub document to which the message will be appended. Toenable the Stub Path field, click the button next to the field.Enable

Use the Stub Path field in conjunction with the Stub URL field. Type in a valid XSL query thatdescribes where to place the generated document in the Stub document. For example, thefollowing document is generated when the GetHistoricalQuotes operation is called in theWSDL Mapping 2 sample:

<jsx1:GetHistoricalQuotes>ibm,yhoo,goog,tibx<jsx1:Identifiers> </jsx1:Identifiers>

Symbol<jsx1:IdentifierType> </jsx1:IdentifierType>3-21-06<jsx1:AsOfDate> </jsx1:AsOfDate>

</jsx1:GetHistoricalQuotes>

The combination of the default and Stub URL(GI_HOME_/GI_Builder/JSX/stubs/soap.xml) Stub

results in the following document being sent:Path(/SOAP-ENV:Envelope/SOAP-ENV:Body)

<SOAP-ENV:Envelope =xmlns:SOAP-ENV "http://schemas.xmlsoap.org/soap/envelope/" =xmlns:SOAP-ENC "http://schemas.xmlsoap.org/soap/encoding/" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" = >xmlns:xsd "http://www.w3.org/2001/XMLSchema" <SOAP-ENV:Body> <jsx1:GetHistoricalQuotes = >xmlns:jsx1 "http://www.xignite.com/services/" ibm,yhoo,goog,tibx<jsx1:Identifiers> </jsx1:Identifiers> Symbol<jsx1:IdentifierType> </jsx1:IdentifierType> 3-21-06<jsx1:AsOfDate> </jsx1:AsOfDate> </jsx1:GetHistoricalQuotes> </SOAP-ENV:Body></SOAP-ENV:Envelope>

This value can be updated at runtime using the API call, .setOutboundStubPath

onBeforeSend

Enter one or more JavaScript statements in this field to execute immediately before the requestmessage is sent. For example, if you want to output the XML request to the System Log beforesending it, you enter the following statement, where the keyword, , refers to the this

instance:jsx3.net.Service

jsx3.log( .getOutboundDocument().getXML());this

99


1.

2.

Modifying Output Rules

Output rules, also known as responses, can be modified in the Settings panel. To modify outputrules, select an rule in the Rules Tree panel. The Settings panel displays theOutput (response)following fields: Stub URL and onAfter Receive.

For more information on fields in the Settings panel, see .Output Rules

Stub URL

The XML Mapping Utility provides a static mode that allows you to test against a typicalservice response. This is useful in situations where the service isn't built yet or is inaccessible.Use the Stub URL field to specify an XML document that contains a response for testingpurposes.

To use the static mode feature, complete these steps:

Save a valid XML document (the typical response) and enter the URL in the Stub URLfield.Do one of the following to set the static mode:

Choose and change the Mode option on theProject > Project SettingsDeployment panel of the Project Settings dialog from Live to Static, and refreshthe browser to reload the project. See . Deployment PanelCall on the instance to make only that instance runsetMode(0) jsx3.net.Service

in static mode while leaving the remainder of the project in live mode.

Now when transactions are run by a service, a request isn't sent. Instead the sample documentis processed as if the remote service returned it.

100


is processed as if the remote service returned it.

This URL can also be set at runtime using the API call, .setInboundURL

onAfterReceive

JavaScript statements entered in the onAfterReceive field execute immediately after theresponse message is received and before the mappings are applied. This script executes incontext of the instance. This means that the keyword, , refers to the Service this Service

instance. For example, if you want to output the XML response to the System Log palette eachtime the service responds, you could write: jsx3.log(this.getInboundDocument().getXML());

onAfterReceive multiRef Example

Another example might be converting a multiRef format to a supported XML Mapping Utilityformat. This involves writing custom XSLT and running the XSLT on the incoming document toconvert a multiRef formatted document to a concrete structure that the XML Mapping Utilityunderstands. The custom XSLT might look similar to the following:

<?xml version= ?>"1.0" < version= = >xsl:stylesheet "1.0" xmlns:xsl "http://www.w3.org/1999/XSL/Transform"

< match= >xsl:template "/ | @* | node()"< >xsl:choose< test= >xsl:when "@href"< select= mode= />xsl:apply-templates "." "concretize"</ >xsl:when< test= >xsl:when "local-name() != 'multiRef'"< >xsl:copy < select= />xsl:apply-templates "@*" </ >xsl:copy</ >xsl:when</ >xsl:choose</ >xsl:template

< match= mode= >xsl:template "*" "concretize"< name= >xsl:param "myId" < select= />xsl:value-of "@href" </ >xsl:param

<< >xsl:copy xsl:apply-templates select= />"//*[@id=substring-after($myId,'#')]/*" </ >xsl:copy</ >xsl:template</ >xsl:stylesheet

To implement the above transformation, assume the above stylesheet is namedmultiRefConverter.xsl. You would enter the following code in the onAfterReceive field for yourgiven operation:

/* get the document just returned from the service */ myXML = .getInboundDocument();var this

/* load the xslt that will convert the axis multiref structure to a more concrete/literal format */

myXSL = ( jsx3.xml.XslDocument()).load("multiRefConverter.xsl");var new

/* transform xml to filter */ newXML = myXSL.transformToObject(myXML);var

/* replace the server's document the , transformed document */with new.setInboundDocument(newXML);this

101


1.

2.

3.

Modifying Message Rules

Message rules are rules that are included in the actual message structure and are identified bythe following icons and types:

Element Complex Attribute CData

When a message rule is selected in the Rules Tree panel, the Settings panel displays a Mappingstable, a Restrictions table, and a Repeat When field.

For more information on fields in the Settings panel, see .Message Rules

Adding a Mapping to the Mappings Table

To add a mapping to the Mappings table, complete the following steps:

Select a message rule in the Rules Tree panel to display the Mappings table in theSettings panel.Click the down arrow in a blank Type field of the Mappings table and select a type, suchas DOM.Type a value in the Value field, if required. For example, if you selected DOM, type thecomponent object name. A Mapping icon now displays next to the rule in the rulestree.

102


1.

2.

3.

For more information on mapping types, see .Mappings

For more information on mapping GUI components, see Mapping GUI Components to.Mapping Rules

For information on mapping response data, see Mapping Response Data to CDF GUI.Components

Restrictions

When Schema or WSDL are used as the input, any restrictions in the input source file display inthe Restrictions table of the Settings panel. Rules that have restrictions are indicated with aRestriction icon in the rules tree.

You can also add restrictions on a rule. For example, you might restrict user input to a five-digitnumber for a field that requires a zip code. To add a restriction:

Select a message rule in the Rules Tree panel to display the Restrictions table in theSettings panel.Click the down arrow in a blank Type field of the Restrictions table and select a type,such as maxLength.Type a value in the Value field, such as . This would limit user input to a maximum of5five characters.

For more information on restriction types, see .Restrictions

Repeat When

The Repeat When field is only applicable to outbound (input) messages. Enter one or moreJavaScript statements in the Repeat When field. As long as this field evaluates to true, thisspecific rule is rerun.

The Repeat When field is typically used by mapping rules that convert a JavaScript array intoan XML Node-set in the outgoing message. Conceptually, this feature is similar to a do-whileloop, where execution will happen at least once and continue as long as the while (RepeatWhen) statement is true.

If your mapping rule was originally created from a source WSDL, you can easily identifymessage rules that are part of a collection by looking at the Restrictions table. The rule is a goodcandidate for using the Repeat When field if it declares a maxLength restriction with a value ofunbounded, *, or greater than 1.

Example 1

For example, if you write a function similar to this:

103


window.iii= 1;window.getNext = () {function window.iii = window.iii+1; window.iii<=3;return}

and enter a call to the function in the Repeat When field for an addressToCheck rule in theWSDL Mapping 1 sample:

window.getNext();

the JavaScript code iterates through the function three times and three records are added to theXML message for the rule. This sample message shows the three added records.

<SOAP-ENV:Envelope =xmlns:SOAP-ENV "http://schemas.xmlsoap.org/soap/envelope/" =xmlns:SOAP-ENC "http://schemas.xmlsoap.org/soap/encoding/" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" = >xmlns:xsd "http://www.w3.org/2001/XMLSchema" <SOAP-ENV:Body> <jsx1:StandardizedAddress = >xmlns:jsx1 "http://ws.cdyne.com/" * ??? *<jsx1:addressToCheck> </jsx1:addressToCheck> * ??? *<jsx1:addressToCheck> </jsx1:addressToCheck> * ??? *<jsx1:addressToCheck> </jsx1:addressToCheck> <jsx1:LicenseKey> <rule_node/> </jsx1:LicenseKey> </jsx1:StandardizedAddress> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Example 2

Another example might be if you have an array of ids that you need to send to a server. Youcan include a Repeat When statement, so that the XML Mapping Utility knows how to iteratethrough this array. For example, the given web service might expect the following XML, wherethe id field repeats to contain as many ids as necessary:

<ids> <id/></ids>

A simple approach is to use the method on a Script mapping that you will bindArray.shift()

to the rule. For example, if you have a global array named , the Script mapping forid myArray

the rule would look like this:id

setValue( myArray.shift() );

Now, place the following in the Repeat When field.

myArray.length > 0

Because the shift method will remove the array element as soon as it is read, you can be certainthat the XML Mapping Utility will only loop as many times as it has array elements. Thisresults in only one node in the outgoing message for each item in the array:

104


<ids> a<id> </id> b<id> </id> c<id> </id></ids>

Also note that CDF mappings automatically repeat when necessary. For more information onCDF GUI components, see .Mapping Response Data to CDF GUI Components

Viewing Sample Messages

After you've modified your rules file, it's helpful to see the sample messages that are generated.This is a quick way to determine if your messages are written as you expect. You can view thedefault sample message or you can test the service and see the actual messages with the data.

To view a sample message, select an rule or an rule andInput (request) Output (response)choose Sample Message.

To test the service, see .Testing Outbound and Inbound Messages

105


1. 2.

1.

Mapping GUI Components to Mapping Rules

Before your application can communicate with a data service, you must define mappingsbetween application objects and data elements. These mappings allow data exchange betweenapplication GUI objects and a data service. For example, a user might enter stock symbols in atext field of an application and click a button to request financial data. After receiving therequest, the data service would send a response to the appropriate GUI objects, such as textfields or a Matrix, to display the financial data for the requested stocks.

Mapping GUI components to mapping rules involves two steps:

Create the mapping rules file. See .Creating Mapping Rules FilesDefine mappings in the rules file to map GUI components to data elements.

There are two ways to define mappings in the XML Mapping Utility:

Manual Mapping See Manually Mapping GUI Components and Input MappingsAutomatic Mapping See Automatically Generating GUI Components and Input

.Mappings

Manually Mapping GUI Components and Input Mappings

After creating the mapping rules file, you need to define mappings between GUI componentsand the rules in the mapping rules file.




To define mappings in the mappings rules file, complete these steps:

Expand the operation in the Rules Tree panel that you want to map to see the requestand response rules. Then expand the child rule. Double-click the ruleInput (request)with the blue down arrow to see the descendant rules. The blue down arrowindicates that there is more content to be mapped. For example, expand the operation rule (not singularGetHistoricalQuotesGetHistoricalQuote*)* in the rules tree. Expand the child rule.Input (request)Double-click the rule with the blue down arrow to see its childGetHistoricalQuotesrules.


106


1.

2.

3.

4. a.

b.

Arrange the Component Hierarchy palette and the Rules Tree panel so that componentsand elements are visible. Drag objects from the Component Hierarchy palette and drop them onto a rule in theRules Tree panel to bind GUI components to rules. Note that the mapped rule now

displays a Mapping icon in the rules tree. For example, drag the component from the Component Hierarchy palette to thesymbolIdentifiers rule in the Rules Tree panel of the XML Mapping Utility. A mapping is created between the GUI component and the target rule. Note thefollowing changes in the Settings panel on the right:

A mapping is added to the Mappings table on the right and default values arepopulated. The type of mapping is displayed in the Type column of the Mappings table. The value of the mapping is displayed in the Path/Value column of the Mappingstable.

Other types of mappings can be created by selecting a mapping type and typing avalue in the Path/Value field. For example, a rule could be mapped to a valuespecified by a JavaScript method call or to a CDF document, record, or attribute.For information on mapping types, see . Message RulesA Script mapping can be used to specify JavaScript code that manipulatesmessage structure or field data. For more information on this type of mapping, see

. Using Code with Data ServicesStructured rules are typically mapped to CDF documents, records, and attributes.For more information on this type of mapping, see Mapping Response Data to

. CDF GUI ComponentsSave the rules file as follows:

Click the button at the top of the XML Mapping Utility. Save

Navigate to the folder and type the filename with the .xml extension in therules

http://www.generalinterface.org/docs/download/attachments/6685502/Mapping_GUI_Components_to_Mapping_Rules-mapping_generated.gif

107


4. a.

b.

c.

1.

2. 3.

1.

2. 3.

Navigate to the folder and type the filename with the .xml extension in therules

field at the bottom of the dialog. The folder is automatically created in yourrules

project folder. However, rules files can be stored in any location in the projectdirectory. Click in the Save File dialog to save the file.Save

Now that you've defined the mappings between the GUI components and the data exposed bythe service, you need to generate the JavaScript function to call the service. Then specify thisevent in the Execute event of a component, such as a button. To generate the JavaScript code,see .Calling a Data Service

Automatically Generating GUI Components and Input Mappings

In addition to manually mapping existing GUI components to rules in the rules tree, it's alsopossible to generate GUI components and map them automatically. The XML Mapping Utilitycreates either a Text Box or a Select component, depending on field characteristics.

Automatically mapping GUI components to mapping rules involves several steps:

Select a component in the Component Hierarchy palette that is of type jsx3.gui.Blockfor the container of the GUI components.Create the mapping rules file.Automatically generate GUI components and mappings.




Automatically Defining Mapping in Rules Files

To automatically generate and map simple GUI components and input mappings, do thefollowing:

Select a component in the Component Hierarchy palette that is of type .jsx3.gui.Block

This will be the container for the GUI components that will be automatically generatedby the XML Mapping Utility.Create the mapping rules files as described in .Creating Mapping Rules FilesExpand the operation rule in the Rules Tree panel that you want to map. Then expandthe child rule. Double-click the rule with the blue down arrow to seeInput (request)its child rules. The blue down arrow indicates that there is more content to be mapped.

If you don't want to map all the child rules to GUI components, use or to select the rules you want to map.Ctrl+click Shift+click

For example, expand the operation rule (not singularGetHistoricalQuotesGetHistoricalQuote*)* in the Rules Tree panel. Expand the child rule.Input (request)


108


3.

4.

5.

Double-click the rule with the blue down arrow to see the rules.GetHistoricalQuotes

Select from the Rules Tree panel menu. Map > DOM (map and create)

The XML Mapping Utility generates the components and a Mapping icon in the rulestree indicates that a rule is mapped.

Save the mapping rules file with the .xml extension.

You can also automatically map and generate simple GUI components for the Output(response) rule.

Now that the mappings between the GUI components and the data exposed by the service aredefined, you need to generate the JavaScript function to call the service. Then specify thisfunction in the Execute event of a component, such as a button. To generate the JavaScript code,see .Calling a Data Service

http://www.generalinterface.org/docs/download/attachments/6685502/Mapping_GUI_Components_to_Mapping_Rules-mapping_operation_node.gif

http://www.generalinterface.org/docs/download/attachments/6685502/Mapping_GUI_Components_to_Mapping_Rules-generate_components.gif

http://www.generalinterface.org/docs/download/attachments/6685502/Mapping_GUI_Components_to_Mapping_Rules-auto_generated_components.gif

http://www.generalinterface.org/docs/download/attachments/6685502/Mapping_GUI_Components_to_Mapping_Rules-auto_generated_mappings.gif

109


1.

2.

3.

4.

Calling a Data Service

Mapping rules typically define how to contact a data service and process the input and outputmessages. To simplify this common use case, the XML Mapping Utility generates the functioncode that invokes the service, which you add to your project in an included JavaScript file.

Generating Function Code

To generate the function code that invokes the service and add it to your application, followthese steps:

Double-click the rules file in the Project Files palette to open it in the XML MappingUtility.Click the button and choose the operation from the drop-down list. ThisGeneratecopies the JavaScript code that implements the function to the clipboard. Click in theOKCode Generator prompt.Minimize the XML Mapping Utility and open or any included JavaScript file inlogic.js

your project.Position the cursor in the JavaScript file and press to paste the function code intoCtrl+v

the JavaScript file. The function code has the following format:

110


4.

5.

jsx3.lang.Package.definePackage( //the full name of the to createpackage "eg.service", //name the argument of this function (service) {function

//call method to begin the service callthis //(eg.service.callGetHistoricalQuotes();\) service.callOperation_Name = () {function objService = Server_Name.loadResource("Project_Resource_File_Id");var objService.setOperation("Operation_Name");

//subscribe and call objService.subscribe(jsx3.net.Service.ON_SUCCESS, service.onOperation_NameSuccess); objService.subscribe(jsx3.net.Service.ON_ERROR, service.onOperation_NameError); objService.subscribe(jsx3.net.Service.ON_INVALID, service.onOperation_NameInvalid); objService.doCall(); };

service.onOperation_NameSuccess = (objEvent) {function // responseXML = objEvent.target.getInboundDocument();var objEvent.target.getServer().alert("Success","The service call was successful."); };

service.onOperation_NameError = (objEvent) {function myStatus = objEvent.target.getRequest().getStatus();var objEvent.target.getServer().alert("Error","The service call failed.TheHTTP Status code is: " + myStatus); };

service.onOperation_NameInvalid = (objEvent) {function objEvent.target.getServer().alert("Invalid","The following message nodejust failed validation:\n\n" + objEvent.message); };

});

where Operation_Name is the name of the SOAP operation to invoke and is the ID of the rules file. Function names and alert text can beProject_Resource_File_Id

customized.The function, service.call is called when the data service_Operation_Name_Success,

responds. Communication between the application and the data service is asynchronous,so this function can be used for notification of a response.

Save the JavaScript file.

111


1.

2. 3.

Generated Code Package Structure

The code generated by the XML Mapping Utility demonstrates how to use packages toencapsulate the callback methods. By using (as well as ), you candefinePackage defineClass

author web pages with the same architectural constructs used in developing the applicationback-end.

In addition to providing a mechanism for good coding practices, is also usefuldefinePackage

because it allows the code to be introspected. This means that when an error occurs in code, astack trace can be run with relevant information about the call. Without this, only rudimentaryerror messages provided by the browser are available.

For example, if you were to use and an error occurred somewhere in your code,definePackage

the System Log palette would display this information:

10:31:36.431 global (ERROR) - Uncaught Exception: 'xp' is undefined(line: 47, file: file://C:\tibco\gi\GI_Builder.hta) at eg.service#doCallYetAgain() at eg.service#doCallAgain() at eg.service#call()

From the above information, you know that an error occurred on line 47, within the function . You also know the order of the call stack and whether iteg.service#doCallYetAgain()

involved static or instance methods. Had you not used , the output to the errordefinePackage

log would look something like this:

10:36:13.443 global (ERROR) - Uncaught Exception: 'xp' is undefined (line: 47, file: file://C:\tibco\gi\GI_Builder.hta) at anonymous() at anonymous() at anonymous()

For more information on how to use General Interface package APIs, see injsx3.lang.Package

General Interface API Reference (Help > API Documentation).

Invoking Function Code

To invoke this function code with a component event, enter the fully qualified name of thefunction into the appropriate field of the Events Editor palette:

Select the component in the work area or the Component Hierarchy palette.For example, in the WSDL Mapping 2 sample, select the button component.QueryChoose to open the Events Editor palette.Palettes > Events EditorEnter the JavaScript statement that calls the function in the Execute field in the EventsEditor palette. Be sure to enter the fully qualified name of the function:

eg.service.callOperation_Name();

For example, in the WSDL Mapping 2 sample, enter:

eg.wsdl2.callGetHistoricalQuotes();

112


3.

1. 2.

Mapping Response Data to CDF GUI Components

After receiving response data, you can map elements in the XML response to objects in theapplication. If the target object is a CDF component, the data must be transformed into CDF tobe displayed in your application. A CDF document is created and stored in the local data cachewhere the component can access it.

Transformation is a two-step process:

Map response elements to the equivalent CDF structures.Map GUI components to the CDF structures.




Map Response Elements to CDF Equivalents

Response elements can be mapped to CDF structures using the XML Mapping Utility. In theWSDL Mapping 2 sample, the GetHistoricalQuotes operation includes a repeating rule in theresponse message named HistoricalQuote. When a concrete message is processed by this rule, anew CDF record is created for each repeating instance. Then, various fields in the concretemessage are appended as attributes to the generated records.


113


1.

2.

3.

4.

5.

To map response elements to CDF, complete the following steps:

In the Rules Tree panel of the XML Mapping Utility, select the immediate parent of theelement that corresponds to a record in the CDF document. In this example, the parent element is GetHistoricalQuotesResult, because it contains therepeating HistoricalQuote elements that will map to records in the CDF document.In the Mappings table of the Settings panel, select from the drop-downCDF Documentlist in the Type column of the Mappings table.Type a cache ID string for the CDF document in the Path/Value column. For the WSDL Mapping 2 example, type historicals. This value becomes the cache ID of the CDF document, which appears in the Local DataCache palette after the response is received and inbound mapping logic is applied. If thefile exists, it's overwritten. If the file doesn't exist, a new file is created in the cache. In the WSDL Mapping 2 example, the rules file looks like this:

Select the element in the Rules Tree panel that corresponds to a record in the CDFdocument. In the WSDL Mapping 2 example, the element that corresponds to a CDF record isHistoricalQuote, which is the repeating rule. Select from the drop-down list in the Type column in the Mappings table.CDF RecordIt's not necessary to specify a value in the Path/Value column for this exercise.

114


1. 2. 3.

4.

You can also select an element in the rules tree and choose .Map > CDF Record

Although the Path/Value field is not required, it can be used to support recursion orhand off processing to another rule. For example, if there is another rule in yourmapping rules file that has a CDF Record mapping, you can enter the jsxid for thatrule. To find the jsxid (Rule ID), select the rule that you wish to call and click theRule Node Profile radio button.

When a repeating rule is mapped to a CDF record, by default the rules file automaticallyiterates through each corresponding node in the concrete message.

In the WSDL Mapping 2 example, the rules file looks like this:

Select an element to map in the Rules Tree panel. For example, select .DateSelect from the Type drop-down list in the Mappings table.CDF AttributeType a string value in the Path/Value field. This value becomes the attribute name in theCDF document. For example, type for the Date element. Date

You can also select an element in the Rules Tree panel and choose Map >. The attribute name is automatically generated in theCDF Attribute

Path/Value field.

In the WSDL Mapping 2 example, the rules file looks like this:

Follow the same process to create mappings for other elements to include in the CDFdocument: select the element, select as the Type, and enter a name for theCDF Attribute

115


4.

5.

1.

2.

document: select the element, select as the Type, and enter a name for theCDF Attributecorresponding CDF attribute.

To add multiple CDF attribute mappings at once, use or Ctrl+click to select multiple rules and select in theShift+click Map > CDF Attribute

Rules Tree panel menu.

In the WSDL Mapping 2 example, the rules file looks similar to this:

If the response has nested rules, you can replicate the nested structure using CDF Recordand CDF Attribute mappings. The attribute, which is required in every CDF document, acts as a key. You canjsxid

map an existing element that acts as a key value, such as a date or other unique value, to . If no such mapping exists, the XML Mapping Utility automatically adds a jsxid jsxid

attribute to the CDF document and generates a unique value.

Save the mappings file.

Map GUI Components to CDF Equivalents

After transforming the XML response to CDF, you need to map the CDF GUI components thatwill consume CDF data. This example uses a Matrix component to show how to create themappings.

To map GUI components to CDF elements, complete these steps:

Select the top-level GUI object that will consume data in the Component Hierarchypalette. In the WSDL Mapping 2 example, the top-level object is a Matrix component,gridResults, with six columns.Open the Properties Editor palette and specify the name of the cache document for theXML Cache ID property. In the XML Mapping Utility, this is the value in the Path/Valuecolumn for the CDF Document mapping. In this example, the value is : historicals

116


2.

3.

4.

5.

Select the GUI object in the Component Hierarchy palette that will display the dataseries. In the WSDL Mapping 2 example, the object is a column in the matrix, such asdate, security, open, and so on.Open the Properties Editor palette and type the attribute name in the Value field of theAtt Name property. In this example, choose in the Component Hierarchy palette and type , thedate Date

attribute name, in the Att Name field to map the date component to the CDF Dateattribute.

Repeat the process for other GUI objects until all series mappings are complete: selecteach object in the Component Hierarchy palette and type the appropriate CDF attributename in the Value field of the Att Name property.

Next, you need to test the rules file to be sure the mappings are correct. To test the rules file, see.Running a Quick Test

117


1. 2.

3.

4.

1.

2.

Testing Outbound and Inbound Messages

The XML Mapping Utility includes features for verifying inbound and outbound messagesgenerated using a rules file. The entire test sequence consists of executing outbound mappings,generating the outbound message, sending the message, receiving the response, and executinginbound mappings. Outbound and inbound filtering logic can also be entered and verified.

The XML Mapping Utility supports one-way (request) and two-way(request/response) messaging for WSDLs. An example of a one-way message is adelete operation sent to the server.

Setting Up a Test

To set up a test, specify values for each mapped element to simulate user input. There are twoways to simulate input:

Specify data in user input fields in the work area.Specify values in the Mappings table.

To specify values in the Mappings table, complete these steps in the XML Mapping Utility:

Select a rule in the Rules Tree panel.In the Mappings table of the Settings panel, select from the drop-down list in theScriptType column.Type the JavaScript function in the Path/Value column and specify a value, setValue

; setValue("value_")

The method is useful for specifying constants normally specified by a user atsetValue()

runtime or a value that is calculated from user input. When all values are specified, click the button.Save

Running a Quick Test

To test your mappings in the rules file, complete these steps:




In the application work area, , simulate user input by entering data in theappCanvas.xml

application. For example, enter stock symbols in the WSDL Mapping 2 example and choose a date. Select an operation rule, such as GetHistoricalQuotes, in the Rules Tree panel of the XMLMapping Utility. Right-click the rule and select . Execute (Quick Test)

When the response is received, a file with the specified name displays in the Local Data


118


2.

3.

a.

b.

When the response is received, a file with the specified name displays in the Local DataCache palette. This file exists in the cache instance used by the current component. In theWSDL Mapping 2 example, the file name in the Local Data Cache palette is .historicals

If you open this file, you'll see the response data from the service. Return to the work area to see the updated information in the mapped component. If theupdated information isn't displayed, complete these steps:

Select the top-level GUI component that consumes the data in the ComponentHierarchy palette. In the WSDL Mapping 2 example, select the component. gridResultsClick the button in the Component Hierarchy palette. Repaint

Test Interface Tool

To use the Test Interface Tool, click the button on the Rules Tree panel toolbar. The TestTestInterface Tool displays.

The Test Interface Tool is designed to guide you through the test sequence. The Create, Send,Receive, and Apply tabs correspond to phases of sending and receiving XML messages.Clicking a tab displays data that is relevant to the current test phase.

Before running a test, you can set breakpoints at various steps in the test sequence or you canalso test a rules file without breakpoints. For more information, see .Setting Breakpoints

119


1. 2.

Mapper Log

You can also use the Mapper Log to view the results of a message exchange. Use the Adjust LogLevel button to select a log level before you begin testing.

Running a Test

To run a test in the Test Interface Tool, complete these steps:

Click the button on the Rules Tree panel toolbar to open the Test Interface Tool.TestSelect the operation to test from the Select drop-down list at upper left.

The Create tab displays in the Test Interface Tool.

120


2.

3.

4.

The Create tab displays mappings for the outbound message and the following fields: Rule Name contains the name of the element. Type shows the type of object that is mapped. Path/Value contains the GUI component name or any associated JavaScript codefor this mapping. Post-Mapping Filter/Handler contains filter code to execute before sending themessage.

Click the button next to the Outbound Mappings label to start the test. IfStart Testyou didn't set any breakpoints and there aren't any errors, the test runs and cyclesthrough each tab: Send, Receive, and Apply. When the test is complete the Create tabdisplays again.If a breakpoint was set, the test advances to the Send tab. For more information, see

. Setting Breakpoints

The Send tab displays the outbound message and the following fields: URL contains the URL specified in the WSDL file.HTTP Headers contains header content for the message. The header text can becustomized by editing this value.

Name and Password are used for services requiring HTTP authentication.

121


4.

5.

6.

Name and Password are used for services requiring HTTP authentication.Method defines the method for contacting the Service. The most common are GETand POST.

The contents of the outbound and inbound messages can be savedto local files for testing purposes. By mapping the saved inboundfile and specifying the application mode as Static on theDeployment panel of the Project Settings dialog (Project > Project

), you can continue developing your application without aSettingsdata service connection. For more information, see Deployment

.Panel

If a breakpoint was set, click the button to advance to the next step. TheResumeoutbound message is sent to the data service, and the response is displayed in theReceive tab. Because the Receive tab doesn't have a breakpoint, the test continues to theApply tab. Click the tab to see the response. Receive

The Receive tab displays the following fields: HTTP Headers contains the HTTP headers.HTTP Status contains the message status, such as 200.Response contains the response. If the response isn't received, testing can still proceed with a simulated response

message. Click the button to the left ofGenerate Alternate Inbound Messagethe Response field. A response message for the specified operation is copied to theResponse field.

If the Test Interface Tool doesn't automatically advance to the Apply tab, click the Applytab to advance to the next step.

122


6.

1.

2. 3.

4.

The Apply tab displays the following fields: Pre-Mapping Filter/Handler contains filter code to execute on the inbounddocument.Inbound Mappings contains mappings of response rules to GUI components andinbound filtering logic, if any.

This is the final step in the testing process. If filtering logic and mappings executed withouterrors, the Create tab displays to allow you to start another testing cycle.

For a step-by-step example of running a test with the Address Lookup example, see Testing.Mappings

Setting Breakpoints

Before running a test, you can set breakpoints for viewing request and response messages ateach step in the process. Breakpoints can be set at the following steps:

Before applying filtering code, if specified, to the outbound messageBefore sending the outbound message to the data serviceBefore applying filtering code, if specified, to the inbound messageBefore executing inbound mappings

You can also test a rules file without breakpoints. However, it is usually helpful to view the testresults after each step. When advancing from one breakpoint to the next, you can return to theprevious breakpoint to retest only that step in the process. After modifications to mappingrules, changes can be tested from the last breakpoint.

To set a breakpoint and run a test with breakpoints in the Test Interface Tool, complete thesesteps:

Click any tab that displays a Breakpoint button , such as the Create, Send, or Applytab.Click a button to set a breakpoint.BreakpointClick the tab and run the test as described in . The test stops at anyCreate Running a Teststep that has a breakpoint set.Click the button to advance to the next step.Resume

123


4. Click the button to advance to the next step.Resume

Setting Filters

Filters can be applied to messages before an input message (request) is sent or after an outputmessage (response) is received and before the mappings are applied. This is useful when youwant to modify requests and responses.

You can enter JavaScript code to run as a filter on message rules. There are two ways to set afilter for message rules:

Input message rules Post-Mapping Filter/Handler field Enter JavaScript code in this field on the Createpanel of the Test Interface Tool to filter the input message during testing. onBeforeReceive field Enter JavaScript code in this field of the Settings panel ofthe XML Mapping Utility. Code entered in this field is always run on the message.Note that code entered here is also automatically displayed on the Create panel ofthe Test Interface Tool and runs during testing.

Output message rules Pre-Mapping Filter/Handler field Enter JavaScript code in this field on the Applypanel of the Test Interface Tool to filter the output message during testing. onAfterReceive field Enter JavaScript code in this field of the Settings panel of theXML Mapping Utility. Code entered in this field is always run on the message.Note that code entered here is also automatically displayed on the Apply panel ofthe Test Interface Tool and runs during testing.

Filters are useful for manipulating input and output messages as they travel between the clientand the server. For example, the XML Mapping Utility doesn't support multiRef structures thatare sometimes used to describe SOAP messages on Apache Axis servers. However, you can usethe onAfterReceive event handler to manipulate the output message from the server beforerunning the inbound mapping rules. Since you can't control your server environment, youcould write an XSLT that would convert the multiref indirection to a supported XML MappingUtility format. This transformation would occur on the client after the message is received. Formore information on this multiRef example, see .onAfterReceive multiRef Example

Further Information




Handling Errors and Timeouts

Setting Timeout Intervals

You can configure timeout intervals for a web service response using the method onsetTimeout

the instance. For more details, see the description of this method in the GeneralService

Interface API Reference in General Interface Builder (Help > API Documentation).


124


Handling Errors

When an operation generates an error, the error information is returned to the objectRequest

for the response. You can write a JavaScript function that gets the error information, addsbusiness logic for handling the error scenario, and displays the error to the user.

When errors occur, they can take several forms:

HTTP errors can be determined by calling on the instance and thengetRequest Service

querying the object for its status ( ) and status description (jsx3.net.Request getStatus

).getStatusText

SOAP faults can be processed by mapping to the fault rules that are created by the XMLMapping Utility when the WSDL is parsed (assuming the WSDL defines them).Formatting errors, such as a string in a number field or an enumerated value not beingentered, can be determined by subscribing to the ON_INVALID subject for the serviceinstance. When an error is encountered during message generation, the specifiedcallback function is notified.JavaScript errors display in the System Log palette for General Interface Builder.

125


1.

2. 3. 4. 5.

Chapter 6 Communicating with a Web Service Tutorial

This tutorial demonstrates how to use a General Interface application to communicate with aweb service.

About the Web Services TutorialCreating the Mapping Rules FileDefining MappingsGenerating Function CodeInvoking Function CodeTesting MappingsFurther Information on Tutorials and Sample Applications

About the Web Services Tutorial

This tutorial demonstrates how to use the XML Mapping Utility to map GUI components in anapplication to exposed data elements in a web service using the example application youcreated in General Interface Getting Started.

The example application allows a user to input a zip code and click a button to send the zipcode data to the web service. The web service receives the user input and sends a response thatreturns the matching city and state.

The example application is also available as a General Interface sample. To open the sample,choose .Project > User Projects > Samples > WSDL_Mapping_1

Before you begin this tutorial, you must create the application in General Interface GettingStarted.

In this tutorial, you'll complete the following tasks:

Create a mapping rules file that defines mappings between application objects and dataelements.Define mappings in the mapping rules file.Generate the function code that calls the web service.Invoke the function code.Test the mappings.

For more information on mapping and the XML Mapping Utility, see Communicating with.Data Services

For an introduction to the General Interface Builder user interface, see General Interface GettingStarted.

126


1. 2.

3.

4.

5.

6.

Creating the Mapping Rules File

Mapping rules files are XML files that define mappings between application objects and dataelements. The XML Mapping Utility provides a simple drag-and-drop interface for creatingmappings.

Rules files use the Common Exchange Format (CXF) for translating between applicationformats and web services. For information about CXF, see .Common Exchange Format (CXF)

To create the mapping rules file, complete the following steps:

Create the application described in General Interface Getting Started.Start General Interface Builder and open the project. For informationmyAddressLookupon starting General Interface Builder, see General Interface Getting Started.Navigate to your project folder in your file system and create a folder in yourwsdlproject folder: ./JSXAPPS/myAddressLookup/wsdlworkspace

Navigate to your General Interface installation in your file system and copy from to Address.wsdl GI_HOME/GI_Builder/plugins/jsx3.ide.mapping/wsdl workspace

./JSXAPPS/myAddressLookup/wsdl

Select in General Interface Builder to open the XMLFile > New > Mapping RuleMapping Utility.Select the radio button, remove the existing URL in the URL field, and enter WSDL

. Click the button. wsdl/Address.wsdl Parse Document

After you click the Parse Document button, you see the Rules Tree panel as shown here:

127


6.

1.

2. 3.

4. a. b.

c.

Defining Mappings

In this step, you'll define mappings between the GUI components of the myAddressLookupapplication and the data exposed by the web service.

The file used in the myAddressLookup project defines several operations.Address.wsdl

Because you only use one operation for the myAddressLookup application, ReturnCityState ,you can remove all other operations for the rules file as they aren't needed.

Defining Mappings for Input Data

To define mappings between the GUI components and the input (request) data, complete thesesteps:

Select the ReturnCityState operation in the Rules Tree panel. Confirm that it's the correctrule by reading the Schema source in the pane below:

<operation name="ReturnCityState">

Delete all other operations by selecting .Delete > Unselected Sibling RulesArrange the Component Hierarchy palette and the Rules Tree panel so that componentsand mapping rules are visible.Create a mapping between the txtZipcode component and the zipcode rule as follows:

Expand the rule in the Rules Tree panel. ReturnCityStateExpand the rule and double-click the child rule.Input (request) ReturnCityStateThe ReturnCityState request has two input rules: zipcode and LicenseKey. Drag the component from the Component Hierarchy palette to thetxtZipcode

zipcode rule in the Rules Tree panel. The following mapping is created in the

128


4.

c.

5. a. b.

c.

zipcode rule in the Rules Tree panel. The following mapping is created in therules tree.

Notice in the Mappings table to the right that the Type is DOM (Document ObjectModel), representing a mapping between a GUI component and a rule in the rulestree. The value is , the name of the GUI component. txtZipcode

Next, you'll use the method to set the license key value to use thesetValue()

evaluation license ("0"). The evaluation license provides limited access to theservice during testing. If the designated number of requests is exceeded, an erroris returned.

Set the value for the license key as follows: Click the rule in the Rules Tree panel.LicenseKeySelect from the drop-down list in the Type column of the Mappings table. Script

Type the following in the Path/Value field of the Mappings table:

setValue("0");

129


5.

c.

1. 2.

3.

4.

5.

6. a. b.

c.

1.

2.

Because the license key value, zero, is a JavaScript string, it must beenclosed in quotation marks.

Defining Mappings for Output Data

To define mappings between the application GUI components and the return (response) data,complete these steps:

Expand the rule and double-click the rule.Output (response) ReturnCityStateResponseDouble-click the rule to expand it to see all the children. ReturnCityStateResultYou'll only use two of the output rules: City and StateAbbrev. Select the output rules City and StateAbbrev, and delete all other operations by selecting

.Delete > Unselected Sibling RulesDrag the component from the Component Hierarchy palette and drop it on thetxtCity

City rule in the Rules Tree panel.Drag the component from the Component Hierarchy palette and drop it on thetxtState

StateAbbrev rule in the Rules Tree panel.Save the rules file as follows:

Click the button at the top of the XML Mapping Utility.SaveOpen the folder in the Save File dialog and type in therules GetCityandState.xml

field at the bottom of the dialog.Click to save the file.Save

Now that you've defined the mappings between the GUI components and the data exposed bythe service, you need to generate the JavaScript function to call the service. This is the samefunction that is defined for the button's Execute event in General Interface Getting Started.

Generating Function Code

A rules file defines the interaction between your application and the data service. Once therules file is complete, the application also needs to invoke the service. The XML MappingUtility generates the function code that invokes the service, which you add to your project in anincluded JavaScript file.

Recall that in one of the last steps of the "Creating an Application" tutorial in General InterfaceGetting Started, you configured the Find City and State button to execute the JavaScriptfunction . In this section, you generate the function codeeg.service.callReturnCityState();

and add it to your project.

To generate the function code that invokes the web service, complete these steps:

Click the button next to the Delete button in the XML Mapping Utility andGeneratechoose from the drop-down menu in the Rules Tree panel menu. ResizeReturnCityStatethe Rules Tree panel if you don't see the button.The JavaScript code for invoking this operation is copied to the clipboard. The codedefines a JavaScript function that creates a service instance. The service instance uses therules file to create the XML request document as well as process the service's XMLresponse document.

Click in the Code Generator prompt, which displays a message that the JavaScriptOK

130


2.

3. 4.

5.

6.

Click in the Code Generator prompt, which displays a message that the JavaScriptOKcode has been copied to the clipboard.Click the button in the XML Mapping Utility.MinimizeClick the tab in the General Interface Builder work area.logic.jsThis file contains business logic for your application. It should be empty except for acomment line.Delete the comment line and press to paste the contents of the clipboard into Ctrl+v

.logic.js

The JavaScript code in the file should look like the following:logic.js

jsx3.lang.Package.definePackage( "eg.service", //the full name of the to createpackage (service) {function //name the argument of this function

//call method to begin the service callthis //(eg.service.callReturnCityState();\)

service.callReturnCityState = () {function objService = myAddressLookup.loadResource("GetCityandState_xml");var objService.setOperation("ReturnCityState");

//subscribe and call objService.subscribe(jsx3.net.Service.ON_SUCCESS, service.onReturnCityStateSuccess); objService.subscribe(jsx3.net.Service.ON_ERROR, service.onReturnCityStateError); objService.subscribe(jsx3.net.Service.ON_INVALID, service.onReturnCityStateInvalid); objService.doCall(); };

service.onReturnCityStateSuccess = (objEvent) {function // responseXML = objEvent.target.getInboundDocument();var objEvent.target.getServer().alert("Success", "The service call was successful."); };

service.onReturnCityStateError = (objEvent) {function myStatus = objEvent.target.getRequest().getStatus();var objEvent.target.getServer().alert("Error","The service call failed. The HTTP Status code is: " + myStatus); };

service.onReturnCityStateInvalid = (objEvent) {function objEvent.target.getServer().alert("Invalid","The following message node just failed validation:\n\n" + objEvent.message); };

});

After the Find City and State button is clicked and the web service is called, the functiondisplays an alert dialog containing the text .The service call was successful

Right-click the tab and select .logic.js Save and Reload

131


6.

1. 2. 3. 4.

1.

2.

Right-click the tab and select .logic.js Save and ReloadThis command saves the file with the modified contents and also loads the file intomemory, making the methods available without requiring the browser window to berefreshed.

Invoking Function Code

In the "Creating an Application" tutorial in General Interface Getting Started, you added anExecute event for the Find City and State button in the Events Editor palette. The JavaScriptstatement you added invokes the function code that you just created.

Confirm that you entered the JavaScript statement that calls the function that invokes the webservice.

Click the tab to return to the application.appCanvas.xmlSelect the button in the Component Hierarchy palette.btnLookupChoose to open the Events Editor palette.Palettes > Events EditorConfirm that the following JavaScript statement is entered in the Value field of theExecute event in the Events Editor palette:

eg.service.callReturnCityState();

Next, you'll test the outbound and inbound messages.

Testing Mappings

The XML Mapping Utility includes features for verifying inbound and outbound messagesgenerated using a rules file. The entire test sequence consists of executing outbound mappings,generating the outbound message, sending the message, receiving the response, and executinginbound mappings. Outbound and inbound filtering logic can also be entered and verified.

To test the address example, complete these steps:

Simulate user input by manually typing a valid 5-digit or 9-digit zip code in the TypeZip Code field in the work area. For example, type in the Type Zip Code field.11357

Select the input rule in the Rules Tree panel in the XML Mapping Utility.LicenseKeyConfirm that you selected Script as the Type and entered in thesetValue("0")

Path/Value column of the Mappings table. If you haven't, refer to the instructions in .Defining Mappings

132


2.

3.

4. 5.

a.

b.

6.

7.

8.

Click the button on the XML Mapping Utility toolbar to open the Test InterfaceTestTool.Select from the drop-down list at upper left.ReturnCityStateBefore testing the mappings, insert breakpoints for viewing request and responsemessages at each step in the process.

Click the tab and click the button toSend Pause Before Sending the Messageinsert a breakpoint. Click the tab and click the Apply Pause Before Executing Inbound Mappingsbutton next to the Inbound Mapping header to insert a breakpoint.

Click the tab. The Outbound Mappings panel lists the bound request parametersCreateand mapping information.

Click the button next to the Outbound Mappings header to begin testingStart Testthe mappings. When the message is generated, the message displays in the Send tab.

Verify the message matches the following:

133


8.

9.

10.

11.

<SOAP-ENV:Envelope =xmlns:SOAP-ENV "http://schemas.xmlsoap.org/soap/envelope/" =xmlns:SOAP-ENC "http://schemas.xmlsoap.org/soap/encoding/" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" = >xmlns:xsd "http://www.w3.org/2001/XMLSchema" <SOAP-ENV:Body>

<jsx1:ReturnCityState = > 11357xmlns:jsx1 "http://ws.cdyne.com/" <jsx1:zipcode> 0</jsx1:zipcode><jsx1:LicenseKey> </jsx1:LicenseKey> </jsx1:ReturnCityState> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

The zip code you specified in the dialog should display as the contents of the element. For example,jsx1:zipcode

<jsx1:zipcode>11357</jsx1:zipcode>

If the message code is incorrect, return to the XML Mapping Utility and verify thatbindings are correctly specified before proceeding.Click the button next to the URL field. The outboundResume Test (Send Message)message is sent to the web service. When a response is received, the message displays inthe Receive tab and the XML Mapping Utility automatically advances to the Apply tab.Click the tab to view the inbound message. City and state information isReceivereturned in the and elements. However, this data has not yet beenCity StateAbbrev

bound to any text boxes. If you view the application in the work area, the City and Statefields are still blank.

Click the tab. The Test Interface displays inbound mappings to text boxes.Apply

134


11.

12. Click the button next to the InboundResume (Execute Inbound Mappings)Mappings header. In the work area, you can see that inbound mappings are applied totext boxes. The City and State fields have a blue background because the fields aredisabled. This is to prevent users from entering data in these fields.

The testing cycle for this data service configuration is complete, and the XML MappingUtility cycles back to the Create tab.

This concludes the tutorial. For other examples of connecting to web services, see samples in and on the Developer Network at ./JSXAPPS/samplesworkspace http://www.generalinterface.org

Further Information on Tutorials and Sample Applications






135


1. 2. 3.

Chapter 7 Using CDF Form Mapping Tutorial

General Interface 3.6 introduces a new CDF form mapping class, in . This newjsx3.gui.CDF

class enables developers to map a CDF document in the local cache to on-screen form fields.

About CDF Form MappingCreating the CDF Mapping ContainerMapping XML Data to the CDF ContainerUsing the APIs to Set CDF Mapping

About CDF Form Mapping

The CDF form mapping class, , enables developers to map a CDF document in thejsx3.gui.CDF

local cache to on-screen form fields.

By combining the features of and , this class enablesjsx3.gui.Block jsx3.xml.Cacheable

developers to read and write cache data without the need to author additional JavaScript code.In other words, this new class is a visual container that knows how to bind the form fields itcontains to values in a CDF document.

Creating the CDF Mapping Container

The CDF Mapping Container is a new control in the Form Elements component library.

To create a new CDF mapping container:

Create a new project.Expand the Form Elements folder in the Components Library.Drag the CDF Mapping Container icon to the Component Hierarchy to add the newelement to the DOM:

136


3.

4.

5.

Add two text boxes to the mapping container---drag two text boxes from the FormElement component library to the mapping container, and name them T1 and T2:cdf

Look at the Properties Editor for the cdf element---the XML String property contains thisValue:

<data jsxid= >"jsxroot"<record jsxid= first= last= middle= />"1" "john" "public" "q"</data>

137


5.

6.

7.

1. 2.

This is the default test document that is provided with the control. Like all other controlsthat implement the interface, this control will parse this string of XML and setCacheableit in the local cache, using a unique ID (or one assigned by the developer if applicable).

Open the Local Data Cache, and you'll see that the CDF mapping container has put the file there:_jsx_1_4_XML

Double-click the XML file name to open it in the work area, then click the FormattedSource XML button to see the formatted XML:

Mapping XML Data to the CDF Container

Now you'll map the contents of the XML data in cache to the CDF container:

Select the text box named T1.In the Properties Editor, type in the Value field of the CDF Attribute Name. first

The name appears in the T1 text box of the CDF mapping container, because thejohnvalue is assigned to the attribute in the XML file. john first

138


2.

3. 4.

1.

2. 3. 4.

5.

6.

Click the text box named T2.In the Properties Editor, type in the Value field of the CDF Attribute Name. middle

The letter appears in the T2 text box of the CDF mapping container, because the value q q

is assigned to the attribute in the XML file.middle

Cursoring CDF Records

This exercise illustrates how the CDF mapping container can cursor through its records todisplay different values in its descendant fields.

Open the Local Data Cache and find the CDF document.

The name of this cache document is assigned by the system and is acombination of the CDF GUI control ID and the string )."_XML"

Double-click the CDF file to open it for editing.Select and copy the record containing CDF attributes.Paste the record into the XML file, then change the record ID to 2, and the name of theattribute to : first jane

Right-click the XML file tab and select : Save to Cache

In the Properties Editor for the component, change the CDF Record Id value from 1 toT12, to change the name in the T1 text box:

139


6.

1. 2.

This exercise illustrates how you can make each form be a separate data store---it always readsthe value of the CDF Record Id, regardless of how the CDF control for the form is mapped.

A CDF container can:

Inherit a document from an ancestor CDF, or it can provide its own document.Map the records of an ancestor CDF, or provide its own mapping.

You can continue nesting components inside components in the CDF mapping container, sothat each nested component becomes a separate data item. Whichever container is the last in thenested chain determines the final mapping.

Using the APIs to Set CDF Mapping

You can use the General Interface APIs to set mapping for CDF containers. To see the API for aproperty, hover the mouse cursor over the property name in the Properties Editor.

To use the API to set a property:

Open .Tools > JavaScript ConsoleType the appropriate API syntax and values for the property.

In this example, the T1 text box originally contains the value of CDF record ID 2, which is .jane

Using the API setCDFId, we change the T1 text box value from record 2 ( ) to record 1 (jane john

):

140


Chapter 8 Optimizing Application Performance

This chapter discusses best practices for optimizing application performance. Fast performanceand a responsive user interface are critical to a good user experience.

For sample applications that demonstrate best practices, visit Developer Network at .http://www.generalinterface.org

Application DesignList of Best PracticesFaster Load TimesJavaScript CodeAPI UsageComponents and Component Serialization FilesBenchmarking Performance

Application Design

One of the critical phases of software design is application design. When designing yourapplication, it's important to consider the following:

What are the end-user requirements?What tasks will the user need to accomplish?What is the work flow?How easy is the application to use?

Application design includes application architecture, user interface design, and componentdesign. If this phase of application development is neglected, usability and performance can beadversely affected. For example, poor performance can occur if the application has a poorlydesigned, complicated user interface and if the application uses components that aren'tdesigned properly. While designing your General Interface application, consider the followingbest practices.

Design Applications to be Asynchronous

Whenever possible design your application to use asynchronous loading to improveperformance and usability. Use the following techniques:

Load only those areas of the application that are viewable by the user and required forthe user to begin using the application. For example, load the tab content for the firstvisible tab and load content of other tabs only when the user selects the tab.Specify an appropriate load type for your GUI components, such as PaintAsynchronously, Deserialize Asynchronously, and so on. For more information, seeGeneral Interface Component Guide.Load GUI components using Referenced - Asynchronous. For more information, see

.Component Hierarchy Palette Context MenuLoad XML data sources asynchronously. For more information, see General InterfaceComponent Guide.

Load resources asynchronously


141


1.

2.

Load resources asynchronously Asynchronously load JavaScript files using the jsx3.app.Server.loadInclude()method Asynchronously load an XML document and store it in the local data cache usingthe method jsx3.app.Cache.getOrLoadAsync

Asynchronously load an XML document using the jsx3.xml.Document.setAsync()method Issue a request asynchronously by passing to the bAsync=true

methodjsx3.net.Request.open()


For more information, see General Interface Component Guide.

Reuse Existing Components

Loading complex components can be one of the most expensive operations. Reuse componentswhenever possible instead of removing and recreating General Interface DOM nodes.

There are typically two use cases for reusing components:

Changing component properties reuse a component by simply changing a propertyprogrammatically, such as a column header or cell width.Showing components intermittently if a component is used intermittently, such as adialog or a tab, show and hide the component instead of destroying and recreating.However, remember that repainting a component repaints all children, even if they'rehidden.

Don't Store Data in Form Elements

Storing data in form elements, which is a typical HTML pattern, is not recommended forGeneral Interface applications. Instead of hiding and showing form elements to access data,persist data separately in an XML/CDF document or JavaScript variable. Note that persistingdata as XML is recommended, because memory management for XML is better than forJavaScript objects. Once data is persisted, load and unload components as needed withoutlosing data. For example, persist login and username data from a dialog and remove the dialogfrom the General Interface DOM instead of hiding the dialog.

List of Best Practices

Use these best practices when developing your applications:

Application Design Design Applications to be Asynchronous Reuse Existing Components Don't Store Data in Form Elements

Components and Component Serialization Files Eliminate Unnecessary Components Use Matrix and Paging

API Usage Minimize Repainting

Search Components in the DOM Efficiently

142


Search Components in the DOM Efficiently Exclude Logging Messages

JavaScript Code Remove Unused JavaScript Code Avoid Initializing Unused Variables Replace Old and Deprecated APIs with More Efficient APIs Replace JavaScript Manipulation of CDF with XSL Transformations Use jsx3.net.Service.compile() Avoid Excessive String Concatenations Identify Slow Functions Calls

Faster Load Times Upgrade to the latest version of General Interface Upgrade Browsers Load from Cache Split CDF Documents Create Custom General Interface Builds

Benchmarking Performance Review Component Statistics Use the General Interface Debug Build Use General Interface Performance Profiler Use JavaScript Profiling Tools Use General Interface Test Automation Kit

Faster Load Times

To improve the load time of your data and application, follow these best practices

Upgrade to the latest version of General Interface

To improve application performance, General Interface 3.3 and later uses a configuration flag todisable the forced synchronization (re-fetching) of an XML document by the MSXML3Document object. Therefore, XML files are retrieved from the browser cache instead ofre-fetched from the HTTP server.

General Interface 3.4 includes a more efficient startup mechanism. General Interface 3.4 and 3.5include significant performance enhancements, especially for Internet Explorer 6.

Upgrade Browsers

When possible, use the latest browsers supported by General Interface. Also, as you developyour application, benchmark your application in all browsers and versions used by your endusers. Benchmarking in all browsers prevents unexpected performance issues after deployment.For example, Internet Explorer 6 is slower than Firefox.

Note that subsequent Internet Explorer releases are significantly faster thanInternet Explorer 6.

143


Load from Cache

Whenever possible, use the method to cache XML GUIjsx3.app.Model.loadAndCache()

components that need to be reloaded multiple times and reload them from the local data cacheinstead of fetching from the server each time.

Split CDF Documents

Split large CDF documents to optimize data load times. For an example, see the Splitting CDFDocuments sample at .http://www.generalinterface.org

Create Custom General Interface Builds

To improve load performance for your application, you can use the General Interface LoadPerformance Optimization script to create a custom General Interface build that's optimized fora particular General Interface application. For more information, see Optimizing Load

.Performance

JavaScript Code

Use the following best practices when developing JavaScript code for your application.

Remove Unused JavaScript Code

Remove unused portions of code to make the JavaScript file smaller, speed up the JavaScriptloading time, and make the code run faster.

Avoid Initializing Unused Variables

Try to avoid initializing variables that might not be used. Initialize them after checking to see ifthey are needed. Logging messages, which are only needed during development, are a goodexample of unused variables.

Replace Old and Deprecated APIs with More Efficient APIs

Replace old and deprecated APIs with new, more efficient APIs. For example, use the faster and jsx3.xml.Entity.getChildIterator(),getAttributeNames(), selectNodeIterator()

methods instead of , , and respectively.getChildNodes() getAttributes() selectNodes()

Another example is to use instead of . Change thejsx3.util.List jsx3.util.Collection

following use of Collection:

for ( i=0;i<collection.getLength();i++){var x = collection.getItem(\i);var}

to List:

for ( it = objList.iterator();it.hasNext();\){var x = it.next();var}


144



Replace JavaScript Manipulation of CDF with XSL Transformations

Replace JavaScript manipulation of CDF with faster, more efficient XSL transformations. Forexample, if fifty customer records are returned from a response, iteratingjsx3.net.Request

through all the elements in JavaScript is less efficient than building an XSL template andapplying it using the API.jsx3.xml.Template

GUI components that implement have built-in properties forjsx3.xml.Cacheable

XSL transformations. See the XML Transformers property in the Properties Editorpalette and in General Interface APIjsx3.xml.Cacheable.setXMLTransformers()

Reference.

Use jsx3.net.Service.compile()

Use the method to compile the CXF rules for a service instance tojsx3.net.Service.compile()

an equivalent XSLT document. This enables much faster performance than using theDOM-based iterator (default) to convert the XML response document into a CDF Documenttype. Call this method immediately before or after the method for best performance.doCall()

For more information, see in General Interface API Reference.jsx3.net.Service.compile()

Avoid Excessive String Concatenations

In Internet Explorer, string concatenations are very expensive, especially with large strings. Abetter approach is to replace string concatenations with an array, push new strings to the array,and then use an method call to get a single string. This approach essentially usesArray.join()

a string buffer instead of successive concatenations. For more information, see in General Interface API Reference.window.Array.join()

Identify Slow Functions Calls

When possible, identify and optimize function calls that are taking excessive time. Use Firebugfor Firefox and jsLex for Internet Explorer to profile your JavaScript code and identify slowfunctions.

In Internet Explorer 6, beware of String and RegExp literals in loops. For bestperformance, declare these literals statically or declare them outside of loops.

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.

145


1.

2.

1. 2.

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 BuildRepaint 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 RepaintsAvoid redundant repaints on the same object.When calling any load APIs, such as the jsx3.app.Model.load(),

, and methods, pass asjsx3.app.Model.loadAndCache() jsx3.app.Model.loadXML() false

the second parameter to avoid a repaint if changes will be made to the component. Thenrepaint the component after changes are complete using the

method.jsx3.gui.Painted.paintChild()

Some methods, such as and , can triggerremoveChild(), setChild(), adoptChild()

repaints of the parent whose child is removed, set, or adopted. When possible, reusecomponents instead of removing and loading them.If removing multiple children at the same time, use the

method to avoid multiple repaints.jsx3.app.Model.removeChildren()

For Matrix components, call the method if only the data has changed.repaintData()

The method paints only the data rows and doesn't recalculate andrepaintData()

re-profile the box profile and resulting XSLT. Therefore, the method isrepaintData()

more efficient than the method.repaint()


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 GeneralInterface DOM is transmitted directly to the browser DOM.Paint/repaint: this is a slower, more expensive paint, where the General Interface DOM isfirst serialized to an HTML string and then replaces part of the browser DOM.

Consider these basic rules when using set methods:

If the set method doesn't have a final boolean parameter ( ), the component isn'tbRepaint

repainted. For example, . However, there arejsx3.gui.Block.setBackground(strBG)

some exceptions.If the set method has a final boolean parameter ( ), you control the behavior. ThebRepaint

default setting is , meaning the component isn't repainted. For example, false

.jsx3.gui.Block.setText(strText, bRepaint)

If the final boolean parameter is set to , the component is repainted, which is usuallytrue

an inexpensive HTML DOM operation. However, in some cases a full repaint occurs.

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

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


146



Search Components in the DOM Efficiently

There are many ways to access objects in General Interface. The most common methods are the and methods. These methods search an application index togetJSXByName() getJSXById()

quickly find the specific object in the General Interface DOM. Other methods are available, suchas , but are less specific and less efficient at locating objects.getJSX()

Don't use to search the General Interface DOM, because it has access to alljsx3.GO()

loaded General Interface applications and searches all of them for a DOM node ofthe given name. Recommended usage is in the General Interface Builder JavaScriptConsole 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 method in a dialog button execute eventgetAncestorOfType()

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 thesemethods. 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. Forinformation on how to search the General Interface DOM safely when deploying multipleapplications in the same web page, see Protecting Namespaces in Multiple Application

.Environments

147


Exclude Logging Messages

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

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

var Logger = jsx3.util.Logger; log = Logger.getLogger("com.tibco");var

(log.isLoggable(Logger.ERROR))if log.info(xmlDoc.toString()); // serializing XML may be // expensive

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

Components and Component Serialization Files

Use the following best practices when working with components and component serializationfiles.

Eliminate Unnecessary Components

For cross-browser compatibility, General Interface abstracts the browser box model andcalculations are handled by JavaScript instead of natively by the browser. Multiple JavaScriptcalculations can slow performance.

Follow these best practices to improve application performance:

Reduce the nestings and total number of blocks Don't use blocks for fillers. Use padding and margins instead of extra filler blocksfor a lightweight and more efficient component. Design your application with the fewest blocks possible. Too many blocks canslow performance when resizing and repainting.

Use layout components sparingly Only use layout components when appropriate. For example, don't use a layoutcomponent if there is only one child.

Use Matrix and Paging

Use the Matrix components whenever possible to display large amounts of data. The Matrixcomponent uses various paging models to improve overall rendering performance and pagingtuners to provide greater control over how and when data is loaded. For more information, seeGeneral Interface Component Guide.

148


Benchmarking Performance

Use the following tools and General Interface features to assist you in benchmarkingapplication performance.

Review Component Statistics

As you work with components in General Interface Builder, you can view component statistics,such as component file size and time to paint, to assist you in evaluating and benchmarkingapplication performance. For more information, see General Interface Component Guide.

Use the General Interface Debug Build

As you develop your applications, use the General Interface debug build to detect and reportsuch performance issues as multiple repaints, multiple box recalculations, times to performvarious operations, and so on. The General Interface debug build is available from thedownload site at .http://www.generalinterface.org

Use General Interface Performance Profiler

Use General Interface Performance Profiler to profile and benchmark your General Interfaceapplications during development. The General Interface Performance Profiler is available fromthe download site at .http://www.generalinterface.org

Use JavaScript Profiling Tools

During development, use JavaScript profiling tools to debug and profile JavaScript code, aswell as expose performance issues.

For more information, visit these web sites:

Firebug http://www.getfirebug.comjsLex http://rockstarapps.com/pmwiki/pmwiki.php?n=JsLex.JsLex

Use General Interface Test Automation Kit

Test your General Interface applications with General Interface Test Automation Kit, which isdeveloped using the open source Selenium Core test tool, is a functional testing tool for testingGeneral Interface applications.

The General Interface Test Automation Kit is available from the download site at .http://www.generalinterface.org



http://www.getfirebug.com

http://rockstarapps.com/pmwiki/pmwiki.php?n=JsLex.JsLex


149


Chapter 9 Accessing Data Across Subdomains

This chapter describes how a General Interface application communicates with web serversacross subdomains. A subdomain is a domain that is part of a larger domain. For example,About.com has several subdomains—antiques.about.com, autorepair.about.com, and so on.

There are two general scenarios for accessing a General Interface application, local provisioningand remote provisioning. Local provisioning doesn't require configuration if default browsersecurity settings are used. Remote provisioning requires configuring proxy communication ormodifying default browser security settings.

Local ProvisioningRemote Provisioning

Local Provisioning

With local provisioning, the application files and the General Interface Framework are locatedon the same machine as the web browser. When the application is accessed, the browser loadsrequired files into cache using a file URL, for example .file:\\C:\tibco\gi\GI_Builder.htmlWith the default browser settings, there are no restrictions on communicating with web serversoutside the subdomain.

Local Provisioning

150


Disabling Firebug in Firefox

When using Firefox, cross-domain access is allowed when running from the file system. Thisallows easy testing of remotely provisioned services from within General Interface Builder.However, if the Firebug add-on is enabled for local files, a permission denied exception isthrown. To bypass this error, disable Firebug in Firefox (Tools > Firebug > Disable Firebug forLocal Files).

Remote Provisioning

With remote provisioning, the deployed application files and the General Interface Frameworkare located on a web server. A browser on a remote machine accesses the files using an HTTPURL and loads files into cache. When an HTTP URL is used, default browser security settingsprevent your application from communicating with web servers outside the subdomain. Thefollowing figure illustrates the remote provisioning scenario before any configuration isperformed.

Remote Provisioning Before Configuration

Without configuration, an application can only communicate with www.mydomain.com. Thebrowser prevents communication with other subdomains, such as inside.mydomain.com andrss.yahoo.com. However, the same application in a local provisioning scenario cancommunicate directly with web servers outside the subdomain.

151


Configuring Proxy Communication

To enable proxy communication, you configure the web server where the application isdeployed and the application. This allows the web server to broker interactions between theapplication and web servers outside the subdomain.

Remote Provisioning After Proxy Services Configuration

Configuring the Server

Steps for configuring the web server vary according to vendor.

Apache Install and configure the mod_proxy module. Then use the ProxyPass directiveto route responses through the General Interface application domain server, such aswww.mydomain.com, rather than a web server outside the subdomain. For details, seethe Apache HTTP Server documentation at .http://httpd.apache.orgMicrosoft IIS Install and configure the Microsoft Internet Security and Acceleration (ISA)Server. Write an ISAPI Filter to perform reverse-proxying or use an equivalentthird-party product. The software must intercept an HTTP Request made to the GeneralInterface application domain server, such as www.mydomain.com. Copy the entireHTTP header packet, change the HTTP Host header, and perform a new HTTP Requestusing the WinHttp API. For details, see

.http://www.microsoft.com/isaserver/default.mspxCustom Write a server process, such as a servlet, .NET service, or web service, that actsas a proxy between the General Interface application domain server and othersubdomains.

http://httpd.apache.org

http://www.microsoft.com/isaserver/default.mspx

152


Configuring the Application

There are two ways to retrofit a General Interface application so that it requests data fromservers using a proxy:

Modify absolute URLs to refer to the proxy URLConvert non-proxied URLs to proxied URLs

Modify Absolute URLs

The simplest way is to modify any absolute URLs in the project to refer to the proxy URL.Absolute URLs may exist in many types of project source files including JavaScript, servicemapping rules, and component serialization files. Use your favorite text editor to perform aglobal search and replace in the project source files for strings matching "http://" or "https://".

Convert Non-proxied URLs to Proxied URLs

The second way to retrofit a General Interface application so that it requests data through aproxy is more complicated but provides a mechanism for easily switching back and forthbetween proxied and non-proxied requests. This is accomplished by defining a function thatconverts a non-proxied URL to a proxied URL and then modifying any request before it is sentto use the proxied URL. Consider the following code sample as shown in the followingexample.

153


jsx3.Package.definePackage("eg.proxy", (proxy) {function

// , all URLs are converted to the proxied formatswitch if true proxy.PROXY = (window.location + "").indexOf("file") != 0;

// the domain of my proxy host proxy.PROXY_HOST = "proxy.eg.com";

// the path prefix of the proxied URLs proxy.PATH_PREFIX = "proxy/";

/** * Converts a non-proxied URI to a proxied URI PROXY is .if true * <p/> * <code>http://www.domain.com/service/op</code> will be converted to * <code>http://PROXY_HOST/PATH_PREFIX/www.domain.com/service/op</code> * * @param strURI { } the URI to convertString * @returns { } the converted URIString */ proxy.convertURI = (strURI) {function (proxy.PROXY) {if uri = jsx3.net.URI(strURI);var new (uri.getHost() != proxy.PROXY_HOST &&if (uri.getScheme() h1. "http" || uri.getScheme() "https")) { jsx3.net.URI.fromParts(uri.getScheme(), ,return null proxy.PROXY_HOST, , proxy.PATH_PREFIX + uri.getHost() +null uri.getPath(), , ).toString();null null } {else strURI;return } } {else strURI;return } };

/** * Open all requests method to ensure that URLs are properlywith this * converted proxy.for */ proxy.openRequest = (strURL) {function objRequest = jsx3.net.Request();var new objRequest.open("GET", proxy.convertURI(strURL)); objRequest;return };

/** * Open all services method to ensure that URLs are properlywith this * converted proxy.for */ proxy.openService = (strRulesURL, strOpName) {function objService = jsx3.net.Service(strRulesURL, strOpName);var new objService.setEndpointURL(proxy.convertURI(objService.getEndpointURL())); objService;return };});

154


1. 2.

3.

Modifying Internet Explorer Security Settings

An alternative to configuring proxy services is to modify Internet Explorer security settings oneach client machine that accesses the application.

This option is only available for Internet Explorer. For Firefox, you must configureproxy communications. See .Configuring Proxy Communication

When the security settings are set to accept the subdomain where the application is deployed asa trusted site, the browser allows direct communication with web servers outside thesubdomain.

Remote Provisioning After Browser Configuration

To modify Internet Explorer browser settings on a client machine, complete these steps:

Exit General Interface Builder.In Internet Explorer, select from the browser menu. TheTools > Internet OptionsInternet Options dialog displays.Click the tab and click the zone.Security Trusted Sites

155


3.

4. 5. 6.

7.

Click the button.Custom LevelEnable the setting, then click OK.Access data sources across domainsClick the button.Sites

Type the name of the subdomain where the application is deployed in the Add this Web

156


6.

7.

8.

Type the name of the subdomain where the application is deployed in the Add this Web field, and then click .site to the zone OK

Click again to close the Internet Options dialog.OK

157


Chapter 10 Adding and Debugging JavaScript Code

This chapter describes how to add and debug JavaScript code in your application.

About Debugging JavaScript CodeAdding Code at the Component LevelAdding Code at the Application LevelUsing Code with Data ServicesThe JavaScript Console

About Debugging JavaScript Code

General Interface Builder allows you to add presentation logic to your application by writingcustom JavaScript code. Presentation logic is any type of coding required to meet a user-specificrequirement. For example, you can query a web service when a user clicks a button, or open adetail view in a list when a user selects a row.

There are several ways to add custom JavaScript to an application. The code is processeddifferently depending on how it's specified.

In General Interface Builder, fields where you can specify JavaScript code aredistinguished visually with a light blue graph pattern background.

The following table shows the locations in General Interface Builder where you can specifycode and the impact of each method.

158


CodeLocation

What Code Does

EventsEditorpalette

Each event can be associated with JavaScript statements.

ComponentProfileview inwork area

JavaScript statements can be executed either before or after a component isloaded in the application.

Dynamicpropertiesfile

JavaScript statements execute in application (server) context to set a dynamicproperty value.

XMLMappingUtility

JavaScript statements execute in context of the mapped XML message nodebeing processed or created.

ProjectSettingsdialog

JavaScript statements execute during the onLoad event in application (server)context immediately after the root and body canvases are drawn on-screen.JavaScript statements execute during the onUnload event when the browserwindow is unloaded.

JavaScriptfileincluded inproject

A file containing JavaScript statements, method calls, constants, and so on canbe included in a project. Any static execution is evaluated before componentsare loaded.

JavaScriptConsole

Any JavaScript statements can be checked for errors before adding them to theapplication.

Adding Code at the Component Level

There are two ways to add code to components:

Associate code with the object's model eventExecute code before or after the object is deserialized

Associating Code with an Event

Each GUI component defines a set of model events. For example, a button component has anExecute event that fires when a user clicks the button. Events act as triggers for JavaScript code.When an event occurs, the associated code is executed. By binding JavaScript code to acomponent's event, user interactions can be captured, providing an event-driven interface.

To associate JavaScript code with an event, type the code in the Value field in the Events Editorpalette, as shown here.

159


The statements and are defined in an included JavaScript filedoListClick() doShowDetails()

that is loaded when the browser first initialized. It is considered best practice to keep eventbinding code to a minimum, managing the bulk of the presentation logic in a JavaScriptinclude. For more information, see .Including JavaScript Files

Executing Code Before or After Deserialization

For any component, you can specify JavaScript to execute before or after the object isdeserialized. The code is executed at runtime as well as in General Interface Builder,immediately before or after the associated serialization file is opened for edit.

Each component, which is represented by a tab in General Interface Builder, exposes a subset offields within the Component Profile view. To execute JavaScript statements before or after

component deserialization, type the statements in the onBeforeDeserialize or

160


component deserialization, type the statements in the onBeforeDeserialize oronAfterDeserialize field, as shown here.

Before Deserialization Example

Before deserialization, the XML file can be accessed directly using the variable. ForobjXML

example, typing in the onBeforeDeserialize field displays the contents of thealert(objXML);

serialization file in an alert dialog.

161


Executing JavaScript statements before an object is deserialized is useful when the runtimeneeds to be prepared before the component is loaded. For example, when data that is used by acomponent needs to be preloaded.

After Deserialization Example

After deserialization, the root-level object in the serialization file can be accessed directly usingthe variable. For example, typing in the onAfterDeserialize field listsobjJSX alert(objJSX);

object type, ID, and name of the root-level object in an alert dialog.

Executing JavaScript statements after an object is deserialized is useful when the componentneeds to be initialized with information only available at runtime. For example, the object ID(which is created after deserialization) can be displayed in the caption bar of a dialog. The mostcommon use for serialization event bindings is to configure generic, reusable components withruntime-specific information.

In both cases, the JavaScript statements are executed only if the component is loaded atruntime.

Adding Code at the Application Level

There are several ways to add code at the application level:

Including JavaScript files. See .Including JavaScript FilesExecuting code to set a dynamic property value. See Specifying Code in Dynamic

162


Executing code to set a dynamic property value. See Specifying Code in Dynamic.Properties

Specifying the onLoad script. See .Executing Code When the Application LoadsSpecifying the onUnload script. See .Executing Code When the Application Unloads

Including JavaScript Files

The most common way of adding custom code to an application is an included JavaScript file.JavaScript files can contain function definitions, method calls, constant declarations, and so on.Functions and other constructs defined in a file can be referenced in any other location whereyou can specify JavaScript code, such as the Events Editor palette. The file must be loaded intomemory to be accessed by the application.

JavaScript files can be created in General Interface Builder and are automatically added to yourproject.

A default JavaScript file, , is created and included in your project when the project islogic.js

created. This file initially contains no code, and can be deleted from the project as needed. Youcan add JavaScript code to , or create one or more new files, partitioning code amonglogic.js

them. For smaller applications, a single included JavaScript file is usually sufficient. For larger,more complex applications, it can be helpful to divide the code among multiple files accordingto feature area, class, or functional role.

To add a JavaScript file to your project, select . A new tab is addedFile > New > JavaScript Fileto the work area for editing the file contents.

When saving files in the work area, you can save changes to disk (Save), save to disk and

163


1.

2.

3.

When saving files in the work area, you can save changes to disk (Save), save to disk andupdate changes in browser memory (Save and Reload), and load or reload from disk intobrowser memory (Load/Reload). Files must be loaded into memory to be part of the liveapplication.

By default, is configured to automatically load after the General Interface system fileslogic.js

have loaded but before the application initializes. Other included JavaScript files can also beloaded automatically by right-clicking the file in the Project Files palette and selecting the AutoLoad option. If a file is required only for a specific module, you can load the file when neededusing the method of the class.loadResource() Server

For more information on the Auto Load options, see . For information onFile Profile Dialogdynamic class loading, see .Class Loading in General Interface

Specifying Code in Dynamic Properties

Each dynamic property has an property that signifies if the contents of the Value field willeval

be executed as JavaScript or simply treated as a string. This feature is useful for configuring acomponent when the value of a component property is determined by an external condition.For example, you could specify conditional logic in a JavaScript file included in your project,then reference the result in a dynamic property.

Dynamic properties files execute their contained JavaScript only once, when they are firstloaded into the application. This means that the DateNow field in the above screenshot willreflect the date/time when the dynamic properties file first loaded.

To associate JavaScript code with a dynamic property,

Open an existing dynamic properties XML file or create a new one. See Creating.Dynamic Properties Files

Check the checkbox for the property to indicate that the value should be evaluatedEvalas code.Type one or more JavaScript statements separated with semicolons in the Value field.

For more information on dynamic properties, see .Dynamic Properties Files

164


Executing Code When the Application Loads

You can execute JavaScript code immediately after the initial component has loaded but beforeit's painted on-screen. The Project Settings dialog includes the onLoad Script field for thispurpose.

To execute JavaScript code when an application loads, select Project > Project Settings > and type the code in the onLoad Script field. In the following figure, is aDeployment init()

global function defined in a JavaScript project resource.

Executing JavaScript code before the application loads is useful for performing tasks thatshould complete before a user accesses your application. For example, you could add code thatchecks for the presence of an HTTP cookie before displaying a login dialog.

Executing Code When the Application Unloads

You can also execute JavaScript code when the browser window is unloaded. The ProjectSettings dialog includes the onUnload Script field for this purpose.

165


There are several ways to unload a browser window, including closing the window, refreshingthe window, or navigating to another URL. The onUnload event allows you to save user stateand do any final cleanup before exiting. This script can include one or more JavaScriptstatements which execute in context of the Server. The variable, , references the this

instance.jsx3.app.Server

The onUnload event only fires when the browser is being unloaded. If you want to warn theuser before the page is unloaded, use the onBeforeUnload event as defined for the givenbrowser. For example,

jsx3.gui.Event.subscribe(jsx3.gui.Event.BEFOREUNLOAD, (objEvent) {functionobjEvent.returnValue = 'If you leave page, your session will end.'; });this

Using Code with Data Services

In the XML Mapping Utility, you can specify JavaScript code for performing tasks related todata service calls. For outbound mappings, the code is executed when the service call is made.For inbound mappings, the code is executed after the response is received.

To associate JavaScript code with a data service call, type the code in the Path/Value column inthe Mappings table of the XML Mapping Utility and set the Type value to Script. In this context,the execution context is an instance of the class. In the Path/Value column,jsx3.net.Service

you can execute any method of the class using the syntax .jsx3.net.Service this.method_name

When sending data to a data service, you can write code to specify a value that is unknown atdesign time. For example, you could specify the license key for using the data service atruntime, then you could pass the license key in the message using the method.setValue()

166


When receiving data, you can use this feature to filter and validate return values or parse datainto the format required by your application. For example, you can extract the value of anoutcome element in a response and use that value to control conditional execution in acomponent callback handler.

For a mapping tutorial, see .Communicating with a Web Service Tutorial

The JavaScript Console

General Interface Builder provides a JavaScript console to assist in executing and debuggingJavaScript code. The JavaScript console:

Displays a running list of commands and command output.Allows you to drill down into nested data structures from command output.

The JavaScript console replaces the JavaScript Test Utility that was available prior toGeneral Interface Release 3.9.

To open the JavaScript console, choose in General InterfaceTools > JavaScript ConsoleBuilder.

In the console, you can use the up and down arrow keys to scroll through the commandhistory. The history is saved even after General Interface Builder is closed and reopend. Forexample, if you enter the command or in the console, the stringdocument.body jsx3

representation of an object is shown with a collapsed arrow to its left. You can click the arrow toexpand the object. Any nested objects can also be expanded.

Property keys are shown in purple, except when the value of the property is inherited from theobject's prototype, in which case the key is shown in gray. Function and Array outputs are alsoshown.

To clear the console history, type or right-click inside the console and choose Ctrl+K Clear.Console

By default, the console evaluates the input when you press . The console supportsEntermulti-line input. You can paste the multi-line text at the prompt or type to insert aShift+Entercarriage return.

167


Code Execution

All code evaluated by the JavaScript console is executed in window scope. For example, if youevaluate the following statement:

f = 1;

you have actually set the property of the top-level object window. If you set a global variablef

in this way, it becomes available to subsequent expressions that you evaluate in the console.

The form does not have the same behavior as . The value of isvar f = 1; f = 1; f

not available to subsequent expressions if it is set in this way.

If the active editor is a JSX component editor then each DOM node in the component is exposedas a variable in the JavaScript console. For example, if the component contains an instance of

whose name is set to "textBox," then the variable will be equal to thejsx3.gui.TextBox textBox

TextBox instance when evaluated in the console. Please note that,

Only objects whose names are valid JavaScript variable names are exposed. The namemust match .[\$a-zA-Z_][\$\w]*

The behavior of name collisions is not defined. If you have two or more objects in thesame component with the same name, the corresponding variable may reference eitherone.

168


Chapter 11 Class Inheritance and Introspection

This chapter describes General Interface extensions to the JavaScript class and inheritancemodel. With these extensions, General Interface provides a richer programming environmentthat is better suited to building complex object-oriented applications.

Classes and Inheritance in JavaScript 1.xjsx3.lang.Object and Classes in General InterfaceDeclaring a ClassClass-Like ConstructsIntrospection

Classes and Inheritance in JavaScript 1.x

JavaScript 1.x supports prototype inheritance. A class is defined by any function:

function Plant(latinName, englishName) { .latinName = latinName;this .englishName = englishName;this}

The prototype field of the class function represents the prototypical instance of the class. A newinstance of the class will be a copy of the prototype, including any fields and methods placed inthe prototype.

Plant.prototype.relatedSpecies = Array();new

Plant.prototype.getLatinName = () {function .latinName;return this};

Inheritance is supported by setting the prototype of a class function to a new instance of thesuperclass:

function Tree(latinName, englishName, flowering) { .latinName = latinName;this .englishName = englishName;this .flowering = flowering;this};Tree.prototype = Plant();new

Tree.prototype.isFlowering = () {function .flowering;return this};

JavaScript supports an inheritance-aware instanceof operator. The following statements aretrue:

( aPlant = Plant()) Plant;var new instanceof( aTree = Tree()) Plant;var new instanceof( aTree = Tree()) Tree;var new instanceof

169


Because all classes implicitly extend the class, the following statement is also true: Object (var

aPlant = new Plant()) instanceof Object;

jsx3.lang.Object and Classes in General Interface

General Interface defines its own base class, , which adds the followingjsx3.lang.Object

capabilities to the JavaScript 1.x model:

Obtaining the class that defines an instance with the methodgetClass()

Calling an overridden method in a superclass with the and jsxsuper() jsxsupermix()

methodsA better method that overrides and includes the name oftoString() Object.toString()

the class from which the object was instantiatedIntrospection of class and interface membership using the methodinstanceOf()

The class works in conjunction with the other classes in the jsx3.lang.Object jsx3.lang

— , and —to provide these further advantages overpackage Class, Exception, Method Package

JavaScript 1.x:

A rich exception model with intelligible stack tracesFull introspection of classes and methodsMixin style interfacesIntrospectable packagesSimple declaration of classes and members using standard JavaScript 1.x syntax thatfrees the developer from the details of prototype inheritance

All classes in General Interface descend from . Developers are encouraged tojsx3.lang.Object

extend the General Interface base class in application code in order to fully incorporate thefeatures enumerated above.

Declaring a Class

Classes are defined with the static method :jsx3.lang.Class.defineClass()

static method defineClass(strName, objExtends, arrImplements, fctBody)

The first parameter, , is a string that is the fully-qualified name of the class to define,strName

such as . The method ensures that the namespace object, "com.tibco.Widget" defineClass()

, exists before creating the Widget constructor.com.tibco

The second parameter, , is the superclass of the class to define. If is passed, objExtends null

is assumed. This parameter is usually provided as the constructor function ofjsx3.lang.Object

the superclass, the fully-qualified class name without quotes.

The third parameter, , is an array of the interfaces that the class implements. ThisarrImplements

array can be empty or null.

The fourth parameter, , is a function that defines the contents of the class. The fctBody

method executes this function exactly once after it has handled the details of thedefineClass()

170


method executes this function exactly once after it has handled the details of thedefineClass()

JavaScript 1.x prototype inheritance implementation. The method passes twodefineClass()

parameters to . The first parameter is the constructor function of the newly definedfctBody

class. The second parameter is the prototype object of the class. This is simply a syntacticalshortcut that allows for the following concise idiom:

jsx3.lang. .defineClass(Class "com.tibco.Widget", jsx3.lang. ,Object // is implicit so parameter could be Object this null // in this case [jsx3.util.EventDispatcher],

(Widget, Widget_prototype) {function // define class members Widgetin // define instance members Widget_prototypein });

There are four types of members that can be included in the class definition: static fields, staticmethods, instance fields, and instance methods. Each of these types is introspectable withmethods of the class. Static members are declared by defining fields of thejsx3.lang.Class

class constructor. Continuing the preceding code example:

// define two fieldsstaticWidget.SERIAL = 1;Widget.ALL_WIDGETS = Array();new

// define a methodstaticWidget.getWidgetBySerial = (serial) {function Widget.ALL_WIDGETS[serial];return};

Static members are globally available using the fully-qualified name of the member, such as . The same member can be referenced with com.tibco.Widget.getWidgetBySerial()

within the class declaration function, because isWidget.getWidgetBySerial() com.tibco.Widget

aliased as inside the function. Unlike in Java, static members are not accessible throughWidget

instances of a class (that is, is undefined).aWidget.SERIAL

Instance members are declared by defining fields in the prototype field of the class constructor:

// define two instance fieldsWidget_prototype.serial = ;nullWidget_prototype.name = "?";

// define an instance methodWidget_prototype.getSerial = () {function .serial;return this};

All classes must define a special instance method called . The methodinit() defineClass()

throws an exception if the method isn't declared in the class declaration function. The init()

method is effectively the constructor function. However, the methodinit() defineClass()

actually creates the class constructor so the developer has no way of customizing it. Instead, the

171


actually creates the class constructor so the developer has no way of customizing it. Instead, thegenerated class constructor simply calls the method passing all the parameters that wereinit()

passed to the constructor. Here is the method for the class:init() Widget

Widget_prototype.init = (name) {function .name = name;this .serial = Widget.SERIAL++;this};

The following code instantiates a :Widget

var widget = com.tibco.Widget("myFirstWidget");new

Class-Like Constructs

The package defines three class-like constructs— , and .jsx3.lang Class, Interface Package

These constructs are not exactly equivalent to their Java/C++ namesakes.

Classes

Classes have the following characteristics:

Are defined with the methodjsx3.lang.Class.defineClass()

Define static fields, static methods, instance fields, instance methods, and abstractinstance methodsAre instantiatedCan be the superclass of another classDescend from jsx3.lang.Object

Interfaces

Interfaces have the following characteristics:

Are defined with the methodjsx3.lang.Class.defineInterface()

Define static fields, static methods, instance methods and abstract instance methodsAre not instantiatedCan be the superclass of another interfaceCan be implemented by a class

Packages

Packages have the following characteristics:

Are defined with the methodjsx3.lang.Package.definePackage()

Define static fields and static methodsContain classes and interfaces defined with jsx3.lang.Class

Unlike in Java, General Interface interfaces may contain concrete instance methods. When aclass implements an interface, the instance methods of the interface are mixed into the class. A

mixed in method overrides a method of the same name inherited from the superclass but

172


mixed in method overrides a method of the same name inherited from the superclass butdoesn't override a method defined in the implementing class or mixed in from an interfacecoming earlier in the parameter to the method.arrImplements Class.defineClass()

Packages must be explicitly defined with the method injsx3.lang.Package.definePackage()

order to be introspectable. Simply defining the class will not define thecom.tibco.Widget

package . Defining a package isn't required for the class to work. It simply allows thecom.tibco

package to be introspected.

Classes, interfaces, and packages can "contain" classes/interfaces. Consider the following codeassuming that the class is defined:com.tibco.Widget.Encoding

// returns [com.tibco.Widget, com.tibco.Widget.Encoding]jsx3.lang.Package.forName("com.tibco").getClasses();

// returns [com.tibco.Widget.Encoding]jsx3.lang. .forName("com.tibco.Widget").getClasses();Class

Introspection

Once a class, interface, or package has been defined as described above, it's introspectable.There are a few ways to get a handle to an instance of or :jsx3.lang.Class jsx3.lang.Package

var aClass = anObject.getClass(); // returns an instance of jsx3.lang.Class aPackage = aClass.getPackage(); // returns an instance of jsx3.lang.Packagevar

com.tibco.Widget.jsxclass; // instance of jsx3.lang.Classcom.tibco.jsxpackage; // instance of jsx3.lang.Package

// the following returns any part of the namespace is undefined:null ifjsx3.lang. .forName("com.tibco.Widget");Classjsx3.lang.Package.forName("com.tibco");

Consult the API Documentation for all the methods of these classes that can be used tointrospect their contents.

173


Chapter 12 Extensions to JavaScript Exception Handling

This chapter describes General Interface extensions to JavaScript exception handling and howto leverage these extensions to write code that is more robust and easier to maintain.

Exceptions in JavaScriptExceptions in General InterfaceExceptions and the Call StackWhen to Use Exceptions

Exceptions in JavaScript

Like many other programming languages, JavaScript provides for throwing and catchingexceptions. JavaScript supports the standard try...catch...finally statement:

try { doSomething();} (e) {catch window.alert(e.description);} {finally cleanUp();}

JavaScript also supports the throw statement. Any type of object can be thrown:

throw "error!"; {name:"anError", description:"an error occurred"};throw

The browser creates and throws errors under certain circumstances. For example, trying toaccess a field on a variable that is undefined will raise an error. Trying to call a function thatdoes not exist also raises an error. These types of exceptions can also be caught with thetry...catch statement.

When an exception is raised and isn't caught, the current call stack is unwound and the browserreceives an error event. Execution of JavaScript code continues when the next stack is createdby a timeout event or by user interaction.

Exceptions in General Interface

General Interface extends the native JavaScript exception facilities in several ways that make iteasier to build and debug large applications.

General Interface defines the class, which extends andjsx3.lang.Exception jsx3.lang.Object

is the superclass of all General Interface exceptions. This base class is stack aware, which meansthat it stores the call stack at the point where it was created. By using and/or extending

, you can take advantage of some features of exceptions that exist in morejsx3.lang.Exception

advanced languages such as Java.

Several methods in the General Interface Framework throw exceptions to communicate to the

caller that an error has occurred. Note that some classes, such as , fail silentlyjsx3.xml.Document

174


caller that an error has occurred. Note that some classes, such as , fail silentlyjsx3.xml.Document

by storing error information in instance fields rather than throwing exceptions. GeneralInterface Framework methods that throw a General Interface exception are documented in theAPI Documentation (Help>API Documentation). Such methods should be surrounded by atry...catch block to prevent the exception from reaching the top of the call stack. Becauseexceptions in JavaScript aren't checked as they are in Java, if a method that throws an exceptionisn't surrounded with a try...catch block, it's not a compilation error.

General Interface also defines a subclass of ,jsx3.lang.NativeError, jsx3.lang.Exception

which wraps the native browser exception object. is a cross-platform interface ontoNativeError

the exceptions that the browser may raise. Since extends , applicationNativeError Exception

code can treat all exceptions caught in a try...catch block as instances of the class. ThisException

is accomplished with the following code:

try { doSomething();} (e) {catch // e may be a browser Error object or an instance ofnative // jsx3.lang.Exception thrown by application or framework code ex = jsx3.lang.NativeError.wrap(e);var window.alert(ex.printStackTrace());}

Finally, in General Interface Builder and when error trapping is enabled in running GeneralInterface applications, any error that reaches the top of the stack and the browser is routed tothe General Interface logging system. The exception will be sent to the global logger,

, with severity ERROR.jsx3.util.Logger.GLOBAL

Exceptions and the Call Stack

Any time an instance of is created, it stores the current call stack. This canjsx3.lang.Exception

be accessed with either the or methods of the class. This featuregetStack() printStackTrace()

can be very helpful when diagnosing a problem in an application.

Unfortunately, in Internet Explorer, the native exception class does not store stack information.Therefore, an instance of only contains the stack up to the point when itjsx3.lang.NativeError

was created, not up to the point where the error it wraps was raised.

The one exception to this is when a native error reaches the top of the call stack. In thatparticular case, the General Interface logging system does have access to the entire stack up tothe function where the error was raised. This is problematic from the point of view of adeveloper, however, because the choice is between maintaining the stack by catching an errorbut losing information about how that error was created and seeing the full stack trace of theerror but not being able to recover from the error.

One possible development practice to deal with this shortcoming of Internet Explorer is toinclude fewer try...catch statements in the early stages of developing an application andincluding more as the quality of the code improves.

175


When to Use Exceptions

Exceptions are a way of communicating an exception or error condition from a method to thecaller of the method. Exceptions are favored over the older technique of returning a status codefrom a method, such as 0 for success and 1 for error, because exceptions can't be ignored by thecalling code. Without exceptions, it's easy to write code that assumes every operation issuccessful. When an operation doesn't end in success, the error can show up in subsequentoperations, and therefore be harder to diagnose.

In most implementations, throwing exceptions is a relatively expensive operation. Therefore,exceptions should be used to communicate truly exceptional conditions rather than conditionsthat may occur under the normal execution of a program.

The benefit of using exceptions usually increases with the size of the application. Exceptionsrequire the developer to define the success and error conditions of methods and require thecalling code to handle both possibilities. Code therefore can have fewer bugs and be clearer andmore robust than code that uses another error reporting mechanism or ignores error conditionsaltogether. Additionally, exceptions help with the principle of failing early. In general, it's betterto fail (raise an exception) at the first sign of trouble when the cause of the failure iswell-known. Otherwise errors might cascade to other parts of a program where they are harderto diagnose.

176


Chapter 13 General Interface JavaScript DocumentationCompiler

This chapter describes how to use the General Interface JavaScript Documentation Compiler(JSXDOC).

OverviewRunning JSXDOC

Overview

JSXDOC is a program that creates API documentation from JavaScript source files. JSXDOCparses JavaScript syntax and a comment metadata syntax to produce the structureddocumentation. JavaScript source files that are run through the compiler must conform to theJSXDOC syntax. JSXDOC can export documentation as XML or HTML files.

Syntax

The supported documentation syntax is similar to javadoc syntax. Relevant comment blocks arerange comments that begin with and are placed immediately before the member that they/**

describe. You can document packages, classes, interfaces, methods, and fields. Methods andfields are defined in the class, interface, or package whose definition most closely precedes it. (Itis an error to define a method or field in a location where there is no such class context).

The documentation compiler parses JavaScript to determine what type of member a commentblock documents. The member declaration that follows the comment block (or that is specifiedwith the tag) must match one of the following patterns.@jsxdoc-definition

jsx3.[lang.]Package.definePackage("NAME", ...) Defines a package. The packagename is determined from the declaration.jsx3.[lang.]Class.defineClass("NAME", SUPER, [IMP1, IMP2, ...], ... ) Defines aclass. The class name, superclass, and implemented interfaces are determined from thedeclaration.jsx3.[lang.]Class.defineInterface("NAME", SUPER, ...) Defines an interface. Theinterface name and super interface are determined from the declaration.prototype.NAME = jsx3.[lang.]Method.newAbstract("P1", "P2", ...) ; Defines anabstract method. The method name and parameter order are determined from thedeclaration.prototype.NAME = jsx3.Y(function(...)) Defines an asynchronous method. Themethod name is determined from the declaration. The method parameters are takenfrom the @param tags.prototype.NAME = function(P1, P2, ...) ... Defines an instance method. The methodname and parameter order are determined from the declaration.NAME: function(P1, P2, ...) ... Defines an instance method (as in the previousdeclaration). The method name and parameter order are determined from thedeclaration.x.NAME = function(P1, P2, ...) ... Defines a static method. The method name andparameter order are determined from the declaration.

177


prototype.NAME = x; Defines an instance field. The field name is determined from thedeclaration.NAME: x - Defines an instance field (as in the previous declaration). The field name isdetermined from the declaration.x.NAME = x; Defines a static field. The field name is determined from the declaration.

Documentation Blocks

Documentation blocks can begin with a free-form paragraph that describes the member. HTMLtags are allowed in this and most other text blocks. HTML entities must be escaped in order tobe interpreted as plain text. The type declaration of a field, if documented, must precede itsdescription.

The , , and tags, and the field description, support optional typeparam return throws

information. Types are always documented between curly braces, { . A type can be any valid}

JavaScript identifier or package+identifier. A type whose class is included in a compilation willbe linked automatically to the definition of that class. The following constructs are alsosupported, both alone and in most combinations.

type1 | type2 | ... or ...type1 or type2

type1... Variable number of method arguments which should be determined from theJavaScript array.arguments

pType<type > Parameterized type such as an that contains objects of another type.Array

pType<type1, type2> Multi-dimensional parameterized type such as a map that containsmultiple sets of objects of other types.

Tags

Tags begin on a new line and begin with the character. The following tags are supported.@

@public, , , Sets the access level of the documented@package @protected @private

member. If a documentation comment exists the default is public, otherwise the defaultis private.@version Documents the version of the member.STRING

@since STRING Documents the version when the member was introduced.@deprecated Documents that the member is deprecated and adds an optional[STRING]

description of the deprecation.@author STRING Documents the author of the member. Any number of author tags maybe documented.@param Documents a method parameter. Any parameters that areNAME [{TYPE}] STRING

not explicitely documented with this tag are parsed from the definition and included(without type or description) in the compiled documentation.@param { This is an alternative supported syntax of a methodTYPE} NAME STRING

parameter.@param-package and You can use these to set the access level of a@param-private

particular parameter so that it does not show up in the compiled documentation.@return Documents the return type of a method and adds a description[{TYPE}] STRING

to the returned object. The type is optional. Method that have no non-empty returnstatements should not include this tag.@throws Documents an exception type that a method may throw and[{TYPE}] STRING

the conditions under which it is thrown.

@final Documents that a method should not be overridden or a class should not be

178


@final Documents that a method should not be overridden or a class should not beextended. The JavaScript language does not enforce this documentation construct.@static Documents a field or member as static even when the member declaration is notunderstood by the parser to be a static declaration.@protected Documents that a method or field should only be used from within the classthat defined it or one of that class's subclasses. The JavaScript language does not enforcethis documentation construct.@abstract Documents that a class is abstract. Methods defined with j

are automatically recognized as abstract. Any class orsx3.lang.Method.newAbstract()

interface with an abstract member is also automatically recognized as abstract.@native Documents that this member is defined by the JavaScript engine or hostbrowser.@see STRING Adds a See section to the documentation of this member. There are severalsupported formats for the STRING argument:

"TEXT" Inserts a text label. <a href="URL">TEXT</a> Inserts an HTML link to URL. #LOCAL_FIELD [LABEL] References a field in the same class with optional labelLABEL. #LOCAL_METHOD() [LABEL] References a method in the same class with optionallabel LABEL. pkg.Class#FIELD [LABEL] References a field in another class, pkg.Class, withoptional label LABEL. pkg.Class#METHOD() [LABEL] References a method in another class, pkg.Class,with optional label LABEL.

@jsxdoc-definition In the case that a documentation block cannot appearJS_DEFINITION

immediately before the member definition, this tag can be used to specify the memberdefinition. This tag can also be used to tell the compiler what member the commentblock describes in the case that members are not defined according to the JavaScriptsyntax that the compiler expects.@jsxdoc-category In the case that the members of a package, class, or interface areCLASS

defined across multiple files or sections of files, this tag can be used to indicate that tagsfollowing it belong to CLASS but without redefining CLASS in the process.

Example

The following code example declares a JavaScript class, , and includes many ofjsx3.util.list

the JSXDOC tags.

/** * Adapted from <code>jsx3.util.List</code>. * <p/> * An object-oriented version of the built- JavaScript <code>Array</code> class.in * <p/> * Note that methods such as <code>indexOf</code> and <code>remove</code> compareobjects * the strict equality operators (<code>=h1. </code> and <code>!</code>\).withTherefore, the purposes of for this * class <code>1</code> and <code>"1"</code> are not equal. * * @since 3.2 */jsx3. .defineClass('jsx3.util.List', , , (List, List_prototype) {Class null null function

179


/** * { } A field.int final static * @final */ List.STATIC_FIELD = 5;

/** * If <code>a</code> is already an instance of class, method returnsthis this<code>a</code>. * If <code>a</code> is an array, method returns a List instance backed bythis new<code>a</code>.* @param a {Array|jsx3.util.List}* @ {jsx3.util.List}return * @ {jsx3.IllegalArgumentException} <code>a</code> is not a list orthrows ifarray. */ List.staticMethod = (a) {function (a List) {if instanceof a;return } (a Array) {else if instanceof List(a, );return new true } {else jsx3.IllegalArgumentException("a", a);throw new } };

/** * The instance initializer. Creates a list.new * @param a {Array} * @param- bLive { }private boolean */ List_prototype.init = (a, bLive) {function (a Array) {if instanceof ._src = bLive ? a : a.concat();this } {else ._src = ;this } };

/** * @ { }return int */ List_prototype.size = () {function ._src.length;return this };

/** * Varargs example. * @param o { ...}Object */ List_prototype.add = (o) {function ._src = ._src.concat(arguments);this this };

/**

180


* Parameterized type example. * @ {jsx3.util.List< >} list converted to a list of strings.return String this */ List_prototype.toStringList = () {function .filter( (e) { e.toString(); });return this function return };

/** @ */private List._privateMethod = (a) {function a;return

181


1.

2.

3.

4.

5. 6.

};

});

Running JSXDOC

JSXDOC is distributed with the source distribution of General Interface as a Java class with anAnt task interface. The easiest way to run JSXDOC is via the Ant interface.

To get started:

Make sure that Java 1.5+ and Ant 1.7+ are installed. Downloads are available at and .http://java.sun.com http://ant.apache.org

Download the GI source distribution from at . Unzip ithttp://www.generalinterface.orgto .GI_SRC

Run the command in the directory . This creates a ant package GI_SRC/build/tools

file in same directory. The JAR file contains the JSXDOC program andjsx-tools.jar

Ant task.Copy and the following files into a new directory, .jsx-tools.jar JSX_RUN

GI_SRC/build/tools/lib/javacc/bin/lib/javacc.jarGI_SRC/build/tools/lib/jaxen/jaxen-1.1.jarGI_SRC/build/tools/lib/dojo/jsl.jarGI_SRC/build/tools/lib/xml/xalan-serializer-2.7.jarGI_SRC/build/tools/lib/saxon/saxon8.jarGI_SRC/build/tools/lib/saxon/saxon8-dom.jarGI_SRC/build/apidoc/

Now create an Ant file in .build.xml JSX_RUN

Copy the following example as a starting point.

<project name= default="General Interface Documentation Compiler" "jsxdoc"basedir= >"."

<target name= >"init" <property file= />"build.properties" </target>

 <target name= depends= >"init-filters" "init" <filterset id= >"filters" <filtersfile file= />"build.properties" </filterset> </target>

<target name= depends= >"init-tools" "init" <path id= >"cp.tools" <path path= />"jsx-tools.jar" <path path= />"javacc.jar" <path path= />"jaxen-1.1.jar" <path path= />"jsl.jar" <path path= />"xalan-serializer-2.7.jar" <path path= />"saxon8.jar"

http://java.sun.com

http://ant.apache.org

182


6.

<path path= />"saxon8-dom.jar" </path>

<taskdef resource= classpathref= />"com/tibco/gi/ant/antlib.xml" "cp.tools" </target>

<target name= depends="jsxdoc" "init, jsxdoc-xml, jsxdoc-html" description="Compiles the API documentation contained in the JavaScript

>files placed in the src/ directory." </target>

<target name= depends= >"jsxdoc-xml" "init-tools" <echo message="Compiling the XML documentation for the JavaScript files in

/>${js.dir}." <echo message="The XML documentation files will be saved in

/>${doc.dir.xml}." <gi-doc destdir= access= >"${doc.dir.xml}" "${jsxdoc.access}" <fileset dir= includes= />"${xsl.dir}" "javascript.js" <fileset dir= includes= />"${js.dir}" "**/*.js" </gi-doc> </target>

<target name= depends= >"jsxdoc-html" "init-filters, init-tools" <mkdir dir= />"${tmp.dir}"

 <copy todir= verbose= encoding= >"${tmp.dir}" "false" "${jsxdoc.encoding}" <filterset refid= />"filters" <fileset dir= >"${xsl.dir}" <include name= />"*.xsl" <include name= />"*.html" <include name= />"*.css" </fileset> </copy>

<echo message="Compiling the HTML documentation for the XML files in/>${doc.dir.xml}."

<echo message="The HTML documentation files will be saved in/>${doc.dir.html}."

<gi-htmldoc srcdir="${doc.dir.xml}" destdir="${doc.dir.html}" docdir= />"${tmp.dir}"

<delete dir= />"${tmp.dir}"

183


6.

7.

8. 9.

10.

</target>

</project>

In the same directory, create the Ant file from the following template.build.properties

The file allows you to configure the Ant build process withoutbuild.properties

modifying the file.build.xml

# The title of the compiled API documentationgi.apidocs.title = My Library®# The title of the compiled API documentation, XML-escapedgi.apidocs.title.esc = My Library®# The copyright of the compiled API documentation, XML-escapedgi.apidocs.copyright = Copyright © My Company

# The minimum access level of documented members: , , public protected privatejsxdoc.access = protectedjsxdoc.encoding = UTF-8

xsl.dir = apidocjs.dir = srctmp.dir = tmpdoc.dir.xml = doc/xmldoc.dir.html = doc/html

Place all JavaScript source files in the directory .JSX_RUN/src

Run the command from . The build process is configured to export XMLant JSX_RUN

documentation to and HTML documentation to .JSX_RUN/doc/xml/ JSX_RUN/doc/html/

Open in a web browser to view the new documentation.JSXRUN/doc/html/index.html

184


Chapter 14 Protecting Namespaces in MultipleApplication Environments

This chapter describes how to design General Interface applications to work properly inmultiple application environments, such as portal deployments.

How Namespaces Affect Deployed ApplicationsProtecting Application Code with Packages

How Namespaces Affect Deployed Applications

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

The namespace of a General Interface application is the name of the global JavaScript variablethat is set to the instance of representing the application. Custom applicationjsx3.app.Server

JavaScript code usually references this variable extensively since the server provides access tothe General Interface DOM and local data cache, among other things.

The namespace of a General Interface application must be unique for each application deployedin a single web page. If a namespace collision occurs, the code of only one of the applicationshas access to its instance. The other applications will likely break. Namespacesjsx3.app.Server

should always be checked for uniqueness before creating a deployment page with multipleGeneral Interface applications.

A good way to ensure namespace uniqueness is to use the reverse domain naming convention

185


A good way to ensure namespace uniqueness is to use the reverse domain naming conventionwhen choosing your application namespace. For example, you could use com.tibco.gi.App1and . This ensures that your applications won't conflict with Generalcom.tibco.gi.App2

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 charactersremoved. The value is displayed in the Namespace field on the Deployment panel of the ProjectSettings dialog (Project > Project Settings) and can be modified to any valid JavaScript variablename.

Using the Namespace in Application Code

The instance, the name of which is specified by the application namespace,jsx3.app.Server

provides access to the General Interface DOM and local data cache.

Access to the DOM is provided by the methods , , , getDOM() getJSX() getJSXByName()

, and of the class. All DOM nodes, which aregetJSXById() getBodyBlock() jsx3.app.Server

instances of , are indexed by both ID and name. The following code retrieves thejsx3.app.Model

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 method is a shortcut for fetching a DOM node by name or ID. The jsx3.GO() jsx3.GO()

method has access to all loaded General Interface applications and searches all of them for aDOM node of the given name. The method is therefore slower than jsx3.GO() getJSXByName()

186


DOM node of the given name. The method is therefore slower than jsx3.GO() getJSXByName()

and allows one application to affect another application. Only use in the Generaljsx3.GO()

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 method in the getCache()

class. The following code fetches a cache document from the App1jsx3.app.Server

application:

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

Protecting Application Code with Packages

The application namespace isn't the only namespace that needs to be protected from otherGeneral Interface applications. Project JavaScript code should also be placed in a uniquenamespace to avoid affecting and being affected by other applications. A JavaScript namespaceis known in General Interface as a package.

In general, applications should not declare global JavaScript functions. The following codedefines a global JavaScript function:

function doTest() { 1;return}

This is equivalent to declaring the function as a member of the global window object:

window.doTest = () {function 1;return};

Since all General Interface applications deployed in the same web page share the same globalwindow object, any code placed in it isn't private to a particular application. If two differentapplications define a global method, one version is overridden by the other and onedoTest()

application will probably break.

To avoid any naming collisions in function and variable names, all code should be placed inpackages. Using the reverse domain naming convention is a good choice for avoiding collisions.A package is essentially a nested data structure descending from the window object. Thefollowing code creates the package and defines the function in it.com.tibco.gi doTest()

window["com"] = ();new Objectcom.tibco = ();new Objectcom.tibco.gi = ();new Objectcom.tibco.gi.doTest = () {function 1;return};

However, this code has a bug in it, because it will destroy any previously defined packagedescending from , such as l. With this technique for creating awindow.com com.tibco.porta

package, the nested objects should only be created if they do not already exist.

The class simplifies the task of creating a package greatly with the jsx3.lang.Package

187


The class simplifies the task of creating a package greatly with the jsx3.lang.Package

method. The following code also defines the function in the definePackage() doTest()

package but without the bug in the previous code sample:com.tibco.gi

jsx3.lang.Package.definePackage("com.tibco.gi", (gi) {function gi.doTest = () {function 1;return };});

Since JavaScript packages can be named using the reverse domain naming convention, they arevery safe from naming collisions.

For more information, see the jsx3.lang. in General Interface API Reference.Package

188


Chapter 15 Implementing Context-Sensitive Help

This chapter describes how to implement context-sensitive help in a General Interfaceapplication.

About Context-Sensitive HelpBasic Steps for Implementing Help

About Context-Sensitive Help

Context-sensitive help is a type of online help specific to a user interface topic or softwarefeature. For example, context-sensitive help for a dialog would explain the options and settingsof the dialog. The end user typically accesses context-sensitive help by clicking a button orpressing hot keys.

General Interface Framework, the General Interface runtime, provides a jsxhelpid property forimplementation of context-sensitive help in your General Interface applications. The jsxhelpidproperty is a unique string identifier that can be set in the Properties Editor palette (Help ID) inGeneral Interface Builder or set programmatically using the jsx3.app.Model.setHelpId()method.

When a help ID is specified for a component, the user can launch context-sensitive help bypressing hot keys, which are system- and locale-dependent. The application automaticallylistens for the key event and determines the closest ancestor of the object receiving the keyevent that has a help ID. If an ancestor exists, the key event is canceled and the application,which is the Server object, publishes an event of subject .jsx3.app.Server.HELP

Application code can register for the HELP event from the application's Server object andperform custom code appropriate for the application, such as launching an external web pageor opening a custom-built General Interface help viewer.

Help Hot Keys

The hot keys that invoke the help system are system- and locale-dependent. Hot keys areexternalized in the properties bundle in the directory. The default hotlocale.xml JSX/locale/

keys in are Alt+F1 for Windows and Command+/ for Mac.locale.xml

Help APIs

The help APIs include the following:

jsx3.app.Model.getHelpId() returns the help ID of a component.jsx3.app.Model.setHelpId() sets the help ID of a component.jsx3.app.Server.HELP is the subject on an event that instances of this class publish whena context-help hot key is pressed in the context of a General Interface DOM node that hasa help ID. The HELP event has the following properties:

subject jsx3.app.Server.HELP

target the serve

helpid the value of the jsxhelpid property

189


1.

2.

helpid the value of the jsxhelpid property model the General Interface DOM node that receives the key event

jsx3.app.Server.invokeHelp(objJSX) invokes context-sensitive help as though the userhad pressed the help hot key in the context of the DOM node.


Basic Steps for Implementing Help

Implementing context-sensitive includes the following steps:

Set help IDs for areas of the user interface, such as palettes and dialogs: Set the Help ID property in the Properties Editor palette of General InterfaceBuilder. Set the help ID programmatically using the method.jsx3.app.Model.setHelpId()

Subscribe to the HELP event using jsx3.app.Server.HELP ("event subject_").

For example, the next example demonstrates how to send a message to an alert when a serverpublishes a HELP event. The JavaScript package is and the server is , aseg.app eg.app.APP

shown in the following example.

eg.app.APP.subscribe(jsx3.app.Server.HELP, eg.app.onHelp);

eg.app.onHelp = (objEvent) {function objEvent.target.alert("Help", " ")};

190


Chapter 16 Logging and Application Monitors

This chapter describes how to use the logging system to send and view logging messages. Italso discusses how to use application monitors to view logging messages from runningapplications.

About Logging and Application MonitorsUnderstanding the Logging System Configuration FileSending Logging MessagesViewing Logging MessagesCreating a Custom HandlerCreating a Custom Logging System Configuration File

About Logging and Application Monitors

General Interface provides an advanced logging system which is defined in the class. The logging system is designed to be an integral part of thejsx3.util.Logger

development process. It can be used in General Interface Builder and in a running GeneralInterface application to trace activity and diagnose errors. Logging messages can be sent to avariety of destinations using custom logging handlers — on-screen, memory, web service, localfile, and so on. Which messages are displayed, where, and how they're displayed can beconfigured declaratively in an XML logging system configuration file without modifying sourcecode.

Loggers and Handlers

Two important classes of objects in the logging system are:

LoggersHandlers

A logger is used to log messages about a particular component of an application. Afterreceiving the log message, the logger forwards the message to registered handlers. A loggermay have one or more handlers associated with it.

A handler, which receives log messages from the loggers it's registered with, defines what to dowith a logging message. A handler can output messages in a specified format to variousdestinations, such as to memory, system log, console, files, and so on. In some cases, a handlermight ignore messages.

A logger is identified by its unique name. All logger instances exist in an inheritance tree andare descendants of the global logger. Inheritance is organized by name with the dot (".")character defining levels of the tree. For example, a logger named inherits from ,com.tibco com

which inherits from the root logger, . Loggers are typically given names based on theglobal

package or class name of the component. Handlers must also have unique names. Becausehandlers don't inherit from other handlers, names can be much simpler and do not need to bebased on inheritance.

191


Log Levels

Each logger has a log level associated with it. Log levels control which messages pass throughthe logger. A logging message also has a level associated with it. Only a message with a levelequal to or more severe than the level specified for the logger passes through the logger. Thelevels defined in the system are, in order of decreasing severity, — , , , , FATAL ERROR WARN INFO

, and .DEBUG TRACE

In the following example, is assigned a level of . This logger only forwardsmylogger DEBUG

messages of level , , , , and to the appropriate handlers. All FATAL ERROR WARN INFO DEBUG TRACE

messages are ignored.

<logger name= level= />"mylogger" "DEBUG"

If a log level isn't specified, the logger inherits the log level of its parent logger, such as theglobal logger. In this example, inherits log level from its parent logger, .mylogger2 INFO global

Only , , , and messages are forwarded by to the registeredFATAL ERROR WARN INFO mylogger2

handlers.

<logger name= level= />"global" "INFO"<logger name= />"mylogger2"

Handlers, like loggers, can also define a minimum level of message that they handle. In thefollowing example from the logging system configuration file ( ), haslogger.xml appMonitor1

been assigned a level of ERROR. This handler only outputs messages of a level equal to andmore severe than , even though the logger it is registered with, , forwards allERROR global

messages of level and more severe.INFO

<handler name= class="appMonitor1" "jsx3.app.Monitor" require= level= >"true" "ERROR" . . .</handler>

<logger name= level= >"global" "INFO" <handler-ref name= />"appMonitor1"</logger>

Understanding the Logging System Configuration File

The logging system configuration file, , specifies which logging messages/logger.xmlGI_HOME

are displayed, how they are displayed, and where they are sent.

You can also edit , as well as create a custom logging system configuration file. See logger.xml

.Creating a Custom Logging System Configuration File

Memory Handler

The memory handler stores a rotating cache of logging messages in memory. Note that somefeatures of the General Interface Builder IDE require this handler. If it's not available, theywon't function properly.

192


<handler name= class= >"memory" "jsx3.util.Logger.MemoryHandler" <property name= eval= value= />"bufferSize" "true" "1000"</handler>

Memory Handler Attributes

See .Handler Attributes

Memory Handler Properties

The memory handler has the following property:

bufferSize : The size of the buffer and the number of records the buffer holds until itbegins discarding old ones.

System Log Handler

The system log handler prints logging messages to the General Interface Builder System Logpalette in the IDE. For logging to work in the IDE, there must be system log handler.only one

<handler name= class= lazy= >"ide" "jsx3.ide.SystemLogHandler" "true" <property name= eval= value= />"bufferSize" "true" "0" <property name= value= />"format" "%t %n (%l) - %M" <property name= eval="beepLevel" "true" value= />"jsx3.util.Logger.ERROR"</handler>

System Log Handler Attributes


System Log Handler Properties

The system log handler has the following properties:

bufferSize : The size of the buffer and the number of records the buffer holds until itbegins discarding old ones.format : The format of the delivered message. For definitions of formatting tokens, see

in General Interface API Reference.jsx3.util.Logger.FormatHandler

beepLevel : The message level that triggers a sound when printed to the System Logpalette in the IDE. For more information, see .Enabling Sound for Messages

For sound to work properly, Firefox requires a plug-in that can play .wavfiles.

JavaScript Alert Handler

The alert handler sends formatted messages to a JavaScript alert. The fatal handler, asconfigured in the default file, ensures that fatal errors are displayed in a JavaScriptlogger.xml

alert. Fatal messages usually relate to failure to initialize the system or load an application andso may indicate that the output of other handlers isn't visible.

193


<handler name= class="alerter" "jsx3.util.Logger.AlertHandler" level= >"ERROR" <property name= value= />"format" "%t %n (%l) - %M"</handler>

<handler name= class="fatal" "jsx3.util.Logger.AlertHandler" level= >"FATAL" <property name= value= />"format" "%t %n (%l) - %M"</handler>

JavaScript Alert Handler Attributes


JavaScript Alert Handler Properties

The class has the following property:AlertHandler

format: The format of the delivered message. For definitions of formatting tokens, see in General Interface API Reference.jsx3.util.Logger.FormatHandler

The alert handler is registered with the logger to capture any errors notjsx3.util.Logger

handled correctly by the other handlers.

<logger name= level= useParent= >"jsx3.util.Logger" "WARN" "false" <handler-ref name= />"alerter"</logger>

Application Monitor Handler

When an application monitor handler is registered for an application running outside ofGeneral Interface Builder, logging messages are sent to a separate browser window. This isuseful for testing and debugging a deployed application.

The logging system configuration file provides a template for creating an application monitorhandler. By default, the application monitor is disabled. For more information, see Creating an

.Application Monitor Handler

<handler name= class="appMonitor1" "jsx3.app.Monitor" require= >"true" <property name= value= />"serverNamespace" "myApp" <property name= eval= value= />"disableInIDE" "true" "true" <property name= eval= value= />"activateOnHotKey" "true" "false" <property name= value= />"format" "%t %n (%l) - %M"</handler>

Application Monitor Handler Attributes


Application Monitor Handler Properties

The application monitor handler has the following properties:

serverNamespace: The value must match the application namespace to associate theapplication monitor with the application. The namespace is specified in the Namespace

field on the Deployment panel of the Project Settings dialog.

194


field on the Deployment panel of the Project Settings dialog.If the property value is omitted, the application monitor is associatedserverNamespace

with the entire General Interface runtime rather than to a particular server instance. Ifthis attribute is omitted, the and attributes have nodisableInIDE activateOnHotKey

meaning.disableInIDE: If set to , the application monitor is disabled when the application istrue

running in the IDE. If set to , the application monitor is enabled in the IDE. Thefalse

default setting is .true

activateOnHotKey: If , this monitor appears when the application is loaded andfalse

when the monitor is closed and a logging message is received. If true, this monitor isonly launched when pressing the keyboard shortcut, Ctrl+Alt+m, in the runningapplication. The default setting is .false

format : The format of the delivered message. For definitions of formatting tokens, see in General Interface API Reference.jsx3.util.Logger.FormatHandler

Global Logger

The global logger is the ancestor of all other loggers. Custom handlers and application monitorhandlers can be registered with the global logger.

<logger name= level= >"global" "INFO" <handler-ref name= />"memory" <handler-ref name= />"ide"</logger>

Alternately, handlers can be registered with a descendant logger.

<logger name= level= >"system.critical" "FATAL" <handler-ref name= />"page_ceo"</logger>

Any logger can have the following attributes and nested entities:

Logger attributes: name : The unique name of the logger. level : Controls which messages pass through the logger. If this attribute isomitted, all log levels pass through the logger. See .Log Levels

Nested entities — handler-ref: name : The name of the handler registered with the global logger. Custom handlersand application monitor handlers can be registered here.

Handler Attributes

Handlers can include the following attributes:

name : The unique name of the handler.class : The name of the handler class.lazy : If true, the logging system waits for the class to load on its own. Use the lazy orrequire attribute but not both.require : If tru , the class is loaded immediately after all statically loaded classes loade

using the dynamic class loading mechanism. If the specified handler class isn't staticallyloaded, use require="true", so the class is loaded and available when it's needed. For alist of statically loaded classes, see . Use the or General Interface Framework Classes lazy

195


list of statically loaded classes, see . Use the or General Interface Framework Classes lazy

attribute but not both.require

level : Controls which messages the handler outputs. See .Log Levels

Sending Logging Messages

The simplest way to send a message to the logging system is with the method. The jsx3.log()

method is simply a shortcut for sending a logging message of level to thejsx3.log() INFO

global logger ( ).jsx3.util.Logger.GLOBAL.info()

In General Interface Builder, inserting this method in your JavaScript code:

jsx3.log("a logging message");

prints the following line to the System Log palette if the default logging file is used:

15:26:35.138 global (INFO) - a logging message

When a message is sent to the logging system, it is sent through a logger instance, which has aunique name and can also have a specified log level. A logging message also has a levelassociated with it. If the message's log level matches or exceeds the logger log level, the loggerforwards it to the registered handler. For more information, see .Log Levels

For more precise control of the logger and level of a logging message, the class can beLogger

used. The static method returns a logger instance of the given name. NoteLogger.getLogger()

that loggers are instantiated dynamically and the method always returns a loggergetLogger()

instance, even if it's not specified in the logging system configuration file.

For example,

var log = jsx3.util.Logger.getLogger("com.tibco");

The class defines an instance method named for each level:Logger

log.error("a terrible error occurred");log.debug("x was equal to " + x);

There are several other methods of the class that are useful for logging. For moreLogger

information, see General Interface API Reference.

It is best programming practice to design logging messages as a permanent part of the sourcecode. It's useful to partition the logging messages that an application or library creates bycategory. Each category corresponds to a unique logger instance. One practice is to define alogger for each class in a system with a name equal to the fully qualified class name. Anothercommon practice is to divide the system into a set of subsystems, each with its own logger.

Logging messages can be stripped from code before the code is deployed. This is necessaryunder logging systems that use standard out, (in JavaScript) , or some otherwindow.alert()

mechanism that is highly visible to both the developer and the user of an application.

In General Interface applications, there's no need to remove the logging messages from thesource code, because the logging system is configured through a declarative XML file. Theadvantage to leaving logging messages in your code is that you can diagnose errors after

deployment. Simply modify the logging system configuration file, run the deployed

196


deployment. Simply modify the logging system configuration file, run the deployedapplication, and determine what the errors are by viewing the logging messages.

The logging system is designed to impact the performance of General Interface applications aslittle as possible. The following code is a good example of how to send a logging messageefficiently when constructing the message is expensive. The code simply checks the logger tosee whether the logging message passes the logger's level before creating and sending themessage.

var Logger = jsx3.util.Logger; log = Logger.getLogger("com.tibco");var

(log.isLoggable(Logger.INFO))if log.info(xmlDoc.toString()); // serializing XML may be // expensive

Viewing Logging Messages

There are two ways to view logging messages:

View in General Interface Builder

View at runtime

Viewing Logging Messages in General Interface Builder

To show logging messages during development, General Interface Builder defines a handlerclass, This class handles logging messages by printing them in thejsx3.ide.SystemLogHandler.

System Log palette located in the bottom panel of the user interface. This handler class isconfigured in the logging system configuration file just like any other handler.

The logging system configuration file, , is located in the directory. Thelogger.xml GI_HOME

default configuration file includes the following lines that declare the General Interface Builder handler:ide

<handler name= class="ide" "jsx3.ide.SystemLogHandler"

lazy= >"true"

<property name= eval= value= />"bufferSize" "true" "0"

<property name= value= />"format" "%t %n (%l) - %M"

<property name= eval="beepLevel" "true"

value= />"jsx3.util.Logger.ERROR"

</handler>

The following lines register the handler with the global logger:ide

197


1.

2.



<logger name= level= >"global" "INFO"

<handler-ref name= />"ide"

</logger>

By default, the handler is defined without a log level, so messages aren't filtered by level.ide

Because the global logger is configured with level , all messages of and higher areINFO INFO

forwarded to the handler and output to the System Log palette. and messageside TRACE DEBUG

aren't forwarded to the handler, regardless of the handler's level.

If you add =" as an attribute of the element, the System Log palette wouldlevel WARN" handler

only display messages of severity and higher, instead of and higher. For example,WARN INFO

<handler name= class="ide" "jsx3.ide.SystemLogHandler"

lazy= level = >"true" "WARN"

Viewing Logging Messages at Runtime

Runtime access to the logging system is provided by the handler class. Thisjsx3.app.Monitor

class handles logging messages by printing them in a separate browser window along side arunning application.

An application monitor has three running modes that correspond to four stages of applicationdevelopment:

Off The monitor isn't configured in the logging system configuration file. This is thedefault setting. This is appropriate at the beginning of application development when alldevelopment occurs in General Interface Builder or at the end of development when theapplication is stable and error-free.

On The monitor is configured in the logging system configuration file with the property equal to . This is appropriate when only developers areactivateOnHotKey false

using a deployed application, because logging messages are always visible.

Hot Key Activated The monitor is configured in the logging system configuration filewith the property equal to . This is appropriate when a mix ofactivateOnHotKey true

developers and users have access to an application or when an error needs to bediagnosed in a live, deployed application.

To enable and use the application monitor,

Modify the logger system configuration file: Create a handler for each application you want to monitor. See Creating an

. Application Monitor HandlerRegister the handler with a logger. See Registering an Application Monitor

.Handler with a LoggerRun the application and see the log messages in the application monitor, which opens ina new browser window. If the activateOnHotKey property is set to , press true

to launch the monitor.Ctrl+Alt+m

198


Creating an Application Monitor Handler

A handler must be configured for each monitored application. Add as manyjsx3.app.Monitor

monitors as you'd like, each with a unique handler name, such as , ,appMonitor1 appMonitor2

and so on. Monitors are matched up to applications by the property. The serverNamespace

for this property should be identical to the server namespace of the application, which isvalue

set in the deployment options (Project > Project Settings > Deployment).

Alternatively, if the property is omitted, the application monitor is associatedserverNamespace

with the entire General Interface runtime rather than to a particular server.

If you prefer, you can use in the directory as alogger.xml /settingsworkspace

template and create a separate logger file for each deployment page. See Creating a.Custom Logging System Configuration File

In the following XML snippet of the logging system configuration file ( , twologger.xml)

monitor handlers are created, one for each application.

<handler name= class="appMonitor1" "jsx3.app.Monitor"

require= >"true"

<property name= value= />"serverNamespace" "myApp"

<property name= eval= value= />"disableInIDE" "true" "true"

<property name= eval= value= />"activateOnHotKey" "true" "false"


</handler>

<handler name= class="appMonitor2" "jsx3.app.Monitor"

require= >"true"

<property name= value= />"serverNamespace" "yourApp"

<property name= eval= value= />"disableInIDE" "true" "true"

<property name= eval= value= />"activateOnHotKey" "true" "false"


</handler>

If the specified handler class is a statically loaded class, use , sonot require="true"

the class is dynamically loaded and available when it's needed. For a list of staticallyloaded classes, see .General Interface Framework Classes

199


Registering an Application Monitor Handler with a Logger

Next, you need to register each monitor with a logger in the logging system configuration file.In the following XML snippet, two application monitor handlers are registered with the globallogger.

<logger name= level= >"global" "INFO"

<handler-ref name= />"memory"

<handler-ref name= />"ide"

<handler-ref name= />"appMonitor1"

<handler-ref name= />"appMonitor2"

</logger>

Popup blockers may interfere with application monitors, since they exist in separatebrowser windows. If the monitor window does not appear as expected, verify thatpopup windows aren't blocked.

Creating a Custom Handler

A custom logging handler is another way to present logging messages. A custom handler couldbe used to send logging messages to a web service, write them to disk, send them to

, or show messages to the users of an application.window.alert()

A custom logging handler, which must implement the abstract method, isHandler.handle()

created by extending the class or one of its subclasses. This methodjsx3.util.Logger.Handler

defines how a logging message is handled. The following implementation, which simply storesa rotating cache of messages in memory, is from the class:MemoryHandler

MemoryHandler.prototype.handle = (objRecord) {function ._buffer.push(objRecord);this

( ._buffer.length > ._bufferSize)if this this ._buffer.shift();this};

Custom handlers are configured in the logging system configuration file just like otherhandlers. Since custom handlers load after the logging system has been configured, they mustbe configured with the attribute , so that the logging system won't throw an errorlazy="true"

on initialization if the handler class isn't loaded. Another option is to use the attribute , so the class is loaded immediately using the dynamic class loading mechanism.require="true"

After calling the method to define a custom handler class, ifjsx3.lang.Class.defineClass()

using , the method must belazy="true" jsx3.util.Logger.Handler.registerHandlerClass()

called to tell the logging system that the handler class has been defined. For example,

jsx3.util.Logger.Handler.registerHandlerClass( com.tibco.LogHandler.jsxclass);

200


Handlers may also define bean-style properties that can be configured in the logging systemconfiguration file. Any element nested within a element defines a name-valueproperty handler

pair of a property of the handler. The handler class must have a bean-style setter method forany configurable property. For example, the handler class, , defines the property FormatHandler

, because it defines and methods. Therefore, any handler of aformat getFormat() setFormat()

class that is a descendant of can be configured with the property.FormatHandler format

For more information, see in General Interface API Reference.jsx3.util.Logger.FormatHandler

Creating a Custom Logging System Configuration File

If you prefer, you can create a custom logging system configuration file and pass it to thedeployed application as a deployment parameter at runtime. Custom logging systemconfiguration files provide more flexibility. Development team members can use their owncustomized files as they develop applications instead of using one file shared by all. Also, youcan create a configuration file for each application you deploy with only one applicationmonitor enabled per file. This makes the file less cluttered and more readable.

For your convenience, a template is provided for you in the logger.xml /settingsworkspace

directory. Open this template, add your custom loggers and handlers, and save it to anylocation with any name. When deploying the application, remember to copy this file to the webserver with the other project files.

To pass the custom logging system configuration file as a deployment parameter, add the attribute to the element on the page that launches the application.jsx_logger_config script

The value of the attribute should be an absolute URI or the relative path from the HTML launchpage to the logging system configuration file.

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

jsxapppath="../workspace/JSXAPPS/samples/WSDL_Mapping_1/"

jsx_logger_config= >"loggers/mylogger.xml"

</script>

For more information, see .Deployment Parameters

201


Chapter 17 Internationalizing and Localizing Applications

This chapter discusses how to internationalize and localize General Interface applications for aninternational audience.

About Internationalization and LocalizationAPI Classes for LocalizationInternationalized GUI ClassesLocalizing an Application

About Internationalization and Localization

Internationalization (i18n) and localization (l10n) of applications is the process of preparing anapplication for international audiences. This process involves separating locale-dependentresources from the program code. These resources can then be localized (translated) for otherregions of the world (locales). The appropriate resource is then loaded at runtime according tothe user's locale.

Definitions and Terms

The following terms are some of the terms used in discussing internationalization andlocalization:

Internationalization is the process of preparing an application and its user interface so itcan be used in more than one locale. An internationalized application istranslation-ready. Internationalization is often abbreviated as 'i18n', where 18 representsthe number of letters between 'i' and 'n.'Localization is the customization of application resources for a particular locale or regionof the world. While internationalization generalizes an application for any locale,localization specializes the application for a single locale. Localization is oftenabbreviated as 'l10n', where 10 represents the number of letters between 'l' and 'n.'A locale defines a set of language and cultural conventions for the display andformatting of data in the user interface, such as labels, dates, numbers, and messages. Alocale is defined by a locale identifier which consists of a language identifier and/or aregion identifier.Resourcing is the process of separating the locale-specific elements from the source code,so they can be externalized from the application. Resource bundles are used forresourcing strings and objects.Resource bundles are specialized files that contain a collection of translatable strings. Aunique resource key identifies each string in the resource bundle. The hard-coded stringin your application is replaced by a reference to the resource bundle and the resourcekey. These separate resource files are then sent to translators for translation into otherlanguages.Unicode is a universal character encoding that provides a unique number for everycharacter. Unicode is used in internationalizing applications, because it is independent oflanguage, computer platform, and programming language. Examples of Unicodeencoding include UTF-8 and UTF-16. For more information, see http://www.unicode.org/.

http://www.unicode.org/

202


API Classes for Localization

General Interface provides the following classes for localizing applications:

jsx3.util.Locale

jsx3.util.DateFormat

jsx3.util.MessageFormat

jsx3.util.NumberFormat

jsx3.app.PropsBundle

For more information on these classes, see General Interface API Reference (Help > APIDocumentation).

jsx3.util.Locale

General Interface 3.2 introduced a new class, , which represents a locale. Ajsx3.util.Locale

locale is a region of the world that shares a common language, writing, calendar, and so on. Alocale is represented with a locale key, such as es_ES for Spanish in Spain. See .Locale Keys

The General Interface system, , has a locale which determines the languagejsx3.lang.System

and formatting of system messages. By default, the system locale is set automatically to thelocale of the host web browser. However, the locale can be changed by calling the

method.System.setLocale()

Each General Interface application, which is an instance of , also has a locale.jsx3.app.Server

The server locale determines the locale of localized GUI controls that it contains. Theapplication locale also determines which locale-sensitive resources are loaded into theapplication.

Locale Keys

The locale key is the string representation of a locale, which includes a language or a languageand a country in one of the following formats:

ll

ll_CC

where is a lowercase, two letter, ISO 639 language code and is the optional, uppercase,ll CC

two letter, ISO 3166 country code.

For a list of codes, visit these web sites:

International Organization for Standardization (ISO) - http://www.iso.ch/iso/en/ISOOnline.frontpageLanguage codes - http://www.loc.gov/standards/iso639-2/langhome.htmlCountry codes - http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html

http://www.iso.ch/iso/en/ISOOnline.frontpage

http://www.loc.gov/standards/iso639-2/langhome.html

http://www.iso.ch/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html

203


DateFormat, NumberFormat, and MessageFormat

Three classes in the form the foundation of the internationalization andjsx3.util package

localization services of General Interface: and . TheseDateFormat, MessageFormat, NumberFormat

classes are internationalized, because they have a constructor that takes an arbitrary localeobject as a parameter. The behavior of an instance of each class is dependent on the specifiedlocale.

General Interface leverages data from the to localize theseCommon Locale Data Repositoryclasses. The following locales from the CLDR are included with General Interface.

General Interface Locales

Language ISO 639-1 Code ISO 639-1 Code + ISO 3166 Code

Arabic ar

Chinese zh zh_CN, zh_HK, zh_TW

Danish da da_DK

Dutch nl nl_BE, nl_NL

English en en_AU, en_CA, en_GB, en_NZ, en_US, en_ZA

French fr fr_FR, fr_CA, fr_BE

Finnish fi fi_FI

German de de_DE

Greek el el_GR

Hebrew he he_IL

Indonesian id id_ID

Italian it it_IT

Japanese ja ja_JP

Korean ko ko_KR

Norwegian nn nn_NO

Polish pl pl_PL

Portuguese pt pt_BR, pt_PT

Russian ru ru_RU

Spanish es es_MX, es_ES, es_US

Swedish sv sv_SE

Thai th th_TH

Turkish tr tr_TR

Vietnamese vi vi_VN

http://cldr.unicode.org/

204


DateFormat

The class formats and parses dates in a localized manner. Months and days of theDateFormat

week are localized. Additionally, factory methods are available for creating formats that areappropriate for a particular locale.

NumberFormat

The class formats numbers in a localized manner. Number symbols, such as theNumberFormat

negative sign, decimal symbol, and percent symbol, are also localized. In addition, factorymethods are available for creating formats that are appropriate for a particular locale.

MessageFormat

The class constructs messages from a format and various inputs. It's localized,MessageFormat

because it can format inputs according to both and .DateFormat NumberFormat

jsx3.app.PropsBundle

The class handles localized loading of resources. A localized resource isjsx3.app.PropsBundle

a collection of dynamic properties files that define a set of properties localized for one or morelocales. For an example of a properties bundle file, see ./JSX/locale/locale.xmlGI_HOME

The directory structure of a properties bundle is as follows:

.xmlbundle_name - the file containing the properties of the default locale and metadatadescribing the locales that are available in other files. For example, .locale.xml

.locale_key1_.xmlbundle_name - the file containing properties localized for locale

. For example, .locale_key1 locale.fr.xml

.locale_key2_bundle_name .xml - the file containing properties localized for locale

. For example, .locale_key2 locale.es.xml

The default locale file in the properties bundle should be formatted as follows:

<data jsxnamespace="propsbundle"locales= >"external_locale_key1,external_locale_key2,..." "key" <locale> <record jsxid= jsxtext= eval= />"prop_key1" "prop_value1" "0|1" ... </locale>

 <locale key= >"locale_key" ... </locale> ...

</data>

Any other file in the same properties bundle should be formatted as follows:

205


<data jsxnamespace= >"propsbundle"  <locale key= >"external_locale_key1" ... </locale>  <locale key= >"locale_key_country1" ... </locale> <locale key= >"locale_key_country2" ... </locale> ...</data>

PropsBundle.getProps()

An instance of the class is obtained programmatically with the static factoryPropsBundle

method, . The first argument for this method is the base path of thePropsBundle.getProps()

localized resource. In this example, it would be preceded by the path to the.xmlbundle_name

directory containing the bundle. For example, . The second/locale.xmlpath_to_bundle

argument is an instance of . The factory method loads the files appropriate forjsx3.util.Locale

the requested locale based on the metadata contained in the default locale. For moreinformation, see General Interface API Reference.

Key Fall-through

The class provides for key fall-through. If a key isn't found in the properties file ofPropsBundle

a particular locale, the value from the next less-specific locale is used. For example, if aninstance of with a locale of en_GB is queried for a key, it checks the properties ofPropsBundle

locale en_GB. If the key isn't found, it checks en, and finally, the properties of the default localeuntil a key is found.

Internationalized GUI Classes

Five GUI controls are internationalized in General Interface:

DatePicker

TimePicker

Select

Menu

Matrix

DatePicker and TimePicker

The and classes use localized properties related to date format toDatePicker TimePicker

display information appropriate for the locale of the application. DatePicker and TimePicker arelocalized for the locales listed in .API Classes for Localization

206


1.

2.

Select, Menu, and Matrix

The , , and classes display messages in the user interface. For example, whenSelect Menu Matrix

a that doesn't have a CDF data source is selected, a message displays: . TheMenu - No Data -

messages for these classes are externalized in the system properties bundle () and are therefore translation-ready (i18n). General Interface providesJSX/locale/locale.xml

translations for the following locales.

Translations for GUI classes and system progress loader

Language ISO 639-1 Code

Chinese h_CN, zh_TW

English en

French fr

German de

Japanese ja

Korean ko

Portuguese pt

Russian ru

Spanish es

Localizing an Application

Localizing an application involves the following steps:

Externalize locale-dependent messages and settings in a properties bundleLoad the propertiesSet the application localeSet and use propertiesLocalize CDF GUI controls

Externalizing Messages and Settings

The first step towards internationalizing an application is to externalize all messages andsettings that are locale-dependent. These are externalized as properties in a properties bundle.A properties bundle is a resource bundle where the type of resource is dynamic property.Properties bundle files contain locale-specific objects, such as menu and button labels in theapplication user interface.

Creating Properties Bundle Files

To create a new single-file formatted, properties bundle in the Properties Bundle editor inGeneral Interface Builder, complete these steps:

Choose to open the editor.File > New > Properties Bundle

Right-click the table header in the editor and choose .Add New Locale

207


2. 3.

4.

5.

6.

1. 2.

Right-click the table header in the editor and choose .Add New LocaleType the key for the locale in the Add Locale dialog, such as for US English or en_US es

for Spanish. For information on keys, see . Click OK.Locale Keys

Click each Default cell and type the value for the default language. For example, for , type .menu_new New

Click each cell of the new locale column and type the value for the new locale. Forexample, for , type for the Spanish locale.menu_new Cree

If a value is specified, the cell background is white. Otherwise, the inherited value fromthe next less-specific locale is shown in a gray cell.

When authoring dynamic properties and properties bundle files usingnon-ASCII characters and non-western languages, save the file in a formatthat supports such characters, such as UTF-8 or UTF-16. See Character

.Encoding

Save the file with the .xml extension in the jss folder of your project.

Properties bundles can be authored in General Interface Builder insingle-file format only. However, the multiple-file format may be moreefficient for large collections of properties.

Loading Properties Bundle Files Automatically

To set the properties bundle file to automatically load when the application loads, complete thefollowing steps in General Interface Builder:

Right-click the properties bundle file in the Project Files palette.Choose . The file now displays in a bold font in the Project Files palette.Auto Load

Using Properties

Any property contained in a dynamic properties file or properties bundle and loaded by anapplication is available to the application in the following ways:

Programmatically through the method and the jsx3.app.Server.getProperties()

API. For example, the following statement: jsx3.app.Properties

208


1. 2.

3. a. b. c.

API. For example, the following statement: jsx3.app.Properties

myApp.getProperties().get("prop_key1");

evaluates to the value of the property, , appropriate for the current locale ofprop_key1

myApp.As dynamic properties of classes extending . When a dynamicjsx3.gui.Painted

property of an instance of is set, that property is expanded to the current valuePainted

of the property stored in the server's properties object before the instance is painted. A dynamic property of an instance of can be set with the Painted

method. jsx3.gui.Painted.setDynamicProperty()

The Properties Editor palette in General Interface Builder allows you to assigndynamic properties to object properties. Right-click the Value cell of a propertyand select a dynamic property from the context menu or type the property key(ID) in the Value cell.

The Properties Editor palette also allows you to assign properties from a properties bundle file.To enter a property from a properties bundle file, type the property key (ID) in a Value cell ofthe Properties Editor palette.

Setting the Application Locale

The locale of an application is determined in the following order, with the first one takingprecedence over the others:

The last value passed to Server.setLocale().The default locale value specified in the Project Settings dialog and stored in theapplication configuration file ( ), if specified. See .config.xml Deployment PanelThe current system locale, which is specified by:

The last value passed to System.setLocale()

The locale as determined from the host browser en_US if the locale could not be determined from the browser

Default Locale

The locale as determined by the browser may not be the most appropriate locale for anapplication. If an application must always display in one locale, regardless of the user, use theDefault Locale setting in the Project Settings dialog. See .Deployment Panel

Server.setLocale() Method

In some situations, specifying a default local isn't the best solution. In the following cases, use to set the locale:Server.setLocale()

The user can choose a locale.The locale that the user wants is stored on a server.

Note that after the method is called, the state of the application may be outServer.setLocale()

of synchronization with the new locale. Call the method toServer.reloadLocalizedResources()

reload any localized properties that have already been loaded by the application. Additionally,the view of the application may have to be repainted.

The following sample code demonstrates how to use the method.Server.setLocale()

209


/** * Function is executed when user selects the language on the Tools menu. * @param objMenu {jsx3.gui.Menu} * @param strID { } the CDF record ID of the execute menu record.String */

localization.doLoadLocalizeResource = (objMenu, strID) {function objServer = localization.APP;var

locale = strID != "-1" ? Locale.valueOf(strID) : ;var null

LOG.info("Setting application locale to " + locale + ".");

// Set the locale of the server to the selected locale objServer.setLocale(locale);

// We need to tell the server to reload any localized properties objServer.reloadLocalizedResources();

// Reset the CDF cache of the menu since dynamic properties are used // the source XML file.in

objMenu.resetXmlCacheData();

// Menus cache their drop-down HTML content, so clear .this objMenu.repaint();

// Repaint the smallest region of the application that is localized. // Non-CDF control Stack localized label textwith objServer.getJSXByName('blkApp').repaint();

}

Localizing CDF GUI Controls

Some CDF attributes may have values that represent dynamic properties. These attributes mustbe of the form { } where is the key of a dynamic property of the control's server. If thekey key

dynamic property exists, the value of the attribute is changed to the value of the dynamicproperty when the XML source document is first loaded. Otherwise, the attribute is leftunchanged.

For example, if you want to localize a menu using the properties bundle file, you would enterkeys from the properties bundle file as the values for the jsxtext attributes, such as jsxtext="{menu_new}".

<data jsxid= >"jsxroot" <record jsxid= jsxtext= />"1" "{menu_new\}" <record jsxid= jsxtext= />"2" "{menu_open\}" <record jsxid= jsxtext= />"3" "{menu_save\}"</data>

Then, if the locale is Spanish, the following keys are replaced with the appropriate values in theproperties bundle file:

menu_new is replaced with Cree

menu_open is replaced with Abra

210


menu_open is replaced with Abramenu_save is replaced with Salve

The replacement of key attributes with the property value occurs only once per XML document.The CDF attributes that are converted automatically include: jsxtext, jsxtip, jsximg,

, and . After the conversion, which occurs before the control isjsxstyle, jsxclass jsxkeycode

painted, the original value of any key that has been converted is lost. Therefore, changing thevalue of a dynamic property after the conversion doesn't change the CDF attribute value. Donot set CDF attributes programmatically to a property key. Instead, set CDF attributes to theproperty value programmatically. You can also use the method toCDF.convertProperties()

perform the conversion.

Custom Localized Logic

Applications may incorporate even more advanced localized functionality with customlocalized code. Localized code would typically query the application server instance for itscurrent locale and then modify its behavior based on the locale. This is a good strategy whenlocalized behavior cannot be represented only as externalized string values.

In the following example, an alert displays on July 4 if the locale is US English.

var today = Date();new (myApp.getLocale.equals(jsx3.util.Locale.US) &&if

today.getMonth()h1. 7 && today.getDate()4) { myApp.alert("Holiday","Today is Independence Day");}

211


Chapter 18 Deploying Applications

This chapter describes how to deploy General Interface applications.

About Application DeploymentDeploying as a Full Console ApplicationDeploying as a Non-Console ApplicationOverriding the Application Base DirectoryPosting Application FilesAccessing Deployed ApplicationsDeployment ParametersUsing Cross-Domain GI

About Application Deployment

Deploying a General Interface application is simpler than deploying conventional web-basedapplications. The process consists of creating an HTML or XHTML page or link for launchingthe application and copying required files and folders to the web server. It isn't necessary topackage the files into an archive.

Deployment consists of configuring the application for one of the following access models:

Full console application The application runs in a dedicated browser window. Theapplication is launched when an end user opens an HTML or XHTML file or clicks anapplication hyperlink in an existing web page.Non-console application The application is inserted into an existing web page as a divelement and only uses a portion of the page. A web page can contain multiple GeneralInterface applications.

General Interface Builder provides the Deployment Utility for generating the HTML or XHTMLcode for launching applications. This chapter describes how to use the Deployment Utility andconfigure your application.

212

Copyright © TIBCO Software Inc. All Rights Reserved.1.

Deploying as a Full Console Application

Full console applications occupy the entire browser window, and run independently of otherdeployed applications.

To launch a full console application, a launch page is required. A launch page is an HTML orXHTML file that loads the application in a browser window. This file initializes the GeneralInterface environment, loads your application into the browser, and renders it to the entire webpage. You can create a new launch page or use the provided parameterized launch pages,

or .shell.html shell.xhtml

There are two ways to launch a full console application:

Create a separate launch pageCreate a launch hyperlink and insert it into an existing web page

Creating a Launch Page

You can use the HTML Page panel of the Deployment Utility to create an HTML or XHTMLlaunch page that launches the application as a full console application.

To create a page for launching a full console application, complete these steps:

Select from the General Interface Builder menu.Project > Deployment Utility

213


1.

2.

3.

4. 5.

6.

Select from the General Interface Builder menu.Project > Deployment Utility

Click the button , to navigate to a directory, and type the launch file name, forBrowseexample launch.html or launch.xhtml. If you're creating an XHTML launch page, checkthe XHTML checkbox and use the .xhtml extension. Click . Save

XHTML launch pages are used to verify the behavior of an applicationthat runs as XHTML, such as a launch DIV on an XHTML portal page.

On the HTML Page panel, click the button to create the launch file. A new file isCreatecreated in the selected directory.Close the Deployment Utility.Open the launch page in a web browser. The General Interface software initializes and your application displays. Beforeproceeding, you can view the source of the HTML page that was automaticallygenerated.Select from the browser menu to view the source of this page. TheView > SourceDeployment Utility generated the following lines of HTML markup:

For XHTML files only, a DOCTYPE declaration is required before the roothtml

element. An XHTML namespace attribute is also required for the element.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" >"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" <html xmlns="http://www.w3.org/1999/xhtml" style= >"border-width:0px;overflow:hidden;"

The element, which defines general window properties.body

<body BGCOLOR= SCROLL="#9898a5" "no" style="position:absolute;width:100%;height:100%;left:0px; top:0px;padding:0px;margin:0px;border:0px;overflow:hidden;">

The element, which provides the HTML container for your General Interfacediv

application. You can change the style of this element by modifying its CSS

214


6.

7.

1.

2.

application. You can change the style of this element by modifying its CSSproperties.

<div style="position:absolute;left:0px;top:0px;width:100%; height:100%;"> . ... script element ... . </div>

The element, which loads the General Interface runtime, passes the projectscript

path to it, and specifies how classes are loaded.

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

The script element contains the following:

src="JSX/js/JSX30.js" The relative path from the web page to the GeneralInterface runtime file. jsxapppath The relative path from the web page to the project directory.

Modify the HTML markup as needed to customize the page.

Creating a Launch Hyperlink

To create a launch hyperlink for you application, use the Launch Hyperlink page of theDeployment Utility. Copy and paste the generated HTML markup into an existing web page.When you click this hyperlink on the web page, a parameterized launch page ( ) isshell.html

called and the application is launched as a full console application.

To create a launch hyperlink to insert into an existing web page,

Select from the General Interface Builder menu to open theProject > Deployment UtilityDeployment Utility.Click the tab.Launch Link

215


2.

3.

4. 5.

1. 2.

Copy the text in the lower pane of the tab and paste it into an HTML page.The following template is used for launch link HTML markup:

<a href= onclick="window.open('shell.html?jsxapppath="#" "..%2Fworkspace%2JSXAPPS%2FMyProject','', 'toolbar=no,location=no,directories=no,status=no,menubar=no, scrollbars=no,resizable=yes,width=800,height=600,top=0, left=0');"> Launch Application </a>

The attribute of the element contains the following: href a

shell.html The relative path from the web page to the parameterized applicationlaunch page. is located in the directory. shell.html GI_HOME

jsxapppath The relative path from to your project directory. shell.html

Launch Application The text of the hyperlink for launching the application. Close the Deployment Utility.Modify the HTML markup as needed to customize the hyperlink. For example, changethe hyperlink text to the name of the application.

Deploying as a Non-Console Application

A non-console application is a deployed General Interface application that occupies a portion ofa web page. Multiple General Interface applications can be deployed in a single web page. Thisis useful if you have multiple applications that interact with each other.

Non-console applications can be inserted into an existing web page using elements. Whendiv

the web page is loaded, the General Interface Framework initializes. Then the General Interfaceapplications are loaded.

Using a DIV Element

Use the Inline DIV tab of the Deployment Utility to automatically generate the HTML markupfor the element. Simply copy and paste this generated markup into the existing web page.div

To generate the HTML markup for a element,div

Select from the General Interface Builder menu.Project > Deployment UtilityClick the tab. Inline DIV

216


2.

3.

4. 5.

Copy the text in the lower pane of the tab and paste into an HTML page.The following template is used for creating a element:div

<div style= >"width:100%;height:400px;" <script type= src="text/javascript" "JSX/js/JSX30.js" jsxapppath= >"../workspace/JSXAPPS/MyProject" </script> </div>

The script element contains src=" , which is the relative path from theJSX/js/JSX30.js"

web page to the General Interface runtime file, and , which is the relative pathjsxapppath

from the web page to the project directory.

Close the Deployment Utility.Modify the HTML markup as needed to customize the page.

To insert multiple applications in one web page, the attribute be identicalsrc mustand the path to the directory must be the same. For a parameterized JSXAPPS src

URI, only the attribute before the "?" needs to be identical. The query can bedifferent. For example, these are considered identical even though the parametersare different. Note that the path to the directory is the same, as required.JSXAPPS

src=" JSX/js/JSX30.js?jsxapppath=../workspace_/JSXAPPS/project1_path_"andsrc=" ForJSX/js/JSX30.js?jsxapppath=../workspace_/JSXAPPS/project2_path_".

more information on parameters, see .Deployment Parameters

Example

General Interface Builder generates the following elements for two of the General Interfacediv

Builder sample applications:

217


<div style= >"width:100%;height:400px;" <script type= src="text/javascript" "JSX/js/JSX30.js" jsxapppath= >"../workspace/JSXAPPS/samples/WSDL_Mapping_1" </script></div>

<div style= >"width:100%;height:400px;" <script type= src="text/javascript" "JSX/js/JSX30.js" jsxapppath= >"../workspace/JSXAPPS/samples/WSDL_Mapping_2" </script></div>

When this HTML markup is inserted in an HTML page, the applications are loaded in the sameHTML page.

Deployed Applications and the Progress Bar

To prevent General Interface progress bars from overlapping when deploying multipleapplications in the same page, add in the element of both deployedposition:relative div

applications. For example,

<div style= >"width:100%;height:400px;position:relative;" <script type= src="text/javascript" "/3.5/GI/JSX/js/JSX30.js" jsxapppath= >"/3.5/GIApps/JSXAPPS/chart/" </script> </div>

<div style= >"width:100%;height:300px;position:relative;" <script type= src="text/javascript" "/3.5/GI/JSX/js/JSX30.js" jsxapppath= >"/3.5/GIApps/JSXAPPS/WSDL_Mapping_1/" </script> </div>

The following figure shows an example.

218


Overriding the Application Base Directory

In some situations, you might need to override the application base directory. Overriding theapplication base directory is useful if other aspects of your development process, such as sourcecontrol or access rights, restrict where files can reside on the disk. The General Interfacejsxappbase parameter provides this flexibility.

To override the application base directory ( ), do the following:jsxappbase

219


1.

2.

1.

Add this record to the project configuration file (config.xml):

<record jsxid="jsxappbase"type= >path_to_content_folder/"string" </record>

Then save the file to the project folder in the directory.config.xml JSXAPPS

If the directory structure looks similar to the following figure, you would add this record to :config.xml

<record jsxid= type= >"jsxappbase" "string" content/</record>

Once the application directory is overridden, all URIs used in the application resolve relative tothe base directory rather than to the file.config.xml

For more information on how URIs are resolved, see .URI Resolution

Posting Application Files

The final deployment step is to post General Interface software and your applications on anHTTP or HTTPS web server. Unlike most web applications, General Interface does not run inthe application server. Instead, all browser-compatible files, such as .js, .xml, .xsl, .css, and .gif,are served to the browser and executed on the client.

General Interface is compatible with all HTTP/S web servers and requires no additionalexecutables to be installed, either on the server or the client.

To finish deploying the General Interface application,

Copy the following files and folders to a directory accessible to the web server. The filescan be in any location on the server.

JSX folder

220


1.

2.

3.

=If you're developing your applications using the General Interfacedebug build ( ), be sure to deploy thetib-gi-version-pro-debug

standard JSX folder from a deploy build or (tib-gi-version-pro

). The debug folder has additionaltib-gi-version-pro-max JSX

debugging code and therefore runs slower. For more informationon these release builds, visit Developer Network at

.http://www.generalinterface.org

JSXAPPS folder which contains the project to be deployed Any other files in your directory required by the application, includingworkspace

add-ins and prototypes

The and folders must be at the same level as the addins prototypes

folder to be available at runtime.JSXAPPS

All launch pages for the applications shell.html or is required if you deployed your application as ashell.xhtml

launch hyperlink. Also, must be located at the same level as the shell.html JSX

folder. These files are located in the . See . GI_HOME Creating a Launch Hyperlinklogger.xml, located in the directory, can be used to monitor loggingGI_HOME

messages from the deployed application. Modify this file as needed. See Logging. and Application Monitors

jxs3.gui.window.html/.xhtml if you're using the class. Copy thejsx3.gui.Window

file(s) from the directory.GI_HOME

Modify the relative URLs in the HTML markup generated by the Deployment Utility ifyour directory structure on the web server is different from the directory structureduring development. For example, you might need to modify the application path, srcpath, path to , and so on.shell.html

Set access rights on the web server in the same manner as any standard HTTP/Saccessible resource.

For dynamic properties files, be sure to use the .xml extension as someservers won't recognize the .jss extension. By default, General Interface,version 3.2 and higher, supports the .xml extension, which is therecommended file extension. See . If you continueDynamic Properties Filesto use the .jss extension, you might need to add a new Mime Type to theserver.


221


Deployment Examples

Because General Interface deployment is extremely flexible, there are few restrictions on whereyour files are located on the web server. Folders and files can be nested and in differentlocations. Due to the relative URI functionality introduced in General Interface 3.2, projects canbe easily renamed and moved to new locations. For more information, see .URI Resolution

In some cases, the General Interface runtime is deployed in one location by the systemadministrator and developers deploy their applications to another location on the same webserver. The following example demonstrates this scenario on a UNIX machine:

The system administrator installs General Interface on the web server at this location — version_number//var/www/htdocs/gi/

This directory contains: shell.html (launch page) JSX folder Other appropriate files

The developer deploys the application here: /home/username/htdocs/JSXAPPS/app1

And also installs a web page containing the application here: /home/username/htdocs/app1/index.html

In another example, as shown in the following figure, the application launch pages, GeneralInterface runtime, and application are deployed to a folder called . However, each ofgideploy

these is in a different folder. The launch pages are in an folder, General Interface is in a apps

folder, and the deployed application is in a folder.gi/3.2 gihome

The element on the launch page shown in the previous figure would look likescript app1.html

this:

222


1. 2. 3.

<script type"text/javascript" src="../gi/version_number/JSX/js/JSX30.js" jsxapppath= >"../gihome/JSXAPPS/app1"</script>

Accessing Deployed Applications

This section describes how end users can access General Interface applications.

To access an application in a browser on the client machine, navigate to the URL where theapplication files are deployed.

For example, if the application is deployed to the URL , the userhttp://www.myserver.comaccesses the application by navigating to:

http://www.myserver.com/project_launch_file_path

where is the path to the HTML file for launching your application,project_launch_file_path

relative to the HTML doc root directory of the HTTP server.

Deployment Parameters

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

There are two areas to consider when deploying GI applications:

Configuring Deployed ApplicationsConfiguring 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 element(s) on the web page thatscript

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 GeneralInterface runtime in the following order, with the first one taking precedence over the others:

Attributes of the HTML element.script

Query parameters of the attribute of the element.src script

Configuration parameters stored in the application configuration file, .config.xml

http://www.myserver.com

223


HTML Script Element

One mechanism for configuring an application is to modify the element of the HTMLscript

launch page where the application is deployed. Deployment parameters can be included asattributes of the element or as query parameters in the attribute of the script src script

element.

General Interface provides several built-in parameters, such as and jsxappns, jsxapploader,

. Custom attributes or parameters can also be added to the element. Forjsxapppath script

example, this mechanism can be used to communicate session information from a web server toa General Interface application. However, all attributes beginning with are reserved forjsx

General Interface.

All attributes of the element are deployment parameters used to configurescript

the application these reserved HTML attributes — except id, space, type,

, and .charset, defer, src language

The following parameters are significant in the General Interface runtime:

jsxappns. Application namespace. For example, . Because everyjsxappns="myAPP"

application deployed on a single page must have a unique namespace, overriding thenamespace 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 whendeploying 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 element, see thescript

following examples.

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

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

<script type src="text/javascript" "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 GeneralInterface runtime file, .JSX/js/JSX30.js

224



<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 pathand the progress bar loading as parameters.


<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 configurationfile, . This file contains configuration parameters that affect deployment of theconfig.xml

application. These parameters can be edited on the Deployment panel of the Project Settingsdialog 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 torun when loading, and so on. For more information on the available parameters, see .File MenuOther deployment options, such as which add-ins to load, are automatically set in config.xmlfrom settings in the IDE.

Custom attributes can also be manually added to , which is located at the root of theconfig.xml

project. Simply open , add a new element, and save the file. For example, youconfig.xml record

could add a record that externalizes a constant from JavaScript code as shown here:

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

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

myApp.getEnv("CONSTANT1");

Configuring the Runtime

The General Interface runtime or JSX system, which is required to run deployed GeneralInterface applications, is configured at deployment with the same element mechanismscript

described in . A runtime configuration parameter is anyConfiguring Deployed Applicationsparameter beginning with but not . Any General Interface application in ajsx jsxapp

multi-application deployment page may configure the runtime. However, it is an error if scriptelements provide conflicting values for a single runtime parameter.

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

225


jsx_logger_config. Specifies the name and location of the logging system configurationfile to be used. You can create a custom logging system configuration file and specify itslocation using this attribute. This is useful for monitoring and testing a deployedapplication at runtime. See .Creating a Custom Logging System Configuration Filejsx_no_messages. When set to , prevents from loading with1 JSX/locale/messages.xml

the system. This file is used for system messages and is probably not necessary for aproduction deployment.jsx_no_locale. When set to , prevents from loading with the1 JSX/locale/locale.xml

system. This properties bundle file provides all localized data to the system, includinginformation for , , , and . This data may not beNumberFormat DateFormat Locale DatePicker

necessary for some smaller applications. For more information, see Internationalizing. and Localizing Applications

An application that specifies the parameter must usejsx_no_locale notany locale data. A common result will be a null pointer exception inDatePicker or TimePicker or painted in Table, Menu, Select, Matrix,null

or BlockX.

jsx_browsers. Overrides the default set of supported browsers. The format of thisparameter is bt={allow,warn}[,...]

where is the browser type returned by the method in the bt getType()

class. See in General Interface APIjsx3.lang.ClassLoader jsx3.lang.ClassLoader

Reference. For example, to show a warning in Internet Explorer 6, modify the applicationlaunch 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 toproceed.

The following Internet Explorer-specific parameters: jsxxmlregkey The default ActiveX XML object key. Specifies the version of theXML Parser instance as referenced in the Microsoft Windows Registry. Forexample, . jsxxmlregkey="Msxml2.FreeThreadedDOMDocument.4.0"

jsxxslregkey The default ActiveX XSL object key. Specifies the version of the XSLParser 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 theHTTP 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, XSLParser, 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 ifavailable, then version 3. If you need to use a different version, use these system parameters tooverride the defaults.

General Interface runtime parameters are available using the method. For morejsx3.getEnv()

information on the method, see .getEnv() 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 to a Generalvalue1

http://www.generalinterface.org/api/versions/latest/

226


to print a value to the system log. The following example assigns a value of to a Generalvalue1

Interface runtime parameter named :jsxprop1

<script type src="text/javascript" "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 is .jsxprop1 value1

Using Cross-Domain GI

The cross-domain loading feature allows you to load the General Interface runtime and yourapplication from different security domains, increasing deployment flexibility and allowingyou to do the following:

Host the GI runtime on a content delivery network (CDN) for improved load times. Use a single runtime installation for several General Interface applications, includingapplications that are hosted on different domains. This can improve load time since theGI runtime may already be in the browser cache.Include General Interface applications in blogs and other management systems wherehosting files is not permitted.Allow a system administrator to install a single instance of the General Interface runtimeto be shared across an organization to simplify application deployment for users.

In a build of GI that supports cross-domain loading all XML and XSL data file have beenconverted into a -like format, which supports loading across domains.JSONP

For example, the file ,JSX/locale/messages.xml

<data jsxnamespace= locales="">"propsbundle"<locale>ClassLoader<record jsxid= jsxtext="boot.env_reset" "Error redefining JSX environment parameter

/>{0} from ''{1}'' to ''{2}''."<record jsxid= jsxtext= />"boot.class_err" "Could not load class {0}."<record jsxid= jsxtext= />"boot.class_ex" "Error loading class {0}: {1}"<record jsxid= jsxtext="boot.class_undef" "Loaded JavaScript file {0} but class {1}

/>was not defined."...

becomes ,JSX/locale/messages.xml.js

http://en.wikipedia.org/wiki/JSON#JSONP

227


jsx3.net.Request.xdr(,"jsx:/locale/messages.xml"

propsbundle\ \"<data jsxnamespace=\" " locales=\" ">\n\n <locale>\n <record jsxid=\"boot.env_reset\ Error redefining JSX environment parameter {0} from" jsxtext=\"''{1}'' to ''{2}''.\ boot.class_err\ Could not load"/>\n <record jsxid=\" " jsxtext=\"class {0}.\ boot.class_ex\ Error loading class {0}:"/>\n <record jsxid=\" " jsxtext=\"{1}\ boot.class_undef\ Loaded JavaScript file {0} but"/>\n <record jsxid=\" " jsxtext=\"class {1} was not defined.\ );"/>\n ... "

This conversion is completely automated by the build process, which uses the new task to compile the XML/XSL resources. The task is turned off by default to avoidJsEncodeTask

some code and data bloat. To enable it you must set the build property to ,build.gi.xd true

either in or on the command line:build/user.properties

$> ant -Dbuild.gi.xd=true

A pre-built cross-domain ready distribution of GI is as well.available for download

If you want to host your application on a separate domain as well, you must process the XMLand XSL resources in your application in a similar manner. You can do so using the same Anttask that General Interface uses. There is also a command line interface for the encoder thatcomes with the General Interface source distribution:

$> cd WORKSPACE/JSXAPPS/myApp$> find . -name -or -name \| xargs \"*.xml" "*.xsl"sh GISRC/build/tools/bin/jsencode.sh -user ../

Deployment

When deploying an application cross-domain you must modify the GI launch page to indicatethe domains from which resources should be loaded in the cross-domain manner. Consider thefollowing example:

The GI launch page is http://www.example.com/myApp.htmlThe GI application is http://apps.example.com/JSXAPPS/myAppThe GI runtime is http://cdn.host.com/gi/3.9.0

Then the launch page should include the following:

<script type="text/javascript" src="http://cdn.host.com/gi/3.9.0/JSX/js/JSX30.js"jsxapppath="http://apps.example.com/JSXAPPS/myApp/"jsxxd="http: >//cdn.host.com/ http://apps.example.com/"

The two URLs in the attribute indicate the cross-domain sites. Any resource whose pathjsxxd

begins with one of these prefixes will be assumed to exist in the JSONP-like syntax and will beloaded in the cross-domain manner.

http://www.generalinterface.org/docs/display/GETGI

228


Synchronous Loading

Since the introduction of the in Release 3.7, General InterfaceAsynchronous Modular Platformrelies less and less on synchronous loading. Some public APIs still trigger synchronous loading,however. These APIs are still available to use in applications, but they will not work if youdeploy the GI runtime or your application cross-domain as described above. This is because theJSONP technique for cross-domain data access works only asynchronously.

The following are examples of synchronous APIs. You must not use any of these in across-domain deployment.

jsx3.require()

(when is called with )jsx3.net.Request.send() open() bAsync=false

jsx3.app.Model.load()

jsx3.xml.Document.load()

jsx3.app.Cache.getOrOpenDocument()

jsx3.lang.ClassLoader.loadJSFileSync()

XML URL (of ) when XML Async is jsx3.xml.Cacheable false

Persistence = Referenced (not Referenced Async)

In addition, relies on synchronous loading. Dynamic class loading occursdynamic class loadingwhen an application loads a component file and one or more of the classes used in thecomponent file is not already loaded. There are several possible workarounds to dynamic classloading:

Use a custom build of GI that pre-loads all GI classes that the application uses.Use the AMP architecture and plug-in pre-requisites to declare the class requirements ofeach plug-in.Use the new 3.9 method before calling .jsx3.requireAsync() Model.loadXML()

229


Chapter 19 Optimizing Load Performance

This chapter describes how General Interface loads the JavaScript framework classes in thestandard General Interface build. It also describes how to optimize load performance usingcustomized General Interface builds.

Dynamic Class LoadingGeneral Interface Load Performance Optimization ScriptSet Up RequirementsQuick StepsSetting up for Custom BuildsCreating Custom BuildsDeploying Custom Builds

Dynamic Class Loading

General Interface 3.2 introduced a new dynamic class loading feature to increase applicationperformance and accelerate load time. Dynamic class loading causes classes to be loaded asthey're needed at the last possible moment. Since only statically loaded classes are loaded atapplication initialization, the application loads much faster.

For more information on dynamic class loading and a list of statically loaded General Interfaceclasses, see .Class Loading in General Interface

At General Interface application initialization, General Interface first loads a version of jsx.jsappropriate for the host browser. The file is located in a browser-specific directory, suchjsx.js

as , and . The file contains/JSX/js/fx, GI_HOME_/JSX/js/ie6GI_HOME /JSX/js/ie7GI_HOME jsx.js

the statically loaded framework classes, such as classes in the package. After jsx3.lang jsx.js

is loaded, subsequent classes are loaded as needed using dynamic class loading. Dynamic classloading loads classes individually by loading the JavaScript files that define them.

Because dynamic class loading is both synchronous and serial, loading multiple classes at thesame time can degrade the performance of a General Interface application, especially whenrunning over HTTP. The typical uses for dynamic class loading, such as loading the

GUI class when a component file loads, almost ensure that degradation ofjsx3.gui.Matrix

performance will occur. Loading the class causes several classes to be loadedjsx3.gui.Matrix

at the same time including , and several others.jsx3.gui.Matrix.Column, jsx3.gui.Form

General Interface Load Performance Optimization Script

To improve load performance for your application, you can use the General Interface LoadPerformance Optimization script to create a custom General Interface build that's optimized fora particular General Interface application. The General Interface optimization script, GI_HOME

, copies classes that would normally be loaded with dynamic class loading/util/gi-merge.sh

into the file, so the classes are pre-loaded before the application loads. Since browsersjsx.js

load single JavaScript files faster than they load several files serially, the initial load of a GeneralInterface application can be improved by creating a custom build.

230


1. a. b.

c.

2. a. b.

3.

a.

The General Interface Load Performance Optimization script is not included in theEnterprise Edition.

Deciding which classes to include in a custom General Interface build requires an iterativeprocess. First, run the General Interface Load Performance Optimization script with one set ofclasses and test the performance of the application. Then run the optimization script again withanother set of classes and compare the performance to the first run.

If you want to eliminate dynamic class loading, you should include every class that yourapplication uses. Depending on how your application is structured, classes might be loadedthat are only required by rare usage patterns. Therefore, the best solution might be to includeonly the classes needed to load the application to its first interactive state.

Set Up Requirements

Before you can create a custom build, you need the following:

General Interface installationThe General Interface Load Performance Optimization script, /util/gi-merge.shGI_HOME

An environment capable of running a Bash script, such as a Linux command line, MacOS X terminal, or Cygwin shell

Quick Steps

Complete these steps to create, test, and deploy a custom General Interface build with theGeneral Interface Load Performance Optimization script:

Set up to create a custom build. See . Setting up for Custom BuildsCreate a new deployment directory. Copy these files from the General Interface installation directory into the newdeployment directory:

JSX/ directoryjsx3.gui.window.htmljsx3.gui.window.xhtmllogger.xmlshell.htmlshell.xhtml

Copy the General Interface optimization script from to/util/gi-merge.shGI_HOME

the same file system drive.Create a custom build. . Creating Custom Builds

Modify the script to customize the set of pre-loaded classes. Run the script.

Deploy the new custom build and the General Interface application to a web server. See . Deploying Custom Builds

Copy the new deployment directory and the General Interface application to aweb server.

231


3.

a.

b.

4.

1.

2.

3.

1. 2.

1.

2.

Modify the path of the attribute on the launch page or in the launch link tosrc

point to the deployment directory.Test the application performance, modify the optimization script as needed and rerun it,and redeploy to test again.

Setting up for Custom Builds

Before you create custom General Interface builds, you need to complete the following setupsteps:

Create a new deployment directory for each customized build you want to create, suchas .gideploy1

Copy the following files and directory from the General Interface installation directoryinto each new deployment directory:

JSX/ directory jsx3.gui.window.html jsx3.gui.window.xhtml logger.xml shell.html shell.xhtml

Copy the General Interface optimization script, , to the same/util/gi-merge.shGI_HOME

file system drive as the new General Interface deployment directories you just created.

To create customized builds for multiple General Interface applications, you need tocreate a deployment directory for each application. For example, if you are creatingcustom builds for three applications, you would create three deployment directories,such as , and gideploy1, gideploy2 gideploy3.

For more information on deployment, see .Deploying Applications

Creating Custom Builds

Creating custom General Interface builds to run your General Interface applications involvestwo steps:

Customizing the General Interface optimization scriptRunning the General Interface optimization script and testing the build

Customizing the Optimization Script

To customize and run the optimization script, complete the following steps:

Open the script in a text editor. In the Professional Edition the script isgi-merge.sh

located in ./util/GI_HOME

Specify which classes to include in the custom build. To include a class in the custombuild, set the class variable to 1 as described below.The file defines a variable for each optional class. Each variable name is thegi-merge.sh

fully-qualified class name with periods ( . ) replaced with underscores ( _ ). For example,

232


2.

1. 2.

3.

fully-qualified class name with periods ( . ) replaced with underscores ( _ ). For example,the class would be in the file.jsx3.gui.Matrix jsx3_gui_Matrix gi-merge.sh

When you run the optimization script, classes with the variable set to 1 are included inthe custom build. The script automatically resolves dependencies between classes. Forexample, if you include the class, the class is alsojsx3.gui.Button jsx3.gui.Form

included because implements . Any classes that are set to 0 and that aren'tButton Form

required by an included class are excluded.The following example shows a code snippet from a sample optimization script file.Classes with a variable of 1, such as , , and so on, arejsx.gui.Form jsx.gui.Heavyweight

copied to the custom build.

. . .jsx3_gui_Dialog=0jsx3_gui_Form=0jsx3_gui_Grid=0jsx3_gui_HotKey=1jsx3_gui_Image=1jsx3_gui_ImageButton=1jsx3_gui_LayoutGrid=1jsx3_gui_List=0jsx3_gui_Matrix=1. . .

Running the Optimization Script and Testing the Build

Running the optimization script modifies the files located in the deployment directory: jsx.js

, , and . The optimization/JSX/js/fxdeploy_dir /JSX/js/ie6deploy_dir /JSX/js/ie7deploy_dir

script notifies you of any classes that are required by the classes that you included. Theoptimization script also creates a backup of the original files in the deploymentjsx.js

directory. For example, if your deployment directory is , then backups of the originalgideploy1

files are copied to these locations:

gideploy1/JSX/js/fx/jsx.js.origgideploy1/JSX/js/ie6/jsx.js.origgideploy1/JSX/js/ie7/jsx.js.orig

To run and test the optimization script, complete the following steps:

Open the command line according to your environment.Change to the General Interface deployment directory. For example, if the custom buildis located in , change to that directory from the command line.gideploy1

The following example shows how to change to the directory in a Linux shellgideploy1

environment.

$ cd gideploy1

Enter the command to run the customized optimization script from the General Interfacedeployment directory.

Because the optimization script modifies files in the directory, alwaysJSX

run the optimization script on each deployment directory, on thenotGeneral Interface installation directory.

The following example shows how to run the command in a Linux shell environment.

233


3.

4.

1.

2.

3.

$ sh /path_to_tool/gi-merge.sh

After running the optimization script, output similar to the following is printed to thecommand line and the listed classes are merged with the classes in the files in thejsx.js

specified deployment directory.In this example output, is set to 1:jsx3_gui_Matrix

Creating backup of ie6/jsx.js Creating backup of ie7/jsx.js Creating backup of fx/jsx.js jsx3_gui_Matrix requires jsx3_xml_Cacheable jsx3_gui_Matrix requires jsx3_gui_Form jsx3_gui_Matrix requires jsx3_gui_Matrix_Column All done

Deploy the custom build and test the performance of your application with the newcustomized build. See .Deploying Custom Builds

If you're not satisfied with the results, continue to modify the optimization script, rerun theoptimization script, and test the application performance until you're satisfied with the results.

Deploying Custom Builds

Once you've created a custom build using the General Interface optimization script, deploy thedeployment directory as you would any General Interface deployment directory.

Application deployment includes the following steps:

Copy the new deployment directory and the General Interface application to a webserver. For more information, see . Deploying Applications

General Interface requires that any applications deployed in the sameHTML page must use the same General Interface deployment directory.Therefore, if you deploy multiple applications in a single page, eachapplication must use the standard General Interface deployment directoryor each application must use the same customized General Interfacedeployment directory.

Create a deployment launch page for the application using the General Interface BuilderDeployment Utility (Project > Deployment Utility).Modify the path in the attribute of the script element on the launch page and verifysrc

that the application path value ( ) is correct as shown in the followingjsxapppath

examples, where represents the relative path from the web page to thedeploy_dir

custom General Interface deployment directory.

<script type= src="text/javascript" "deploy_dir/JSX/js/JSX30.js"

jsxapppath= >"../JSXAPPS/MyProjectDir/" </script><a href= onclick="window.open('deploy_dir/shell.html?jsxapppath="#" ../JSXAPPS/MyProjectDir','','toolbar=no,location=no, directories=no,status=no,menubar=no,scrollbars=no, resizable=yes,width=800,height=600,top=0,left=0');"> Launch Application</a>

234


4. Use the application launch page to run the deployed application and test theperformance.

For example, to launch your application using as the launch page, enter a URLshell.html

similar to the following in the browser:

http://web_server/deploy_dir/shell.html?jsxapppath=../JSXAPPS/MyProjectDir

where is the address of the web server, such as or ,web_server localhost:8080 mywebserver.com

is the deployment directory on the web server, and is the applicationdeploy_dir MyProjectDir

project directory.

http://web_server/deploy_dir/shell.html?jsxapppath=../JSXAPPS/MyProjectDir

235


Chapter 20 Asynchronous Modular Platform

This chapter describes the Asynchronous Module Platform (AMP) and its features.

About AMPExtension Point Contract and ProcessingAMP Applications and Built-In Extension PointsPlug-ins with Extensions and Extension PointsApplication Techniques and Utilities

About AMP

The Asynchronous Modular Platform (AMP) is a General Interface framework for buildingmodular and high-performing enterprise-sized General Interface applications. AMP is anoptional part of General Interface and is packaged as an add-in. AMP provides the libraries andtemplates that allow you to easily create extensible and loosely-coupled applicationcomponents and combine them into a working whole. The design of AMP is inspired by theEclipse plug-in architecture.

AMP Capabilities

This section describes common pitfalls of General Interface application development and howAMP helps overcome them to improve code quality and manageability.

Component Files

Component files that are unnecessarily large often contain many objects that are initiallyinvisible and may only become visible during uncommon use cases.

AMP helps manage component files so that they do not burden the overall code base. From thebeginning of application development, AMP encourages decomposition of applications intoconstituent parts.

Asynchronous Resource Loading

Dynamic class loading and synchronous resource loading are convenient for developers, butmay cause major performance bottlenecks in a deployed application.

AMP makes working with asynchronously loaded resources as easy as working withsynchronously loaded ones. By using asynchronous resource loading, developers can avoid theperformance problems associated with dynamic class loading and synchronous resourceloading. AMP also enforces asynchronous behavior by providing only asynchronous APIs.

Code Components

Large, successful applications generally use a publish-subscribe pattern to notify applicationcomponents of a change in application state. Unfortunately, this paradigm typically requires agreat deal of boilerplate code, plus careful attention to components as they are added orremoved from the application.

AMP allows you to define these types of dependencies declaratively in XML, thereby

significantly reducing the amount of required boilerplate code.

236


significantly reducing the amount of required boilerplate code.

Application Extensibility

It is common for large applications to lack extensibility features. Extending this type ofapplication typically involves both coding the extension and modifying the application. If suchan application is extensible, it is because the developer has spent considerable effort to designan extensible framework.

AMP provides a modular framework that is engineered around the needs of extensible GeneralInterface applications. The AMP infrastructure encourages and when appropriate, enforces, thedesign of application components according to well-defined interfaces that you can extend inthe future without modifying the application.

Scaling and Complexity

Adding new components can increase design complexity. In a poorly designed system,complexity can increase very rapidly (polynomially) as components are added, because eachexisting component must be modified to take into account interactions with every newcomponent.

AMP reduces this complexity by encouraging application components to communicate witheach other through well-defined interfaces, even for internal system components.

Testing

In most application development environments, special care is required to build applicationsthat can be easily tested. Because developers are usually pressed to complete developmentquickly, they may employ large, monolithic components, and create ad-hoc frameworks thatare not designed with testing in mind.

AMP addresses testing concerns by encouraging developers to create modular components andby offering an application framework with generous log coverage and benchmark statistics.

Extension Point Contract and Processing

This section describes how extension points and contracts are processed.

Extension Points and Contracts

Each extension point defines a contract that all of its extensions must adhere to. The extensionpoint is the controller of the relationship with its extensions. The extension point processes itsextensions (it is not processed by its extensions). Therefore, all extensions must meet theexpectations of the extension point contract in order for the extension point to be able to processthem.

Because extension points and extensions are declared in XML, the basic form of the contractmust be defined in XML. Significant flexibility is permitted when augmenting the basic pattern.The most common way of processing extensions is to use the method of theprocessExts()

jsx3.amp.ExtPoint class. The following example uses the method of a subclass of onLoad()

.jsx3.amp.PlugIn

237


CustomPlugIn.prototype.onLoad = () {function

log = .getLog();var this .getExtPoint("xp1").processExts( (ext, xml) {this function log.info("Processed XML " + xml + " from extension " + ext + "."); };};

The method implements a visitor pattern. The parameter to the method is aprocessExts()

function that is called once for every child element of the XML declarations of every extensionto the extension point.

The following extension declaration

<extension-point id= >"xp1" </extension-point>

<extension point= id= >"com.tibco.example.p1.xp1" "x1" <item id= />"1" <item id= />"2"</extension>

logs the following messages when the is loaded.com.tibco.example.p1

[INFO] Processed XML <item id="1"/> from extension com.tibco.example.p1.x1.[INFO] Processed XML <item id="2"/> from extension com.tibco.example.p1.x1.

It is a good practice to document the contract of the extension point with its declaration usingan XML comment, as shown above, or with arbitrary nested XML. Any nested XML is allowed,provided that it is not in the AMP XML namespace.

AMP recognizes a child element of the element. This allows theprocessor extension-point

extension point to define the processing visitor declaratively rather than in code. If theprocessor is declared in the extension point definition, the parameter to the processExts()method is optional. When no parameter is passed, a processor is created via the getProcessor()method of the class. See the General Interface API Guide for morejsx3.amp.ExtProc

information.

Processor Types

This section describes the built-in processor types that cover the most common extension pointcontracts.

Type eval

The inner text content of every extension child element is taken as a script and evaluated in thecontext of the extension object. The extension elements may define the attribute . Inload="true"

this case, the plug-in that defines the extension is loaded before the script is evaluated.Therefore, the script can be evaluated synchronously ( ) or asynchronously (load="false"

). Example (Descriptor file):load="true"

238


<extension-point id= >"xp"<processor type= />"eval"</extension-point>

<extension point= >"com.tibco.example.p1.xp" this.getPlugIn().doSomething();<eval load= >"true" </eval></extension>

Example (Processing code):

this.getExtPoint("xp").processExts();

Type return

The inner text content of every extension child element is taken as a script and evaluated in thecontext of the extension object. The value of the evaluated script is returned by the extensionprocessor. Example (Descriptor file):

<extension-point id= >"xp"<processor type= />"return"</extension-point>

<extension point= >"com.tibco.example.p1.xp" this.getPlugIn()<eval> </eval></extension>


this.getExtPoint("xp").processExts().each( (rv) {function jsx3.log("Script returned: " + rv);});

In this case, the extension point contract does not specify whether or not the extending plug-inis loaded before the script is evaluated. Either the extending plug-in must be able to evaluatethe code without being loaded or the processing plug-in must load the extending plug-in beforeevaluating the script.

Type return-async

This type is the same as the return type, except that the extension elements may declare . In this case, the plug-in that declares the extension is loaded before the script isload="true"

evaluated. The processor object returns an object of type instead of the actualjsx3.$AsyncRV

value of the script, because the script may be evaluated asynchronously. Example (Descriptorfile):

<extension-point id= >"xp"<processor type= />"return-async"</extension-point>

<extension point= >"com.tibco.example.p1.xp" this.getPlugIn()<eval load= >"true" </eval></extension>


239


this.getExtPoint("xp").processExts().each( (rv) {function rv.when( (v) {function jsx3.log("Script asynchronously returned: " + v); });});

Type instantiator

The instantiator type instantiates an object of a custom class for every child element of everyextension declaration. The attribute should be the fully qualified name of ainstance-class

General Interface class. The class must define a constructor with the following signature:

function init(ext : jsx3.amp.Ext, xml : jsx3.amp.XML);

Example (Descriptor file):

<extension-point id= >"xp" <processor type="instantiator"instance-type= />"com.tibco.example.XDescriptor"</extension-point>

<extension point= >"com.tibco.example.p1.xp" <descriptor id= .../>"foo1" <descriptor id= .../>"foo2"</extension>


this.getExtPoint("xp").processExts().each( (o) {function jsx3.log("Instantiated: " + o);});

Custom Processor Types

In addition to the built-in types, you can register your own custom extension processor types touse with declarative extension processing.

To register a custom type, call the static method . Thejsx3.amp.ExtProc.addProcessorFactory

first parameter is the key. Any processor elements whose attribute matches thistype type

parameter will be handled by this custom type. The second parameter is the factoryprocessor

function. This function is called once for each processor element with a matching attribute.type

The function is passed the processor element and should return an object that implements a function.process()

jsx3.amp.ExtProc.addProcessorFactory("customType", (procXML) {function {process: (ext, xml) {return function procXML.attr("prefix") + "-" + xml.attr("id");return }}; });

Registering this custom processor type allows the following processor definition in the plug-indescriptor file:

240


<extension-point id= >"xp" <processor type= prefix= />"customType" "p"</extension-point>

When a processor is defined declaratively for an extension point in the plug-in descriptor file,the argument to the method is optional:processExts

this.getExtPoint("xp").processExts().each( (e) {function jsx3.log("Extension: " + e);});

The method returns the list of values returned by the method of theprocessExts process

processor, which was returned by the processor factory. The following extension definition

<extension point= >"com.tibco.example.p1.xp" <item id= />"001" <item id= />"002"</extension>

would log the following when the extension processing code included above executes

Extension: p-001Extension: p-002

Extending PlugIn, ExtPoint, and Ext

You can extend the AMP classes , , and and use them in the AMP metadata.PlugIn ExtPoint Ext

The following example shows how to use a custom plug-in class.

<plugin id= class= />"..." "com.tibco.example.CustomPlugIn"

The attribute is the fully-qualified name of the class constructor function. The class mustclass

be defined before the plug-in is registered, because the plug-in cannot be instantiated if theclass is not loaded. Therefore, define the class inline in the descriptor file (in a scriptplugin.xml

element) or in an early load resource of a required plug-in. This also holds for custom extensionpoint and extension classes.

You can use custom extension point and extension classes by declaring the attribute ofclass

their declarations.

<extension-point id= class= />"..." "com.tibco.example.CustomExtPoint"<extension id= class= />"..." "com.tibco.example.CustomExt"

Extending one of these classes allows you to define custom logic on instances of plug-ins,extension points, and extensions. You can use either of the following techniques; theappropriate technique depends on how you like to organize code and whether you want todefine the same methods on a single instance or on multiple instances. Use the first techniquewhen you want to define members on a single instance.

Use the , , and elements, and JavaScript resource with ="true" toscript method field eval

define fields and methods on these objects.Extend a class if you want to define the same methods on multiple instances of a plug-in,extension point, or extension.

241


AMP Applications and Built-In Extension Points

This section describes the AMP applications, extension points, and plug-ins.

Applications and Extension Points

Writing an AMP application is slightly different from writing a typical General Interfaceapplication because AMP takes over certain parts of the application life cycle. AMP itselfdefines the extension points that AMP applications use to perform actions at life cycle events.

An AMP application must enable the AMP add-in. Use the Project Settings dialog inGeneral Interface Builder.

A non-AMP General Interface application defines a default component file that the runtimeloads when the application loads. This setting is managed in the Project Settings dialog or withthe deployment parameter saved in the file. AMP applications do notobjectseturl config.xml

define a default component file. Rather, they extend the extension pointjsx3.amp.main.layout

to provide a layout. The declaration of this extension point documents its contract.



<extension point id= name= >"layout" "Main Component Extension Point"  <processor type= />"return-async"</extension>

The following example shows a possible implementation of this extension point.

<extension point= >"jsx3.amp.main.layout"

[function (parent) {<eval> var b = new jsx3.gui.Block(); b.setText( );"Hello World" parent.setChild(b); }][0] </eval></extension>

The array literal syntax ( ) is included to make sure that the script evaluates[function(){}][0]

to the function reference rather than just declaring a function in the global scope.

A non-AMP application defines an script that is executed as soon as the applicationonLoad

paints for the first time. Instead of defining such a script in the Project Settings dialog, an AMPapplication extends the extension point. The processor on this extensionjsx3.amp.main.init

point is the simple type.eval

242


<extension point= >"jsx3.amp.main.init" this.getPlugIn().onAppInit();<eval load= >"true" </eval></extension>

Standard Extension Points and Plug-Ins

AMP defines other standard extension points and plug-ins for several useful application-levelGUI controls. AMP also defines a plug-in for each optional class in the General Interfacestandard library. The names of these plug-ins are equal to the fully-qualified names of theclasses that they load. Using these plug-ins, an AMP application can completely bypass lazyclass loading, which is implemented with a synchronous (lower performing) load.

See the General Interface AMP API documentation for more information.

Extension Point: jsx3.amp.main.progress

This extension point allows application code to be notified of AMP loading progress. Forexample, an application may implement a custom load progress indicator when it first loads.An application may also provide feedback to the user when AMP is loading resources over thecourse of running the application.

Plug-In: jsx3.amp.util.menumgr

This plug-in allows a menu bar to be composed of AMP extensions. This plug-in is helpful if anapplication requires an extensible menu bars or context menus.

Plug-In: jsx3.amp.util.prefspanel

This plug-in implements an extensible preferences panel. Panes may be added to the panel viaAMP extensions.

Plug-In: jsx3.amp.util.wizard

This plug-in implements a wizard control. Wizard panes may be added to the wizard via AMPextensions.

Plug-In: jsx3.amp.util.toolbarmgr

This plug-in allows a toolbar to be composed of AMP extensions.

Optional Classes of the General Interface Standard Library

The General Interface standard library contains the following optional classes; an AMP plug-inis defined for each of these classes:

243


jsx3.app.UserSettingsjsx3.gui.Alertsjsx3.gui.Blockjsx3.gui.BlockXjsx3.gui.Buttonjsx3.gui.CheckBoxjsx3.gui.ColorPickerjsx3.gui.DatePickerjsx3.gui.Dialogjsx3.gui.Formjsx3.gui.Imagejsx3.gui.ImageButtonjsx3.gui.LayoutGridjsx3.gui.Matrixjsx3.gui.Matrix.Columnjsx3.gui.Menujsx3.gui.Paintedjsx3.gui.RadioButtonjsx3.gui.Selectjsx3.gui.Sliderjsx3.gui.Soundjsx3.gui.Splitterjsx3.gui.Stackjsx3.gui.StackGroupjsx3.gui.Tabjsx3.gui.TabbedPanejsx3.gui.Tablejsx3.gui.TextBoxjsx3.gui.TimePickerjsx3.gui.ToolbarButtonjsx3.gui.Treejsx3.gui.Windowjsx3.gui.WindowBarjsx3.net.Formjsx3.net.Servicejsx3.xml.Cacheable

Plug-ins with Extensions and Extension Points

This section describes the AMP plug-ins, extensions, and extension points.

Plug-Ins

Each AMP application comprises a set of AMP plug-ins, the functional units of an AMPapplication. As a developer, you decide how to decompose the application into its constituentplug-ins. Consider plug-ins to be application components that are either present (loaded) orabsent (unloaded). In other words, design cohesive plug-ins that contain the parts of theapplication that function together, and tie plug-ins loosely to each other.

When decomposing an application, keep in mind that an AMP application loads at thegranularity of plug-ins; by default, all parts of a plug-in are loaded together.

Plug-ins are defined with a descriptor file. Each plug-in has a unique identifier thatplugin.xml

is also the name of the directory in which the plugin.xml file is placed.

In the following example, the plug-in identifier is .com.tibco.example.p1

244


In the following example, the plug-in identifier is .com.tibco.example.p1

<plugin xmlns="http://www.tibco.com/gi/amp" =xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.tibco.com/gi/amphttp://gi.tibco.com/xsd/plugin.xsd" id="com.tibco.example.plugin" name="Example Plug-In" version= >"0.1" ...</plugin>

To register plug-ins, refer to them in the file, and place the file in the plugins.xml plugins

directory at the root of the General Interface application that uses AMP. Alternatively, you canuse the AMP API to register plug-ins programmatically. For each plug-in registered in the

file, there should be a directory in the directory with a name equal to theplugins.xml plugins

ID of the registered plug-in. Each of these directories should contain a file.plugin.xml

<plugins xmlns="http://www.tibco.com/gi/amp"=xmlns:xsi "http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation= >"http://www.tibco.com/gi/amp"<plugin id= />"com.tibco.example.p1"...</plugins>

The following figure shows the directory structure. plugins

You can locate the directory of a plug-in outside of the application's pluginsdirectory. In this case, the attribute of the element should be the relativepath plugin

path from the directory to the directory that contains the directory.plugins plugin

<plugins> <plugin id= />"com.tibco.example2.plugin"path= >"../../otherApp/plugins/"...</plugins>

245


Extension Points and Extensions

A plug-in defines extension points and extensions. An extension point is an interface or contractbetween the plug-in that defines it and any extension that extends it. The form of this contract isloosely defined in AMP itself. It is a developer decision whether the contract takes the form ofan XML schema, a JavaScript interface, or both.

An extension point is often designed to accept any number of extensions (one-to-many) but canalso be designed to accept only one extension (one-to-one) or a specified number of extensions.The cardinality is not specified declaratively; it is enforced by the JavaScript code that processesthe extensions.

An extension point is declared in a plug-in descriptor file.

<plugin id= />"com.tibco.example.p1"<extension-point id= />"example-xp"</plugin>

An extension is a concrete implementation of the extension point contract. You can define anextension in the same plug-in that defines its extension point or in another plug-in. In bothcases, the attribute of the element is the fully-qualified identifier of thepoint extension

extension point. The fully-qualified identifier is the attribute of the elementid extension-point

appended to the identifier of its plug-in and separated with a period (".").

<plugin ...>

<extension point= >"com.tibco.example.p1.example-xp"...</extension></plugin>

The extension point-extension relationship is loosely coupled and controlled by the extensionpoint. It is possible for an extension to extend an extension point that is not registered.Similarly, it is usually acceptable for an extension point to have no extensions.

Plug-in Resources and the Plug-in Life Cycle

Plug-ins comprise the descriptor file and a collection of resources, which can beplugin.xml

JavaScript, CSS, XML, XSL, or JSS properties, or properties bundles. These reside in theplug-in's directory and are referenced within the descriptor file, as in the following example.

246


1. 2.

3. a. b.

c.

4.

5.

6.

<plugin ...> <resources> <script id= path= />"js" "logic.js" <xml id= path= load= />"xml" "data.xml" "manual" ... </resources>

</plugin>

Resources can declare a load setting with the attribute, as in the example above. Theload

possible values are , (the default value), and . The load setting affects whenearly normal manual

the resource is loaded in relationship to the plug-in life cycle.

AMP plug-in life cycle follows this process:

An AMP engine is instantiated for every AMP application.The AMP engine processes plug-ins in the order that they are listed in the plugins.xmlregistry file.For each plug-in, the following apply:

Plug-in resources designated for early loading are loaded first. The plug-in is instantiated and registered. Its method is called. AtonRegister()

this point, some of the extensions to the plug-in's extension points may not beregistered. As the rest of the plug-ins are registered, the plug-in's method isonExtension()

called each time a plug-in is registered that extends one of its extension points.After all plug-ins have been registered, the AMP engine is considered to be loaded and itpublishes its event.LOAD

If and when the method is called on a plug-in, all of its normal loading resourcesload()

are loaded, after which the plug-in is considered to be loaded, and its method isonLoad()

called.After the plug-in is loaded, any manual loading resources can be loadedprogrammatically.

You can also define resources inline in the file. Instead of defining the pathplugin.xml

attribute, you can nest the file contents in a element inside the resource element. For<data>

JavaScript and CSS resources, the nested element is optional; for example, you can<data>

define a script in the text content of the element.<script>

The inline resource definition must be valid XML. Characters that are validJavaScript or CSS but invalid XML must be properly encoded. Consider using aCDATA block for better readability.

<resources><![CDATA[<script id= >"js"

this.getLog().info( );"Loaded resource js."]]></script></resources>

XML, XSL and dynamic properties resources are defined inline as a document fragment. Whendefining these resources inline, make sure that you define the correct XML namespace for thecontent. If the attribute is not specified, the document fragment will inherit the AMPxmlns

XML namespace.

247


XML namespace.

<resources> <xml id= >"info" <data> <info xmlns=""> <item id= />"1" </info> </data> </xml></resources>

Prerequisites and Load Order

Plug-ins and resources can define dependencies that enforce a load order. You must declaredependencies in order for the load order of application resources to be well-defined.

A plug-in can depend on another plug-in by declaring that it requires it in its descriptor file.When a plug-in requires another plug-in, then the required plug-in will load ( , above)step 5before the requiring plug-in. In addition, the required plug-in is instantiated before therequiring plug-in. This means that all early load resources of the required plug-in are loadedbefore the early load resources of the requiring plug-in.

<plugin id= >"com.tibco.example.p1" <requires> <plugin id= />"com.tibco.example.lib" </requires> ...</plugin>

Similarly, a resource may require that another resource be loaded before it is loaded. A resourcecan also declare that a plug-in loads before the resource. This second option is useful formanual load resources for which the plug-in does not declare the dependency. In the followingexample, the plug-in loads before and loads before com.tibco.example.lib logic.js logic.js

.SampleClass.js

<plugin id= >"com.tibco.example.p1"

<resources> <script id= path= >"js" "logic.js" <prereq plugin= />"com.tibco.example.lib" </script> <script id= path= >"SampleClass" "SampleClass.js" <prereq id= />"js" </script> </resources> ...</plugin>

Application Techniques and Utilities

This section describes techniques and utilities that AMP supports.

248


Declarative Event Subscriptions

The AMP plug-in metadata allows plug-ins to declare information about events that theypublish. It also allows plug-ins to declaratively subscribe to these events. The followingexample shows how to declare that a plug-in publishes an event.

<plugin> <event id= >"saved" <param id= type= />"value" "String" </event></plugin>

The nested elements are for documentation purposes only and are notparam

validated at runtime.

An event is published with the method of the interface,publish() jsx3.util.EventDispatcher

which is implemented by . It is up the developer to publish the eventjsx3.amp.PlugIn

programmatically in JavaScript.

CustomPlugIn.prototype.save = (strValue) {function // Perform the save .publish({subject:"saved", value:strValue});this};

Event registration can be performed declaratively as in the following example. The inner text ofthe subscribe element is taken as a script to be evaluated in the context of the plug-in thatdeclares it. The variable is defined in this context and is equal to the event object that wasevt

published.

<plugin> <subscribe event= >"com.tibco.example.p1.saved" this.getLog().info("The saved event was published withvalue: " + evt.value); </subscribe></plugin>

Instead of declaring the event subscription as a block of JavaScript code in the content of thesubscribe element, you can use the attribute to reference a method on the plug-in objecthandler

that will handle the event.

<plugin><method id= params= >"evtHandler" "evt" this.getLog().info("The saved event was published withvalue: " + evt.value);</method>

<subscribe event="com.tibco.example.plugin.saved"handler= />"evtHandler"</plugin>

249


AMP Events and the OpenAjax Hub

www.openajax.org) is an open source initiative with the goal ofThe OpenAjax Alliance (increasing interoperability among JavaScript libraries. One part of the specification is theOpenAjax hub, which is an event publishing bus. When the OpenAjax hub is loaded in a webpage containing and AMP application, AMP automatically publishes events to the bus. Allevents that are declared in the plug-in descriptor files are published to the OpenAjax hub.

Asynchronous Execution

AMP is built from the ground up around asynchronous execution. All plug-ins and theirresources are loaded asynchronously, and no synchronous APIs are provided.

Asynchronous loading performs much better than synchronous loading, especially over ahigh-latency HTTP connection. Asynchronous loads do not block the browser's UI thread,whereas synchronous loads do block the UI thread. However, asynchronous JavaScript code isusually harder to develop than synchronous code. The result has often been an unfortunatetrade-off between developer productivity and application performance.

By contrast with other development environments, AMP effectively supports asynchronousprogramming through its declarative structure. Because AMP handles the asynchronousloading of all resources and their dependencies are defined declaratively, it is not necessary towrite significant amounts of boilerplate code to load resources.

AMP also takes advantage of the powerful asynchronous idioms in General Interface. Thecenterpiece of these idioms is the function, which declares an asynchronous method.jsx3.Y()

Asynchronous methods defined using have a strict contract that helps promote uniformityY

across all asynchronous code. An example of these idioms is in the method of load()

. The following example shows how an action is performed when both jsx3.amp.Resource rsrc1

and have loaded asynchronously.rsrc2

this.getResource("rsrc1").load().and(.getResource("rsrc2").load()).when( () {this function

// Perform an action});

See the General Interface API documentation for a detailed description of the methodjsx3.Y()

and its related objects.

Packaging Resources

Decomposition into components is a powerful tool for decreasing coupling between logicalcomponents and managing application complexity. AMP makes it easy to package resourcesinto a cohesive plug-in. These resources can refer to other resources within the same plug-inwithout much boiler plate code and without reference to a global namespace.

Plug-ins, extension points, and extensions can define fields and methods and execute arbitrarycode inside the descriptor file. The elements , , and can beplugin.xml script method field

children of the , , or elements. In the following example, the plugin extension-point extension

element refers to the parent object.script this

http://www.openajax.org

250


1.

2.

<script> this.getLog().info( + this);"I am plug-in: "</script>

<method id= params= >"add" "a, b" return a + b;</method>

<field id= >"strValue" "value"</field>

By convention, is defined to be the parent object (plug-in, extension point, or extension)this

containing an XML text block that is interpreted as a script field. This convention is evident inthe script element above, the declarative event subscription mechanism and the standardextension point processors, , , and . We recommend that you follow theeval return return-async

AMP convention when you define how your own extension points interpret their extensions.

Another useful feature is the eval attribute of a script resource. When this attribute is set to true, it causes the contents of the JavaScript file to be evaluated in the context of the plug-ininstance. The following example shows how this is used in an external JavaScript file.

( (plugIn) {function plugIn.doSomething = () {function // something heredo };})( );this

Plug-Ins and GUI Components

AMP also makes it easy to refer to a plug-in from a loaded GUI component. When a componentfile is loaded with the method of a plug-in, the following occur:loadRsrcComponent()

A method is defined on the root object of the component file that returns thegetPlugIn()

plug-in on which was called.loadRsrcComponent()

The component file is loaded with the plug-in as the URI resolver. This means that allrelative paths are resolved relative to the directory of the plug-in.

The first item above makes it easy for all the code, whether defined in a JavaScript file or in the block of a component file, to refer to the plug-in that contains the code. TheonAfterDeserialize

second means that all paths contained in plug-in resources are defined relative to the plug-initself. The following example shows a component file that takes advantage of these features.

251


<serialization xmlns= >"urn:tibco.com/v3.0" <![CDATA[<onAfterDeserialize>

objJSX._onBtnClick = function() { this.getPlugIn().performAction();};

]]></onAfterDeserialize>

<object type= >"jsx3.gui.Button" <strings jsxtext= />"Click Me" <events jsxexecute= />"this._onBtnClick()" </object></serialization>

Build Tools

The source distribution of General Interface 3.8 includes build tools that specifically aid in thedeployment of high performing AMP applications.

One obvious downside of AMP applications is that application decomposition results in a largenumber of resource files. Loading a large number of files is usually much slower than loadingfewer files, even when the sum size of the files is the same. This is especially true over an HTTPconnection.

The new tools are delivered as tasks:Ant

AmpResourceMergeTask. This tool merges the resources of a plug-in into the plugin.xmldescriptor file. This process takes advantage of the fact that most types of resources canbe included inline in the descriptor file directly beneath the resource element.AmpPluginMergeTask. This tool merges plug-ins into the file. Just as resourcesplugins.xml

can be included inline in , plug-ins may be included inline in the plugin.xml plugins.xml

file.

By using these tools, you can deliver an AMP application with as few as two files, by contrastwith the large number of files that would otherwise be required.

The files are:

config.xml, the General Interface application descriptorplugins/plugins.xml, the AMP plugins file

There are potential disadvantages in loading all resources in one file, because many resourcesmay be used only in rare application use cases. For this reason, the build tools include optionsto merge a subset of the application plug-ins and resources.

252


<target name= >"mergeAmpPlugIns"  <taskdef resource= >"com/tibco/gi/ant/antlib.xml" <classpath path= />"jsx-tools.jar" </taskdef>

 <amp-rmerge ids="com.tibco.example.p1.*com.tibco.example.p2.*"> <fileset dir= >"JSXAPPS/ampApp/plugins" <include name= />"**/plugin.xml" </fileset> </amp-rmerge>

 <amp-pmerge pluginsfile= />"JSXAPPS/ampApp/plugins/plugins.xml" </target>

AMP Localization

This section describes how to localize an AMP application using localization features in AMPand in the General Interface Framework.

Resources

A plug-in can localize one of its resources by registering multiple versions of the resource, onefor each locale. The attribute registers these versions and is supported for all resourcelocales

types. It is a whitespace-separated list of locale keys, as in the following example.

<resources> <xml id= path= locales= />"data" "data.xml" "en fr de"</resources>

This resource declaration implies that the following files exist in the plug-in's directory.

data.xmldata.en.xmldata.fr.xmldata.de.xml

The locale of the AMP application determines which of the(jsx3.app.Server.getLocale())

available files is loaded. In this example, the locales and would load .en_US en data.en.xml

When no localized version of the resource is available for the locale, the default resource isloaded. In the example, the locale would load .ja data.xml

Plug-in Metadata

You can localize the plug-in descriptor file using a technique similar to that used for resources.With this technique, you can localize the metadata that is part of the extension point andextension declarations.

Localized versions of are registered with the attribute of the elementplugin.xml locales plugin

in the main file. This attribute is a whitespace-separated list of locale keys for whichplugin.xml

the file is localized. For example, the following plugin declaration:

253


1. 2.

a. b.

3.

a. b.

the file is localized. For example, the following plugin declaration:

<plugin id= locales= >"com.tibco.example" "es de"</plugin>

implies that the following files are in the plug-ins directory in addition to , theplugin.xml

contents of which are shown above:

plugin.es.xmlplugin.de.xml

By contrast with localized resources, where the entire resource is replaced with the localizedversion of the resource, the contents of the localized version of the plug-in descriptor file aremerged into the main descriptor file. This is handy because usually most of the plugin.xmlcontent does not need to be localized (such as JavaScript functions).

The following algorithm is used when merging the localized plug-in descriptor file into themain descriptor file:

Copy all attributes of the localized document element into the base file.plug-in

For each element in the localized document, search for an extension-point

element in the base file with the same value for the attribute. If thatextension-point id

element exists, do the following: Copy all attributes from the localized element into the base element. If the localized element has one or more child elements, replace all the children ofthe base element with the children of the localized element. Elements , script

, , and are not removed from the base element.method field processor

For each element in the localized document, search for an elementextension extension

in the base file with the same value for the attribute. If that element exists, do theid

following: Copy all attributes from the localized element into the base element. If the localized element has one or more child elements, replace all the children ofthe base element with the children of the localized element. Elements , script

, and are not removed from the base element.method field

There is no locale "fall through" for localized plug-in descriptor files. For example, if is localized for locales and , and the application locale is ,plugin.xml en en_US en_US

the merged file is the combination of just and . In thisplugin.en_US.xml plugin.xml

case, is not used in the merge. However, if is localizedplugin.en.xml plugin.xml

only for the locale and the application locale is , then the merged file is theen en_US

combination of and .plugin.en.xml plugin.xml

Property Bundles

For fine grained localization using string replacement and message formats, AMP offers aproperties bundle resource type.

<resources> <propsbundle id= path= />"messages" "messages.xml"</resources>

The format of is specified by the class from the Generalmessages.xml jsx3.app.PropsBundle

Interface core library.

254


Interface core library.

After this resource is loaded, the localized strings that it contains are available in the followingways:

Via the AMP API

plugIn.getResource("messages").getData().get("key")

Via the application

plugIn.getServer().getDynamicProperty("key")

Via CDF attribute conversion

<data jsxid= >"jsxroot" <record jsxid= jsxtext= />"id" "{key}"</data>

One possible application of this functionality is in a extension point contract, as in the followingextension point declaration:

<extension-point id= >"keys" </extension-point>

<extension point= >"com.tibco.example.key" <key id= />"key"</extension>

It is then up to the extension processing logic to interpret the attribute as a property key:id

var bundle = .getResource("messages").getData();this.getExtPoint("keys").processExt( (ext, xml) {this function

jsx3.log("Got key:" + xml.attr("id") + " and value:" + bundle.get(xml.attr("id")));});

For more information, see the "Internationalizing and Localizing Applications" chapter in theGeneral Interface Developer Guide.

Using the AMPsample Application

General Interface (GI) includes an optional add-in module called the Asynchronous ModularPlatform (AMP) to address some of the inherent difficulties encountered during thedevelopment of a large application. AMP provides a modular framework for GI developers tocreate application units called plug-ins which contain design components and other resources.

The intent of this guide is to examine the AMPsample application and each of its plug-inexamples and look at how they individually contribute to the overall application.

MenuManager

ToolbarManager

Wizard (via "Help :: Red Help...")

255


PrefsController (via "File :: Settings...")

jsx3.amp.main.progress extension point

AMP metadata localization

<binding> and support in MenuManager and ToolbarManager

Event publishing/subscribing

jsx3.amp.persist plug-in

The running application has a series of menus and buttons that change the color of thebackground screen. In addition, there are two dialog examples to demonstrate a multi-screen"wizard" technique of gathering information and another to set a property.

There are a set of menus and buttons on the main layout screen that are populated during theinitialization of each plug-in module. The selection of either the menu item or the button willchange the application background to a different color.

Additionally, there is a plug-in with an associated menu called "Locale" that creates the text ofeach menu item by iterating through a list of language locales to convert them to their longername. For example, the code "en" is transformed to "English".

256


In total, there are eight plug-in modules in seven directories that constitute the overallfunctionality of the application and each plug-in handles its own set of capabilities. The nextsection will begin investigating the structure of the AMPsample application.

Structure

A GI AMP project contains a directory named "plugins" and within it a descriptor file called"plugins.xml" is used to register each plug-in. An AMP engine is instantiated for every AMPapplication at runtime.

Each plug-in can be contained in its own directory structure. The name and path of thedirectory is part of the reference given in the plugins.xml file. The AMP engine processesplug-ins in the order that they are listed in the plugins.xml registry file.

As part of the registry entry, a path can be provided to reference the containing directory. Forinstance, you can use a relative path to another project with the following:

<plugin id="green" path="../../otherApp/plugins/"/>

As the AMP engine processes each of the plug-in entries, it will assume the default path isrelative to the "plugins" directory and will look for a directory with the same name as theplug-in "id" attribute. The plug-in directory will contain a file that describes the plug-incomponents and uses a default name of "plugin.xml". Note: it is also valid to bypass thereferenced file and enter the same information entirely within the plugin element. However,keeping the plugin.xml file with the rest of its resources seems like a better practice.

The format of the plugins.xml file adheres to the plugins.xsd schema located at and .http://gi.tibco.com/xsd/plugins.xsd http://www.generalinterface.org/xsd/plugins.xsd

The AMPsample plugins.xml file contains the following XML:

<plugins xmlns="http://www.tibco.com/gi/amp"

http://gi.tibco.com/xsd/plugins.xsd

http://www.generalinterface.org/xsd/plugins.xsd

257


xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.tibco.com/gi/amp ">http://gi.tibco.com/xsd/plugins.xsd

<plugin id="init">

<method id="onRegister">

var uri = jsx3.app.Browser.getLocation();

var localeId = uri.getQueryParam("locale");

if (localeId)

this.getEngine().getServer().setLocale(jsx3.util.Locale.valueOf(localeId));

</method>

</plugin>

<plugin id="main"/>

<plugin id="red"/>

<plugin id="yellow"/>

<plugin id="purple"/>

<plugin id="settings"/>

<plugin id="locale"/>

<plugin id="progress"/>

</plugins>

The first plug-in is identified by "init" and has a method available named "onRegister". Themethod's JavaScript will execute automatically after the plug-in is registered by the engine.

Each plug-in is loaded in the order that it appears in the list; therefore the second plug-in is"main". Let's take a look at the plugin.xml file associated with main.

<plugin xmlns="http://www.tibco.com/gi/amp"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://www.tibco.com/gi/amp "http://gi.tibco.com/xsd/plugin.xsd

id="main"

name="UI Plug-In"

version="0.1">

The plugin.xml descriptor file starts out with the "plugin" element name and the schema namesassociated to namespaces. The attribute "id" matches the registered plug-in entry in the

plugins.xml file and must be unique. The version attribute is arbitrary and could be used to

http://gi.tibco.com/xsd/plugins.xsd

http://gi.tibco.com/xsd/plugin.xsd

258


plugins.xml file and must be unique. The version attribute is arbitrary and could be used tocheck if the version of the plug-in supports certain capabilities for example. The id, name andversion attributes can be read programmatically using the jsx3.amp.PlugIn class API.

The next section of the plugin.xml file describes which GI classes will be required in order forthe plug-in to run properly.

<requires>

<plugin id="jsx3.gui.Block"/>

<plugin id="jsx3.amp.util.menumgr"/>

<plugin id="jsx3.amp.util.toolbarmgr"/>

</requires>

In this case, the "main" plug-in will depend on the three declared classes. The engine managesthe loading of the classes. All required plug-ins will be registered and instantiated before theplug-in is registered.

The next section of the plugin.xml file defines the resources used by the plug-in. Six resourcetypes are allowed inside the resource tags:

script – JavaScript files;

xml – XML such as CDF and WSDL files;

xsl – XSL transformation files;

css – Cascading Style Sheet;

jss – GI dynamic properties file;

propsbundle – GI language properties.

<resources>

<script id="js" path="main.js" eval="true"/>

<xml id="layout" path="layout.xml"/>

</resources>

An optional attribute can be added to a resource element to designate how the engine shouldload it. Three options are available: early, normal and manual. If the resource type is "script"and the "eval" attribute is "true", the engine will read the JavaScript and load it into memory.

The life-cycle.

<event id="colorChanged">

<param id="color" type="string"/>

</event>

Event processing.

259


Event processing.

<! >- Extension Points -

<extension-point id="menu">

<processor type="instantiator" instance-class="jsx3.amp.util.Menu"/>

</extension-point>

<extension-point id="menu-item">

<processor type="instantiator" instance-class="jsx3.amp.util.MenuItem"/>

</extension-point>

<extension-point id="toolbar">

<processor type="instantiator" instance-class="jsx3.amp.util.ToolbarItem"/>

</extension-point>

<extension-point id="content">

</extension-point>

Extension points

<! >- Extensions -

<extension point="jsx3.amp.main.layout" id="main-layout">

<eval load="true">var p = this.getPlugIn(); jsx3.$F(p.paint).bind(p)</eval>

</extension>

<extension point="main.menu" id="menus">

<menu id="file" label="File" path="/">

</menu>



<menu id="view" label="View" path="/">

</menu>

<menu id="help" label="Help" path="/">

</menu>

260


</extension>

Extensions

</plugin>

261


Chapter 21 Asynchronous Programming Utilities

This chapter describes how to use the $Y and $Z methods to create powerful asynchronousGeneral Interface programs.

About $YCalling Asynchronous FunctionsDesigning Asynchronous FunctionsUsing $ZAsynchronous AMP APIs

About $Y

$Y allows you to write concise and readable asynchronous code, providing the followingcapabilities:

A standard way to pass and handle callbacks and a standard way to send return valuesMultiple callbacks per asynchronous callCondition chainingAsynchronous method chaining via automatic parameter resolutionReturn value chaining

You can use $Y instead of the following "anti-patterns" for asynchronous JavaScriptprogramming:

1. Passing a callback function as a method parameter

2. Using publish-subscribe as an asynchronous callback

The following code examples all show an asynchronous method that loads an XMLdocument and sample code that uses the method.

The following code provides an example of anti-pattern 1:

function loadXmlAsync(url, callback) { req = XMLHttpRequest();var new

req.onreadystatechange = () {function (callback)if callback(req.responseXML); }; req.open("GET", url, ):true req.send();}

loadXmlAsync("data.xml", (doc) {function jsx3.log("Got document: " + doc);});

As shown in the example, passing a callback function works but can get messy and there is no

262


As shown in the example, passing a callback function works but can get messy and there is nostandard idiom. The following questions may arise:

Is the callback function the first method parameter or the last?Is the function required or optional?How are multiple callbacks executed?What is the signature of the callback function?How are return values handled?

The following code provides an example of anti-pattern 2:

this.loadXmlAsync = (url) {function req = XMLHttpRequest();var new req.onreadystatechange = () {function .publish({subject:"done",this doc: req.responseXML}); }; req.open("GET", url, ):true req.send();};

.subscribe("done", (evt) {this function jsx3.log("Got document: " + evt.doc);});

.loadXmlAsync("data.xml");this

The following issues may arise with anti-pattern 2:

Mandatory event subscription is verbose.It is necessary to handle event un-subscription or risk garbage collection issues.An object with an asynchronous API can be used by only one object at a time.To support synchronous completion, the subscription must come before theasynchronous call.The object that publishes the event must implement the jsx3.util.EventDispatcherinterface.The publish-subscribe pattern is designed for one-to-many, anonymous, and optionalcommunication. This example is none of these.

The following example shows how to use $Y to implement the function in the previousexamples.

263


this.loadXmlAsync = jsx3.Y( (cb) {function url = cb.args()[0];var req = XMLHttpRequest();var new req.onreadystatechange = () {function cb.done(req.responseXML); }; req.open("GET", url, ):true req.send();});

.loadXmlAsync("data.xml").when( (doc) {this function jsx3.log("Got document: " + doc);});

Calling Asynchronous Functions

The function returned by $Y (the wrapping function) meets the following requirements:

It always returns an instance of .jsx3.$AsyncRV

It can take any of a number of parameters. Consult the API documentation of thefunction for the expected parameters.

A Simple Example

Any function passed to the method of is called when the asynchronouswhen() jsx3.$AsyncRV

method is done.

The function is passed a single parameter, which is the asynchronous return value of theasynchronous function, as in the following example:

var rv = loadXmlAsync("data.xml");rv.when( (doc) {function jsx3.log("The asynchronous value is: " + doc);return});

Multiple Callbacks

A program can call any number of times before or after the asynchronous methodwhen()

finishes. Regardless of when it is called, all callbacks are invoked. For example:

var rv = loadXmlAsync("data.xml");rv.when( (doc) {function jsx3.log("Got document: " + doc);});rv.when( (doc) {function doSomethingElse(doc);});

Condition Chaining

Use the and methods of to chain asynchronous return conditions.and() or() jsx3.$AsyncRV

Both methods also return instances of . For example:jsx3.$AsyncRV

264


var rv1 = loadXmlAsync("data1.xml"); rv2 = loadXmlAsync("data2.xml");var

rv1.and(rv2).when( () {function jsx3.log("Got docs: " + rv1.rv() + " and " + rv2.rv());});

Automatic Parameter Resolution

If an instance of is passed as a parameter to an asynchronous function, thejsx3.$AsyncRV

function automatically waits for the parameter to be available before calling the wrappedfunction.

This can eliminate a call to and an anonymous function, thereby improving codewhen()

readability and conciseness.

var getURL = jsx3.Y( (cb) {function cb.done("data.xml");});

asyncURL = getURL();varloadXmlAsync(asyncURL).when( (doc) {function jsx3.log("Got document: " + doc + " from URL " + asyncURL.rv());});

The previous code is equivalent to but more concise than the following code.

var getURL = jsx3.Y( (cb) {function cb.done("data.xml");});

asyncURL = getURL();varasyncURL.when( (url) {function loadXmlAsync(url).when( (doc) {function jsx3.log("Got document: " + doc + " from URL " + url); });});

Designing Asynchronous Functions

The function passed to $Y (the wrapped function) must take exactly one parameter, , which iscb

an instance of . The function must synchronously or asynchronously call the jsx3.$AsyncCB

method once on . The parameter sent to is the asynchronous return value.done() cb cb.done()

In most cases, the synchronous return value (the argument of the return statement) of thefunction is ignored.

Declare a method to be asynchronous with $Y when it performs an asynchronous operationand needs to communicate its completion to client code. Keep in mind that there are only a fewtypes of asynchronous operations in JavaScript:

Loading a JavaScript file or using ( )XMLHttpRequest jsx3.net.Request

Waiting for user input

265


window.setTimeout/jsx3.sleep

Other Y functions

Method Parameters

You can call the wrapping function with any parameters.

Because the wrapped function takes exactly one parameter, , the parameters passed to thecb

wrapping function are accessible via . For example:cb.args()

var asyncFct = jsx3.Y( (cb) {function jsx3.log("asyncFct called args " + cb.args());with cb.done();});

Return Value

You can define an asynchronous return value by passing it to .cb.done()

The return value is passed to any callback registered with . It is also retrievable via the when()

method of . For example:rv() jsx3.$AsyncRV

var asyncFct = jsx3.Y( (cb) {function cb.done("Hello World");});

// Logs "Hello World"asyncFct().when( (rv) { jsx3.log(rv); });function

Return Value Chaining

An asynchronous function can return a local instance of produced by a call tojsx3.$AsyncRV

another asynchronous function. This can eliminate the need for a call to and anwhen()

anonymous function. For example:

var asyncFct = jsx3.Y( (cb) {function loadXmlAsync(cb.args()[0]);return});

asyncFct("data1.xml").when( (doc) {function jsx3.log("Got document " + doc);});

The previous code is a more concise form of the following:

var asyncFct = jsx3.Y( (cb) {function loadXmlAsync(cb.args()[0]).when( (doc) {function cb.done(doc); });});

asyncFct("data1.xml").when( (doc) {function jsx3.log("Got document " + doc);});

266


Putting It All Together

Parameter resolution and return value chaining allow you to write asynchronous methods thatlook just like synchronous methods, thereby improving readability and usability.

var mergeTwoURLs = jsx3.Y( (cb) {function args = cb.args();var url1 = args[0], url2 = args[1];var doc1 = loadXmlAsync(url1),var doc2 = loadXmlAsync(url2); merge(doc1, doc2);return});

merge = jsx3.Y(...);var

In an application in which many business logic functions depend on asynchronous primitives,$Y allows you to make these functions asynchronous without requiring extensive boilerplatecode.

You cannot use variables of type with control statements, such as .jsx3.$AsyncRV if

However, parameter resolution allows you to use parameters with controlstatements. As a workaround, you can pass such variables to another function.

Using $Z

$Z is another useful utility method that is similar to $Y. Like $Y, it returns a wrapping functionthat conforms to the contract of an asynchronous function. (The wrapping function alwaysreturns an instance of .) Unlike $Y, $Z enforces no contract on the wrappedjsx3.$AsyncRV

function. allows you to use automatic parameter resolution and return value chainingjsx3.Z

with normal, synchronous functions, as in the following example:

function add(a, b) { a + b; }return

firstArg = jsx3.Y( (cb) {var function cb.done(cb.args()[0]);});

one = firstArg(1), two = firstArg(2);varjsx3.Z(add)(one, two).when( (rv) {function jsx3.log("1 + 2 = " + rv);});

Asynchronous AMP APIs

The following public APIs in AMP are asynchronous functions:

In Engine: register()In PlugIn: load(), loaded()

In Resource: load(), loaded()

267


In Resource: load(), loaded()

For more information on AMP, see .Asynchronous Modular Platform

268


Chapter 22 Using the Test Recorder

This chapter describes the test recorder and how it works.

About the General Interface Test RecorderHow the Test Recorder WorksLaunching the Test RecorderTest Recorder Recording InterfaceRecording an ApplicationWorking with the Test Case TableAbout the GIPP Test Recording Resource FileRecording GITAK Test CasesDesigning Recordable Controls

About the General Interface Test Recorder

The General Interface Test Recorder is a utility included with General Interface Builder thatrecords user interactions with an application as a replayable test case. The recordings allow youto generate General Interface Performance Profiler (GIPP) or General Interface Test AutomationKit (GITAK) test cases simply by interacting with your application instead of coding test casesby hand.

By simplifying test case development, the Test Recorder dramatically reduces the barriers tocreating comprehensive test suites for your General Interface applications.

How the Test Recorder Works

The Test Recorder listens for GI level events, called model events, and records any that have thepotential to change the state of the application. When a recording is played back, theapplication state is updated as if a user were interacting directly with the application.

There are two types of events that may change the state of the application:

An event with a registered event handler. Because the event handler typically callsapplication logic, it can cause the state of the application to change. Event handlers areset in the .Events Editor palette in General Interface Builder

Specific events known by the system to change the state of the application. These include on Tab, on Select, and others that cause the display or value of a GUIjsxshow jsxselect

control to change. These are recorded because they change the state of the application,even if nothing is listening for them. By contrast, an execute event, such as a ,mouseover

does not change the state of the application and is not recorded, unless custom logic isadded.

For information on how to design custom GUI controls that are compatible with the TestRecorder see .Designing Recordable Controls

By restricting the recorded events to those that are important to the functional behavior of the

application, the Test Reorder helps you construct useful test cases with a minimum of

http://www.generalinterface.org/docs/display/GIDOCS/Specifying+Model+Events

269


1. 2.

3.

application, the Test Reorder helps you construct useful test cases with a minimum ofextraneous noise.

Launching the Test Recorder

If you are using Internet Explorer, make sure that Allow Active Content to Run in is selected before launching the Test Recorder. The setting isFiles on My Computer

in the Advanced section of .Tools > Internet Options

To open the Test Recorder, perform the following steps:

Open General Interface Builder.Choose or to open aFile > New > GIPP Test Cases File > New > GITAK Test Casesnew GIPP or GITAK test case. To open an existing test case, choose from the File menu.A new component tab opens to display the Test Recorder test case table.

Click the button to open the Test Recorder recording interface.Launch Recorder

Before launching the Test Recorder, make sure that your browser openspages in a new window instead of a new browser tab. This allows you tosee what is occurring in General Interface Builder while you interact withthe Test Recorder.

Test Recorder Recording Interface

The Test Recorder interface consists of two main areas:

Recorder area at the top.Application area, which displays the live application.

The next figure shows an example. The recorder buttons are at the top, and the main body ofthe window shows a sample address validation application.

270


1.

The recorder interface includes the following buttons and controls.

Item Description

Assert button Modal button that captures assertion conditions.

Wait button Modal button that captures wait conditions.

Pause icon

Resume icon

Icons that toggle between Pause and Resume. Pause stops recordingapplication interactions until the Resume button is clicked.

Stop icon Stops the recording process and closes the recorder

Recording an Application

As you interact with your application, the Test Recorder records the interactions and displaysthem in the test case table from which you started the Test Recorder.

The process works as follows for the sample zip code application. This sample is available inthe samples that ship with General Interface. To open the sample project, choose Project > User

.Projects > samples > WSDL_Mapping_1

Enter a zip code, and a change event is recorded with the target object . The change#zip

event is added as a row in the test case table tab from which you launched the TestRecorder. The event action is , and the target is . The Test Recorder alsojsxchange #zip

records event metadata, shown in the Value column, which allows the Test Recorder toplay back the event.

271


1.

2.

3.

Click , and a new event is added to the test case table. The eventFind City and Stateaction is , and the target is . jsxexecute #lookupButton

Another event is added when you dismiss the pop-up success message.

272


3.

4. To verify that the application is working, click the button. This puts the recorder inWait"wait" mode. The next click on the application will generate a wait test case instead ofrecording a model event. The recorder automatically picks what it determines to be themost appropriate command. You can change the command later, if needed, in the testcase table. As shown in the next figure, clicking on a text box generates a jsxwait_valueevent.

273


4.

5.

6.

In the sample zip code application, the target it and the value is "San Francisco."#city

This means that when the action is replayed by GIPP or GITAK, it will wait until thevalue of equals "San Francisco." #city

When constructing test cases, it is best to interact with the application and then do asingle or operation. For a list of wait actions, see wait assert Working with the Test Case

. TableWhen the recording is complete, you can go to the test case table and makemodifications. In general, the recorder makes a best guess as to your intentions;however, because many interactions have multiple interpretations, you may need tomanually edit some entries. For example, the next figure shows the result when the button was clicked twiceWaitduring recording. By returning to the test case table, you can delete the second instanceof the event. wait

To keep the generated test cases, save the test case table. GIPP test cases require a .jsextension and GITAK test cases require an extension..html

After saving the recorded file, you can run the test case by launching it in GIPP orGITAK. Before doing so, make sure that GIPP and GITAK are configured. To do so,choose Click and specify the appropriateTools > IDE Settings. GIPP & GITAKinstallation directory.

274


6.

7. installation directory.Click the or button in the builder window.Launch GIPP Launch GITAK

Clicking the button launches only the current file. To runLaunch in GIPPGIPP with all of the available test cases, choose Project > Run Project in

.GIPP

Working with the Test Case Table

The test case table contains the following columns:

ID/Label---GIPP only, optional. The ID distinguishes between test cases; there can beonly one ID assigned within a test case. (If you do not assign an ID, the Test Recorderautomatically assigns the value .) This column is not included in the GITAK version of1

the test case table, because GITAK supports only one test case per test case table.Action---Drop-down list of built-in actions. Note that when you record an or assert wait

action while interacting with your application, the Test Recorder tries to automaticallydetermine the best action to take. You can change any automatically chosen actions byselecting another value from the drop-down list.

GIPP Actions

275


GITAK Actions

Target---Unique address for the GI object to which the action applies. The Test Recorderautomatically resolves name collisions to assign a unique address. The syntax of thisaddress is defined by the method. For morejsx.app.Model.selectDescendents()

information, refer to the API documents available at .http://www.generalinterface.org/docs/display/DOC/Learning+Center

Value---Argument or value of the action. Allowed values are determined by the actiontype. Examples may include a text value or or for a check box field. For model events,0 1

the value consists of metadata that was part of the event and object. The metadata is theschema of the model event object and includes the attributes that are necessary for thereplay action. To record properly, it is necessary to know not only that there is a change,but what the change is. The schema in the value column can also include a previousvalue that is saved for possible future use.

Test Case Table Operations

In addition to adding events by interacting with the application as a user, you can interactdirectly with the test case table.

To add an event, click . Choose the action from the drop-down list andInsert a Row

http://www.generalinterface.org/docs/display/DOC/Learning+Center

276


To add an event, click . Choose the action from the drop-down list andInsert a Rowspecify the target.To edit an event, highlight the row and make changes as needed.To reorder rows, select them and drag from the leftmost column.To delete an event, highlight the event and click the icon on the right.Delete

For , deleting the extra event and events in the zip code examplejsxexecute jsxwait_value

results in a simplified three-event test case, as shown in the next figure. The test case consists ofthe following events:

Entering the zip code.Clicking the button.Waiting for the value "San Francisco" to be returned.

Multiple Test Cases (GIPP Only)

Each test case in the GIPP test case table consists of a series of one or more actions with a heavyblack link below the last action.

A GIPP test case is terminated by any row that:

Contains a action. There can be only one action per test case.wait wait

Defines a value for ID/Label.

As you set or clear a value in the ID/Label column or toggle an entry in the Action columnbetween a and other action, you can see the thick blank line that delineates the test casewait

appear in the appropriate place.

About the GIPP Test Recording Resource File

The next figure shows an example of a GIPP resource file..js

277


The JavaScript code that defines the recorded events is located between the lines

/* BEGIN GIPP RECORDER */

and

/* END GIPP RECORDER */

The last line in the file invokes GIPP on the data structure, and must not be moved or removed.

Below the link , you can optionally add documented GIPP methods.Insert manual tests here

For example, the next figure shows the addition of a new test case, , after the testmanual1 test1

case.

The manual test case does not appear in the table in General Interface Builder, but it is includedwhen the cases are actually run. For example, the next figure shows how the manual test caseappears in GIPP.

278


Recording GITAK Test Cases

Operation of the Test Recorder in GITAK is similar to GIPP operation, except for the following:

The resource file requires a extension..html

To launch the Test Recorder in GITAK, click .Launch in GITAKGITAK considers the whole table to be a single test case.There is no ID/Label column.

When you click , GITAK opens with the test case displayed. The testLaunch in GITAKsuite is generated automatically to run from Builder. The purpose of the Test Recorder isto help you construct the test case. Note that the and actions are not listed.wait assert

279


Editing the GITAK Events Table

The GITAK Test Recorder helps you to create a bootstrap version of your test cases; however, itwill not help in every situation. To check below the level of GITAK abstraction you mustmanually insert additional commands (for example, for browser level events). In general, thetest recorder is good for bootstrapping, but some manual steps are generally required.

Designing Recordable Controls

This section describes how to design a custom GUI control to be compatible with the TestRecorder and GIPP and GITAK playback. A custom GUI control is typically a subclass of

with functionality that is not part of the standard GI library of controls.jsx3.gui.Block

Model Events

The custom control must use General Interface model events in the following ways:

A model event must be published after any user interaction that changes the state of thecontrol. This type of published event must define the event property and set it to_gipp

be equal to .1All events that the control publishes and which may have an arbitrary number ofsubscriptions must be published as a model event.

A model event is published with the method .jsx3.gui.Interactive.doEvent()

The following example shows a method that is called when the user clicks on a hypotheticalcontrol.

ClickCounter.prototype._ebClick = function(evt, elm) { ( .value == ) .value = 0;if this null this

newValue = .value++;var this veto = .doEvent( , {oldVal: .value, newVal:newValue});var this "click" this

(veto !== ) {if false .value = newValue;this .doEvent( , {newVal:newValue, _gipp:1});this "change" }}

The first published model event, , allows the event handler to veto the change in valueclick

that occurs by default when the user clicks on the control. It does not necessarily indicate a

280


that occurs by default when the user clicks on the control. It does not necessarily indicate achange in value of the control, so it does not define the property._gipp

The second published model event, , indicates that the control state did change, so itchange

defines the property. This ensures that the event is recorded by the Test Recorder even if_gipp

no event handlers are registered for the event.change

Playback

The custom control must include code that replays the recorded events and changes its ownstate as if the event were caused by a real user interaction. This code is invoked by GIPP orGITAK during test replay.

To replay the recorded event, implement a method in the control's class, as inreplayEvent()

the following example.

ClickCounter.prototype.replayEvent = function(objEvent) { (objEvent.subject == ) {if "change" // handle the change event by changing the control value

.value = objEvent.newVal;this .doEvent(objEvent.subject, objEvent);this } {else // handle click and other events that don't affect the control state

.doEvent(objEvent.subject, objEvent);this }}

In this example, the replay logic sets the value of the control to the value of the eventnewVal

property, which was set in the first code example when the event was published.change

Typically, this method also calls in case there are any subscriptions on the event.doEvent()

In this case, the event property is necessary to replay the event properly. Without thisnewVal

property, the change in application state that occurs when the event is recorded can not beapplied when the event is replayed. There must be similar cooperation between the code thatpublishes an event (with ) and the code in that replays the event._gipp:1 replayEvent()

281


Appendix A General Interface Builder Menus, Toolbars,Dialogs, and Tools

This appendix describes General Interface Builder menu and toolbar commands, as well as fielddescriptions for dialogs and tools.

For an overview of the General Interface Builder user interface, see General Interface GettingStarted and .General Interface Builder Basics

Menu CommandsToolbar CommandsDialog Field DescriptionsTool Field Descriptions

Menu Commands

This section describes General Interface Builder menu commands.

Project Menu

The Project menu includes the following commands.

Command Description

New Project Displays a prompt to create a new project and opens the new project in thesame browser window. A default project directory structure is also created onthe file system.

RecentProjects

Displays a list of the last ten projects that were opened. Clicking a project nameopens the project.

UserProjects

Displays a list of all projects in the folder. Clicking a project/JSXAPPSworkspace

name opens the project.

ProjectSettings

Displays the Project Settings dialog for configuring project deployment,add-ins, class path, and legacy settings for the open project.

DeploymentUtility

Displays the Deployment Utility which is used to generate code for deployingthe application in a browser. Create an HTML or XHTML launch page forstandalone applications or generate HTML code to insert applications into anexisting web page.

Run Project Runs the current project configuration in a new browser window to simulatethe runtime environment. The project runs in the same mode as GeneralInterface Builder, such as HTML or XHTML.

Run Projectfrom HTTP

Runs the project in a new browser window on an HTTP web server as specifiedon the Paths panel of the IDE Settings dialog. If the HTTP server isn'tconfigured, you are prompted to configure it.

282


File Menu

The File menu includes the following commands.

Command SubmenuCommand

Description (Sheet 1 of 3)

New Creates a new, empty tab in the work area for the selected file type.

GUIComponent

Creates an empty GUI component file. Save with the .xml extensionin the directory of the project.components

XMLDocument

Creates an empty XML file for content data, such as default values,for the application. Save with the .xml extension in the xmldirectory of the project.

XSLDocument

Creates an empty XSL file for transforming XML files containingapplication data. Save with the .xsl extension in the directory ofxsl

the project.

JavaScriptFile

Creates an empty JavaScript file. Save with a .js extension in the jsdirectory of the project.

CSS File Creates an empty CSS file for defining application styles. Save witha .css extension in the directory of the project.css

DynamicPropertiesFile

Creates an empty dynamic properties resource file. Save with the.xml extension in the directory of the project. See jss Dynamic

.Properties Files

PropertiesBundle

Creates a properties bundle file which contains a set of dynamicproperties localized for one or more locales. See Internationalizing

.and Localizing Applications

MappingRule

Creates an empty mapping rules file for connecting to web services.Save with the .xml extension in the directory of the project.rules

See .Mapping GUI Components to Mapping Rules

Open Displays the File dialog for opening an existing file for use in theapplication.

RecentFiles

Displays a list of recently created files. Clicking a file name opensthat file in the project.

Close Closes the active tab. If the file contains unsaved changes, you areprompted to save the file.

Close All Closes tabs for all open files. If a file contains unsaved changes, youare prompted to save the file.

Revert Displays a Confirm Revert dialog where you can choose to revertthe active file to the last saved state. After reloading, any recycledobjects are cleared from the Recycle Bin and cannot be recovered.

Revert All Displays a Confirm Revert dialog where you can choose to revertall open files to the last saved state. After reloading, any recycledobjects are cleared from the Recycle Bin and cannot be recovered.

283


Save Saves the active file.

Save toCache

For an XML cache document, saves the active file to thein-memory, local data cache.

Save andReload

Saves the active file to disk and reloads the file appropriate to thefile type. For example, JavaScript files (.js) are reloaded into thebrowser memory space to reflect the updated code. Afterreloading, any recycled objects are cleared from the Recycle Binand cannot be recovered. This menu isn't available for open datacache files.

Save As Saves the active file with a different file name.

Save aCopy toDisk

For an XML cache document, opens the Save File dialog where youcan enter a new file name and save the file to disk.

Save All Saves all open files in the project.

Tools Menu

The Tools menu includes the following tools.

Command Description

XML/XSLMerge Tool

Displays the XML/XSL Merge Tool, which displays the results of applyingan XSLT document. You can open multiple instances of this tool. See

.XML/XSL Merge Tool

XML MappingUtility

Displays the XML Mapping Utility, which is used to map WSDL, Schema,and XML documents to application objects. See Communicating with Data

.Services

Color Picker Displays the Color Picker Tool for choosing color values. See Color Picker.Tool

JavaScriptConsole

Displays the JavaScript Console for executing and debugging JavaScriptcode. See .The JavaScript Console

Find andReplace

Displays a search dialog for searching and replacing text in open text files.

GeneralInterface TestAutomation Kit

Links to the download site for General Interface Automation Kit, whichyou can use to test your General Interface applications.

IDE Settings Displays a dialog for setting preferences for the visual authoringenvironment, such as IDE settings, IDE hot keys, and paths. See

.Customizing the IDE

Palettes Menu

The Palettes menu includes the following palettes. Each of these palettes has a context menu.See .Palette Context Menus

For more information on palettes, see .Using Palettes

284


For more information on palettes, see .Using Palettes

Command Description KeyboardShortcut

ComponentHierarchy

Displays or hides the Component Hierarchy palette. Ctrl+1

PropertiesEditor

Displays or hides the Properties Editor palette. Ctrl+2

EventsEditor

Displays or hides the Events Editor palette. Ctrl+3

AttributesEditor

Displays or hides the Attributes Editor palette. Ctrl+4

XSLParameters

Displays or hides the XSL Parameters palette. Ctrl+5

ComponentLibraries

Displays or hides the Component Libraries palette. Ctrl+6

Local DataCache

Displays or hides the Local Data Cache palette. Ctrl+7

ProjectFiles

Displays or hides the Project Files palette. Ctrl+8

Recycle Bin Displays or hides the Recycle Bin palette. Objects that have beendeleted using the Component Hierarchy palette can be recoveredfrom the Recycle Bin.

Ctrl+9

System Log Displays or hides the System Log palette. Ctrl+l(lowercaseL)

Help Menu

The Help menu includes the following commands.

Command Description

Online UserGuides

Opens the General Interface documentation page in a new browser window.

APIDocumentation

Provides access to General Interface API Reference. You can view the APIdocumentation in a dialog, a separate window, or the HTML version in abrowser window. Also provides access to these additional references:

General Interface GUI Property ReferenceGeneral Interface GUI Event ReferenceGeneral Interface XSL Parameter Reference

Getting Started Provides a link to the Learning Center home page, which contains links todocumentation, API reference, utility, samples, and other information.

285


SearchDiscussionForums

Opens a search window to allow you to find forum topics.

Open SourceProject

Provides a link to General Interface Open Source Project, which providesaccess to General Interface source code, public bug tracking, release builds,and developer forums.

Bug andEnhancementTracking

Opens the JIRA bug tracking window

About GeneralInterface

Provides version information for General Interface and General InterfaceBuilder, as well as important legal notices.

LicenseAgreement

Displays the License Agreement for the product.

WelcomeScreen

Launches the Welcome screen. See .Welcome Screen

Check forUpdates

Checks for updates to General Interface.

Context Menus

To access a context menu, right-click an area of the user interface or right-click an object in apalette, such as a file name in the Project Files palette. Press the Escape or Left Arrow keys toclose the menu.

Palette Context Menus

This section describes the context menu for each palette.

Attributes Editor Palette Context Menu

To access the context menu in the Attributes Editor palette, right-click a cell in the Name orValue column.

Command Description

Remove Attribute Removes the selected attribute.

Component Hierarchy Palette Context Menu

To access the context menu in the Component Hierarchy palette, right-click a node in the DOMtree. When multiple components are selected using Ctrl+click or Shift+click, the menucommand is executed on all selected components.


Description

Clone Creates an exact copy of the selected object(s) and any children.The new object is added as the last child of the selected object'sparent object.

286


Repaint Repaints the Live Component view in the work area to reflectchanges.

Re-FetchData andRepaint

Refreshes the data in the cache and repaints the LiveComponent view in the work area. Available for objects thatimplement .jsx3.xml.Cacheable

Persistence Transitory Sets the selected component(s) to transitory. When thecomponent file is saved, the transitory object isn't saved to disk.

Embedded Embeds the selected component(s). When the component file issaved, the embedded object is saved to disk. By default,components from the Component Libraries palette areembedded.

Referenced Sets the selected component(s) to a reference. A referencedcomponent is a link to a component file. For example, <includesrc="workspace_/prototypes/greenbutton.xml"

. The name of a referenced component in theasync="false"/>

Component Hierarchy palette is displayed using blue italic font.

Referenced -Asynchronous

Sets the selected component(s) to an asynchronous reference. Anasynchronous referenced component is a link to a componentfile that loads asynchronously. For example, <includesrc="workspace_/prototypes/greenbutton.xml"

. The name of a referenced component in theasync="true"/>

Component Hierarchy palette is displayed using green italicfont.

Import Embedded Imports a copy of a component. When saved, the component issaved to disk.

Referenced Imports a link to a component file, not the actual contents of thecomponent. For example, <includesrc="workspace/_prototypes/greenbutton.xml"

. The name of a referenced component in theasync="false"/>

Component Hierarchy palette is displayed using blue italic font.

Referenced -Asynchronous

Imports a link to a component file asynchronously. For example,<include src="workspace_/prototypes/greenbutton.xml"

. The name of a referenced component in theasync="true"/>

Component Hierarchy palette is displayed using green italicfont.

Export As XML Exports the selected General Interface DOM branch as an XMLfile, which can then be used in other projects.

As HTML Exports the selected DOM branch as an HTML file. This isuseful for testing and printing.

Recycle Moves the selected object(s) to the Recycle Bin. There is aseparate Recycle Bin for each GUI component file.

CopyName toClipboard

Copies the object(s) name to the clipboard.

287


CopyGetterCode toClipboard

Copies the Getter code for the object(s) to the clipboard. Forexample, .myAddressLookup.getJSXByName("block")

Component Libraries Palette Context Menu

To access the context menu in the Component Libraries palette, expand a components folderand right-click a component.

Command Description

Copy Path Copies the path of the selected component to the clipboard. For example, thepath for the Dialog component would be

.GI_Builder/prototypes/Containers/Dialog.xml

Events Editor Palette Context Menu

To access the context menu in the Events Editor palette, right-click a cell in the Value column.

Command Description

Reset/Clear Clears the value field of the selected row.

Local Data Cache Palette Context Menu

To access the context menu in the Local Data Cache palette, right-click a node in the tree.

Command Description

View/Edit Opens the selected cache document in the work area.

View Markup Opens the selected document in the work area as a read-only, formattedfile.

Copy Name Copies the name of the document to the clipboard.

Copy Source Copies the selected document's source to the clipboard.

Remove fromCache

Removes and deletes the selected document from the in-memory cache.

Project Files Palette Context Menu

To access the context menu in the Project Files palette, right-click a file.

Command Description

Edit Opens the selected file in the work area for editing.

Edit Profile Displays the File Profile dialog where you can modify the file ID, file type, fileURI, and whether the file auto loads or not. See .File Profile Dialog

Auto Load Sets the selected file(s) to auto load when the application runs.

Dereference Dereferences the selected file and removes it from the project. The file isn'tdeleted from disk.

288


Load/Reload Loads or reloads selected files from disk into browser memory.

Copy Path Copies the file path to the clipboard. For example, .js/logic.js

XSL Parameters Palette Context Menu

To access the context menu in the XSL Parameters palette, right-click a cell in the Name orValue column.

Command Description

Remove Parameter Removes the selected parameter.

Work Area Context Menus

The work area context menus include menus for the work area tabs and the work area editors.

Work Area Tabs Context Menu

The tabs at the top of the work area have a context menu. To access the context menu,right-click a tab at the top of the work area.

Command Description

Close Closes the selected file.

Revert Revert to the previously saved version of the file.

Save Saves the file.

Save toCache

For a cache document, saves it to the cache.

Save andReload

Saves the active file to disk and reloads the file appropriate to the file type. Forexample, JavaScript files (.js) are reloaded into the browser memory space toreflect the updated code. After reloading, any recycled objects are cleared fromthe Recycle Bin and cannot be recovered. This menu isn't available for open datacache files.

Save aCopy toDisk

For a cache document, displays the Save File dialog where you can save the fileto disk.

Save As Displays the Save File dialog where you can save the file with a different nameand to a different location.

If a file is read-only, a Lock icon displays on the work area tab. To open a locked,read-only file, double-click the Lock icon.

Work Area Editors Context Menus

For text and XML files, there is a context menu in the work area. For more information oneditors, see .Work Area Editors

Command Description

289


Wrap Text Wraps the text in the work area so all of the text is visible without horizontalscrolling.

UnwrapText

Displays the text without any wrap.

Dynamic Properties Editor Context Menu

The Dynamic Properties editor has a context menu. To invoke the menu, right-click a cell or thetable header. For more information, see .Dynamic Properties Files

Command Description

Insert New Record Inserts a new record in the table.

Properties Bundle Editor Context Menu

The Properties Bundle editor has a context menu. To invoke the menu, right-click the tableheader. For more information, see .Internationalizing and Localizing Applications

Command Description

Add NewLocale

Launches the Add Local dialog where you enter a locale key, such as en_US ores_ES (Spanish). After the key is entered, a new locale column displays in thetable in the Properties Bundle editor. For more on language and country codes,see .Locale Keys

DeleteLocale

Deletes the selected locale column.

Taskbar Context Menu

To access the taskbar context menu, right-click the project name link at the bottom left of theGeneral Interface Builder user interface.

Command Description

CopyNamespaceto Clipboard

Copies the project namespace to the clipboard.

Copy Path toClipboard

Copies the project path to the clipboard. For example, workspace./JSXAPPS/myAddressLookup

ProjectSettings

Displays the Project Settings dialog where you can modify project settings,such as deployment, add-ins, class path, and legacy settings. See Project

.Settings Dialog

Run Project Runs the project in a new browser window.

XML Mapping Utility Context Menu

The XML Mapping Utility has a context menu in the Rules Tree panel. For more information onthe XML Mapping Utility, see .Communicating with Data Services

290


Rules Tree Panel Context Menu

The Rules Tree panel context menu has the following commands.


Description

Add NewRule

Adds a new rule to the selected rule.

Element Adds a new element rule to the selected rule.

Attribute Adds a new attribute rule to the selected rule. Attributes associatename-value pairs with elements.

CDATA Adds a new CDATA rule to the selected rule. Text in a CDATAsection is ignored by the XML parser. CDATA sections begin withthe string .<!CDATA( and end with the string]>

Clone Clones a selected node in the rules tree, including its descendantcontent.

Reparse Reparses the deleted children of a selected rule. Displays theReparse Selected Branch dialog. Click Reparse to reparse theselected rule. Note that reparsing removes any existing descendantsrules of the selected rule.

SampleMessage

Displays a sample input message for the selected request rule and asample output message for the selected response rule.

Execute(QuickTest)

Runs a test on the selected operation rule in the rules tree.

Toolbar Commands

This section describes General Interface Builder toolbar commands.

Work Area Toolbar

The work area provides several views of the open file. These views are available from the workarea toolbar to the lower right of the work area.

For more information, see .Work Area View Support

Button Description

Displays the active file in Live Component view. This view is available for GUIcomponents and dynamic properties files.

Displays the active file in Source XML/Source Text view. This view is available for allfile types.

291


Displays the active file in Formatted Source XML view. This view is read-only and isavailable for XML, XSL, dynamic properties, and GUI component files.

Displays the active file in Rendered HTML view. This view is read-only and isavailable only for GUI components.

Displays the active file in Component Profile view. This view is available only forGUI components.

Attributes Editor Palette Toolbar

The Attributes Editor palette toolbar has the following buttons:

Button Description

Controls docking options for the palette, which include the following:

Fixed Positions the palette in the selected quadrant.Floating Floats the palette, which can be moved and minimized.Close Closes the palette.

Adds the specified name-value pair to the component definition as an HTMLattribute and value. Type values in the Name and Value fields and click the Addbutton to add the attribute. The addition is visible in the component definition(Source XML view) and in the Rendered HTML view in the work area. For example,

.<properties mycolor="red"/>

Press the key to navigate the Attributes Editor palette fields.Enter

Component Hierarchy Palette Toolbar

The Component Hierarchy palette toolbar has the following buttons:

Button Description



Creates an exact copy of the selected object and any children. The new object isadded as the last child of the parent of the selected object.

Repaints the Live Component view of the selected object in the work area to reflectchanges.

Refreshes the data in the cache and repaints the Live Component view in the workarea. Available for objects that implement .jsx3.xml.Cacheable

292


Moves the selected object and its children, if any, to the Recycle Bin. There is aseparate Recycle Bin for each GUI component file.

Shows or hides the focus rectangle in the work area. Most GUI objects can beselected in the work area using Ctrl+click. This button is off by default, because it caninterfere with interactions and events of the selected object's children.

Toggle snap-to-grid behavior for objects in the work area.

Synchronizes the Component Hierarchy palette with the current version of thehierarchy on disk.

Component Libraries Palette Toolbar

The Component Libraries palette toolbar has the following buttons:

Button Description



Synchronizes the Component Libraries palette with the current version of thelibraries on disk.

Local Data Cache Palette Toolbar

The Local Data Cache palette toolbar has the following buttons:

Button Description



Opens the selected file in a tab in the work area, where it can be edited.

Opens the selected file in the Formatted Source XML view.

Removes the selected file from cache.

Project Files Palette Toolbar

The Project Files palette toolbar has the following buttons:

Button Description

293




Creates a new tab in the work area for the selected file type.

Displays the Open File dialog for adding an existing file to the project. Also opensthe file in a tab in the work area.

Opens the selected file in the project in a tab in the work area.

Opens the File Profile dialog, where you can edit file ID, type, Auto Load, and URIvalues for the selected file. See .File Profile Dialog

Removes the selected file from the project. The file isn't deleted from disk.

Loads or reloads selected file(s) in the work area.

Rescans project files from disk.

Recycle Bin Palette Toolbar

The Recycle Bin palette toolbar has the following buttons:

Button Description

Restores the selected recycled objects.

Empties all objects in the Recycle Bin and deletes them from memory. Deleted itemscan't be recovered.

System Log Palette Toolbar

The System Log palette toolbar has the following buttons:

Button Description


Bottom Positions the palette at the bottom of the IDE.Floating Floats the palette, which can be moved and minimized.Window Opens the palette in a separate browser window, which isindependent of General Interface Builder.Close Closes the palette.

Clears the contents of the System Log palette.

Controls the message log level. Choose from , , , , , , or OFF FATAL ERROR WARN INFO DEBUG

.TRACE

294


XSL Parameters Palette Toolbar

The XSL Parameters palette toolbar has the following buttons:

Button Description



Adds the specified name-value pair to the component definition as an xslparameterselement. Type values in the Name field. Enter a value in the Value field and click the

button to add the parameter. The addition is visible in the component definitionAdd(Source XML view) and the Rendered HTML view in the work area. For example,

.<xslparameters jsx_rowbg1="#ffffff" jsx_rowbg2="#efefff"/>

Press the key to navigate the XSL Parameters palette fields.Enter

XML Mapping Utility Toolbar

The XML Mapping Utility has the following buttons on the top toolbar. Other areas of the XMLMapping Utility also have toolbars.

Button Description

Creates a new rules file.

Opens an existing rules file for viewing and editing.

Saves the currently open rules file.

Saves the currently open rules file with a new file name.

Rules Tree Panel Toolbar

The Rules Tree panel toolbar in the XML Mapping Utility has the following buttons:

Button Name Command Description

Test Launches the Test Interface Tool where you can stepthrough and execute operations in the rules tree.

Map Automatically maps rules to GUI components and CDFelements.

CDFAttribute

Creates a CDF attribute mapping using the rule name as theattribute name.

CDFRecord

Creates a CDF record for the selected rule(s) and CDFattribute mappings for descendant rules.

295


DOM (Mapand Create)

Creates a new Form element ( or jsx3.gui.TextBox

) and adds it as a child of the activejsx3.gui.Select

selection within the Component Hierarchy palette. Alsocreates the mapping.

Detach Detaches values applied in the Settings panel.

Mappings Removes all mapping rules for the selected rule(s).

Restrictions Removes all restrictions for the selected rule(s).

Headers Removes all HTTP headers for the selected rule(s).

Delete Deletes a selected rule(s) or all unselected rules.

SelectedRules

Deletes the selected rules from the tree.

UnselectedSiblingRules

Deletes all siblings of the selected rule(s) from the tree.

Generate Generates JavaScript code for the selected operation andplaces it on the clipboard for pasting into a JavaScript file.The rules file must be saved first.

Mapper Log Toolbar

The Mapper Log toolbar in the XML Mapping Utility has the following buttons:

Button Description

Clears the Mapper Log panel of the XML Mapping Utility.

Controls the message log level. Choose from , , , , , , or OFF FATAL ERROR WARN INFO DEBUG

.TRACE

Test Interface Tool Toolbar

The Test Interface toolbar has the following buttons:

Button Description

Resets the tester.

Starts or resumes the test.

Pauses the test.

(Receive tab) Generates alternate inbound message.

Taskbar Toolbar

The taskbar is located at the bottom left of the General Interface Builder user interface.

The taskbar toolbar has the following buttons:

296


Button Description

Opens the project directory in a new browser window.Right-click this hyperlink to access the taskbar context menu.See .Taskbar Context Menu

Shows the work area and the palettes.

Shows the work area only and hides all palettes.

Dialog Field Descriptions

This section describes the fields of General Interface dialogs.

Create a New Project Dialog

In the Create a New Project dialog, you can create a new General Interface project.

To open the Create a New Project dialog, choose or click the Project > New Project Create A link in the Welcome screen (Help > Welcome Screen).New Project

Field Description

ProjectName

The name of the project and project directory, which is created in the JSXAPPSdirectory. You can type the name or click the Browse button to browse to and enter afolder name in the JSXAPPS directory.

Button Description

Cancel Cancels the action and closes the dialog.

Create Creates the project and launches General Interface Builder with the project open.

For more information on creating projects, see .Managing Projects

File Profile Dialog

In the File Profile dialog, you can edit the profile of the file selected in the Project Files palette.

To open the File Profile dialog, right-click a file in the Project Files palette and choose Edit. You can also select a file and click the Edit Profile button on the Project Files paletteProfile

toolbar.

Command File Type Description

ID ID of the file generated by General Interface. This ID can bemodified but be unique.must

Type Type of file, such as GUI Component, JavaScript, CSS, XML, XSLT,or Dynamic Properties

Auto Load Sets how files are loaded. Available options vary by file type.

297


Auto Load JavaScriptFiles

For more information on how JavaScript files are loaded, see Class.Loading in General Interface

The JavaScript file is dynamically loadedManually/As Neededwhen it's needed. For the file to be loaded automatically, it must beregistered in a class path on the Classpath panel of the ProjectSettings dialog (Project > Project Settings) or loaded using a

method call. Otherwise, it can only be loadedjsx3.require()

programmatically with the method. If aServer.loadResource()

JavaScript class file is registered on a class path, it doesn't need tobe registered as a project resource to be dynamically loaded.

The JavaScript file is automatically loaded when theAt Initapplication initializes. When this option is selected, the file name inthe Project Files palette is displayed in a bold black font.

Auto Load CSS FilesDynamicPropertiesFilesMappingRules FilesXML andXSL Files

The file is loaded programmatically with the Manually or ) method.loadResource() loadInclude(

It's not recommended to load CSS filesprogrammatically, because they can be very slow toload.

XML and XSL files are typically set to Manually. They can also beloaded into cache using the XML URL property in the PropertiesEditor palette. Rules files are typically set to Manually.

The file is automatically loaded when the applicationAt Initinitializes. When this option is selected, the file name in the ProjectFiles palette is displayed in a bold black font.

GUIComponentFiles

The Auto Load option is disabled for GUI component files. You canspecify a GUI component file to automatically load when theapplication initializes in the Initial Component field on theDeployment panel of the Project Settings dialog.

URI The path of the file relative to the project folder.

Buttons

The following buttons are on the bottom right of the File Profile dialog:

Button Description

Apply Applies the changes but doesn't close the dialog.

Save Saves the changes and closes the dialog.

Cancel Cancels any changes and reverts back to the last saved version.

298


IDE Settings Dialog

In the IDE Settings dialog, you can modify General Interface Builder integrated developmentenvironment (IDE) preferences for the visual authoring environment. The options in this dialogallow you to customize the IDE, modify and add keyboard shortcuts for menus, and set paths.Settings in this dialog are saved to ./settings/builder.xmlworkspace

To open the IDE Settings dialog, choose .Tools > IDE Settings

The IDE Settings dialog has the following panels:

IDE Settings PanelIDE Hot Keys PanelPaths Panel

For more in-depth discussion of some of these options, see .Customizing the IDE

IDE Settings Panel

The IDE Settings panel displays options for the General Interface IDE.

Field Description

Outputcharacterencoding

Specifies the character encoding to use when saving files, such as UTF-16. Ifthis field is empty, the default is used, which is system-dependent. Click theTest button to verify that the specified encoding can be written and that it'savailable on the system. For Internet Explorer, encoding behavior variesaccording to Microsoft Windows updates and security settings, which mightneed to be modified. UTF-16 and the default system encoding should besupported regardless. If the test fails for other encodings, you might need toenable the object. See "How to disable the ADODB.Stream objectADODB.Stream

from Internet Explorer" at and reverse thehttp://support.microsoft.com/default.aspx?kbid=870669


Output lineseparator

Specifies the line separator by operating system, such as UNIX, Mac OS, orMicrosoft Windows.

Insteadencode XMLfiles as

Specifies the character encoding to use when saving XML files. This settingoverrides the XML declaration, if any. Check the Add character encoding to

option to modify the encoding in the XML declaration.XML declarationsClick the Test button to verify that the specified encoding can be written andthat it's available on the system. If this option isn't set, the setting in theprevious field is used. For Internet Explorer,Output character encodingencoding behavior varies according to Microsoft Windows updates andsecurity settings, which might need to be modified. UTF-16 and the defaultsystem encoding should be supported regardless. If the test fails, you mightneed to enable the object. See "How to disable theADODB.Stream

ADODB.Stream object from Internet Explorer" at and reverse thehttp://support.microsoft.com/default.aspx?kbid=870669




299


Addcharacterencoding toXMLdeclarations

Adds the encoding, specified in the field, to theInstead encode XML files asXML declaration. For example, if UTF-8 is specified, the XML declarationwould look like this: <?xml version="1.0" encoding="UTF-8" ?>

Give DOMfocus tonewly addedGUI objects

Specifies whether to assign focus to a new object in the Component Hierarchypalette and the work area after it's created.

Warn beforedereferencinga projectresource file

Specifies whether to display a warning dialog before a file is dereferenced inthe Project Files palette.

Warn beforeremovingdocumentsfrom thelocal XMLcache

Specifies whether to display a warning dialog before a document isdereferenced in the Local Data Cache palette.

Warn beforedeletingobjects fromtheComponentHierarchy

Specifies whether to display a warning dialog before a component is recycledin the Component Hierarchy palette.

Open lastproject whenlaunchingGeneralInterfaceBuilder

Specifies whether to open the last project when General Interface Builder islaunched.

Showwelcomesplash screenon start

Specifies whether to display the Welcome screen when General InterfaceBuilder is launched. See .Welcome Screen

Snap-tospacing

Specifies the grid pixel size. Used when repositioning objects in the work area.To enable or disable the snap-to-grid feature, use the Toggle Snap-to Gridbutton in the Component Hierarchy palette.

IDE Hot Keys Panel

The IDE Hot Keys panel displays a list of General Interface Builder menus that you can assignkeyboard shortcuts to. To assign a keyboard shortcut, double-click a row, press the keycombination on the keyboard, and click . Restart General Interface Builder for the changesSaveto take effect.

Field Description

Menu The name of the menu command.

300


Key The shortcut key that activates the menu command.

Paths Panel

The Paths panel allows you to set paths for the workspace and HTTP base.

Field Description

Workspace A user home directory that contains your projects, custom add-ins andprototypes, and your user settings for General Interface Builder. Browse to anexisting directory, create a new one, or accept the default workspace.

HTTP Base The path in the HTTP Base field is used when you select Project > Run Project. To use this feature, you must have an HTTP web server, such asFrom HTTP

Apache, hosting both the General Interface installation directory and yourworkspace directory.

WS Path If the relative path between General Interface installation directory and yourworkspace directory aren't the same on the HTTP server as they are on disk, youmust enter the relative path to the workspace directory in the WS Path field.

Buttons

The following buttons are on the bottom right of the IDE Settings dialog.

Button Description




Launches context-sensitive help.

Open Files, Save File, and Choose Folder Dialogs

The Open Files dialog is used to open existing files and the Save File dialog is used to save andrename files. The Choose Folder dialog is used when choosing a folder.

To open the Open Files dialog, choose or click the button on theFile > Open Open FileProject Files palette. In some dialogs and tools, you can click the Browse button next to a fieldthat supports opening a file.

To open the Save File dialog, choose or right-click a work area tab and choose File > Save As. To open the Save File dialog in the XML Mapping Utility, click the buttonSave As Save As

on the toolbar.

To open the Choose Folder dialog, click the Browse button next to a field in a dialog or tool thatsupports choosing a folder.

Field Description

Directory Displays the current directory.

File or Folder Name The name of the file to open or save or the name of the folder to choose.

301


Buttons

The following buttons are on the top and bottom of the File Open, File Save, and Choose Folderdialogs.

Button Description

Moves up a directory level.

Creates a new folder in the current directory.

Reloads the dialog.

Cancel Cancels any changes and closes the dialog.

Open Opens the selected file (Open Files dialog). Use Shift+click and Ctrl+click to selectmultiple files.

Save Saves the file and closes the dialog (Save File dialog).

Choose Chooses the selected folder and closes the dialog (Choose Folder dialog).


Project Settings Dialog

The Project Settings dialog contains settings for configuring project deployment, add-ins, classpath, and legacy settings.

To open the Project Settings dialog, choose .Project > Project Settings

The Project Settings dialog has the following panels:

Deployment PanelAdd-Ins PanelClasspath PanelLegacy Settings Panel

For more in-depth discussion of some of these options, see .Modifying Project Settings

Deployment Panel

The Deployment panel has settings for application deployment. For more information, see .Deploying Applications

Field Description

Caption The text to display in the browser title bar while the application is running.

Namespace Each General Interface application has a single instance. Thejsx3.app.Server

application namespace is a unique identifier for this single jsx3.app.Serverinstance. All objects in a General Interface application are governed by thisserver instance and uniquely located using the application namespace. The dotsymbol (".") is supported in the namespace. For example, .eg.chart.APP

302


InitialComponent

The path to the component to automatically load when the applicationinitializes at runtime. The path is relative to the project directory. For example,

.components/appCanvas.xml

CancelError

Specifies whether to trap errors and display them in the System Log palette. Ifchecked, JavaScript errors are routed to the System Log palette in GeneralInterface Builder. If unchecked, JavaScript errors are routed to the browser.

CancelRight-Click

Specifies whether to trap the right-click event. If checked, developers canreplace the browser right-click menu with a custom menu. If unchecked,right-click events are routed to the browser.

Mode The deployment mode for the deployed application used by the class. Live Mode An online mode where the application isjsx3.net.Service

connected over HTTP/S to a back-end server, allowing access to online data.When requests for data are made by the application, the request goes out overHTTP/S and data is returned and rendered. Static Mode An offline mode wherethe application isn't connected to a server. Data is static and is referenced usingstatic URLs stored in rules files. When a request for data is made by theapplication, the request is routed to a local static XML document. That staticdata is returned as if it came from a server and is rendered in the application.Select this mode when developing an application offline or disconnected fromthe server. This is useful when applications and back ends, such as web services,are in development simultaneously or a back end is currently unavailable. See

.Modifying Output Rules

Body HotKeys

Specifies whether to route key events that bubble up to the window from anapplication keyboard shortcut. If checked, the keyboard shortcut event bubblesup to the HTML element and is then sent to the application. Check thisbody

option for deployment of standalone console applications. If unchecked,keyboard shortcuts only function if the focus is in the General Interfaceapplication. This option should be unchecked for deployment of non-consoleapplications that are a portion of a web page.

Overflow Determines how the application container behaves when movable objects, suchas dialogs and CDF drag masks, are moved off the edge of the container. ScrollMovable objects cause the container to scroll. Expand Movable objects can leavethe container. Hidden Movable objects are invisible.

DefaultLocale

Specifies the locale of the localized application. Enter the two letter, ISO 639language code and the optional, two letter ISO 3166 country code. The format is

or For example, for French or for French in France. See ll ll_CC. fr fr_fr

. If this field is empty, the locale is determined by the browser. ForLocale Keysmore information about localization, see Internationalizing and Localizing

.Applications

onLoadScript

JavaScript code to execute when the application initializes. For example, youmight want to execute a main method, communicate with a server, createcontroller objects by instantiating a controller class, or create the state of theapplication. For more information, see Executing Code When the Application

.Loads

303


onUnloadScript

JavaScript code to execute when the browser window is unloaded. There areseveral ways to unload a browser window, including closing the window,refreshing the window, or navigating to another URL. The onUnload eventallows you to save user state and do any final cleanup before exiting. For moreinformation, see .Executing Code When the Application Unloads

Add-Ins Panel

Select which add-ins to load for the project, such as Charting or custom add-ins. Restart GeneralInterface Builder for changes to take effect. For more information on the Charting add-in, seeGeneral Interface Component Guide.

Field Description

Charting If selected, General Interface Builder charting components display in theComponent Libraries palette.

Classpath Panel

The project class path is used by General Interface to find custom classes that are dynamicallyloaded by your application. This accelerates load time for your application. For setting classpaths, see .Classpath Panel

For more information on how classes are loaded, see . ForClass Loading in General Interfacenaming conventions for dynamically loaded classes, see .Class Naming Conventions

Field Description

Path The path to the custom classes. The class path is relative to the project directory. Forexample, entering as the path would load the specified classes in the js/ workspace

directory./JSXAPPS/project_dir/js

Package The name of the package. Wildcards

are allowed. |

Legacy Settings Panel

The Legacy Settings panel has the following options:

Field Description

ProjectVersion

A version number for the project. When a resource in the project is accessed, thestring is appended to the name of the resource.?jsxversion=<project_version>

This is useful for reloading cached files each time the project is modified.

EventProtocol

Specifies the event protocol for the project. The options include 3.1 (default) and 3.0(deprecated). In General Interface 3.0, certain public methods, such as

, generated model events, in this case the SELECT event. SuchTree.setValue()

methods have been deprecated in General Interface 3.1 or have had their behaviorchanged so that model events aren't generated. In order to provide backwardcompatibility, a per-project setting was introduced in 3.1 that determines whetherthe project uses the 3.0 event protocol or the 3.1 event protocol. New projects usethe 3.1 event protocol by default. Setting the event protocol to 3.0 maintains thebehavior of General Interface 3.0.

304


Buttons

The following buttons are on the bottom right of the Project Settings dialog:

Button Description





Welcome Screen

The Welcome screen provides links to projects, documentation, Developer Network, andGeneral Interface Open Source Project.

By default, the Welcome screen displays when General Interface Builder is launched. TheWelcome screen can be enabled or disabled by toggling the Show at Startup option in theWelcome screen or the Show Welcome Splash Screen on Start option in IDE settings (Tools >IDE Settings > IDE Settings). The Welcome screen is also available from the Help menu.

Item Description

Create a NewProject

Launches the Create a New Project dialog. See .Create a New Project Dialog

Open anExisting Project

Provides a drop-down list of existing projects to open.

Recent Projects Provides a list of recent projects to open.

Documentation Provides links to User Guides and to API documentation in HTML format, ifinstalled. Documentation downloads in HTML and PDF format are alsoavailable at .http://www.generalinterface.org

CommunityNews

Provides information and links to General Interface announcements onDeveloper Network.

Community Provides links to Developer Network, General Interface Open SourceProject, and popular forum topics. Visit Developer Network at http://www.generalinterface.org

for developer forums, information on getting started with General Interface,and other resources and information. Visit General Interface Open SourceProject at


to browse source code, track bugs, and suggest enhancements.

Show atStartup

Specifies whether to display the Welcome screen when General InterfaceBuilder is launched.




305


Tool Field Descriptions

This section describes the fields of General Interface tools.

Color Picker Tool

The Color Picker allows you to select colors to copy and paste into General Interface Builder.

To open the Color Picker, choose .Tools > Color Picker

To navigate in the Color Picker, use the arrow keys to move the slider, scroll through hexvalues in the Hex field, and move between radio buttons.

Field Description

Colorpalette

Click in the color palette to select a color.

Color slider Use the slider to change color spectrum in the Color palette.

Previewcolor box

The box at the lower right displays the currently selected color. Click in this boxto copy the hexadecimal (hex) color value to the clipboard.

H (Hue) Specifies the color hue or gradation.

S(Saturation)

Specifies the color saturation, which is the intensity or purity of a specific hue.

B(Brightness)

Specifies the color brightness or strength.

R (Red) Specifies the red portion of the RGB value. After specifying a value, press theEnter key to view the updated hex equivalent.

G (Green) Specifies the green portion of the RGB value. After specifying a value, press theEnter key to view the updated hex equivalent.

B (Blue) Specifies the blue portion of the RGB value. After specifying a value, press theEnter key to view the updated hex equivalent.

Hex The hex value for the selected color.

Deployment Utility

Use the Deployment Utility to create a launch page for your application, a launch link, or aninline element. For more information, see .div Deploying Applications

To open the Deployment Utility, choose .Project > Deployment Utility

The Deployment Utility has three panels:

HTML Page PanelLaunch Link PanelInline Div Panel

306


HTML Page Panel

Select the HTML Page tab to create an HTML or XHTML page that launches the deployedapplication as a standalone application.

Command Description

XHTML If checked, XHTML markup is generated for the launch page. XHTML launchpages are used for applications that run in XHTML pages, such as portletapplications.

Create Creates the HTML or XHTML page for launching the deployed application.

Launch Link Panel

Select the Launch Link tab to generate a hyperlink that launches the application in a newbrowser window.

Copy and paste the link into your HTML page and modify as desired. This hyperlink requiresthe file \ to be deployed also.GI_HOME shell.html

Button Description

Copies the contents of the textbox to the clipboard which you can then paste intoyour HTML page.

Inline Div Panel

Select the Inline Dive tab to generate an inline DIV for your HTML page. Use this option whenrunning multiple applications in the same browser window.

Copy and paste the inline DIV into your HTML page and modify as desired.

Button Description

Copies the contents of the textbox to the clipboard which you can then paste intoyour HTML page.

Find and Replace Tool

To open Find and Replace, choose .Tools > Find and Replace

Field Description

Find Enter the text string to search for in the active open text file in the project.

CaseSensitive

If checked, finds only exact case matches to the string entered in the Find field.

RegularExpression

If checked, JavaScript regexp syntax is supported in the Find field. For moreinformation, see Help > Internet Resources > Regular Expressions Guide(Mozilla).

Replace Enter a replacement text string for the found text in the active open text file inthe project.

307


Replace Replaces the found text string with the replacement string.

ReplaceAll

Replaces all occurrences of the text string with the replacement string.

Find Finds the next occurrence of the text string.

Cancel Closes the dialog.

XML Mapping Utility

The XML Mapping Utility provides a visual environment for configuring and testing dataservices.


Data Connection and MappingXML Mapping Utility User InterfaceCommunicating with Data ServicesXML Mapping Utility Toolbar

To open the XML Mapping Utility, choose XML Mapping Utility or Tools > File > New >.Mapping Rule

The XML Mapping Utility has several panels:

Rules Tree PanelRule Profile PanelSettings PanelMapper Log

When you open the XML Mapping Utility from the Tools menu, the first panel allows you toselect the file(s) to open.

Field / Button Description

WSDL Select this radio button if you are using a WSDL as the sourcedocument for generating the mapping rules.

XML/XHTML/Schema Select this radio button if you are using a XML, XHTML, or Schemaas the source document(s) for generating the mapping rules.

URL If WSDL is selected, choose the URL for the WSDL to be used forgenerating the mapping rules. If XML/XHTML/Schema is selected,enter the URLs for the outbound and inbound document(s).Documents that are created are "outbound," while documents thatare processed are "inbound."

Parse Document Parses the selected document(s).

For more information, see .Choosing the File for the Rules File Starting Point

308


Rules Tree Panel

The Rules Tree panel of the XML Mapping Utility contains the structures defined in the rulesfile displayed in an hierarchical format. It provides a visual interface for creating bindings andfor testing data services. Right-click a rule to see what's available on the context menu.


Working in the Rules Tree PanelRules Tree Panel ToolbarRules Tree Panel Icon DefinitionsCommunicating with a Web Service Tutorial

Rule Profile Panel

The Rule Profile panel has two views: one for viewing the WSDL source and one for editing therule profile.

For more information, see .Working in the Rule Profile Panel

RadioButton

Description

OriginalSchemaSource

Displays the original Schema or XML node used to generate the selected rule.

RuleNodeProfile

Displays name-value pairs for the selected rule. Many of the fields in the RuleProfile panel are editable. Typically, you would modify the node name and thetarget namespace.

Button Description

DisplayWSDLSource

When the Original Schema Source radio button is selected in the Rule Profile paneland the WSDL node is selected in the Rules Tree panel, this button is available inthe Rule Profile panel. Depending on the size of the WSDL, displaying the WSDLmight take some time.

Rule Node Profile

The Rule Node Profile includes these fields:

Field Description

Abstract If the value is 1, this rule is abstract and only exists in the rules tree, not in thefinal XML message. An abstract rule can be used to reorganize the rules treewithout affecting the structure of the XML message.

DataType

For encoded messages, the data type to encode, such as string, boolean, decimal,and so on.

DataType NS

For encoded messages, the namespace for the data type.

309


InputSource

URL to the input source file used to generate these rules. The input source filecould be a WSDL, XML, XHTML, or Schema file.

NodeName

The name of the node as it appears in the XML message that is created orprocessed.

OperationName

The name of the operation as defined in the input source file.

Rule ID Unique ID (jsxid) assigned by the General Interface system when the rule wascreated.

RuleType

The type of rule, such as WSDL, transaction, service, operation, input, output,element (E), attribute (A), complex type (C), and CDATA (D). Each rule type hasan associated icon in the rules tree. For icon definitions, see .Table 13

SimpleType

Set the value to 1 to denote that this rule is a simple type (). Simple types include string, int, href andhttp://www.w3.org/2001/XMLSchema

so on. For definitions of simple types, see the XML Schema at .http://www.w3.org/2001/XMLSchema

SourcePath

XPath statement that points to the location of the node in the source documentthat was used to generate the rule. Maintains the binding between the sourcedocument and the rule node.

Target If set to a specific URI, the node name is auto-prefixed (QName) to designate thetarget namespace. For example, <jsx1:zipcode>.

Settings Panel

The fields displayed in the Settings panel on the right side of the XML Mapping Utility dependon the type of rule selected in the Rules Tree panel. The type of rules include the following:

Operation RulesInput RulesOutput RulesMessage Rules

For information on how to use the Settings Panel, see and Working in the Settings Panel.Communicating with a Web Service Tutorial

Operation Rules

When an operation rule is selected in the Rules Tree panel, the following fields are displayed inthe Settings panel.

For more information, see .Modifying Operation Rules

Field Type Description

EndpointURL

This is the URL for the service to contact. It can be absolute (http/https)or relative ( ). To override this setting at/services/address.asmx

runtime, call on the instance.setEndpointURL Service



310


Method When making a call, the class is used toService jsx3.net.Request

transport the call. The most common methods are POST and GET. POSTis used for sending XML content with the request. GET merely calls thegiven URL. To override this setting at runtime, call on the setMethod

instance.Service

POST Submits data to be processed, such as a SOAP request envelope, to theidentified resource. The data is included in the body of the request.

GET Requests the specified resource, such as a URL.

PUT Uploads the specified resource.

DELETE Deletes the specified resource.

HTTPHeaders

Each HTTP request can send different types of information. Forexample, the HTTP request can send any of the following: an XMLdocument (POST), a URL overloaded with data of its own (GET orPOST), or information about the content and purpose of the requestitself. The HTTP headers listed in this field are automatically generatedduring the initial parse. If additional headers are needed, you can addthem statically to this field. You can also add them at runtime on the

instance by calling for each additional headerService setRequestHeader

that should be added. Other headers not listed are also sent, includingthe content-length and any cookies used by the service.

Input Rules

When an input (request) rule is selected in the Rules Tree panel, the following fields aredisplayed in the Settings panel.

For more information, see .Modifying Input Rules

Field Description

Stub URL Typically used in conjunction with the Stub Path field to support SOAP-basedweb services. When SOAP is used, each request document is encapsulated bya SOAP Envelope. The XML Mapping Utility treats the Envelope as a staticdocument into which the actual request is placed. This document is genericenough to encapsulate the majority of SOAP messages. If this defaultdocument does not contain enough information, you can specify the URL fora static stub of your own. This value can be updated at runtime using the APIcalls, or .setOutboundStubURL setOutboundStubDocument

Stub Path Used in conjunction with the Stub URL field. Type a valid XSL query thatdescribes where to place the generated document in the Stub document. Thisvalue can be updated at runtime using the API call, .setOutboundStubPath

onBeforeSend JavaScript statements entered in this field execute immediately before therequest message is sent. This script executes in context of the instance.Service

This means that the keyword, , refers to the instance. Forthis Service

example, if you want to output the XML request to the System Log beforesending it, you would enter: jsx3.log(this.getOutboundDocument().getXML());

311


Output Rules

When an output (response) rule is selected in the Rules Tree panel, the following fields aredisplayed in the Settings panel.

For more information, see .Modifying Output Rules

Field Description

Stub URL Enter the URL for a valid XML document (the typical response) whenrunning the XML Mapping Utility in static mode (offline). The static modeallows you to test against a typical service response. This is useful insituations where the service isn't built yet or is inaccessible. To change themode to static, choose . This URLProject > Project Settings > Deploymentcan also be set at runtime using the API call, . For moresetInboundURL

detailed information, see .Modifying Output Rules

onAfterReceive JavaScript statements entered in this field execute immediately after theresponse message is received and before the mappings are applied. Thisscript executes in context of the instance. This means that theService

keyword, , refers to the instance. For example, if you want tothis Service

output the XML response to the System Log each time the service responds,you could write: Forjsx3.log(this.getInboundDocument().getXML());

other examples, see .onAfterReceive

Message Rules

When message rules are selected in the Rules Tree panel, the following fields are displayed inthe Settings panel. Message rules, which are children of input and output rules, includecomplex type, element, attribute, and CDATA rules.

For more information, see .Modifying Message Rules

Field Type Description

Mappings The Mappings table is where the actual work is done. When arequest message is generated or a response message isprocessed, each mapping listed in this table is run sequentiallyfor the given rule. Although different mapping types exist, allmapping types provide a map between objects in the application(textbox, JavaScript variable, CDF attribute, and so on) and rulesin the rules tree. For more information on mapping, see

.Communicating with Data Services

Script Filter or JavaScript code that evaluates in context of the Serviceinstance. For example, you can set a value: setValue("0");

NODE Maps to a node in the Local Data Cache palette. Type the cachedocument name, two colons, and a valid XSL Query. Forexample, .myDocument:://recordjsxid=12

DOM Maps to a GUI object in the General Interface DOM. Enter theobject name.

312


CDFDocument

Queries for or creates a CDF document in the Local Data Cachepalette. Enter the CDF document name.

CDF Record Queries for or creates a CDF Record as a child of the currentCDF record context. The Path/Value field is not required but canbe used to support recursion or hand off processing to anotherrule. For example, if there is another rule in your mapping rulesfile that has a CDF Record mapping, you can enter the jsxid forthat rule. To find the jsxid, select the rule that you wish to calland click the radio button.Rule Node Profile

CDFAttribute

Queries for or creates a CDF attribute on the nearest CDF recordancestor. Enter the attribute name, such as jsxid, jsxtext, price,and so on.

Restrictions When Schema or WSDL are used as the input for the XMLMapping Utility, any restrictions appear in the Restrictionstable. You can also add additional restrictions on a rule. Forexample, you might restrict user input to be equal to dog or cat.To restrict such input, you would add two new enumerationrestrictions to the rule: one for cat, the other for dog. At runtime,these restrictions can be used to validate the request documentas it's created node-by-node. For more information about what'spublished when a node value doesn't adhere to its restrictions,refer to the ON_INVALID subscription for the class. ForService

more information, see .Restrictions

length Specify an exact number of characters allowed in a string. Forexample, type for a string to contain exactly five characters.5

maxLength Specify a maximum number of characters allowed in a string.For example, type for a string to contain a maximum of five5characters.

minLength Specify a minimum number of characters allowed in a string.For example, type for a string to contain a minimum of five5characters.

pattern Specify a regular expression to validate against. For example,entering the following regular expression would ensure thatonly numeric content can be entered by the user: For/^d+$/

more information on regular expressions, see Help > InternetResources > Regular Expressions Guide (Mozilla).

enumeration Specify an enumerated value to validate against. For example,you could limit the values for a stock to three values: symbol,CIK (Central Index Key), and CUSIP (Committee on UniformSecurities Identification Procedures).

maxInclusive Specify a maximum inclusive value. The node value must beless than or equal to the specified value.

minInclusive Specify a minimum inclusive value. For example, the node valuemust be greater than or equal to the specified value.

313


maxExclusive Specify a maximum exclusive value. For example, the nodevalue must be less than the specified value.

minExclusive Specify a minimum exclusive value. For example, the nodevalue must be greater than the specified value.

maxOccur Specify an inclusive maximum number of times this node canappear in the XML message. For example, type for the node to5appear a maximum of five times in the XML message.

minOccur Specify an inclusive minimum number of times this node canappear in the XML message. For example, type for the node to5appear a minimum of five times in the XML message.

nillable Set to to allow this node to be empty without beingtrue

automatically removed by the XML Mapping Utility. The XMLMapping Utility automatically removes any node from anoutgoing message that doesn't have text content or descendantnodes with text content. However, if an empty node has anillable restriction that's set to , the XML Mapping Utilitytrue

leaves the empty node untouched. If you have a rule that mightbe empty when the outgoing message is being created and youwant to make sure that it isn't removed, add a nillable restrictionto the given rule.

Field Description

RepeatWhen

As long as the JavaScript code in this field evaluates to true, the rule and alldescendant rules are run again. The JavaScript function is used to create and define acollection from a single node. The collection is added as nodes in the XML messageto the server. Don't enter in this field, because it results in an infinite loop. Thetrue

Repeat When field is only applicable to outbound (input) messages. It's typicallyused by mapping rules that convert a JavaScript array into an XML Node-set in theoutgoing message. Conceptually, this feature is similar to a do-while loop, whereexecution will happen at least once and continue as long as the while (Repeat When)statement is true. For examples, see . Also note that CDF mappingsRepeat Whenautomatically repeat when necessary. For more information on CDF GUIcomponents, see .Mapping Response Data to CDF GUI Components

Mapper Log

The Mapper Log displays information about the outcome of parsing the starting pointdocument and testing mappings.

For more information, see and .Mapper Log Mapper Log Toolbar

Field Description

Textarea

Displays the XML Mapping Utility log messages according to the selected log level.Use the Adjust Log Level button to select a log level.

314


Test Interface Tool

The Test Interface Tool of the XML Mapping Utility is designed to guide you through the testsequence. The Create, Send, Receive, and Apply tabs correspond to phases of sending andreceiving XML messages. Clicking a tab displays data that is relevant to the current test phase.

To use the Test Interface Tool, click the button on the Rules Tree panel toolbar in the XMLTestMapping Utility.

The Test Interface Tool has four panels:

Create PanelSend PanelReceive PanelApply Panel


Testing Outbound and Inbound MessagesTesting Mappings

Each panel of the Test Interface Tool contains this drop-down list:

Field Description

Select Select the operation to test from the drop-down list.

Create Panel

Mappings for the outbound message display on this panel.

Field Field Description

OutboundMappings

Mappings of GUI objects to mapping rules for the outboundmessage.

RuleName

Name of the element (mapping rule).

Type Type of object that is mapped. Types include Script, NODE,DOM, CDF Document, CDF Record, and CDF Attribute.

Path/Value GUI component name or any associated JavaScript code forthis mapping.

Post-MappingFilter/Handler

Filter code to execute before sending this message.

Send Panel

The outbound message displays on this panel.

Field Description

URL URL specified in the WSDL file.

315


HTTPHeaders

Header content for the message. The header text can be edited.

Name User name used for authentication if required.

Password Password used for authentication if required.

Method Method for contacting the Service. Choose from POST, GET, PUT, and DELETE.The most common are GET and POST.

Receive Panel

The Service response displays on this panel.

Field Description

HTTP Headers Header content for the response message.

HTTP Status Status of message, such as 200, 404, and so on.

Response Response message.

Apply Panel

The inbound mappings display on this panel.

Field Field Description

Pre-MappingFilter/Handler

Filter code to execute on the inbound document.

InboundMappings

Mappings of response rules to application objects.

RuleName

Name of the element (mapping rule).

Type Type of object that is mapped. Types include Script, NODE,DOM, CDF Document, CDF Record, and CDF Attribute.

Path/Value GUI component name or any associated JavaScript code forthis mapping.

XML/XSL Merge Tool

Use the XML/XSL Merge Tool for testing the XML and HTML output from a merge operation.For more information, see .Data and Cache Management

To open the XML/XSL Merge Tool, choose .Tools > XML/XSL Merge Tool

Field Description

URL The location of the XML or XSL file, either on an accessible file system or on aweb server.

Cache The name of the XML or XSL file in browser cache, as displayed in the LocalData Cache palette.

316


Script JavaScript code that produces an XML document or a node in an XML documentas output.

Source XML or XSL code typed directly into the tool dialog. If URL, Cache, or Script isused to specify the XML or XSL source, this field displays the file contents. In thecase of XSL, modifications can be made before the merge operation.

MergeDocuments

Merges the XML document with the XSLT filter document and displays theresults.

RenderedOutput

Displays the result of the merge operation as rendered XML or HTML (as itwould appear in a browser).

RawOutput

Displays the result of the merge operation as XML or HTML.