Tib Gi Users Guide

TIBCO® General Interface Builder

User’s GuideSoftware Release 3.0August 2005

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 THIS MANUAL). 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, Information Bus, The Power of Now, TIBCO General Interface, and TIBCO General Interface Builder are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or 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. Please 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.

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

TIBCO Software Inc. Confidential Information

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiTIBCO General Interface Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

How to Contact TIBCO Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Providing the Best of Both Worlds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Processing Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Server-Based MVC Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Rich Client MVC Architecture: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Architecture Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Ease of Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Support for Industry Standards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Scalable Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Required Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Installing TIBCO General Interface Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Installation Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Installation History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Starting TIBCO General Interface Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 3 TIBCO General Interface Builder Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Interface Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

TIBCO General Interface Builder User’s Guide

iv | Contents

Container Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Object Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Component Libraries Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Component Hierarchy Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Properties Editor Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Events Editor Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Data and Cache Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Compatibility with Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Business Logic Development and Debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Project Files Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Dynamic Properties Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Data Connection and Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35SOAP Mapping Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Additional Visual Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 4 Building a Simple Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Create a New Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Add and Position Application Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Create the Dialog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Customize Pane Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Add Form Elements to the Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Communicate with a Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Map Dialog Fields to SOAP Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Associate an Operation with a GUI Component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Test the Rules File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Test the Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

Chapter 5 Handling Data in Your Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Receiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Receiving XML Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Receiving Non-XML Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Sending Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Caching Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Calling Cache Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Components and Automatic Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Automatically and Manually Caching Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71


Contents | v

Using the Common Data Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Basic Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Calling CDF Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Chapter 6 Communicating with Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Mapping Components to WSDL Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Testing Outbound and Inbound Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Calling the Web Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Mapping Response Data to CDF GUI Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Map SOAP Elements to CDF Equivalents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Map GUI Components to CDF Equivalents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Test the Rules File to View Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Handling Errors and Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Setting Timeout Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Handling Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Chapter 7 Adding Custom Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Adding Code at the Component Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Associating Code with an Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Executing Code Before or After Deserialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Specifying Code in Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Adding Code at the Application Level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Including JavaScript Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Executing Code Before the Application Loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

Using Code with Web Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Testing JavaScript Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Chapter 8 Deploying Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Deploying as a Full Console Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Posting Applications for Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

Accessing Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Chapter 9 Localizing Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Setting Default Unicode Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Using Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Creating Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124


vi | Contents

Specifying a Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Referencing Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Enabling Runtime Language Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Using Static Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

TIBCO Software Inc. End User License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135


| vii

Figures

Figure 1 Server-based MVC Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Figure 2 Rich Client MVC Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Figure 3 Tab Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Figure 4 Tab Object View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Figure 5 TIBCO General Interface Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Figure 6 TIBCO General Interface Builder Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Figure 7 Component Libraries Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Figure 8 Component Hierarchy Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Figure 9 Events Editor Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Figure 10 Local Data Cache Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Figure 11 XML/XSL Merge Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Figure 12 System Log with XML Parsing Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Figure 13 Included JavaScript File and Project File Palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Figure 14 Dynamic Properties Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Figure 15 SOAP Mapping Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figure 16 Launch Page Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Figure 17 Deployment Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118


viii | Figures


| ix

Tables

Table 1 Tab Object Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Table 2 Supported Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Table 3 TIBCO General Interface Required Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Table 4 Application Directory Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Table 5 Summary of JavaScript Customization Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100


x | Tables


| xi

Preface

TIBCO General Interface Builder is a development environment for building rich client applications. The object modeling features of TIBCO General Interface Builder enable developers to quickly create reusable GUI components and assemble them into full applications or application modules. Applications can be accessed in a web browser from a URL, existing HTML page, or portal environment.

Topics

• Related Documentation, page xii

• How to Contact TIBCO Customer Support, page xiii


xii | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO General Interface DocumentationThe following documents form the TIBCO General Interface documentation set:

• TIBCO General Interface Builder User’s Guide: Read this manual for overview information, installation instructions, and information on how to build TIBCO General Interface applications. This manual includes several tutorials

• TIBCO General Interface Builder GUI Reference. Refer to this manual for descriptions of interface elements and prototype components in TIBCO General Interface Builder.

• TIBCO General Interface API Reference. Refer to this online help content for descriptions of the TIBCO General Interface JavaScript API functions and methods.


Preface | xiii

How to Contact TIBCO Customer Support

For comments or problems with this manual or the software it addresses, please contact TIBCO Support Services as follows.

• For an overview of TIBCO Support Services, and information about getting started with TIBCO Product Support, visit this site:

http://www.tibco.com/services/support/default.jsp

• If you already have a valid maintenance or support contract, visit this site:

http://support.tibco.com

Entry to this site requires a username and password. If you do not have a username, you can request one.


xiv | How to Contact TIBCO Customer Support


| 1

Chapter 1 Introduction

This chapter provides an introduction to TIBCO General Interface and a broad orientation to the environment.

Topics

• Providing the Best of Both Worlds, page 2

• Processing Model, page 4

• Architecture, page 6

• Features, page 12


2 | Chapter 1 Introduction

Providing the Best of Both Worlds

A recent survey by Forrester Research revealed that 70% of Fortune 2000 CIOs want to standardize on deploying applications to a browser. However, of those surveyed, more than half stated that the limits of HTML prevented them from reaching this objective.

Significant investment has been made in web browser development since the first version of Mosaic was released. As a result of that effort, today’s web browsers, such as Internet Explorer and Mozilla, do provide a stable environment where enterprise-grade applications can be deployed. However, despite the volume of research and development, the web browser today remains fundamentally aligned with the document-centric paradigms that first defined the concept of a web page. HTML, evolving from its SGML roots, has always been a document-oriented markup language.

With the advent of XML, DHTML, and CSS, the browser began to become increasing powerful and flexible in its core capabilities. Yet, as enterprises migrated applications to the web, they discovered that web applications provided far less interactivity and performance than the thick-client solutions they were meant to replace. Of course the good news was that the cost of web applications was much lower than that of thick client development, deployment and maintenance. As a result, many businesses traded off performance for cost, or alternatively when the document paradigm of HTML was insufficient, paid the higher costs of developing, deploying and maintaining thick clients. Either way, businesses have had to choose between thick clients and web applications, while needing the benefits of both options.

The TIBCO General Interface application framework solves this problem by enabling enterprises to deliver applications that look, feel and perform like desktop installed software, but run in a standard web browser. With TIBCO General Interface, enterprises can have the best of both options: rich, highly productive, service-differentiating GUI functionality with the low cost profile of web development, instant distribution, and anywhere, anytime accessibility.

The TIBCO General Interface application framework leverages inherent capabilities of the web browser to instantly create a powerful, object-based enterprise-grade application environment into which your TIBCO General Interface applications can be deployed. By working with an object-based environment, as opposed to declarative markup languages, development time is shortened, and the business can easily distribute, manage and deploy, high performance solutions.


Providing the Best of Both Worlds | 3

The application programming interfaces (APIs) provided by the browser remain a weak point in the development of end user applications more complex than online retail shopping. The existing browser APIs are not designed for developers who need to create robust enterprise-grade applications, therefore development is time-consuming and expensive, maintainability is difficult, and many businesses completely avoid implementing enterprise web applications. Fundamentally, browsers lack the foundation classes familiar to Windows programmers and the object-oriented presentation packages familiar to Java programmers. Instead, HTML browsers provide a generic API intended for displaying series of hyperlinked web pages that lack the features provided by many thick clients.

TIBCO General Interface solves existing browser limitations by distributing many of the processes typically handled by a centralized web application server to the browser on the client machine. The application framework does this by first wrapping, then extending, browser APIs with functionality more suitable to object-oriented application development. Rather than forcing developers to model complex workflows with a series of flat HTML pages, the TIBCO General Interface API enables developers to create stateful, interactive, object-based, client applications that look, feel, and perform as if launched from the local operating system.



Processing Model

By distributing many of the processes usually handled by centralized application servers to the browser on the client machine, enterprises can deliver full featured software solutions that simply run in the browser without any need for extra runtime components or plug-ins.

TIBCO General Interface is a powerful implementation of model-view-controller (MVC) principles. Unlike server-centric MVC architectures, with TIBCO General Interface, the View processes are distributed to the web browser. This design removes the View generation work from servers and reduces demands on bandwidth, making applications far more scalable. The design also leverages the power of the client CPU to deliver highly responsive, stateful, full featured applications in a browser.

Server-Based MVC ArchitectureView processes run on the server returning streams of HTML and data to the browser. The browser is simply an HTML page rendering device.

Figure 1 Server-based MVC Architecture

Rich Client MVC Architecture:View processes are distributed to the browser where they run on the client system. The distributed View employs a MVC Architecture of its own, turning the browser into a rich Internet client environment. Client side objects generate the HTML. Significantly fewer processes need run on the server. Bandwidth is optimized for data. Application performance and scalability are significantly enhanced.


Processing Model | 5

Figure 2 Rich Client MVC Architecture

In a traditional server-based MVC architecture, all processes run on the server. Requests are sent to the Controller, Models are updated, and the View returns a stream of HTML and data to the browser where it is rendered for the user. This results in system latency and reduced functional possibilities for the end user. The resulting HTML typically comprises 80% presentation instructions and 20% data.

TIBCO General Interface software enables the View portion of the MVC architecture to be distributed to, and to run on, the client system in a web browser. This approach has the following benefits:

• improves application scalability by removing significant server processes

• decreases latency by using substantially all the bandwidth to deliver data (instead of a minority of bandwidth for data in the traditional model where HTML markup takes up most of a transmission)

• delivers full-featured application performance and rich GUI features to an unmodified web browser, with no plug-ins, no runtime environments, no extra software to install



Architecture

The TIBCO General Interface MVC implementation means that the TIBCO General Interface components are broken down into three architectural elements, each of which plays a crucial role in how the component behaves.

ModelThe Model maintains the state data for each object instance. The model portion of the Table object, for example, tracks state properties such as the number of columns in the table, the widths of each column, the outer dimensions for the table, how to sort which column, and so on.

ViewThe View refers to how the object instance is actually displayed on the client machine. A good way to envision a View is to think of object look and feel. Figure 3 shows several different Views that the Tab object can produce:

Figure 3 Tab Objects

ControllerThe Controller dictates how a given object will interact with events. Events include user-initiated events and system-initiated events, including mouse-clicks, key-presses, drag and drop operations, screen and component repainting, and calls from the application business logic.

The best way to describe how these three elements work together is to describe a typical GUI object, such as the Tab object, in context of these three elements.

Figure 4 Tab Object View


Architecture | 7

The easiest aspect of MVC to understand is the View. The View is what end users see when they use the application. The three Tab object instances shown in Figure 4, for example, have a consistent View that adheres to the visual design for the application.

With the View element now defined, it is easier to explain the Model portion of the MVC architecture. Although Figure 4 provides a good visual depiction for a sibling set of tabs, it is inadequate for the object to track its state internally. Instead, the Model element allows the given Tab object to keep an index of properties that uniquely define its state in memory (see Table 1). Accordingly, the Model is unaffected by how the tab visually displays its state. Instead, it maintains a single Boolean property, active, that is set to true or false. From an architectural perspective, separating the Model from the View means that more of the code base can be leveraged on future projects. Regardless of whether the View for a Tab object has beveled edges or graphical icons, the Model remains the same. This means that only the View code for a given class needs to be updated from project to project.

The Controller element updates the Model based on events passed from the corresponding View. For example, a user clicks the displayed View for a Tab object in an attempt to bring the contents of that Tab forward in the View. The View, in this case the actual HTML that is displayed, then processes the click event by calling the Controller requesting that the selected Tab be made active, and therefore brought forward in the View. Next, the Controller queries the Model to validate that the Tab object that was clicked is not already active. If the given Tab object is already active, the Controller exits early without applying any changes to the object. However, if the Tab object is inactive, the Controller updates the Model by setting the active property to true. And then, the View is repainted in the browser to visually depict the new Model value.

Table 1 Tab Object Models

Tab 1 Tab 2 Tab 3

Text Account Info Search Results Account History

Index 0 1 2

Active true false false

activeColor cccccc cccccc cccccc

inactiveColor 8c8c8c 8c8c8c 8c8c8c

…



In general, the Model passes data to the corresponding View for rendering, which in turn passes events to the Controller for processing. This updates the Model to reflect the property changes, providing a closed feedback loop.

Architecture DetailsApplications that leverage TIBCO General Interface run in a standard browser. No other software is required to run the application on a client machine. This means that the client application is completely native, allowing for stable, fast, and true thin client, zero-install applications. No applets, plug-ins, or ActiveX controls are required to deliver robust application functionality.

To deliver high functionality in a standard browser environment, TIBCO General Interface leverages many of the same principles that make server-side architectures successful. TIBCO General Interface software is founded upon solid, object-oriented principles. This means that robustly scalable functionality requires only a minimal footprint of client memory and network bandwidth. The class libraries that underlie the software are lean, comprising over 400 logical functions in approximately 300KB of data. Due to the object-oriented architecture and object inheritance framework, over 2,200 function calls are actually available at run time across more than 40 foundation objects. Furthermore, because the class libraries follow a consistent object-oriented structure, they can be modified as necessary by runtime updates, additions, and even sub-classing. In addition, new objects can also be built by combining foundation objects, all without increasing the overall framework size.

To manage such a broad array of functionality, TIBCO General Interface employs a multi-tier approach to object design. Essentially, any available function can be categorized into four distinct layers, as illustrated in Figure 5. These include:

• Client Logic Layer This layer consists of all programmatic logic, such as business rules and client-specific functionality.

• Presentation Layer This layer is founded upon solid object oriented design principles that leverage many of the key concepts used by Java Swing, without the overhead of the Java Runtime Environment (JRE). A familiar Java-like syntax is used, generating complex DHTML and JavaScript that runs natively in the browser, rather than Java Class files that require the browser to load the memory-intensive JRE.

• Data Layer This layer client-side data cache used for quick access to application data. All data is cached as parsed XML and can be accessed at runtime through XSL queries. This is similar to the way SQL is used to interface with relational data stores on the server.


Architecture | 9

• Communication Layer This layer manages threaded communications with remote web servers using both web service protocols such as SOAP and XML-RPC, as well as traditional web protocols like HTTP GET/POST.

Figure 5 TIBCO General Interface Architecture

Application Layer

TIBCO General Interface provides libraries of functional objects that hide the complexities of DHTML development. Developers do not need to be familiar with the specifics of DHTML in a given browser and can focus instead on the actual business logic for the application. The developer writes JavaScript to enforce business rules and workflow, not to move DHTML around the screen. Accordingly, enterprises get more yield out of their development resources.

Presentation Layer

TIBCO General Interface employs a presentation approach similar to Java Swing but without the overhead of the Java Runtime Environment. Developers familiar with container-based GUIs will find similar constructs in the TIBCO General Interface environment. Application components, screens, and widgets are constructed from TIBCO General Interface foundation GUI objects, and then saved as object sets that can be imported or exported at run time to deliver incremental application functionality on demand. Accordingly, businesses can leverage the TIBCO General Interface foundation components out of the box, or create libraries of their own reusable application components.



TIBCO General Interface provides the following foundation class objects. From these objects, developers can create custom objects:

Note that various prototype objects can be instances of the same base class. For example, TextBox provides the base class for instances of a text box, a text area, and a password field. Similarly the BlockX class is used as the base for Label and Image.

TIBCO General Interface GUI objects generate custom DHTML and JavaScript on the client. This design differs from traditional ASP or JSP architectures, where the presentation is generated on the server, and then the resulting stream of HTML is returned to the browser for rendering. With TIBCO General Interface, no presentation generation is necessary on the server and no transfer of presentation instructions over the network is necessary. The result is highly responsive GUI applications that free up bandwidth for data (not HTML) and reduce the number of servers and server software licenses necessary to deliver a given application.

Data Layer

The client-side XML data cache provides developers with a consistent API for data access and management. Benefits include:

• Efficient data reuse Multiple client objects within the presentation layer can use the same XML document for their source data, keeping redundant data transfer to a minimum.

• Runtime data access Since server data is stored as XML, integrity is retained, allowing for DOM based access to the original data.

Alerts Block BlockX

Button CheckBox Column

DatePicker Dialog Form

Grid LayoutGrid List

Menu RadioButton Select

Splitter Stack StackGroup

Tab TabbedPane TextBox

ToolbarButton Tree WindowBar


Architecture | 11

• Cache management methods A robust API allows developers to write application-specific business rules that keep the client-side data synchronized with the server.

• Client-side HTML generation With HTML generation on the client, server communications are unnecessary for presentation changes such as sorting and styling.

Communication Layer

TIBCO General Interface supports multiple protocols for communicating with services in the network. The basic supported interactions, which all function over HTTP/S, include:

A key principle that drives the TIBCO General Interface communication efficiency is limit refresh to subsets of the screen, not the entire browser window. To facilitate this, TIBCO General Interface improved and extended the traditional click-and-refresh APIs provided by the browser. Developers familiar with web application development have traditionally used standard approaches like HTML frames. Consider a standard web mail client, for example. To improve the user experience, the left frame persistently displays various folders and tools, while the right frame displays dynamic data. Although this design is adequate, there is no question that a web mail client is far less useable than an installed executable, such as Microsoft Outlook.

Technologies that provide single-page persistence in a web browser (such as Microsoft Remote Scripting) do exist, but these often leverage a client-side Java applet that requires loading the Java Runtime Environment into client memory or running a specific server platform. However, this design can quickly undermine application stability and available client-side memory.

Table 2 Supported Interactions

Communication Type Outbound Request Format Expected Response

Format

XML GET URL with Name/Value Pairs XML Document

SOAP SOAP Message SOAP Message

XML RPC XML Message XML Message

HTML GET URL with Name/Value Pairs HTML Document

HTML FORM POST

HTML Form HTML Document



Features

In addition to a powerful and efficient architecture, TIBCO General Interface applications are easy to develop and deploy. Industry-standard technology is used, so knowledge of existing technologies can be leveraged.

Ease of DeploymentThe TIBCO General Interface application framework and all TIBCO General Interface applications are composed of a set of JavaScript, XML, and CSS type files. To deploy the environment and applications, simply include a reference to these files in an HTML page that can be accessed by an end user from any HTTP or HTTPS server. The end user simply types the URL into a browser and starts using the TIBCO General Interface application. To restrict and secure access to your application, use any standard, existing mechanism for securing web page access.

Support for Industry StandardsTIBCO General Interface uses industry standard and widely accepted technologies in both its underlying code (JavaScript, XML, and CSS) and overall architecture (Model-View-Controller and multi-tier design). Strategically, best-practice, server-side tasks are migrated to the browser to deliver the same successful results, maintainable code, and scalable performance. TIBCO General Interface takes best-practice approaches from the server and implements them in the browser.

Scalable ArchitectureThe fastest page server simply cannot compete with locally served data. Load balancing, additional processors, page pre-caching, and any number of server-side enhancements are all ultimately short-term solutions. Rather than attempting to scale the server to meet the needs of the nth end user, consider a paradigm where each end user provides the resources for their own processing needs.

Unlike traditional server architectures, TIBCO General Interface runs on the client, using the client CPU for data presentation and interaction. Even the TIBCO General Interface foundation classes that facilitate this process are cached on the client. This means after a TIBCO General Interface application is accessed, only raw data is requested from the server. Since no HTML needs to be transferred to the client, bandwidth is freed up to deliver more data to the end user more


Features | 13

quickly. In addition, because presentation processes are now distributed to the client, servers no longer need to generate HTML for each connected user. With HTML generation processes no longer running on the server, the ratio of servers to end users is greatly improved.

Development ToolsYou can develop TIBCO General Interface powered client applications and components using either a script authoring environment or your favorite IDE. Once the TIBCO General Interface runtime environment is loaded into an HTML page in the browser, you can directly interact with the TIBCO General Interface GUI, data, and communication objects using JavaScript APIs.

In addition, TIBCO provides the developer with TIBCO General Interface Builder, a rapid deployment environment. This visual authoring environment is optimized for creating TIBCO General Interface applications, and can run either as a standalone tool or within the embedded browser module of your favorite IDE.



As a standalone development environment, TIBCO General Interface Builder provides a powerful, rapid application assembly and scripting environment. You can drag and drop GUI components, connect to services, examine cached data, and implement the behaviors of the client application using JavaScript business logic and events.

When running TIBCO General Interface Builder in conjunction with your favorite IDE, you have a complete end-to-end live development and testing environment with object, code, message, and error inspection, plus a runtime JavaScript debugger.


| 15

Chapter 2 Installation

This chapter describes how to install TIBCO General Interface Builder software. TIBCO General Interface, the runtime framework, is included with TIBCO General Interface Builder software.

Topics

• Required Software, page 16

• Installing TIBCO General Interface Builder, page 17

• Installation Registry, page 19

• Starting TIBCO General Interface Builder, page 20

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. Please see the readme.txt file for the availability of this software version on a specific operating system platform.


16 | Chapter 2 Installation

Required Software

This section describes required software components for TIBCO General Interface. For supported version and vendor information, see the readme.txt file provided with this release.

Table 3 TIBCO General Interface Required Software

Product Purpose

Web browser A web browser is required for running TIBCO General Interface Builder and all other TIBCO General Interface applications.

HTTP server An HTTP server is required for hosting deployed TIBCO General Interface applications.


Installing TIBCO General Interface Builder | 17

Installing TIBCO General Interface Builder

To start the installer program:

1. Log into the machine as a user with administrative privileges.

2. Navigate to the installer directory on the installation media.

3. Double-click TIB_gi-builder-simple_3.0.0_w32.exe.

4. In the Welcome screen, click Next.

5. Review the license text, scroll to the end of the text and click I accept the terms of the License Agreements, then click Next.

If TIBCO General Interface 2.4.5 is installed, the following dialog prompts you to either overwrite or move the existing installation.

6. Read the Importance Notice text, then click Next.

The installer displays the TIBCO Home directory, which is specified the first time a TIBCO product is installed on this machine. The value cannot be modified. The directory name must not include any space characters.

7. Select Typical to install all TIBCO General Interface components, or select Custom to select the components to install, then click Next. The following table describes each component:

Component Name Description

TIBCO General Interface This option includes only the runtime framework.

TIBCO General Interface Builder

This option includes TIBCO General Interface Builder as well as the runtime framework.



8. Confirm your selections, then click Next.

9. Click Next to install the software.

10. Click Finish to exit the installer.

Documentation This option includes HTML and PDF files for online documentation.

Component Name Description


Installation Registry | 19

Installation Registry

The installer maintains an installation registry. The registry location depends on platform. This section explains where the registry files are located. The files have vpd as a prefix, which stands for Vital Product Database.

The installation registry is maintained in the %SystemRoot% folder. The following files represent the installation registry:

%SystemRoot%\vpd.properties%SystemRoot%\vpd.properties.tibco.systemName

Installer Disk Space Requirements in Temporary Area

The entire package is extracted into a temp folder, typically SystemDrive:\Temp or SystemDrive:\Documents and Settings\<user_name>\Local Settings\Temp.

The installer requires 11MB of free space in the temp directory.

Installation HistoryThe installer and uninstaller creates a file called TIBCOInstallationHistory.xml in the same location where the installation registry is created. Each time an installation and uninstallation is performed, entries are appended to the file.

On Windows: %SystemRoot%\TIBCOInstallationHistory.xml

The file TIBCOInstallationHistory.xml therefore contains the record of all installation and uninstallation activities of all products, features and components.

Do not edit, modify, rename, move, or remove any of the registry vpd files.

Do not edit, modify, rename, move, or remove the TIBCOInstallationHistory.xml file.



Starting TIBCO General Interface Builder

TIBCO General Interface Builder must be served from a Windows file server so that edits and updates can be saved to disk.

To start TIBCO General Interface Builder:

1. In Internet Explorer, open the GI_Builder.html file in the folder where TIBCO General Interface Builder was installed.

For example, if the software was installed in the C:\TIBCO\gi\ directory, a developer can access it from the Windows file server by opening C:\TIBCO\gi\GI_Builder.html in the browser.

The following prompt displays:

TIBCO General Interface Builder uses the Microsoft File System Object for reading and writing files to and from the file system.

2. Click Yes to enable file system access for the browser.


Starting TIBCO General Interface Builder | 21

The application window displays:

The first time TIBCO General Interface Builder is started after installation, the application window is blank. Using the Projects menu, you can either create a new project or open an existing project. For instructions on creating new projects, see Chapter 4, Building a Simple Application.


| 23

Chapter 3 TIBCO General Interface Builder Basics

This chapter provides an overview of TIBCO General Interface Builder features.

Topics

• Interface Basics, page 24

• Container Architecture, page 26

• Object Modeling, page 27

• Data and Cache Management, page 31

• Business Logic Development and Debugging, page 33

• Data Connection and Mapping, page 35

• API Documentation, page 37


24 | Chapter 3 TIBCO General Interface Builder Basics

Interface Basics

Developers familiar with visual, component-based environments such as Microsoft VisualBasic and Borland JBuilder will notice some parallel constructs in TIBCO General Interface Builder. Feature similarities include tools like data connection wizards, event-binding, and object modeling.

The following diagram describes the main interface elements of TIBCO General Interface Builder:

Figure 6 TIBCO General Interface Builder Window

Projects are collections of files you create and edit in TIBCO General Interface Builder. When a project is created, the default files logic.js and appCanvas.xml are created and opened for you in work area tabs. Developers create and modify application components in the work area, using palettes and tool dialogs. All palettes can float, or be minimized or repositioned for convenient access.

TIBCO General

Palettes

Work

System

Current

LinkProject

Log Panel

Area

Interface Builder Menu

Browser Menu

Open File Tabs


Interface Basics | 25

Figure 6 shows the default application layout before modification. If you modify the layout, this information is saved and the next time TIBCO General Interface Builder is started, the modified layout is used.

Component definitions and other application files are saved on a local or remote file system, and a third-party source control system can be used to manage files.



Container Architecture

TIBCO General Interface uses a container-based model for visual components, similar to that of Java Swing and other object-based GUIs. Rather than treating a web application as a series of hyperlinked pages, this architecture provides true object modeling when building an application.

Container-based architectures have significant advantages, including:

• Intelligent data refresh Specific containers can be targeted for updates while others remain untouched. Compared with refreshing an entire HTML page, less network bandwidth and CPU time is required.

• Incremental functionality An application can import additional object sets only when required. The application initializes and responds faster because only a minimum object set is loaded. User actions can drive the loading of additional functionality. TIBCO General Interface Builder is an example of a robust application that loads functionality on demand.

• Modular design paradigm Developers work in a familiar, modular environment that is more efficient than the clutter and confusion of HTML. High- level objects such as List Views and Dialogs take the place of DIV and SPAN tags. Rather than dealing with browser-specific event models and DHTML syntax, a simple property value, such as red, Arial, or 20 can be specified.


Object Modeling | 27

Object Modeling

Component Libraries PaletteThe Component Libraries palette provides a wide array of GUI prototype objects for adding functionality to your application. Components are organized in folders according to function. For example, objects in the Containers folder such as Dialog, Layout, and Tabbed Pane act as containers for other objects. Form Elements objects, such as Text Area, Button, and Select collect user input.

Figure 7 Component Libraries Palette

These object libraries not only reduce the time required to build applications, they also allow object behavior and look and feel to be easily customized. Objects such as list views and tree views that normally require custom JavaScript code can be added to your application using drag and drop.

Prototype objects can be dragged from the Component Libraries palette to any object in the work area, or to the Component Hierarchy palette. A new object of the selected type is created as a child of the object where it was dropped.

You can also create, manage and share your own libraries of components. Saving a component definition to the <install_dir>\user\prototypes directory adds it to the User folder in the Component Libraries palette. The custom component can then be reused like any other prototype component.



Component Hierarchy PaletteThe Component Hierarchy palette lets you view and manage the hierarchical model of objects in your application.

Figure 8 Component Hierarchy Palette

Objects can contain other objects, for example, a Tabbed Pane with multiple Tabs. A hierarchy of related objects and components is a component. For example, a form component could include Text Box , Label, and Button objects, as well as other components. Applications usually consist of multiple components that work together using JavaScript logic.

In this palette, objects can be selected before making modifications. Once a component or object is defined, it can also be duplicated to quickly make multiple copies. Objects can also be exported to reuse in other applications, or imported from another project into the current one.

Properties Editor PaletteProperties provide an abstraction layer for the complexities of browser events models and DHTML syntax. The objects that make up prototype components are preconfigured with default property values, which can be modified.


Object Modeling | 29

Each object has a predefined set of properties that define look and feel, on-screen position, and other characteristics. When a component is selected, its properties display in the Properties Editor palette. Properties are name-value pairs, for example:

Property names display in the Name column. Clicking to the right of a property name displays a menu for specifying field values. Dynamic properties, once defined, can be selected from the menu. Static values are entered directly in the Value column, either by typing or selecting from a dropdown list in the right field.

Dynamic properties are object properties with values that are defined in resource (.jss) files. At run time, the application substitutes the appropriate value. This feature enables developers to define skins and localized versions for an application. For more information, see Chapter 9.

Events Editor PaletteIn addition to properties, objects can have events. Events detect user actions and react in a defined way, allowing your application to respond to user input. When a user clicks a Cancel button in a dialog, for example, an event can specify to close the dialog and discard any data that was entered.

The Events Editor palette provides a set of model events for each object. Events are name-value pairs, where the value is a JavaScript function.



Figure 9 Events Editor Palette

Event definitions are abstracted from HTML event attributes. For example, the Execute event for a component might trigger an onkeypress or onclick event.


Data and Cache Management | 31

Data and Cache Management

At the most basic level, a TIBCO 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. Developers can use viewing and editing features built into TIBCO General Interface Builder, or can opt to use external editors. After modifying a file on the file system, it can be reloaded into browser cache.

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

• Access to all component XML files for inspection and updates. Work area tabs provide multiple views of each component, including an editable XML view. Component definitions can be refreshed using the toolbar on the Component Hierarchy palette.

• Access to all cached XML and XSL files for inspection and updates. The Local Data Cache palette allows developers to view and open cached files for editing. Modified files can be saved and reloaded with a single command.

Figure 10 Local Data Cache Palette

• XML/XSL merge tool for testing the HTML output from a merge operation. A developer can view both the parsed HTML and its source. If parsing errors occur, error notification is provided.



Figure 11 XML/XSL Merge Tool

• Cache locking features that keep critical documents from being deleted from the cache.

• Character-level debugging that helps developers identify the location of any XML parse errors (see Figure 12)

Figure 12 System Log with XML Parsing Error

Compatibility with Source Control TIBCO General Interface application files can be managed by an external source control system. TIBCO General Interface Builder detects whether project files are read-only and prevents these files from being edited.


Business Logic Development and Debugging | 33

Business Logic Development and Debugging

Business logic tends to be different for each application, thus requiring custom code. TIBCO General Interface Builder includes several tools that make coding and debugging easier for the developer.

Figure 13 Included JavaScript File and Project File Palette

Project Files PaletteThe Project Files palette is a list of all files referenced by an application, including GUI components, XSL files, and included JavaScript files. Files are grouped according to type.

The ability to include JavaScript files in your project is a powerful feature for implementing business logic. Functions and other JavaScript constructs defined in an included file are loaded into browser cache, and can be used by all components of an application. Developers can edit JavaScript files in a tab in the work area of TIBCO General Interface Builder. Moving back and forth between writing code and implementing the logic in GUI components is quick and seamless.



When saving files in the work area, you can save changes to disk, update changes in memory, or both. Files must be saved in memory to be part of the live application. It is often useful to test code in memory before saving it to disk. A JavaScript Test Utility is provided for this purpose.

Dynamic Properties FilesDynamic properties can be used to customize look and feel, to localize the application with language resource files, and to create dynamic layouts. In all these scenarios, properties can be specified as static values or JavaScript.

Dynamic properties are defined in XML files that developers can open and edit in TIBCO General Interface Builder. When a dynamic properties file is opened in the work area, the tab includes custom editor features. When files are ready to save, they are saved with a .jss extension.

Figure 14 Dynamic Properties Editor


Data Connection and Mapping | 35

Data Connection and Mapping

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

SOAP Mapping UtilityThe SOAP Mapping Utility provides a visual environment for configuring and testing SOAP interactions, including data mapping, testing, and off-line development.

Visual Bindings

The utility provides a visual interface for mapping GUI components to SOAP elements. Developers can use drag-and-drop to create bindings for inbound and outbound SOAP messages. SOAP elements can be bound to the values of GUI objects, nodes in XML documents, and JavaScript variables. All mapping information is stored in an XML file referenced in the project. If modifications are needed, the developer reopens this file in the SOAP Mapping Utility.

Testing

When mappings are complete, the web service interaction can be tested. Developers can preview 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 is received.



Figure 15 SOAP Mapping Utility

Decoupled Web Service Development

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

Additional Visual ToolsAdditional protocols and interactions are supported using the TIBCO General Interface APIs. For more information on designing interactions, see the online API documentation in TIBCO General Interface Builder.

In future releases, visual tools similar to the SOAP Mapping Utility are planned for other protocols and interactions. For TIBCO General Interface feature updates and examples to assist the application development process, go to http://power.tibco.com.


API Documentation | 37

API Documentation

Online API documentation is available for all TIBCO General Interface classes and methods. To access API help, select Help>API Documentation from the TIBCO General Interface Builder menu.

Class summaries show detailed inheritance, implementing classes, and method information. You can use the Show Inherited Methods checkbox to toggle between the methods unique to the selected class and all methods available for this class.


| 39

Chapter 4 Building a Simple Application

This chapter is a tutorial that describes how to build a simple application using TIBCO General Interface Builder.

Topics

• Overview, page 40

• Create a New Project, page 41

• Add and Position Application Components, page 44

• Communicate with a Web Service, page 54

• Test the Application, page 63

• Summary, page 64


40 | Chapter 4 Building a Simple Application

Overview

This chapter demonstrates how to build a sample application that looks up city and state information by communicating with a web service. In TIBCO General Interface Builder, you create all the components that make up the application and run it to view the result.

The completed application, which allows end users to type a zip code and get the corresponding city and state, looks like the following:


Create a New Project | 41

Create a New Project

The first step is to create a new TIBCO General Interface project. A new project folder is created in the <install_dir>\JSXAPPS directory, and all application-specific files are created and saved in this folder.

1. Start TIBCO General Interface Builder by opening the GI_Builder.html file in the folder where the software was installed.

An ActiveX control prompt displays.

2. Click Yes to allow saving your work to the file system.

All default objects are loaded into the TIBCO General Interface Builder window.

3. Select Project>New Project from the application menu.

4. Type myAddressLookup in the Project/Directory Name field, then click Create.

5. Click Yes in the ActiveX prompt.

At this point, you can safely close the original browser window.

A new browser window opens with a new TIBCO General Interface Builder project. Two tabs with default, empty files are open in the work area, and a link with the project name and path, JSXAPPS/myAddressLookup, displays in the lower left corner. Clicking this link opens the project folder in a Windows Explorer window.

While building this sample application, all project data is stored locally in browser memory. The application is not automatically saved to the file system. If you close or refresh the browser window, or close a dialog without saving the contents, the data is lost.



A directory for the project is created in your <install_dir>\JSXApps directory. The project directory structure looks like the following:

The top-level project folder has the same name as your project, myAddressLookup in this example. All project folders include the following default subdirectories and files:

Table 4 Application Directory Structure

components Contains the XML files for application components. Each component has an associated XML file with object definitions.

When you create a new project, a default component named appCanvas.xml is created in this folder.

css Contains any CSS files used for defining application styles. These files can be referenced in the Properties Editor for an object.

js Contains included JavaScript files for your application.

When you create a new project, a default file named logic.js is created in this folder.

jss Contains dynamic properties files.

rules Contains rules files for connecting to web services. Rules files define the mappings between GUI components and SOAP message elements.

xml Contains any XML files with content data, such as default values, for the application.

xsl Contains any XSL files used for transforming application data.


Create a New Project | 43

This default structure can be modified, and additional folders can be created as needed.

config.xml Contains application configuration data, such as the path to the logic.js file, and whether the application is in live mode.

Table 4 Application Directory Structure



Add and Position Application Components

In this section, you create an interface component (a dialog), add a layout component to arrange space, and add subcomponents to the dialog. For all components, position information can be defined in two ways:

• Absolute positioning, with integer values for top, left, height, and width

• Relative positioning, using either a percentage of available space or by arranging components in sequence from top left to bottom right

This tutorial demonstrates both methods of positioning components.

Create the DialogA default GUI component file, appCanvas.xml, is open in a tab in the work area. The following steps show how to add a dialog component to this component.

The Component Libraries palette displays folders containing prototype components that can be added to the current component.


Add and Position Application Components | 45

6. In the Component Libraries palette, open the Containers folder and drag a Dialog component to the work area.

The work area should look like the following:

The Component Hierarchy palette shows that the new component is added as a child of the default block component of appCanvas.xml. In the work area, the component is automatically selected and bounded by a focus rectangle for changing its size and position.

Component Modification Tips:

• To select a component, either press Ctrl-click in the work area, or click the component name in the Component Hierarchy palette.

For components with complex mous behaviors, such as trees, menus, and buttons, Ctrl-click acts like a user click at run time. Use the Component Hierarchy palette for selecting these components.

• To move a component, click the positioning handle in the center of the focus rectangle, then drag to a new location. You can also change the position by editing object properties.

The work area tab shows the name of the appCanvas.xml component in a red font. This indicates that changes have been made since the component was last saved.



• To resize an absolutely positioned component, click and drag a resize handle on the focus rectangle.

• To delete a component, select the component and either press Ctrl+Delete in click the Recycle self button in the Component Hierarchy palette toolbar. Deleted components are stored in the Recycle Bin, and can be recovered if necessary.

• When a selected object is bound by the focus rectangle, most runtime mouse behaviors are ignored.

• To hide the focus rectange, either double-click the component or click the show/hide focus rectangle button in the Component Hierarchy palette toolbar.

7. Save the new dialog component, either by right-clicking on the appCanvas.xml tab in the work area and selecting Save, or by selecting File>Save from the TIBCO General Interface Builder menu.

The dialog is saved along with its parent component in an XML file in the <install_dir>\projects\myAddressLookup\components directory. After saving, the font on the work area tab changes color from red to black.

The next step is to modify properties of the dialog. To modify component properties, you select the component in the Component Libraries palette, then edit its properties in the Properties Editor palette.

8. Select the following components in the Component Hierarchy palette, then modify the specified values in the Properties Editor palette:

To save a value, press the Tab or Enter key after typing the value. The Name property is an internal name for the dialog object, and the Text/HTML property of the caption bar component provides the text label for the dialog in the application.

Do not click the dialog close button in the work area. The work area in TIBCO General Interface Builder is a running TIBCO General Interface application, and closing the dialog actually removes the dialog component from the Component Hierarchy palette. In case of accidental deletions, components can be recovered in the Recycle Bin.

Component Name Property Name Property Value

dialog Name addressLookupDialog

caption bar Text/HTML Address Lookup Service




The sample address lookup dialog requires several subcomponents, which you add and resize in the following steps.

9. In the Component Libraries panel, open the Containers folder and drag a Layout (--) component to the addressLookupDialog component in the work area.

This component provides two panes, or regions, for laying out application components.



Customize Pane PropertiesIn this section, you set the properties for each pane in a Layout component, including background color, size, and display name.

1. Select the following components in the Component Hierarchy palette, then modify the specified values in the Properties Editor palette.

Values preceded by an @ symbol are dynamic properties. To access static or dynamic property values in the Properties Editor palette, click in the Name column. A menu displays options for the current property.


layout Size Array 50,*

pane (first) Name inputPane

BG Color @Solid Medium

Border @No jsxborder

pane (second) Name outputPane

BG Color @Solid Light

Border @Outset



The component hierarchy and the work area should look similar to the following:

2. Save the appCanvas.xml component.

Add Form Elements to the DialogText fields are required for entering a zip code, and for displaying returned city and state information. The sample application also requires a button for calling the web service.

1. In the Component Libraries palette, open the Block folder and drag a Block(100pct) element to the inputPane component.

2. Open the Form Elements folder and drag a Label object and a TextBox object to the Block component in the Component Hierarchy palette.



The component hierarchy should look like the following:

3. Select the following components in the Component Hierarchy palette, then modify the specified values in the Properties Editor palette:

4. Click the block component to select it, then click the Clone toolbar button twice to create two copies of the component.

5. Drag the two copies, each composed of a block parent with label and textbox children, to the outputPane component.


block Height 18

Padding @8pixel

Overflow Expand

label Height 18

Padding padding-top:4px;

Margin margin-right:4px;

textbox Height 18

Margin margin-right:4px;



The component hierarchy and work area should look like the following:

6. In the Properties Editor palette, modify the properties of the new objects as follows:


label (first) Text/HTML Type Zip Code:

textbox (first) Name zip

label (second) Text/HTML City:

textbox(second) Name city

Enabled Disabled

label (third) Text/HTML State:

textbox(third) Name state

Enabled Disabled



The dialog should look similar to the following:

7. Drag a Button component to the InputPane component and modify its properties as follows:

8. In the Events Editor palette, specify the following for the Execute event:

doTest();

You define the doTest(); function later in the tutorial, when defining the interaction between the web service and your application. This function calls


button Name lookUpButton

Text/HTML Find City and State



the web service that returns city and state information. When a user clicks the button, the zip code is sent to the web service.

9. Save the appCanvas.xml component.

The objects created in the previous steps are live application objects. When you save the parent component to disk, the parent and all child components are saved with the current object states.



Communicate with a Web Service

In this section, you create a rules file that defines the communication between a TIBCO General Interface component and a web service. TIBCO General Interface supports a variety of protocols for communicating with network services including XML GET, XML RPC, SOAP, HTML GET, and HTML FORM POST. This sample application communicates with a web service that uses SOAP.

1. Select File>New>Mapping Rule.

The SOAP Mapping Utility displays:

You use the SOAP Mapping Utility to configure a rules file for communicating with a web service. The rules file is an XML file with mappings of SOAP message fields to TIBCO General Interface components.

This tutorial uses the default WSDL file, Address.wsdl, so the WSDL URL value is already specified.

2. With the default value, JSX/addins/wsdl/wsdl/Address.wsdl, specified in the WSDL URL field, click the Parse WSDL button.


Communicate with a Web Service | 55

WSDL structures defined in the file are parsed and displayed in the Rules Tree panel on the left.

Map Dialog Fields to SOAP Parameters1. Locate ReturnCityState in the list of available methods and expand the request

and response operations defined for this method.

The WSDL file defines a single request operation, ReturnCityState, with two input parameters, zipcode and LicenseKey. To map TIBCO General Interface components to SOAP method parameters, you drag components from the Component Hierarchy palette directly to the Rules Tree.

2. Drag the zip component from the Component Hierarchy palette and drop it on the zipcode input parameter in the Rules Tree.

The request node in the Rules Tree is updated to show a binding to the zip component:

For the LicenseKey parameter, you specify a value of 0 for an evaluation license. The evaluation license provides limited access to the service during testing. If the designated number of requests is exceeded, an error is returned.



3. Click LicenseKey in the Rules Tree, then type the following in the Scriptlet field in the Rules Editor:

setValue("0");

Notice that values are enclosed in quotation marks, since the values are JavaScript values. These values could be modified, for example by replacing them with new values or JavaScript functions or variables.

The setValue method is a global method that allows you to set a value for a component. See the TIBCO General Interface API Reference for more information.

4. Click Add to bind the JavaScript method call to the input parameter.

The next step is to bind components to response parameters.

5. Drag the city component from the Component Hierarchy palette and drop it on the City input parameter in the Rules Tree.

6. Drag the state component from the Component Hierarchy palette and drop it on the StateAbbrev input parameter in the Rules Tree.

When the response is received, these values are displayed in the dialog fields. The Rules Tree should show the following mappings:

7. Save these mappings by clicking the Save toolbar button.



The Save File dialog displays.

8. Open the rules folder, specify GetCityandState.xml as the name of the rules file, then click Save.

Associate an Operation with a GUI ComponentAt this point, bindings exist between SOAP fields and dialog components, and both outbound and inbound SOAP messages have been verified. The button in the dialog is already configured to execute a JavaScript function, doTest, for calling the web service. In this section, you define the doTest function code and add it to your project.

1. Click the Code Generator button in the SOAP Mapping Utility toolbar, and select ReturnCityState from the list of operations.

The JavaScript code for invoking this operation is copied to the clipboard. The code defines a JavaScript function that creates a service instance. The service instance submits the GetCityandState.xml file to the web service and receives the ReturnCityState operation results.

The following prompt displays:

2. Click OK.

3. Click the minimize button at the upper right corner of the SOAP Mapping Utility to minimize the window. A minimized icon remains in the toolbar. Clicking the icon restores the utility window.

4. In the Project Files palette, click the logic.js tab to display the file contents in the work area.

This file contains business logic for your application. It should be empty except for the following comment line:

/*place JavaScript code here */

5. Click in the work area and press Ctrl-V to paste the contents of the clipboard into logic.js.




In addition to creating a service instance, the JavaScript code includes commented lines for specifying an inbound URL, user name, password, and service URL. Setting these values is not required for this example.

After the Find City and State button is clicked and the web service is called, the function displays an alert dialog containing the text The service call is complete.

6. With the logic.js tab open in the work area, select File>Save and Reload.

This command saves the file with the modified contents and also replaces the older version of the file in browser cache.

Test the Rules FileThe SOAP Mapping Utility provides features for testing web service configuration before deploying an application. You can verify outbound and inbound SOAP messages, component bindings, and service connectivity. It is also possible to insert breakpoints at each step in the process.

1. Simulate user input by manually typing a valid 5-digit or 9-digit zip code in the Type Zip Code: field in the dialog in the work area.

2. Click the Test Rules tab in the SOAP Mapping Utility window, then select ReturnCityState from the dropdown list.



3. Before testing the mappings, insert break points for viewing request and response messages at each step in the process.

a. Click the Send tab and insert a break point by clicking the Pause before sending the message button.

b. Click the Apply tab and insert a break point by clicking the Pause before executing inbound mappings button.

4. Click the Create tab.

The Outbound Mappings panel lists bound request parameters and mapping information.

5. To begin testing the mappings, click the Start Test button next to the Outbound Mappings header.



When the SOAP message is generated, the message displays in the Send tab.

6. Verify the message code matches the following:

<SOAP-ENV:Envelopexmlns: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 xmlns:jsx1="http://ws.cdyne.com/">"><jsx1:zipcode>94304</jsx1:zipcode><jsx1:LicenseKey>0</jsx1:LicenseKey></jsx1:ReturnCityState></SOAP-ENV:Body>

</SOAP-ENV:Envelope>

After the <jsx1:zipcode> element, the zip code you specified in the dialog should appear. If message code is incorrect, return to the Edit Rules tab and verify that bindings are correctly specified before proceeding.

7. Click the Resume test (send message) button next to the URL field.

The outbound message is sent to the web service. When a response is received, the message displays in the Receive tab, then the utility automatically advances to the Apply tab.



8. Click the Receive tab to view the inbound message.

City and state information is returned in the <City> and <StateAbbrev> elements. However, this data has not yet been bound to dialog fields. If you view the dialog in the work area, the City and State fields are still blank.

9. Click the Apply tab.

The dialog displays inbound mappings to dialog fields.

10. Click the Resume (execute inbound mappings) button next to the Inbound Mappings header.



In the work area, you can see that inbound mappings are applied to dialog fields:

The City and State fields have a grey background because the fields are disabled. This is to prevent users from entering data in these fields.

The testing cycle for this web service configuration is complete, and the utility cycles back to the 1. Send tab.


Test the Application | 63

Test the Application

You can quickly test your work by following these steps:

1. Select Project>Deployment Options from the TIBCO General Interface Builder menu.

2. In the Project Deployment Options dialog, verify that the path to appCanvas.xml is specified in the Initial Component field.

3. Click Cancel to close the dialog.

4. Select Project>Run Project in TIBCO General Interface Builder.

If there are no errors, your application displays in a new browser window.

You can type a zip code value, click the button to submit the value to the web service, then view the result. To make this application accessible to end users, you could also deploy the application to a web server as described in Chapter 8.



Summary

This tutorial demonstrates how to build a basic TIBCO General Interface application, including the following common tasks:

• Modeling GUI components

• Specifying static and dynamic properties for objects

• Configuring web service communication

• Binding events to objects that call business logic


| 65

Chapter 5 Handling Data in Your Application

This chapter explains how to send, receive, and cache data in a TIBCO General Interface application. It also describes the Common Data Format (CDF).

Topics


• Receiving Data, page 67

• Sending Data, page 69

• Caching Data, page 70

• Using the Common Data Format, page 73


66 | Chapter 5 Handling Data in Your Application

Overview

TIBCO General Interface applications can receive any type of text data that is sent using an HTTP or HTTPS connection. XML data can be stored in browser cache for use in your application. Non-XML data requires some pre-processing tasks.

The HttpRequest class is used for exchanging data. HttpRequest provides a generic transport mechanism for text content, regardless of format. For a full description of this class and its methods, see the online API Documentation in TIBCO General Interface Builder.


Receiving Data | 67

Receiving Data

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

Receiving XML DataTo receive XML data, you call the getResponseXML method for the HttpRequest instance. This method returns a jsx3.Document object, which is an XML document in a format that TIBCO General Interface can use.

For example:

//create a function and get a handle to the request objectfunction doGetXMLData() {var request = new jsx3.HttpRequest();var listView = jsx3.GO("myListComponent");

//get user-specified data and open the request objectvar URL = jsx3.GO('myURLComponent').getValue();var reqSocket = request.open('GET',URL);

//send the data

reqSocket.send();

//get the reply as XMLvar repXML = reqSocket.getResponseXML();

If the response data is for consumption by a CDF component, you can write a function to load the data directly into the component. If data is for consumption by a non-CDF component or another purpose, you must also execute the setDocument function to load it into browser cache. For example:

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

For more information on the CDF, see Using the Common Data Format on page 73.

Handling Failures If the incoming XML cannot be parsed, the getResponseXML() call fails. One possible cause of failure is invalid XML, while another is unspecified content type. The server must set the Content-type field in the HTTP header to text/html. If the value is not text/html, the method call fails.

If the getResponseXML() call fails, call the getResponseText method, then parse the XML string into a jsx3.Document object.

For example:

var o = new jsx3.Document();o.loadXML("<XML_string>");if(o.getError().code == "0") alert('success');



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

Receiving Non-XML DataTo receive non-XML data, you call the getResponseText method for the HTTPRequest instance. This method returns the body of the response as a string value. It is not necessary to load the document into browser cache.

For example:

var strText = objRequest.getResponseText();window.alert(strText);

Non-XML data can be displayed in the application, or can be reformatted into CDF for use by a component. You can use JavaScript code or XSL templates and transformations to modify the data. Once data has been reformatted into XML, XSL, or CDF, it can be stored in browser cache and referenced by the TIBCO General Interface Cache API.


Sending Data | 69

Sending Data

You can send data from an application using either a HTTP GET or HTTP POST interaction.

The following describes the general pattern for sending data:

1. Create a new jsx3.HttpRequest instance.

2. Call the open method and specify the interaction type, either GET or POST.

For an asynchronous call (recommended), specify true for the Boolean bAsync parameter. Use an object callback or handler, which can be any function defined in an included JavaScript file. After calling open(), use the subscription mechanism provided by the EventDispatcher class. to receive the response.

3. Call the send method.

For a POST interaction, pass the string content as the only parameter to the method. For GET, use another content mechanism, such as an overloaded URL.

For example:

function sendRequest() {var req = new jsx3.HttpRequest();req.open("GET", "http://www.yahoo.com/", true);

var objSubscriber = new Object();objSubscriber.onResponse = function(objEvent) {var req = objEvent.target;// do something with req

};

req.subscribe(jsx3.HttpRequest.EVENT_ON_RESPONSE, objSubscriber, "onResponse");req.send();

}



Caching Data

Each server instance maintains a separate area of browser cache. A server instance corresponds to a tab in the work area in TIBCO General Interface Builder. Any XML document, including XML, CDF, and XSL files, can be stored in cache.

Browser cache is used when building an application and at run time. At run time, data must be programmatically loaded into cache before it can be displayed or used by an application component. When you work in TIBCO General Interface Builder, after a file is modified and saved it must also be reloaded to work with the new version.

Calling Cache MethodsTo load files into cache for use at run time, you call methods of the jsx3.Cache class. However, all cache method calls must be qualified with application namespace information. If the namespace for your application is app1, when storing and retrieving documents use the syntax app1.Cache.<method_name>.

You can load any XML, CDF, or XSL document into cache using the openDocument method. This method allows you to specify the URL of a file to load into cache, then parses the file into a jsx3.Document instance. After specifying the URL, you can also automatically load the document by leaving the strId parameter set to null.

For example:

app1.Cache.openDocument("http://ibiblio.org/bosak/coriolan.xml");

This method call is always synchronous, so browser performance can be affected if the document is large.

To explicitly load a file into cache independently of the openDocument method, use the setDocument method.

To retrieve a file from cache, use the getDocument method. For example:

app1.Cache.getDocument("myDocument");

Components and Automatic CachingAll CDF GUI components and the BlockX component are cache-optimized. For example, when a CDF document is created, it is automatically loaded into the cache for the associated component. No separate method call is required. Also, association between a cached document and its identifier is predefined for convenience. For more information on the CDF, see Using the Common Data Format on page 73.


Caching Data | 71

TIBCO General Interface Builder also caches files for system use. For example, when you create a component that uses an XSL file to control look and feel, the associated XSL file is loaded into cache. At run time, an XSL file is loaded with the component it describes. In the Project Files palette, these filenames display in a regular, non-bold typeface to indicate they are not automatically loaded with the application.

Automatically and Manually Caching FilesIn TIBCO General Interface Builder, project files can be loaded automatically when the application loads. It is recommended to automatically load files that are needed by all users, without actions being performed. To manually specify which project files are automatically loaded into cache, do one of the following:

• In the Project Files palette, right-click on the file name and select Auto Load.

Any type of project file except a GUI component can be configured to automatically load. The file is available after the application initializes. For GUI components, only one component can be automatically rendered by the browser when the application is launched. This component is specified in the Project Deployment Options dialog, in the Initial Component field.

When you are working in TIBCO General Interface Builder, project files can also be manually loaded or reloaded into memory by doing the following:

• In the Project Files palette, right-click on the file name and select Load/Reload.

• In the work area, right-click on the associated tab and select Save and Reload after modifying the file.



XML, XSL, dynamic properties and rules files are loaded into the cache of each active server instance. GUI components are loaded into browser memory. Included JavaScript files are loaded into browser memory space and can be reloaded at any time. CSS files are loaded into browser memory only when the browser is launched.


Using the Common Data Format | 73

Using the Common Data Format

The Common Data Format (CDF) is a pre-defined schema for internal XML documents used by TIBCO General Interface applications. CDF provides a simple mechanism for interacting with complex data structures without using XSL. The following types of TIBCO General Interface components require data to be in the CDF:

• List

• Tree

• Grid

• Select and Combo

• Menu

• Charts

Understanding the CDF lets you map incoming data to CDF GUI components and manipulate CDF data. You can also enable features such as dragging and dropping between CDF GUI components.

Basic StructureA CDF document consists of a series of record definitions, which can include other records. Attributes describe the records. A hierarchy describes the relationship of records to each other.

The following example shows the structure of a typical CDF document:

<?xml version="1.0"?><data name="" number="" jsxid="jsxroot">

<record name="a" number="0" jsxid="null" jsxtext="Select a State"/>

<record name="b" number="1" jsxid="AL" jsxtext="ALABAMA"/><record name="c" number="2" jsxid="AK" jsxtext="ALASKA"/><record name="d" number="3" jsxid="AZ" jsxtext="ARIZONA"/><record name="e" number="4" jsxid="AR" jsxtext="ARKANSAS"/><record name="f" number="5" jsxid="CA" jsxtext="CALIFORNIA"/><record name="g" number="6" jsxid="CO" jsxtext="COLORADO"/><record name="h" number="7" jsxid="CT" jsxtext="CONNECTICUT"/><record name="i" number="8" jsxid="DE" jsxtext="DELAWARE"/>...

<record name="Y" number="50" jsxid="WI" jsxtext="WISCONSIN"/><record name="Z" number="51" jsxid="WY" jsxtext="WYOMING"/>

</data>

The jsxid attribute is required in all CDF documents. This attribute acts as a key, and should be a unique value.



Calling CDF MethodsIn addition to a set of component-specific methods, each CDF component also implements a common set of CDF methods. The CDF methods are provided for convenience, as an alternative to performing more complicated operations directly on XML data and using XSL.

Reading CDF Records

To query an object in a CDF document, use the getRecord method. This method is useful for determining the jsxid value for the currently selected record. After obtaining the jsxid value, the record can then be updated. For example:objList = jsx3.GO("list");objList.getRecord("CO").jsxid;

This code retrieves an object handle to the record with jsxid value of CO in a list object. It then returns the jsxid attribute of the specified record.

Updating CDF Records

To update an existing object or insert a new record in a CDF document, use the insertRecord method. The structure of the inserted object must match the schema of the CDF document. If a record with the specified id already exists, the record is updated. If the record id does not exist, a new record is added.

For example:

//get a handle to a list objectobjList = jsx3.GO("list");objList.setGrowBy(1);

//create a JavaScript object with name/value pairsvar o = new Object();o.name = "AB";o.jsxtext = "new state";o.jsxid = "xxx"

//insert the object into the listobjList.insertRecord(o);

CDF methods automatically handle routine GUI tasks, such as repainting the component after an object insertion. Since updating records is resource-intensive, the repaint operation is selective. When an update is performed using insertRecord(), only the changed row is repainted in the application. This feature makes the insertRecord method practical for updating application data in real time.


Using the Common Data Format | 75

When inserting new records, you must pass an integer value or an object to the setGrowBy method for a specific object. If an integer value is passed to this method, the CDF component adds the specified number of rows each time a record is inserted. If an object is passed, only a single row is added. By default, components do not expand when new records are inserted.

To update an existing attribute or add a new attribute in a CDF document, use the insertRecordProperty method. If an attribute with the specified id already exists, the attribute is updated. If the attribute id does not exist, a new attribute is added. For example:

objList.insertRecordProperty("xxx","number",456);


| 77

Chapter 6 Communicating with Web Services

This chapter describes how to communicate with web services in a TIBCO General Interface application.

Topics


• Mapping Components to WSDL Nodes, page 79

• Testing Outbound and Inbound Messages, page 84

• Mapping Response Data to CDF GUI Components, page 91

• Handling Errors and Timeouts, page 97


78 | Chapter 6 Communicating with Web Services

Overview

When a TIBCO General Interface application communicates with a web service, data is exchanged using SOAP messages over an HTTP connection. The HTTP connection is data-agnostic, and all SOAP-specific tasks are performed by an instance of the jsx3.Service class. The service instance uses a rules file that maps SOAP message elements to TIBCO General Interface components or CDF documents, records, or attributes. You create rules files in TIBCO General Interface Builder using the SOAP Mapping Utility.

Doc/ LiteralSupport

To begin creating a rules file, you load a local or remote WSDL file in the SOAP Mapping Utility. A WSDL file can conform to either doc/literal or RPC style. Only WSDL files that conform to the doc/literal style can be used in a TIBCO General Interface application. RPC style is unsupported.


Mapping Components to WSDL Nodes | 79

Mapping Components to WSDL Nodes

You use the SOAP Mapping Utility to create and edit rules files for your application. Rules files are XML files that define mappings between GUI components and SOAP message elements. The utility provides a simple drag-and-drop interface for creating mappings. You can also test rules files after mappings have been defined.

1. Select File>New>Mapping Rule to open the SOAP Mapping Utility.

A new rules file is created and the Edit Rules tab displays:

The utility window includes a toolbar and two tabs, Edit Rules and Test Rules. The Edit Rules tab is for mapping application components to SOAP message elements. The Test Rules tab is for verifying inbound and outbound messages after defining mappings.

In order to define mappings, you must first reference the WSDL file that contains web service definitions.

2. Specify the location of the WSDL file in the WSDL URL field. This value can be either a URL or a file system path. For local files, specify the path relative to the <install_dir> directory, for example JSX/addins/wsdl/wsdl/Address.wsdl.

3. Click the Parse WSDL button at the right of the WSDL URL field.



Structures defined in the WSDL file are parsed and displayed in the Rules Tree panel. Clicking an element displays the associated WSDL definition in the Original Schema Source field.

4. Arrange both the Component Hierarchy palette and the Rules Tree panel so that components and elements are visible.



5. Drag the component from the Component Hierarchy palette to the corresponding element in the Rules Tree panel.



The Rules Tree panel is updated to show the association between element and component. In the Rules Editor panel, the Map Type and Mapped Object ID fields display the type of mapped object and the mapped component name.

— The Scriptlet field can be used to specify JavaScript code that manipulates message structure or field data. For more information on using this field, see Using Code with Web Services on page 110.

— The Repeat field can be used to specify JavaScript code for iterating through a repeating node. As long as the condition evaluates to true for the mapped node, the logic is repeated. Your code must include logic for stopping the iteration process.

If the repeating node is mapped to a CDF component, iteration logic is handled for you and no custom JavaScript code is required. For more information on CDF GUI components, see Mapping Response Data to CDF GUI Components on page 91.

— The red [untitled] string at the upper right indicates the rules file has not yet been saved.

6. When all outbound and inbound mappings are complete, save the rules file by clicking the save toolbar button.

The Save File dialog displays. Although rules files can be saved anywhere in your project directory, a rules folder is provided.



7. Navigate to the rules folder and type the filename, with an .xml extension, in the field at the bottom of the dialog.

8. Click Save to save the file.

The [untitled] string is replaced by the file path at the upper right of the SOAP Mapping Utility window.

The rules file is an XML file in CDF format. The following is an example of a record that defines a SOAP element mapping. The mapped component name is shown in bold typeface.

<record jsxid="jsxoperation_AlternateCities_input_jsx_AlternateCities" jsxtext="AlternateCities" jsximg="c" jsxopen="1" jsxfullpath="/definitions/types/s:schema/s:element[index() = 22]" jsxdatatype="" jsxfriendlytype="" jsxbasename="AlternateCities" jsxtargetschemapath="/definitions/types/s:schema" jsxtargetnsprefix="s0" jsxtargetnsuri="http://ws.cdyne.com/" tns="http://ws.cdyne.com/" efd="1" afd="0" jsxmapobjecttype="DOM" jsxmapobjectname="zipcode"/>

</record>



Testing Outbound and Inbound Messages

The SOAP Mapping Utility includes features for verifying inbound and outbound SOAP messages generated using a rules file. The entire test sequence consists of executing outbound mappings, generating the outbound SOAP message, sending the message to the web service, receiving the response, and executing inbound mappings. Outbound and inbound filtering logic can also be entered and verified.

To test a rules file:

1. In the SOAP Mapping Utility, open the rules file to test.

2. Specify values for each mapped element, to simulate user input.

A simple way to specify values is to use the JavaScript setValue function in the Scriptlet field on the Edit Rules tab. For example:

setValue is useful for specifying constants normally specified by a user at run time, or a value that is calculated from user input. Values set in this way become a part of the application until they are deleted. To specify values for testing purposes only, you can edit the outbound message in the SOAP Mapping Utility before it is sent, or specify data in user input fields in the work area.

After specifying each value, click the Add button. Save the rules file when all values are specified.


Testing Outbound and Inbound Messages | 85

3. Click the Test Rules tab.

The Test Rules tab is designed to guide you through the test sequence. The Configure, Create, Send, Receive, and Apply tabs correspond to phases of sending and receiving SOAP messages. Clicking a tab displays data that is relevant to the current test phase.

The Configure tab provides several fields for customizing the SOAP message for an operation:

— Stub URL allows you to specify a preconfigured SOAP message template. A stub file is useful if the SOAP header, for example, requires customization.

— Inbound URL allows you to specify a file containing a SOAP message that contains a response for the current operation. Storing a local copy of response code is useful when the service is unavailable or when running the application in static mode.

— Endpoint URL allows you to use the endpoint information in one WSDL file location during testing, then later substitute different endpoint information.

4. Click the Create, Send, and Apply buttons and set breakpoints as needed.



Before running a test, you can set breakpoints at various steps in the test sequence by clicking a button. Breakpoints can be set at the following steps:

— Before applying filtering code, if specified, to the outbound message

— Before sending the outbound message to the web service

— Before applying filtering code, if specified, to the inbound message

— Before executing inbound mappings

You can also test a rules file without breakpoints. However, it is usually helpful to view the test results after each step. When advancing from one breakpoint to the next, you can return to the previous breakpoint to retest only that step in the process. After any modifications to mapping rules, changes can be tested from the last breakpoint.

5. Select the SOAP operation to test from the dropdown list at upper left.

Mappings for the outbound SOAP message display in the the Create tab.

This example shows mappings for the AlternateCities operation.

— The Node Name column contains the name of the SOAP element.

— The Map Type column shows the type of object that is mapped.

— The Mapped To column contains the GUI component name.

— The Scriptlet column contains any associated JavaScript code for this mapping.

6. Click the start test button next to the Outbound Mappings field.



The outbound SOAP message displays in the Send tab.

— The URL field contains the URL specified in the WSDL file.

— The HTTP Headers field contains header content for the SOAP message. The header text can be customized by editing this value.

7. If a breakpoint was set, click the resume button to advance to the next step.

The contents of the outbound and inbound SOAP messages can be saved to local files for testing purposes. By mapping the saved inbound file and specifying the application mode as Static in the Project Deployment Options dialog, you can continue developing your application without a web service connection.



The outbound message is sent to the web service, and the response is displayed in the Receive tab.

If the response is not received, testing can still proceed with a simulated response message. Click the generate alternate inbound message button to the left of the Response field. A response message for the specified operation is copied to the Response field.

8. If the utility does not automatically advance to the Apply tab, click the Apply button to advance to the next step.



Mappings of SOAP response nodes to GUI components are shown, along with inbound filtering logic, if any.

This is the final step in the testing process. If filtering logic and mappings executed without errors, the Create tab displays to allow you to start another testing cycle.

9. When testing is complete, close the SOAP Mapping Utility by clicking the close button at upper right.



Calling the Web Service

A rules file defines the interaction between your application and the web service. Once the rules file is complete, the application also needs to call the service. The SOAP Mapping Utility generates the function code, which you add to your project in an included JavaScript file.

To call a web service from an application:

1. With the rules file open in the SOAP Mapping Utility, click the Code Generator button.

A menu with a list of operations displays. Operations in the selected WSDL file with defined mappings are included in the list.

2. Select the name of the operation to invoke from the menu.

This copies JavaScript function code to the clipboard.

3. In the work area, open logic.js or any included JavaScript file in your project. A separate file can be used for code related to web service calls.

4. Click in the tab and press Ctrl-v to paste function code.

The function code has the following format:

function doTest() {var objService = new jsx3.Service("<rules_file_path>","<op_name>");//objService.setInboundURL("someRuntimeAlternate.xml");objService.setOnSuccess("onTest(this);");//objService.setUserName("loginname");//objService.setUserPass("password");

//objService.setServiceURL("anAlternatEndpointURL/forTheWebService/toContact/atRuntime/differentFromWSDL");objService.doCall();

}

function onTest(objService) {alert("The service call is complete.");

}

where rules_file_path is the path to the rules file relative to <install_dir>, and op_name is the name of the SOAP operation to invoke. Commented lines are optional, and can be removed if not needed. Function names and alert text can also be customized.

The onTest callback function is called when the web service responds. Communication between the application and the web service is asynchronous, so this function can be used for notification of a response.

5. Call the function from a GUI component, such as a button, using the Events Editor palette.


Mapping Response Data to CDF GUI Components | 91

Mapping Response Data to CDF GUI Components

After a receiving a SOAP response message, you can map response elements to components in your application. If the target component is a CDF component, the SOAP response must be transformed into CDF to be displayed in your application. An intermediate CDF document is created and stored in browser cache, where the component can access it.

Transformation is a two-step process. First, you map SOAP response elements to the equivalent CDF structures, then you map GUI components to the CDF structures. This section uses an example to demonstrate the process.

Map SOAP Elements to CDF EquivalentsYou can map SOAP elements to CDF structures using the SOAP Mapping Utility. The sample operation includes a repeating node in the response message, so for each element in the response a separate CDF record must be created.

The SOAP response has the following structure:

Due to the large number of response elements, a subset of the response structure is shown here.

When a user submits a stock symbol and a date range, a sequence containing one record for each date is returned. Each record contains attributes with values for that date.



To map SOAP response elements to CDF:

1. In the Rules Tree, select the parent element of the element that corresponds to a record in the CDF file.

In the example, the parent element is Quotes, which is defined as an array of repeating HistoricalQuote elements. Only child elements of Quotes need to be included in the CDF document.

2. Select CDF Document from the Map Type dropdown list in the Rule Editor.

In this case, you could also map the GetHistoricalQuotesRangeResult node to CDF Document.

3. Type a cache ID string for the CDF document in the Mapped Object ID field. For example, historicals.

This value becomes the cache ID of the CDF file, which appears in the Local Data Cache palette after the response is received and inbound mapping logic is applied. If the file exists, it is overwritten. If the file does not exist, a new file is created in cache. To persist the file, use the Cache.setDocument method.

4. Click Add to add the mapping.



In the example, the rules file looks like the following:

5. Select the element that corresponds to a record in the CDF file in the Rules Tree.

In the example, the element that corresponds to a CDF record is HistoricalQuote, which is the repeating node.

6. Select CDF Record from the Map Type dropdown list, then click Add to add the mapping. It is not necessary to specify a Mapped Object ID value.

When a repeating node is mapped to CDF Record, by default the rules file automatically iterates through each instance of the node until the end of the structure is reached.



In the example, the rules file looks like the following:

7. Select an element to map in the Rules Tree.

8. Select CDF Attribute from the Map Type dropdown list.

9. Type a string value in the Mapped Object ID field, then click Add to add the mapping. This value becomes the attribute name in the CDF file.

10. Follow the same process to create mappings for other elements to include in the CDF file: selecting the element, specifying CDF Attribute as the Map Type, specifying a name for the corresponding CDF attribute, then clicking Add to add the mapping.

If the response has nested nodes, you can replicate the nested structure using CDF Record and CDF Attribute mappings.

The jsxid attribute, which is required in every CDF file, acts as a key. You can map an existing element that acts as a key value, such as a date or other unique value, to jsxid. If no such mapping exists, the utility automatically adds a jsxid attribute to the CDF file and generates a unique value.

For convenience, you can also map an element to use as a visual cue to the jsxtext attribute.



In the example, the completed rules file with all mappings looks like the following:

Map GUI Components to CDF EquivalentsAfter transforming the SOAP response to CDF, you also need to map GUI components that consume response data to CDF elements. This example uses a List component to show how to create the mappings.

To map GUI components to CDF elements:

1. Select the top-level GUI object that will consume data in the Component Hierarchy palette. In this case, the top-level object is a List component.

2. Open the Properties Editor palette and specify the name of the cache document for the XML Cache ID property. In the SOAP Mapping Utility, this is the value of Mapped Object ID for the CDF Document mapping. In this example, the value is quotes.

3. Select the GUI object that will display data in the Component Hierarchy palette. In this case, the object is a column in the list.

4. Open the Properties Editor palette and specify a value of @jsxid for the Path property.

5. Repeat the process for other GUI objects, selecting them and specifying the appropriate CDF attribute name preceded by the @ character, until all mappings are complete.



Test the Rules File to View Data1. With the top-level GUI component open in the work area, test the rules file.

For details, see Testing Outbound and Inbound Messages on page 84.

When the SOAP response is received, a file with the specified name appears in the Local Data Cache palette. This file exists in the cache of the current component.

2. In the Component Hierarchy palette, click the Re-Fetch Data and Repaint button to display the response data in the list.


Handling Errors and Timeouts | 97

Handling Errors and Timeouts

Setting Timeout IntervalsYou can configure timeout intervals for a web service response using the setTimeouts method of the jsx3.Service class. This method has four parameters that specify timeout values for resolving the domain name, establishing the connection to the server, sending the data, and receiving the response. When calling setTimeouts(), all four parameters must be specified. For more details, see the description of this method in the API Reference in TIBCO General Interface Builder.

Handling ErrorsWhen a SOAP operation generates an error, the error information is returned to the HttpRequest object for the response. You can write a JavaScript function that gets the error information, adds business logic for handling the error scenario, and displays the error to the user.

To get the error information, call the getRequest method of the HttpRequest class to get a handle to the request object. Call the getStatus and getStatusText methods to get error information. Then, create the error handling logic using the setOnError and setOnSuccess methods of the jsx3.Service class.

The setOnError method takes either a string value to evaluate as code, or the name of a user-defined function to notify when the service call completes. Other methods of this class are also useful for performing error- related tasks. For example, getResponseText is useful for determining the data returned by the response.

In the following example, the myFailure function gets the HTTP response code for the error. The setUpService function uses the setOnError method to call myFailure when an error occurs. If the operation succeeds, the setOnSuccess method displays an alert window containing the text Operation Succeeded.

function myFailure(objService) {var objRequest = objService.getRequest();alert(objRequest.getStatus());

}

function mySuccess(objService) {var objRequest = objService.getRequest();

Error handling logic should not rely on the presence of an HTTP response code as an indicator of operation failure.



alert('Operation Succeeded');}

function setUpService() {var objService = new jsx3.Service("JSXAPPS/app1/services/historicals.xml","GetHistoricalQuotesRange");objService.setOnError(myFailure);objService.setOnSuccess(mySuccess);objService.doCall();

}


| 99

Chapter 7 Adding Custom Code

This chapter describes how to add custom JavaScript code to your application.

Topics


• Adding Code at the Component Level, page 102

• Adding Code at the Application Level, page 106

• Using Code with Web Services, page 110

• Testing JavaScript Code, page 111


100 | Chapter 7 Adding Custom Code

Overview

TIBCO General Interface Builder allows you to add business logic to your application by writing custom JavaScript code. Business logic is any type of coding required to meet a user-specific requirement. For example, you can query a web service when a user clicks a button, or open a detail view in a list when a user selects a row.

There are several ways to add custom JavaScript to an application, and the code is processed slightly differently depending on how it was specified. Table 5 is a summary of places in TIBCO General Interface Builder where you can specify code, and the impact of each method:

Table 5 Summary of JavaScript Customization Options

Scope Code Location What Code Does

Component Events Editor palette Each event can be associated with one or more JavaScript functions.

Component Component Profile view in work area

JavaScript code can be executed either before or after a component is loaded in the application.

Component Dynamic properties file

JavaScript code can be specified as the value of a dynamic property when the value is painted on-screen.

SOAP message

SOAP Mapping Utility

JavaScript code can be specified to manipulate SOAP message fields.

Application Project Deployment Options dialog

JavaScript code can be executed after the application loads and before the application is initialized.

Application JavaScript file included in project

A file containing JavaScript functions, method calls, constants, and so on can be included in a project. Any static execution is evaluated before components are loaded.

JavaScript Test Utility

Any JavaScript code can be checked for errors before adding it to the application.


Overview | 101

In TIBCO General Interface Builder, fields where you can specify JavaScript code are distinguished visually with a light blue graph pattern background.



Adding Code at the Component Level

If business logic affects only a single component, the scope of the associated code can be automatically restricted to just the component. To affect a single component, specify code in one of the following locations:

• the Events Editor palette

• the Component Profile view in the work area

• a dynamic properties file

Associating Code with an EventEach component has an associated set of events. For example, a button component has an Execute 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.

Associating JavaScript code with an event is useful when code should be executed for a single component only, usually in response to user interaction. The code is executed only if the component is deserialized or loaded at run time.

To associate JavaScript code with an event, type the code in the Value field in the Events Editor palette. For example:

The functions doListClick() and doShowDetails() are defined in an included JavaScript file that is loaded into memory. Events, along with other ways of specifying custom code in TIBCO General Interface Builder, can reference constructs in included JavaScript files.


Adding Code at the Component Level | 103

Executing Code Before or After DeserializationFor any component, you can specify JavaScript to execute before or after the object is deserialized. The code is executed at run time as well as in TIBCO General Interface Builder, immediately before or after the associated XML file is loaded.

With the component selected in the Component Hierarchy palette, code can be specified in the Component Profile view. To execute JavaScript code before or after component deserialization, type the code in the onBeforeDeserialize or onAfterDeserialize field. For example:



BeforeDeserialization

Example

Before deserialization, the XML file can be accessed directly using the objXML variable. For example, typing alert(objXML); in the onBeforeDeserialize field displays the contents of the serialization file in an alert dialog.

Executing JavaScript code before an object is deserialized is useful when code should be executed for a single component only, such as when the application includes functions required by a single component that is not always loaded. It is also useful for components that require initialization.

AfterDeserialization

Example

After deserialization, the root-level object in the serialization file can be accessed directly using the objJSX variable. For example, typing alert(objJSX); in the onAfterDeserialize field lists the properties of the root-levelobject in an alert dialog.


Adding Code at the Component Level | 105

Executing JavaScript code after an object is deserialized is useful when code should be executed for a single component only, and when information about the object, such as an identifier, is required for display in the application. For example, the object ID (which is created after deserialization) can be displayed in the caption bar of a dialog. This feature is also useful when reusing objects, to make behavior portable.

In both cases, the code is executed only if the component is loaded at run time.

Specifying Code in Dynamic PropertiesEach dynamic property has an eval property that can execute a JavaScript function. The returned result becomes the property value. This feature is useful for configuring a component 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.

For example:

The newDate function creates the current date and time in the browser preferred format. This function is evaluated any time the object is painted or repainted.

To associate JavaScript code with a dynamic property:

1. Open the .jss file in your project.

2. Check the Eval checkbox for the property, to indicate the value should be evaluated as code.

3. Type valid code in the Value field. Make sure the contents of this field can be executed as independent JavaScript code, with trailing semicolons for function calls, string values enclosed in quotation marks, and so on.



Adding Code at the Application Level

In many cases, business logic applies to multiple components and the associated JavaScript code is required by the entire application. To affect the entire application, specify code in one of the following locations:

• an included JavaScript file

• the Project Deployment Options dialog

Including JavaScript FilesThe 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 where you can specify JavaScript code, such as the Events Editor palette. The file must be loaded into memory to be accessed by your application.

JavaScript files can be created in TIBCO General Interface Builder, and are automatically added to your project. This feature promotes a best practice in application design, separating business logic from presentation.

A default JavaScript file, logic.js, is created and included in your project when the project is created. This file initially contains no code, and can be deleted from the project as needed. When adding business logic, you can add code to logic.js, or remove logic.js from the project and replace it with one or more new files, partitioning code among 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 according to feature area or functional role.


Adding Code at the Application Level | 107

For example:

To add a JavaScript file to your project, select File>New>JavaScript File. A new tab is added to the work area for editing the file contents.



For convenience, you can access a list of classes and methods in the TIBCO General Interface APIs by typing Ctrl-spacebar.

When saving files in the work area, you can save changes to disk, update changes in memory, or both. Files must be saved in memory to be part of the live application.

By default, logic.js is configured to automatically load after the application initializes. Other included JavaScript files can also be loaded automatically by right-clicking on the file in the Project Files palette and selecting the Auto Load option. If a file is required only for a specific module, you can load the file when needed using the loadResource method of the Server class.


Adding Code at the Application Level | 109

Executing Code Before the Application LoadsYou can execute JavaScript code immediately before the browser loads your application. The Project Deployment Options dialog includes a field for this purpose.

To execute JavaScript code before an application loads, select Project>Deployment Options and type the code in the onLoad Script field. For example:

In this example, the reference to the main application component appCanvas.xml is deleted from the Initial Component field, and a function myInit() that conditionally loads this component is defined in the onLoad Script field.

Executing JavaScript code before the application loads is useful for performing tasks that should complete before a user accesses your application. For example, you could add code that checks for the presence of an HTTP cookie before displaying a login dialog.



Using Code with Web Services

In the SOAP Mapping Utility, you can specify JavaScript code for performing tasks related to web 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 web service call, type the code in the Scriptlet field in the SOAP Mapping Utility. In this context, the root object is an instance of the jsx3.Service class. The service instance creates the SOAP messages that are sent to the web service. In the Scriptlet field, you can execute any method of the jsx3.Service class using the syntax this.<method_name>.

When sending data to a web service, you can write code to specify a value that is unknown at design time. For example, a user could specify the license key for using the web service at run time, then you could pass the license key in the SOAP message using the setValue() function.

The following example shows how to manually create a mapping between an application component named state and a SOAP message field.

When receiving data, you can use this feature to filter and validate return values, or parse data into the format required by your application.

A list of available constants and methods displays when you hover the cursor over the Scriptlet field label.


Testing JavaScript Code | 111

Testing JavaScript Code

The JavaScript Test Utility is a useful tool for debugging any issues with JavaScript code before adding it to your application. The utility provides a convenient, standalone test environment for your code. JavaScript code entered in the JavaScript Test Utility affects the application loaded in TIBCO General Interface Builder, but is not a permanent part of your application and does not affect the application at run time.

The utility provides direct access to the JavaScript memory space. When code is executed in this window, either the return value or any errors are displayed. Error detection features include null, object, method, and structural errors.

To check your code for errors:

1. Select Tools>JavaScript Test Utility.

2. Type code in the Enter JavaScript to evaluate/execute field.



3. Click the execute all button to test all the code, or click the step through code button to step through each line of code using the JavaScript Step-Through Debugger.

The following tips are useful when using the JavaScript Test Utility:

• To access a list of methods, type Ctrl-spacebar in the Enter JavaScript to evaluate/execute field. When you select a method from the list, a template method call is added to this field. Complete the syntax by editing template text.

• You can view the code of any method in the application namespace. Simply type the name of the method, for example myMethod, in the Enter JavaScript to evaluate/execute field, then click the execute all button. The method code displays in the Return Value field.

To execute the method, add the trailing parentheses, for example myMethod(). The return value, if any, displays in the Return Value field.

• Use the History button to access a list of recently executed statements. Clicking a statement in the list replaces all current code with the selected statement for execution.


Testing JavaScript Code | 113

The JavaScript Step-Through Debugger provides line-by-line access, object inspection, and insight into code execution. Supported operations include step into, step out of, execute all, and cancel execution. Only code within the context of a function can be debugged.

To use the debugger:

1. Open the debugger by doing one of the following:

— Click the step through script button in the JavaScript Test Utility

— Add the return jsx3.ide.debug statement to your code in the JavaScript Test Utility, immediately below the function declaration. The debugger opens with the function already loaded.

The line of code that will be executed is highlighted in yellow.

2. Click the execute statement button to execute the current line of code, or click the execute all button to execute all code in the dialog.

If the code has a return value, the value is displayed in the field below. For more information about objects that are returned, click the blue links in this field.



For execute all, execution stops when an error is found. To skip the error and resume execution, click the skip statement button.

3. To close the debugger, click the cancel/close button.

Stepping out of code is not supported. It is recommended to avoid debugging loop constructs with many repeating steps.


| 115

Chapter 8 Deploying Applications

This chapter describes how to deploy TIBCO General Interface applications.

Topics

• Deploying as a Full Console Application, page 116

• Posting Applications for Deployment, page 118

• Accessing Applications, page 119


116 | Chapter 8 Deploying Applications

Deploying as a Full Console Application

If users need to launch your application as an independent application, a separate launch page is required. A launch page is an HTML file that provides access to the application. This file initializes the TIBCO General Interface environment, loads your application into the browser, and renders it to the entire HTML page. TIBCO General Interface Builder provides a simple utility for generating this file.

To generate a launch page for your application:

1. Select Project>Launch Page Utility from the TIBCO General Interface Builder menu.

Figure 16 Launch Page Utility

2. Click the Browse button and type the launch file name, for example launch.html.

Launch files must be in the same directory as the JSX and JSXAPPS directories.

3. Click Save.

4. On the HTML Page tab, click the Create button to create the launch file.

A new file is created in the required folder.

If users need to launch the application from an existing web page, you can build a hyperlink or similar trigger into an existing web page for launching your application. In this case, there is no need to create a launch page. Instead, you can copy and customize HTML code provided on the Launch Link or Inline DIV tabs in the Launch Page Utility.


Deploying as a Full Console Application | 117

5. In a web browser, open the launch file page.

After the TIBCO General Interface software initializes, your application displays. Before proceeding, you can view the source of the HTML page that was automatically generated.

6. Select View>Source from the browser menu to view the source of this page. The following lines of HTML code include your application in the HTML page:

— the < body> element

<body BGCOLOR="#9898a5" SCROLL="no" RIGHTMARGIN="0" BOTTOMMARGIN="0" LEFTMARGIN="0" TOPMARGIN="0" style="padding:0px;">

This element defines general window properties.

— the <div> element

<div id="jsxbodydiv" style="position:absolute;left:0px;top:0px;width:100%;height:100%;z-index:1;">

<div id="JSXWINDOW" style="width:100%;height:100%;" xmlns:v="urn:schemas-microsoft-com:vml">...

</div> </div>

The <div> element provides the HTML container for your TIBCO General Interface application. You can change the position and style of this element by modifying its CSS properties.

— the <script> element

<script language="JavaScript" src="JSX/js/JSX30.js?jsxapppath=JSXAPPS/myAddressLookup/">

</script>

The <script> element loads the initialization routine and passes the jsxapppath parameter, which specifies the folder containing the project you want to include.

The remaining HTML code configures the page and its title, including the Powered by TIBCO General Interface message that is displayed while the application initializes.



Posting Applications for Deployment

The final deployment step is to post TIBCO General Interface software and your applications on an HTTP or HTTPS web server. Unlike most web applications, TIBCO General Interface does not run in the 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. The same runtime model is also used for your application, as View-related processes are distributed to each additional client.

TIBCO General Interface is compatible with all HTTP/S web servers and requires no extra executables to be installed, either on the server or the client. Therefore, no configuration of the web server is necessary. The only required step is to place the JSX and JSXAPPS folders, along with any other files or folders containing the applications to deploy, in a directory accessible to the web server. Then, set access rights in the same manner as any standard HTTP/S accessible resource. The directory should look similar to Figure 17.

Figure 17 Deployment Directory Structure

Applications can be located in a folder directly below the directory where TIBCO General Interface is installed, or in a nested directory structure such as <install_dir>/JSXAPPS/<project_name>.


Accessing Applications | 119

Accessing Applications

This section describes how end users can access TIBCO General Interface applications.

To access an application:

• In a browser on the client machine, navigate to the URL where the application files were deployed.

For example, if the application was deployed to the URL http://www.myserver.com, the user accesses the application by navigating to:

http://www.myserver.com/<project_launch_file_path>

where project_launch_file_path is the path to the HTML file for launching your application, relative to the HTML doc root directory of the HTTP server.

AccessingLocalized

Applications

To access a localized application, the end user machine must have the language packs required for viewing the application installed. Any language pack supported by the Microsoft Windows operating system can be used for localizing the interface.


| 121

Chapter 9 Localizing Interfaces

This chapter describes how to localize interfaces built using TIBCO General Interface Builder.

Topics


• Setting Default Unicode Behaviors, page 123

• Using Dynamic Properties, page 124

• Using Static Properties, page 129


122 | Chapter 9 Localizing Interfaces

Overview

TIBCO General Interface applications, including TIBCO General Interface Builder can be localized to languages and character sets other than English. Using both static and dynamic properties, interface text can be modified for the appropriate locale. Users can select a display language at run time, or the developer can define a specific language to use by default.

Application text strings are stored either in a resource file with .jss extension or a static XML document in CDF format. For TIBCO General Interface Builder, CDF documents containing text strings are located in the <install_dir>\GI_Builder\language\eng.

At any time, only one .jss file is loaded into memory. TIBCO General Interface applications do not automatically check browser locale settings, but you can write JavaScript code for this purpose. For example, if an app_english.jss automatically loads when the project is launched, it can be replaced with an app_espanol.jss file if a startup script detects a localization property such as:

• navigator.browserLanguage (Browser - Localized Language)

• navigator.systemLanguage (Windows - Localized Language)

• navigator.userLanguage (Windows - Regional Settings)


Setting Default Unicode Behaviors | 123

Setting Default Unicode Behaviors

Localizing an interface usually involves creating and saving one or more files containing non-ASCII characters. Before saving any files in your application, be sure to specify that files should be saved in Unicode format.

To save application files in Unicode format:

1. Select Project>Deployment Options.

The Project Deployment Options dialog displays:

2. Click the Yes radio button for the Unicode option.

3. Click Save.



Using Dynamic Properties

With dynamic properties, localized text is stored in resource files that are part of your application.

Creating Resource Files1. To create a resource file with dynamic properties, select File>New Dynamic

Properties File (.jss) from the TIBCO General Interface Builder menu.

A new tab is created in the work area, with fields for managing dynamic properties:

In this tab, create a property and value for each string to localize in your application.

2. Create new properties by clicking in any field in the last row.

A new property line is automatically added below the current line. Any empty lines that remain do not affect the properties file.

3. To configure properties:

a. Click in the id field, then type a name for the property. You can also use the default name, jsx_#, where # is a positive integer.

b. Select the appropriate type from the type dropdown list.

c. Type a value in the value field.

This value is used when the associated id is specified for an object property, and the .jss file is loaded by the application.


Using Dynamic Properties | 125

For example:

4. Save the dynamic properties file by either selecting File>Save from the menu, or right-clicking on the tab in the work area and selecting Save.

5. In the Save As dialog, navigate to the jss folder and save the file with a .jss extension, for example english.jss.

6. Repeat these steps, creating a separate file for each set of localized strings required by your application.

Substitution variables can be included in the value string. For example, for a dynamic property named tokenProp with a value of Error encountered in the {0} component, at run time the token in the dynamic property can be replaced with a string using the following JavaScript code:

myServer.getDynamicProperty(’tokenProp’, "appCanvas.xml")



For example, if your application supports Japanese as well as English, you would define the following additional values for the same set of properties, using a separate dynamic properties file:

Specifying a Default LanguageWhen a dynamic properties file is created or opened in TIBCO General Interface Builder, the file is automatically loaded into browser memory. Files currently loaded in memory are listed in the Project Files palette in the Dynamic Properties Files folder.

You can use right-click menu commands to open a file, edit the location and other metadata, specify a file as the default, remove a file from the project, reload a modified version into browser cache, and copy the location for use in JavaScript code.


Using Dynamic Properties | 127

To specify a default language for the application, you designate the appropriate dynamic properties file to load by default, when the application is initialized.

To load a dynamic properties file when the application starts:

• Right-click on the file name in the Project Files palette and select Auto Load from the menu.

If multiple resource files in the application are configured to automatically load, at run time the last file loaded into memory is used by default.

Referencing Dynamic PropertiesYou can assign the properties defined in a dynamic properties file to objects in your application. The lookup menu in the Properties Editor palette, which displays when the Name field for a property is clicked, displays all dynamic properties of the correct type. To reference a dynamic property, select the property name in the list. If a property is missing from the list, either the corresponding .jss file is not loaded into memory, or the file has been modified and needs to be reloaded.

For example, each interface element has a default caption defined by the Text/HTML property, and the default caption text is static. To make the caption text dynamic and localizable, you modify the Text/HTML property.

1. In the Project Files palette, click the item that corresponds to your .jss resource file, then click the load/reload button.

2. Select the component to modify, then click the property in the Properties Editor palette.

3. Click the right side of the Name field.



A menu displays with a list of properties defined in the loaded resource file. Only dynamic properties of the correct type are listed. Click a property name to select it.

This step associates the text property with the dynamic property in the resource file. In the work area, the associated text for the component is updated with the value of the dynamic property.

4. Repeat the previous step for all other properties to localize.

Enabling Runtime Language SwitchingTo view the effect of assigning a dynamic property, create a menu or dropdown list for the user to switch between resource files at run time. For example, a Menu component uses the following XML code to define options:

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

</data>

This XML code can be defined in the XML (String) property of a Menu object, or in a separate file referenced in the XML URL property.

To enable end users to switch between multiple languages, with strings for each language defined in a dynamic properties file, you modify the menu XML code. For example:

<data jsxid="jsxroot"><record jsxid="1" jsxtext="Display English" jsxexecute="jsx3.GO('block_localize').getServer().loadResource('english_jss');jsx3.GO('block_localize').repaint();"/>

<record jsxid="2" jsxtext="Display Chinese" jsxexecute="jsx3.GO('block_localize').getServer().loadResource('chinese_jss');jsx3.GO('block_localize').repaint();"/>

<record jsxid="3" jsxtext="Display French" jsxexecute="jsx3.GO('block_localize').getServer().loadResource('french_jss');jsx3.GO('block_localize').repaint();"/>

</data>

In this example, the menu provides three options: Display English, Display Chinese, and Display French. The root object in the component hierarchy is named block_localize. All objects with localized strings are children of this object. When the Display French option is selected, for example, the french_jss dynamic property file is loaded and the application repaints the block_localize object using this resource file.


Using Static Properties | 129

Using Static Properties

In addition to interface elements with dynamic caption text, you can create interface elements with static, localized text. With static properties, your application components use only the specified localized text they were configured to use. Any application component that displays text or contains default text can use a static property.

1. With your application open in TIBCO General Interface Builder, select the component to localize in the Component Hierarchy palette.

2. Modify component properties by specifying localized text.

— For components that have text properties, click the Text/HTML property in the Properties Editor palette and type or paste localized text in the Value field.

— For components that can contain text, such as a TextBox component, type or paste localized text in the component directly in the work area.

— For components that can display XML code, type or paste localized text in thr Properties Editor palette, or create an XML file and save the file in Unicode format.

For example:

In this example, Chinese characters are specified for the dialog caption bar object and for the label object. These characters were specified by editing the Text/HTML property in the Properties Editor palette.

Chinese characters are also specified as default text for a TextBox Row (short label) component. These characters were specified by modifying the



component directly in the work area. At run time, this string becomes the default value of the component.

The XSLT Block component shown in this example also contains Chinese characters. The following example describes how to configure a component that displays XML to use localized text.

XML DataExample

Components that display XML data have an XML (String) property that specifies the XML document as a string value. By default, the XML (String) property for the XSLT Block component has the following value:

<helloworld></helloworld>

You can either specify localized text directly in the Properties Editor palette, or create an XML file and reference the file using the XML URL property. To create an external file, select File>New>XML Document in TIBCO General Interface Builder. Edit the file in the work area, adding an XML markup declaration line and using the following element structure:

<?xml version="1.0"?><sample>data</sample>

Replace the data string in the <sample> element with localized text, keeping the structural elements of the XML code intact.

For example:

<?xml version="1.0"?><sample> </sample>

Save the file with an .xml extension, with the Unicode field in the Project Deployment Options dialog set to Yes. To display localized data in the work area, select the component in TIBCO General Interface Builder, then click the refresh data and repaint toolbar button.


TIBCO Software Inc. End User License Agreement | 131

TIBCO Software Inc. End User License AgreementREAD THIS END USER LICENSE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THE SOFTWARE, YOU AGREE TO BE BOUND BY THIS AGREEMENT. IF YOU DO NOT AGREE TO THESE TERMS, DO NOT DOWNLOAD OR INSTALL THE SOFTWARE AND RETURN IT TO THE VENDOR FROM WHICH IT WAS PURCHASED.

Upon your acceptance as indicated above, the following shall govern your use of the Software except to the extent all or any portion of the Software (a) is subject to a separate written agreement, or (b) is provided by a third party under the terms set forth in an Addenda at the end of this Agreement, in which case the terms of such addenda shall control over inconsistent terms with regard to such portion(s).

License Grant. The Software is the property of TIBCO or its licensors and is protected by copyright and other laws. While TIBCO continues to own the Software, TIBCO hereby grants to Customer a limited, non-transferable, non-exclusive, license to use the number of Permitted Instances set forth in the Ordering Document, in machine-readable, object code form and solely for Customer's internal business use.

Restrictions. Customer agrees not to (a) make more copies than the number of Permitted Instances plus a reasonable number of backups; (b) provide access to the Software to anyone other than employees, contractors, or consultants of Customer; (c) sublicense, transfer, assign, distribute to any third party, pledge, lease, rent, or commercially share the Software or any of Customer's rights under this Agreement (for the purposes of the foregoing a change in control of Licensee is deemed to be an assignment); (d) use the Software for purposes of providing a service bureau, including, without limitation, providing third-party hosting, or third-party application integration or application service provider-type services, or any similar services; (e) use the Software in connection with ultrahazardous activities, or any activity for which failure of the Software might result in death or serious bodily injury to Customer or a third party; or (f) directly or indirectly, in whole or in part, modify, translate, reverse engineer, decrypt, decompile, disassemble, make error corrections to, create derivative works based on, or otherwise attempt to discover the source code or underlying ideas or algorithms of the Software.

Beta and Evaluation Licenses. Notwithstanding the foregoing, if the Software is being provided for demonstration, beta testing, or evaluation purposes, then Customer agrees (a) to use the Software solely for such purposes, (b) that the Software will not be used or deployed in a production environment, and (c) that such use shall automatically terminate upon the earlier of thirty days from the date Customer receives the right to install the Software, or Customer's receipt of notice of termination from TIBCO.

Technical Support. Provided Customer has paid applicable support fees (not included with Software fees unless separately listed), TIBCO shall provide support for generally available TIBCO Software on an annual basis commencing on the Purchase Date, as follows ("Support"): Customer shall designate at TIBCO's support website https://support.tibco.com/eSupport/newuser.html, the number of technical support contacts permitted under the level of Support purchased (contacts are changeable upon 48-hours prior written notice to TIBCO). Each contact may contact TIBCO for problem resolution during TIBCO's published support hours corresponding to the level of Support fees paid.

Upon notice from a contact of a Software problem which can be reproduced at a TIBCO support facility or via remote access to

Customer's facility, TIBCO shall use reasonable efforts to correct or circumvent the problem according to its published support objectives. TIBCO reserves the right to make changes only to the most currently available version. TIBCO will use reasonable efforts to support the previously released version of the Software for a maximum of six months.

TIBCO shall have no obligation to support the Software (i) for use on any computer system running other than the operating system software for which the Software is approved (as set forth in the Software documentation) and licensed hereunder, or (ii) if Customer has modified or authorized a third party to modify the Software. TIBCO shall have no obligation to modify any version of the Software to run with any new versions of any operating system, or any other third party software or hardware. If Customer purchases Support for any Software, Customer must purchase the same level of Support for all copies of the Software for which it is licensed.

Support may be extended for one-year periods on the anniversary of each Purchase Date at the standard amounts set forth in its price list, for as long as TIBCO offers Support. Customer may reinstate lapsed support for any then currently supported Software by paying all Support fees in arrears and any applicable reinstatement fee. Upgrades, patches, enhancements, bug fixes, new versions and/or new releases of the Software provided from time to time under Support shall be used only as replacements to existing Permitted Instances, and shall not be deemed to increase that number, and use thereof shall be governed by the terms of this Agreement, except for the first paragraph of the Limited Warranty and any right of return or refund.

Consulting Services. Customer may request additional services ("Services") either in an Ordering Document, or by a separate mutually executed work order, statement of work or other work-request document incorporating this Agreement (each, a "Work Order"). Unless otherwise expressly agreed to in a Work Order, all Services and any work product therefrom shall be (a) performed on a time and materials basis, plus meals, lodging, travel, and other expenses reasonably incurred in connection therewith, (b) deemed accepted upon delivery, and (c) exclusively owned by TIBCO (except for confidential information of Customer identified to TIBCO in the Ordering Document), including all right, title and intellectual property or other right or interest therein. Each Work Order is intended to constitute an independent and distinct agreement of the parties, notwithstanding that each shall be construed to incorporate all applicable provisions of this Agreement. Specific to TIBCO training services, additional information regarding courses, registration, restrictions or limitation can be found at TIBCO's website at http://www.tibco.com/services/education under Education Programs. Fees for Services shall be due and payable in United States dollars net 30 from the date of TIBCO's invoice.

Limited Warranty. If Customer obtained the Software directly from TIBCO, then TIBCO warrants that for a period of thirty (30) days from the Purchase Date: (i) the media on which the Software is furnished will be free of defects in materials and workmanship under normal use; and (ii) the Software will substantially conform to its published specifications. This limited warranty extends only to the original Customer hereunder. Customer's sole and exclusive remedy and the entire liability of TIBCO and its licensors under this limited warranty will be, at TIBCO's option, repair, replacement, or refund of the Software and applicable Support fees, in which event this Agreement shall terminate upon payment thereof.


132 | TIBCO Software Inc. End User License Agreement

This warranty does not apply to any Software which (a) is licensed for beta, evaluation, testing or demonstration purposes for which TIBCO does not receive a license fee, (b) has been altered or modified, except by TIBCO, (c) has not been installed, operated, repaired, or maintained in accordance with instructions supplied by TIBCO, (d) has been subjected to abnormal physical or electrical stress, misuse, negligence, or accident, or (e) is used in violation of any other term of this Agreement. Customer agrees to pay TIBCO for any Support or Services provided by TIBCO related to a breach of the foregoing on a time, materials, travel, lodging and other reasonable expenses basis. If Customer obtained the Software from a TIBCO reseller or distributor, the terms of any warranty shall be as provided by such reseller or distributor, and TIBCO provides Customer no warranty with respect to such Software.

EXCEPT AS SPECIFIED IN THIS LIMITED WARRANTY, THE SOFTWARE, SUPPORT AND SERVICES ARE PROVIDED "AS IS", ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS, AND WARRANTIES INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTY OR CONDITION OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, SATISFACTORY QUALITY OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE, ARE HEREBY EXCLUDED TO THE EXTENT ALLOWED BY APPLICABLE LAW. NO WARRANTY IS MADE REGARDING THE RESULTS OF ANY SOFTWARE, SUPPORT OR SERVICES OR THAT THE SOFTWARE WILL OPERATE WITHOUT ERRORS, PROBLEMS OR INTERRUPTIONS, OR THAT ERRORS OR BUGS IN THE SOFTWARE WILL BE CORRECTED, OR THAT THE SOFTWARE'S FUNCTIONALITY OR SERVICES WILL MEET CUSTOMER'S REQUIREMENTS. NO TIBCO DEALER, DISTRIBUTOR, AGENT OR EMPLOYEE IS AUTHORIZED TO MAKE ANY MODIFICATIONS, EXTENSIONS OR ADDITIONS TO THIS WARRANTY.

Indemnity. If Customer obtained the Software from TIBCO directly, then TIBCO shall indemnify Licensee from and against any final judgment by a court of competent jurisdiction, including reasonable attorneys' fees, that the unmodified TIBCO Software infringes any patent issued by the United States, Canada, Australia, Japan, or any member of the European Union, or any copyright, or any trade secret of a third party; provided that TIBCO is promptly notified in writing of such claim, TIBCO has the exclusive right to control such defense and/or settlement, and Licensee shall provide reasonable assistance (at TIBCO's expense) in the defense thereof. In no event shall Licensee settle any claim, action or proceeding without TIBCO's prior written approval. In the event of any such claim, litigation or threat thereof, TIBCO, at its sole option and expense, shall (a) procure for Licensee the right to continue to use the TIBCO Software or (b) replace or modify the TIBCO Software with functionally equivalent software. If such settlement or modification is not commercially reasonable (in the reasonable opinion of TIBCO), TIBCO may cancel this Agreement upon sixty days prior written notice to Licensee, and refund to Licensee the unamortized portion of the license fees paid to TIBCO by Licensee based on a five-year straight-line depreciation. This Section states the entire liability of TIBCO with respect to the infringement of any Intellectual Property rights, and Licensee hereby expressly waives any other liabilities or obligations of TIBCO with respect thereto. The foregoing indemnity shall not apply to the extent any infringement could have been avoided by use of the then-current release.

Limitation of Liability. EXCEPT AS PROVIDED UNDER INDEMNITY OR RESULTING FROM A BREACH OF CONFIDENTIALITY (THE "EXCLUDED MATTERS"), IN NO EVENT WILL EITHER PARTY OR TIBCO'S LICENSORS BE LIABLE FOR ANY LOST DATA, LOST REVENUE, LOST PROFITS, DAMAGE TO REPUTATION, BUSINESS INTERRUPTION, OR ANY OTHER

INDIRECT, INCIDENTAL, CONSEQUENTIAL, SPECIAL, PUNITIVE, EXEMPLARY OR ANY SIMILAR TYPE DAMAGES ARISING OUT OF THIS AGREEMENT, THE USE OR THE INABILITY TO USE THE SOFTWARE, OR THE PROVISION OF ANY SUPPORT OR SERVICES, EVEN IF A PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. EXCEPT FOR THE EXCLUDED MATTERS, IN NO EVENT SHALL A PARTY BE LIABLE TO THE OTHER, WHETHER IN CONTRACT, TORT (INCLUDING ACTIVE OR PASSIVE NEGLIGENCE), BREACH OF WARRANTY, CLAIMS BY THIRD PARTIES OR OTHERWISE, EXCEED THE PRICE PAID BY CUSTOMER UNDER THE APPLICABLE ORDERING DOCUMENT.

THE FOREGOING LIMITATIONS SHALL APPLY EVEN IF THE ABOVE-STATED REMEDY OR LIMITED WARRANTY FAILS OF ITS ESSENTIAL PURPOSE. BECAUSE SOME STATES OR JURISDICTIONS DO NOT ALLOW LIMITATION OR EXCLUSION OF CONSEQUENTIAL OR INCIDENTAL DAMAGES, THE ABOVE LIMITATION MAY NOT APPLY TO CUSTOMER.

Confidentiality. "Confidential Information" means the terms of this Agreement; all information marked by the disclosing party as proprietary or confidential; any provided software, related documentation or related performance test results derived by Licensee; and any methods, concepts or processes utilized in provided software or related documentation. Confidential Information shall remain the sole property of the disclosing party and shall not be disclosed to any non-Authorized User without the prior written consent of the disclosing party. If Confidential Information is communicated orally, such communication shall be confirmed as "Confidential" in writing within thirty days of such disclosure. The parties agree to protect the Confidential Information of the other in the same manner it protects the confidentiality of similar information and data of its own (and at all times exercising at least a reasonable degree of care). Except with respect to the Software, items will not be deemed Confidential Information if (i) available to the public other than by a breach of an agreement with TIBCO, (ii) rightfully received from a third party not in breach of any obligation of confidentiality, (iii) independently developed by one party without use of the Confidential Information of the other; (iv) known to the recipient at the time of disclosure (other than under a separate confidentiality obligation); or (v) produced in compliance with applicable law or court order, provided the other party is given reasonable notice of the same. Both parties agree to indemnify the other for any damages the other may sustain resulting from their unauthorized use and/or disclosure of the other's Confidential Information. Such damages shall include reasonable expenses incurred in seeking both legal and equitable remedies. To the extent required by law, at Customer's request, TIBCO shall provide Customer with the interface information needed to achieve interoperability between the Software and another independently created program, on payment of TIBCO's applicable fee. Customer agrees to observe obligations of confidentiality with respect to such information.

Export. Software, including technical data, is subject to U.S. export control laws, including the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations in other countries. Customer agrees to comply strictly with all such regulations and agrees to obtain all necessary licenses to export, re-export, or import Software.

Government Use. If the Customer is an agency, department, or other entity of the United States Government ("Government"), the use, duplication, reproduction, release, modification, disclosure or transfer of the Software, or any related documentation of any kind, including technical data or manuals, is restricted in accordance with Federal Acquisition Regulation ("FAR") 12.212 for civilian agencies and Defense Federal Acquisition Regulation Supplement ("DFARS")


TIBCO Software Inc. End User License Agreement | 133

227.7202 for military agencies. The Software is commercial computer software and commercial computer software documentation. Use of the Software and related documentation by the Government is further restricted in accordance with the terms of this Agreement, and any modification thereto.

Orders. An Ordering Document shall be deemed accepted only by issuance of a TIBCO invoice and solely for purposes of administrative convenience. None of the terms of the Ordering Document (other than the Software product name, number of Permitted Instances, level of Support, description of Services, and fees due in connection therewith) shall apply for any reason or purpose whatsoever, regardless of any statement on any Ordering Document to the contrary, unless countersigned by an officer of TIBCO. This Agreement constitutes the entire agreement between the parties with respect to the use of the Software, Support and Services, and supersedes all proposals, oral or written, and all other representations, statements, negotiations and undertakings relating to the subject matter hereof. All orders of Software, Support or Services by Customer from TIBCO shall be deemed to occur under the terms of this Agreement (with or without reference to this Agreement), unless expressly superseded by a signed written Agreement between the parties. Software shall be delivered electronically, and such delivery shall occur when the TIBCO Software is made available for download by Customer. Physical deliveries (as applicable) of Software and documentation which typically accompanies the Software on delivery shall be on CD-ROM, FOB Palo Alto, and delivery shall occur by depositing the CD-ROM with TIBCO's overnight carrier (at no charge to Customer).

Term and Termination. Support or Services may be terminated: (a) by either party upon a default of the other, such default remaining uncured for fifteen days from written notice from the non-defaulting party; (b) upon the filing for bankruptcy or insolvency of the other party, (c) by either party upon prior written notice at least sixty days prior to the end of any annual Maintenance period; or (d) by Licensee (for Services), upon ten days prior written notice. Termination of Support or Services shall not terminate this Agreement. Customer may terminate this Agreement in its entirety at any time by destroying all copies of the Software. Upon termination of this Agreement in its entirety, for any reason, Customer must cease using and return or destroy all copies of the Software. Customer's obligation to pay accrued charges and any fees due as of the date of termination, as well as the sections entitled "Confidentiality", "Limited Warranty" and "Limitation of Liability" shall survive any such termination.

Authority. You hereby represent and warrant that you have full power and authority to accept the terms of this Agreement on behalf of Customer, and that Customer agrees to be bound by this Agreement.

General. Fees on the Ordering Document (all to be paid on the latter of thirty days from Invoice by TIBCO or the date set forth in the Ordering Document) do not include sales, use, withholding, value-added or similar taxes, and Customer agrees to pay the same, excluding therefrom taxes related to TIBCO's income and corporate franchise tax. Customer agree to pay all reasonable costs incurred (including reasonable attorneys' fees) in collecting past due amounts under this Agreement. Except as set forth in the Section entitled Limited "Warranty" all fees paid under or in connection with this Agreement are non-refundable and no right of set-off exists. All payments of fees due shall be made in U.S. dollars, net 30 from Purchase Date, or, for any other amounts coming due hereafter, net 30 from TIBCO's invoice. A service charge of one and one-half percent per month will be applied to all invoices that are not paid on time. Licensee agrees to pay all sales, use, value-added, withholding, excise and any other similar taxes or government charges, exclusive of TIBCO's income taxes. No delay in the performance of any

obligation by either party, excepting all obligations to make payment, shall constitute a breach of this Agreement to the extent caused by force majeure. Customer hereby grants TIBCO and its independent auditors the right to audit Customer's compliance with this Agreement. If any portion of this Agreement is found to be void or unenforceable, the remaining provisions shall remain in full force and effect. This Agreement shall be governed by and construed in accordance with the laws of the State of California, United States of America, as if performed wholly within the state and without giving effect to the principles of conflict of law. The state and/or federal courts in San Francisco, California, shall have exclusive jurisdiction of any action arising out of or relating to this Agreement. The United Nations Convention on Contracts for the International Sale of Goods is excluded from application hereto. If any portion hereof is found to be void or unenforceable, the remaining provisions of this Agreement shall remain in full force and effect.

Definitions. In connection with this Agreement, the following capitalized terms shall have the following meaning: "Agreement" means this End User License Agreement; "Case Start" means the initiation of a single instance of a defined business process; "Connection" for the following TIBCO Software products shall mean: for TIBCO Enterprise Message Service, a TIBCO Enterprise Message Service client connection to the TIBCO Enterprise Message Service server for the purpose of sending or receiving messages, for TIBCO SmartSockets and TIBCO SmartMQ, any network protocol link established with such TIBCO Software (directly or indirectly) to any other entity, including but not limited to software, firmware or hardware, for TIBCO Enterprise RTView - Standard Monitor System, the number of monitored server instances to TIBCO Rendezvous daemons or TIBCO Hawk agents; for TIBCO Enterprise RTView- EMS Monitor System, a monitored TIBCO Enterprise Message Service Connection (as defined above for that product); for TIBCO General Interface, an electronic data interface to a CPU on a server (which excludes CPUs on devices such as routers, switches, proxies, or HTTP or application servers configured to substantially pass-through information or messages to TIBCO General Interface) that produces information or messages consumed by TIBCO General Interface; "Customer" means the original purchaser or licensee of the Software and any permitted successors and assigns; "Developer" means one user/developer of a TIBCO Software product for use in Development; "Development" means used for software development purposes only; "Enterprise" means an unlimited number of Permitted Instances for a period of one year from the Purchase Date (unless otherwise set forth in the Ordering Document), at which time existing licenses convert to perpetual and Customer may not thereafter deploy additional Permitted Instances, and in any event, shall (during the one-year unlimited deployment period) exclude any entity which acquires, is acquired by, merged into, or otherwise combined with Customer. Customer hereby agrees to provide TIBCO with notice of the number of Permitted Instances deployed at the end of such one-year period within thirty days thereafter; "Fab" means unlimited use for shop-floor manufacturing applications at a Site; "Workstation" shall mean a single end-user computer that is generally intended to be accessed by one person at a time; "Ordering Document" means any purchase order or similar document or agreement requesting Software, Support or Services; "Permitted Instance(s)" means the number of copies of Software running on a Server Instance, Workstation, User, or Development basis, on a designated Platform, as set forth in an Ordering Document, including, without limitation, Enterprise, Site and Fab licensing; "Platform" means the operating system set forth in an Ordering Document; "Purchase Date" means the date of the Ordering Document is accepted by TIBCO; "Server Instance" means a computer with 1 CPU (unless otherwise set forth in the Ordering Document) performing common services for multiple machines; "Site" means an unlimited number of Permitted Instances at a specific physical address set forth in the Ordering Document (or, in the


134 | TIBCO Software Inc. End User License Agreement

absence of any address, at Customer's corporate headquarters); "Software" means the software products listed in an Ordering Document (except as provided in the second paragraph hereof), in whole and in part, along with their associated documentation; "TIBCO" means TIBCO Software Inc.; and "Named User" means the number of named users with access to the Software.

Special Product Provisions. TIBCO BusinessPartner: Customer may sublicense to third parties ("Partners") up to the total Number of Copies of TIBCO BusinessPartner, provided that for every such sublicense, the Number of Copies Customer is licensed to use shall be reduced by the same number, and provided further that prior to delivery of TIBCO BusinessPartner to a Partner, such Partner agrees in writing (a) to be bound by terms and conditions at least as protective of TIBCO as the terms of this Agreement, (b) that TIBCO BusinessPartner be used solely to communicate with Customer's implementation of TIBCO BusinessConnect, and (c) for such Partner to direct all technical support and Maintenance questions directly to Customer. Customer agrees to keep records of the Partners to which it distributes TIBCO BusinessPartner, and to provide TIBCO the names thereof (with an address and contact name) within sixty days of the end of each quarter. Third Party Software: Use of any other third-party software identified by its company and/or product name or otherwise designated in Licensee's Ordering Document (collectively "Third Party Software") is subject solely to the terms and conditions of the click-wrap or shrink-wrap license agreement included with the Third Party Software products, and for which TIBCO shall be an intended third-party beneficiary of same. TIBCO shall have no obligation whatsoever in connection with the Third Party Software (including, without limitation, any obligation to provide maintenance or support) and the provision of Third Party Software is accomplished solely as an accommodation and in lieu of Customer purchasing a license to Third Party Software directly from the third party vendor. Embedded/Bundled Products. Some TIBCO Software embeds or bundles other TIBCO Software (e.g., TIBCO InConcert bundles TIBCO Rendezvous). Use of such embedded or bundled TIBCO Software is solely to enable the functionality of the TIBCO Software licensed on the Cover Page, and may not be used or accessed by any other TIBCO Software, or for any other purpose. Open Source Software: If Licensee uses Open Source software in conjunction with the TIBCO Software, Licensee must ensure that its use does not: (i) create, or purport to create, obligations of use with respect to the TIBCO Software; or (ii) grant, or purport to grant, to any third party any rights to or immunities under TIBCO's intellectual property or proprietary rights in the TIBCO Software. You also may not combine the TIBCO Software with programs licensed under the GNU General Public License ("GPL") in any manner that could cause, or could be interpreted or asserted to cause, the TIBCO Software or any modifications thereto to become subject to the terms of the GPL.

Version 5.2, 3/05


| 135

Index

A

API documentation, accessing 37appCanvas.xml 42applications

accessing 119adding and positioning components 44caching 70calling web services 90deploying 116, 118executing JavaScript before loading 109receiving data 67sending data from 69specifying default language 126testing 63tutorial 40

C

caching data 70CDF

definition 73mapping GUI components to 95mapping response data to 91reading records 74structure 73updating records 74

Component Hierarchy palette 28Component Libraries palette 27

componentsadding 44calling web services from 57expanding on inserts 75loading 71mapping to CDF 95modifying 45saving 46using events 52using JavaScript with 103

config.xml 42customer support xiii

D

datacaching 70receiving 67sending 69

deploymentposting applications 118standalone 116

directory structuredeployment 118project 42

dynamic propertiesediting 34referencing 127specifying JavaScript for 105using 124

TIBCO General Interface User’s Guide

136 | Index

E

eventsbinding to components 52specifying JavaScript for 102

Events Editor palette 29

I

installer programpreserving 2.4.5 installations 17registry file 19starting on Windows 17

J

JavaScriptdefining events 102executing before or after deserialization 103executing for web service calls 110executing on application load 109included files 33including files 106testing 111using in dynamic properties 105

JavaScript Step-Through Debugger 113JavaScript Test Utility 111

L

Launch Page Utility 116logic.js 42

P

Project Files palette 33

projectsaccessing on file system 41adding JavaScript files 106creating 41directory structure 42running in TIBCO General Interface Builder 63

propertiesdynamic vs. static 48modifying 46

Properties Editor palette 28

R

receiving data 67required software 16rules files

creating 79example 54testing 58, 84

S

sending data 69SOAP

mapping parameters 55viewing messages 84

SOAP Mapping Utilityexample 54setting breakpoints 86

support, contacting xiii

T

technical support xiiiTIBCO General Interface

API documentation 37container model 26


Index | 137

TIBCO General Interface BuilderGUI basics 24project link 41starting 20

TIBCO home directory 17typeahead feature 108

U

Unicode, saving files as 123URLs, application 119

W

web servicecalling example 57

web servicescalling 90doc/literal support 78example 54handling errors 97mapping GUI components 79setting timeout intervals 97using JavaScript with 110

WSDL files, parsing 79


138 | Index


Tib Gi Users Guide

Documents

Transcript of Tib Gi Users Guide