title component guide - TIBCO Software General Interface - Enterprise Edition Component Guide Software Release 3.9.1 April 2012

TIBCO® General Interface - Enterprise Edition

Component Guide

Software Release 3.9.1April 2012

Important Information

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

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

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

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

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

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

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

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

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

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

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

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

TIBCO Software Inc. Confidential Information

1

Copyright © TIBCO Software Inc. All Rights Reserved.

General Interface Component GuideGeneral Interface Component Guide

Software Release 3.9

March 2010

Chapter 1 Working with ComponentsChapter 2 Loading Components and XML Data SourcesChapter 3 Tutorial on Creating a Custom ButtonChapter 4 Assigning Hot Keys to GUI ComponentsChapter 5 Distributing an Application Across Multiple Browser WindowsChapter 6 Tutorial on Creating a Custom Add-inChapter 7 System ComponentsChapter 8 Using the Table ComponentChapter 9 Using Matrix ComponentsChapter 10 Dojo Toolkit IntegrationChapter 11 Working with ChartsChapter 12 Charting ComponentsChapter 13 Creating GUI Classes in General InterfaceChapter 14 Forms in General InterfaceAppendix A System ResolversAppendix B Control StatementsAppendix C Contextual Variables

2


1. 2.

3. 4.

Chapter 1 Working with Components

This chapter explains how to work with components in General Interface Builder.

Creating ComponentsViewing Component StatisticsAdding ComponentsSelecting ComponentsMoving ComponentsResizing ComponentsCloning ComponentsDeleting ComponentsModifying PropertiesSpecifying Model EventsProperty and Event DocumentationWorking with Multiple ComponentsFurther Information on General Interface Components

Creating Components

When you create a new project from the Empty Project template in General Interface Builder, adefault component file, is automatically created for you. This is typically whereappCanvas.xml,

you begin designing the application user interface. You can also create new components, suchas buttons, dialogs, and so on.

To create a new component file, choose . A new untitled file tabFile > New GUI Componentopens in the work area.

Then develop the component by adding other components, setting properties and events, andso on.

To save the new component file, complete these steps:

Choose or right-click the file tab at the top of the work area and choose .File > Save SaveBrowse to a directory. Optionally, browse to the recommended folder in thecomponents

project.

If you want to add the component to the Component Hierarchy palette soyou can reuse it, save the component to your folder./prototypesworkspace

See .Saving a Custom Button

Enter a file name and the extension..xml

Choose to close the Save File dialog.Save

3


Viewing Component Statistics

As you work with components in General Interface Builder, you can view component statisticsto assist you in evaluating and benchmarking application performance. The statistics display inthe work area status bar of an open component. Hover the mouse over the status bar to see thedescription of the statistics. Save or reload the component file to update the statistics or click theRefresh button in the work area status bar.

The following statistics are reported:

Component file size in kilobytes (KB)Time to unmarshal (deserialize) the component serialization file in secondsDOM (Document Object Model) node countTime to paint in secondsHTML size in kilobytes (KB)

Any asynchronous operation isn't reflected in the DOM node count. Forexample, when a component is set to Referenced-Asynchronous or anasynchronous Load Type property is used, such as Paint & Deser. Async.These asynchronous operations are also not included in the timings orHTML size.

4


1.

2. 3.

You can improve application performance by specifying how a component loads with the LoadType property. For more information, see .Loading Components and XML Data Sources

Adding Components

To add a component to your application, do the following:

Open the component file that you want to add the new component to, such as .appCanvas.xml

Typically, if you're developing an application, you add the component to the defaultproject file, To create a new component, choose appCanvas.xml. File > New > GUI

.ComponentSelect a component in the Component Libraries palette.Do one of the following:

Drag and drop the component onto an open component file in the work area. Drag and drop the component in the Component Hierarchy palette. If you dropthe component onto a node, the component is added as a child of the node. If youdrop the component between nodes, it's added as a sibling of the nodes.

Selecting Components

To select a component in the Component Hierarchy palette, click a component or use the arrowkeys to navigate the DOM tree and press . To select multiple components in theEnterComponent Hierarchy palette, use to select a range of components and toShift+click Ctrl+clickselect multiple, individual components.

To select a component in the work area, use The component is also selected in theCtrl+click.Component Hierarchy palette. Components with complex mouse behaviors, such as trees,menus, and buttons, may capture and respond to a Ctrl+click in the work area. For example, ifyou use Ctrl+click to select a button in the work area, the button event is executed. To avoid thisbehavior, select these components in the Component Hierarchy palette, not the work area.

Using the Show/Hide Focus Rectangle Button

The Show/Hide Focus Rectangle button on the Component Hierarchy palette toolbar togglesthe focus rectangle in the work area. When the Show/Hide Focus Rectangle button is enabled,the selected component displays in a bounding box with handles. The bounding box is blue forabsolutely positioned components and orange for relatively positioned components.

The button is off by default, because it can interfereShow/Hide Focus Rectanglewith interactions and events of the selected object and its children.

To show the focus rectangle, click the button in the ComponentShow/Hide Focus RectangleHierarchy palette toolbar.

To hide the focus rectangle, double-click the component or click the enabled Show/Hide Focus button in the Component Hierarchy palette toolbar.Rectangle

5


1.

2. 3.

4.

1.

2. 3.

4.

1. 2.

Moving Components

There are two ways to move components that you've added to your project:

In the work areaIn the Component Hierarchy palette

Moving Components in the Work Area

Use the work area when you want to reposition an absolutely positioned component within theparent container. Relatively positioned components can't be moved.

To move an absolutely positioned component, follow these steps:

Enable the button on the Component Hierarchy paletteShow/Hide Focus Rectangletoolbar to turn on the bounding box for selected components.If the bounding box is blue, the component is absolutely positioned and can be moved. Ifthe bounding box is orange, it's relatively positioned and can't be moved.Use to select the absolutely positioned component you want to move.Ctrl+clickHover the mouse over the center handle of the focus rectangle until the cursor changes to

the Move icon .

Click and drag the component to a new position within the parent container.

To move groups of absolutely positioned components in the work area, complete these steps:

Enable the button on the Component Hierarchy paletteShow/Hide Focus Rectangletoolbar to turn on the bounding box for selected components.Select components in the Component Hierarchy palette using Ctrl+click or Shift+click.Hover the mouse over the center handle of the group focus rectangle until the cursor

changes to the Move icon .Click and drag the group of components to a new position within the parent container.

You can also change the position of a component by editing object properties in the PropertiesEditor palette. See .Modifying Properties

To change a relatively positioned component to absolute, do the following:

Use to select the component in the work area.Ctrl+clickIn the Properties Editor palette, choose for the Relative XY property.Absolute

6


1.

2. 3.

4.

1.

2.

Moving Components in the Component Hierarchy Palette

Use the Component Hierarchy palette to move components to another container in theapplication. For example, you might want to move components from one pane to another.

There are two ways to move components in the Component Hierarchy palette:

Select a component or multiple components in the Component Hierarchy palette anddrag to another location in the tree.Drag and drop a component or multiple components from the Component Hierarchypalette into the work area.

Resizing Components

To resize a component in the work area, do the following:

Enable the button on the Component Hierarchy paletteShow/Hide Focus Rectangletoolbar to turn on the bounding box for selected components.Use to select the component you want to resize.Ctrl+clickHover the mouse over a resize handle of the focus rectangle until the cursor changes tothe Resize icon .Click and drag the resize handle to a new position.

If the component is relatively positioned, you can only change the Eastand South positions.

Selections of multiple components can't be resized using the Show/HideFocus Rectangle.

You can also resize a component by editing object properties in the Properties Editor palette.See .Modifying Properties

Cloning Components

Making clones of components saves development time in creating your application and insetting component properties. A clone is a copy of a selected component. Once you've clonedthe component, you can modify the properties of the cloned component.

To create a clone of a component, complete these steps:

Select a component in the Component Hierarchy palette or in the work area.

Click the button on the toolbar to create a clone. The cloned component isClonecreated in the work area and is added to the Component Hierarchy palette below theselected component.

7


2.

3.

1.

2.

3.

To clone multiple components, select them using Ctrl+click or Shift+clickand then click the button.Clone

Modify the component properties as desired in the Properties Editor palette. See .Modifying Properties

Deleting Components

To move a component to the Recycle Bin, select the component in the Component Hierarchypalette and press or click the button on the toolbar.Ctrl+Delete Recycle

To delete multiple components, select them using Ctrl+click or Shift+click and thenclick the button.Recycle

Components can be recovered from the Recycle Bin palette at any time during the projectsession. To open the Recycle Bin palette, choose .Palettes > Recycle Bin

For more information, see the "Project Files Palette" section in the General Interface DeveloperGuide.

Modifying Properties

Properties provide an abstraction layer for the complexities of browser event models andDHTML syntax. General Interface prototype components are preconfigured with defaultproperty values, which can be modified.

These properties are name-value pairs that are displayed in the Properties Editor palette. Forexample, the properties of a button include some of the following: text/HTML, font size,background color, width, and so on.

To modify a property, complete the following steps:

Select a component or multiple components in the work area or the ComponentHierarchy palette.

Use to select multiple components. Use to choose aCtrl+click Shift+clickrange of components. See .Working with Multiple Components

Find the property you want to modify in the Properties Editor palette.

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

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

Type a value in the Value column. For example, for the Font Size property, you

8


3.

Type a value in the Value column. For example, for the Font Size property, youmight type . 12

Right-click and choose a dynamic property value from the menu, if available. Forexample, for the Color property, you might choose the dynamic property, .@Light

For properties that are common to many components and properties that requirelocalization, such as labels, it's recommended that you use dynamic properties orproperties bundle files. See the General Interface Developer Guide. Type the key (ID) of a dynamic property or a properties bundle in the Valuecolumn. Click the down arrow in the Value column and select a value from the list, ifavailable. For example, for the Font Weight property, you might choose .Bold

Entering CSS Values

For properties that require CSS values, such as padding, margin, and border, you can enter aW3C valid CSS syntax or General Interface syntax. General Interface syntax is a more efficient,concise syntax specific to General Interface. Values are converted to General Interface syntax atruntime. If performance is critical, the General Interface syntax is recommended, because CSSsyntax can reduce performance.

For examples of General Interface syntax, see the following topics:

PaddingMarginBorder

When using the General Interface syntax, be sure to enter a space betweenvalues as shown in the examples. Some CSS values also require a space.

For more information on CSS, see Cascading Style Sheets Specification at http://www.w3.org/TR/CSS21/.

Padding

The Padding property (jsxpadding) sets the white-space gap between the outer edge or borderof the object to its inner content. When using General Interface syntax, padding is specified asone or four implied pixel values applied in this order: top, right, bottom, and left.

General Interface Syntax

The following are valid General Interface syntax for specifying 8 pixels of padding:

8

8 8 8 8

W3C CSS Syntax

W3C CSS syntax is also supported as long as explicit pixel units are used. The following are allvalid CSS for specifying 8 pixels of padding:

padding:8px;

padding:8px 8px;

padding:8px 8px 8px 8px;

padding-top:8px;padding-right:8px;padding-bottom:8px;padding-left:8px;

http://www.w3.org/TR/CSS21/

9


Margin

The Margin property (jsxmargin) sets the gap between the object's border and its parent and/orsibling containers. When using General Interface syntax, margin is specified as one or fourimplied pixel values (top, right, bottom, and left).


The following are valid General Interface syntax for specifying 4 pixels for margins:

4

4 4 4 4

W3C CSS Syntax

The following are all valid CSS for specifying 4 pixels for margins:

margin:4px;

margin:4px 4px;

margin:4px 4px 4px 4px;

margin-top:4px;margin-right:4px;margin-bottom:4px;

margin-left:4px;

Border

The Border property ( ) sets the CSS border definition. The border is one or four valuejsxborder

sets (top, right, bottom, and left).

The General Interface syntax is specified in this form:

style width color[;style width color;...]


The following are valid General Interface syntax for specifying a black 1 pixel border:

solid 1px black

solid 1px #000000;solid 1px #000000;solid 1px #000000;solid 1px #000000;

W3C CSS Syntax

The following are all valid CSS for specifying a black 1 pixel border:

border:solid 1px black;

border-top:solid 1px #000000;border-right:solid 1px #000000;border-bottom:solid1px #000000;border-left:solid 1px #000000;

CSS values of either type can also be used in the Dynamic Properties editor and in JavaScriptcode using the JavaScript API. For example:

myBlock.setBorder("solid 1px red;solid 1px red;solid 1px red;solid 1px red;");

10


1. 2. 3.

Specifying Model Events

In addition to properties, objects can also have model events that are published in response touser actions. For example, the Execute event for a component might be published in response toan or event. A model event is an abstraction layer that wraps nativeonkeypress onclick

browser events. Model events translate events from the domain of the browser user interfaceinto events from the General Interface model domain. Model events are persistent in GeneralInterface GUI component serialization files and are thus a static binding from the user interfacedefinition to JavaScript code. Model events, with a few exceptions such as hide, destroy, andshow, can't be generated programmatically. Events are typically only generated by the userinteraction with the browser.

In General Interface 3.1, the event model changed. By default, projects created inGeneral Interface 3.1 and later use the 3.1 event model. However, you can set yourproject to use the 3.0 event model for backward compatibility. See the GeneralInterface Developer Guide.

The majority of model events grant access to the current wrapped event object with objEVENTand are only generated by user interaction. If a model event doesn't provide access toobjEVENT, it may be generated programmatically. Events are documented in the Events Editorpalette.

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

Events that can be generated programmatically include the following:

All Classes: DestroyButton: Execute.Button has a method that allows the Execute model event to fire without adoExecute()

browser event.DatePicker: Show/HideMenu: HideStack: ShowTab: Show/HideTabbedPane: Change

To specify a model event for a component, complete these steps:

Select a component in the work area or the Component Hierarchy palette.In the Events Editor palette, click in the Value column next to the event name.Type the JavaScript code to run when the event is published.

11


3.

Property and Event Documentation

Properties and events are described in the following references:

General Interface GUI Property Reference (Help > API Documentation > GUI PropertyReference)General Interface GUI Event Reference (Help > API Documentation > GUI EventReference)

This information is also available in a spyglass when you hover over property names in theProperties Editor palette and event names in the Events Editor palette.

Working with Multiple Components

Because the Component Hierarchy palette supports multiple selection of components, you canmodify groups of components instead of modifying individual components. This productivityenhancement allows you to develop your applications more quickly.

12


Use to select multiple components in the Component Hierarchy palette.Ctrl+clickUse to choose a range of components.Shift+click

The ability to select multiple components in the Component Hierarchy palette provides thefollowing productivity enhancements:

Drag and drop multiple selections to any location in the Component Hierarchy palette.Move multiple, absolutely positioned components in the Live Component view of thework area. If the Focus Rectangle is enabled in the Component Hierarchy palette, youcan move groups of selected components in the work area if they're absolutelypositioned.The Component Hierarchy palette context menu can be used on multiple selections.Clone multiple components.Delete multiple components.

When multiple components are selected in the Component Hierarchy palette, other palettesdisplay the following behavior:

The Properties Editor palette displays properties that are common to all selectedcomponents, allowing you to modify these properties in a single step.The Events Editor palette is active if all selected nodes are of the same class, allowingyou to set events for multiple components.The Attributes Editor palette displays attributes common to all selected components,allowing you to modify attributes in a single step.The XSL Parameters palette displays parameters common to all selected components ifthey are instances of . This feature allows you to modify these parameters in aCacheable

single step. The Name combo box is prefilled only if all selected components are of thesame class.All palettes display the text, , if the values for the selected[multiple values]

components are different.

Further Information on General Interface Components

For more in-depth information, see the following topics:

Adding a Button and Button Event in General Interface Getting Started.

Adding and Debugging JavaScript Code in the General Interface Developer Guide.

General Interface samples in for other examples of/JSXAPPS/samplesworkspace

specifying events for components. Other samples are also available on DeveloperNetwork at .http://www.generalinterface.org

http://www.generalinterface.org/docs/display/GIDOCS/Adding+a+Button+and+Button+Event#AddingaButtonandButtonEvent-further.info

http://www.generalinterface.org/docs/display/GIDOCS/Chapter+10+Adding+and+Debugging+JavaScript+Code

http://www.generalinterface.org

13


Chapter 2 Loading Components and XML Data Sources

Loading components and XML data sources asynchronously can improve applicationperformance and usability. General Interface provides properties and APIs for specifying howto load components and XML data sources.

For more information on setting properties, see . For descriptions ofModifying Propertiesproperties, see General Interface GUI Property Reference. For information on designing yourapplication to be asynchronous, see the "Optimizing Application Performance" section in theGeneral Interface Developer Guide.

Deserializing and Painting ComponentsLoading XML Data Sources

Deserializing and Painting Components

You can specify how to deserialize and paint a component with the Load Type property, whichhas the following options and recommended usages:

Normal deserialize and paint with the parent. This is the only behavior in GeneralInterface 3.4 and earlier.

Paint Asynchronously deserialize with the parent and paint after sleep. This optionimproves the "pop" of a component since painting a DOM branch can be slow.Deserializing with the parent increases backward compatibility, because the DOMalways appears the same as it would with the Normal setting.

Deserialize Asynchronously deserialize and paint after sleep. This option furtherimproves "pop" of a component by offloading the deserialization step to anasynchronous operation. However, it may be inconvenient to the developer for the DOMto exist momentarily in an incomplete state.

This option is the recommended setting for the content pane of a dialog or other componentswhere loading needs to provide immediate feedback and a screen flicker is acceptable. This isthe closest equivalent to loading a referenced component asynchronously in General Interface3.4 and earlier.

Paint and Deserialize Asynchronously deserialize after sleep and paint after anothersleep. This option is similar to the Deserialize Asynchronously option, except the CPUrests after deserializing and before paint. This option is the recommended setting forvery large DOM branches that take a long time to deserialize.

Paint on Show deserialize with parent and paint on show. This option offloads paintingof a DOM branch until the result of the paint is visible.

This option is the recommended setting for the content panes of Tabs and Stacks.

Deserialize on Show deserialize and paint on show. This option is similar to the Paint onshow option, but deserialization is also offloaded until the component is shown. Thiscould increase "pop" even more than the Paint on show option, but it may beinconvenient to the developer for the DOM to exist momentarily in an incomplete state.

14


By default, the Dialog component is set to Paint Asynchronously and Tab and Stack are set toPaint on Show in General Interface Builder.

Recommended Usage

Follow these recommended usages when specifying load type for components:

For increased "pop," use Paint Asynchronously, Deserialize Asynchronously, or Paintand Deserialize Asynchronously.

To display a dialog and then its content, use Paint Asynchronously, DeserializeAsynchronously, or Paint and Deserialize Asynchronously on the Block that contains thecontent of the dialog.

For the content panes of Tabs and Stacks, use Paint on Show or Deserialize on Show.

You can also use the ) and jsx3.app.Model.getLoadType( jsx3.app.Model.setLoadType()

methods to get and set the load type programmatically. For more information, see GeneralInterface API Reference.

Loading XML Data Sources

For components that implement the interface, such as Matrix and Menu,jsx3.xml.Cacheable

you can also specify whether to load XML data sources asynchronously or synchronously usingthe following properties:

XML Async specifies whether an XML URL data source should be loaded synchronouslyor asynchronously. This property is used in conjunction with the XML URL property.

If the property is set to Asynchronous, the data source is loaded asynchronouslyand a loading message displays until the data has finished loading. If this property is not set or is set to Synchronous, the data source is loadedsynchronously as in General Interface 3.4 and earlier.

XML Bind specifies whether a control is bound to its cached XML data. If set to Bound,the control repaints whenever the cached XML document changes.

To get and set these properties programmatically, see the , jsx3.xml.Cacheable.getXmlAsync()

and jsx3.xml.Cacheable.setXmlAsync(),jsx3.xml.Cacheable.getXmlBind(),

in General Interface API Reference.jsx3.xml.Cacheable.setXmlBind()

The BlockX component has an additional property:

XSL Async specifies whether an XSL URL template should be loaded synchronously orasynchronously. This property is used in conjunction with the XSL URL property.

If this property is set to Asynchronous, the XSL template is loadedasynchronously and a loading message displays until the template has finishedloading. If this property is set to Synchronous, the XSL template is loaded synchronouslyas in General Interface 3.4 and earlier.

To get and set these properties programmatically, see the jsx3.xml.Cacheable.getXslAsync()and in General Interface API Reference.jsx3.xml.Cacheable.setXslAsync()

15


Note that fetches the XML resource using . The XMLjsx3.xml.Document.load() XMLHTTPRequest

resource is fetched asynchronously if is called on the setAsync(true) jsx3.xml.Document

instance before calling . By default, the load is synchronous.load()

The use of means that this optimization technique works on the web serverXMLHTTPRequest

configuration to make maximum use of the asynchronous request and caching. For example,adding a long expiration time to resource files can help improve application load time onsubsequent startup. However, browsers such as Internet Explorer 6 and 7, which have aconnection limit of 2, may not benefit as much from asynchronous loading.

Whenever possible, design your application to use asynchronous loading to improveapplication flow and usability. For more information, see the "OptimizingApplication Performance" chapter in the General Interface Developer Guide.

Property Behaviors

When the XML Async property is set to Asynchronous, the behaviors are as follows:

Tree and Matrix if the control paints and the data source is not loaded, paints a "Loadingdata..." message in the body of the control and repaints asynchronously after the datasource loads.Select and Menu when the control is painted, immediately requests the data sourceasynchronously. If the control is expanded before the data source has loaded, shows a"Loading data..." message.BlockX the same behavior as Tree and Matrix. If the XSL template is also asynchronouslyloaded, shows a "Loading XSL..." message until the XSL template loads.

16


1.

2. 3. 4.

5.

6.

7. a.

b.

c.

Chapter 3 Tutorial on Creating a Custom Button

The use of custom components offers many advantages in application development -component reusability, consistency of look-and-feel across applications, faster developmenttime, and reduction in repetitive, time-consuming component development.

After you've created customized components, you can add them to your user componentlibrary and access them from any project, as well as share them across the entire developmentteam.

Creating a Custom ButtonSaving a Custom ButtonUsing a Custom Button

Creating a Custom Button

Let's begin by creating a custom button as follows:

Open or create a project in General Interface Builder. See the General Interface DeveloperGuide.Choose to create a new component.File > New > GUI ComponentOpen the folder in the Component Libraries palette.System > Form ElementsDrag and drop a component from the Component Libraries palette to the workButtonarea.Open the and delete the alert value for the Execute event.Events Editor paletteTypically, you won't want to assign an event until you use it in your application.Open the and enter the following property values to give theProperties Editor palettebutton a custom look-and-feel:

FontWeight: BoldColor: blueBG Color: #ccffcc

You can use the Color Picker to choose color values. Choose Tools > You can also click in the Value field in the PropertiesColor Picker

Editor palette and click the Color Picker button to open theColor Picker.

Click the button at the bottom right of the work area. Component ProfileType in the Name field. This is the name that displays in theBlue Button

Component Hierarchy palette. Enter a description. This information displays in a tooltip when you hover overthe component name in the Component Libraries palette. Type the URL for an optional custom image in the Icon URL field. The URL isrelative to the launch page that launches the application. For example, if you're launching the application with GI_Builder.html

and the image is located in , the(GI_HOME/GI_Builder.html) /imagesworkspace

URL would be .../workspace/images/icon.gif

17


1. 2. 3. 4. 5. 6.

7. 8.

9.

1. 2. 3.

4. 5. 6.

If you're using images across your applications, you might create an folderimages

for all your images in your workspace directory.

Saving a Custom Button

After you've created the custom component, save it to the directory. Any/prototypesworkspace

components saved to this directory appear in the User folder of the Component Librariespalette. You can create nested folders to organize your components.

To save the custom button so that it appears in the Component Libraries palette,

Press to save the new component.Ctrl+sNavigate to the workspace/prototypes folder.Click the button in the Save File dialog.Create New FolderName the folder and click .Buttons CreateOpen the folder in the Save File dialog.ButtonsType in the Name field and click .BlueButton.xml Save

Click the button at the bottom right of the work area.Live ComponentClick the button on the Component Libraries palette toolbar to load the newReloadcomponent from disk.Open the folders in the Component Libraries palette to see the BlueUser > ButtonsButton you just created. If you entered an image URL, you'll also see an icon for thebutton. Move the mouse over the button to see the description in a tooltip.

Using a Custom Button

Now that you've created the custom button, you can use it in your application just as youwould with any of the pre-built GUI components in the Component Libraries palette. You canalso modify the button as needed once you drop it on your layout.

To use and modify your custom button, complete the following steps:

Create or open a project.Open the folders in the Component Libraries palette.User > ButtonsDrag and drop the component from the Component Hierarchy palette toBlue Buttonthe work area.Modify the properties of the button in the Properties Editor palette or use it as is.Add an Execute function in the Events Editor palette. See .Specifying Model EventsRight-click the tab and select .appCanvas.xml Save and Reload

Now that you have a custom button, you can continue to develop your own library of customcomponents. Simply create a new GUI component file, drag and drop a component from theComponent Libraries palette into the new file, modify it, and save it to theworkspace/prototypes folder to add it to your User library. As you can see, using customcomponents can save time by eliminating repetitive rework and can also facilitate a commonlook-and-feel across the application.

18


19


Chapter 4 Assigning Hot Keys to GUI Components

This chapter describes how to assign hot keys to button and menu components in GeneralInterface applications. Hot keys are keyboard shortcuts that enable access to an applicationwithout the use of a mouse.

Introduction to Hot KeysAllowed Keys for Hot KeysHot Key CollisionsAssigning Hot Keys to ButtonsAssigning Hot Keys to MenusHot Keys Registration and Deployment

Introduction to Hot Keys

Hot keys are keyboard shortcuts—combinations of keys that enable users to interact with anapplication without using a mouse. For example, a user might use a hot key to activate a menucommand.Assigning hot keys to button and menu components in your General Interface applicationsensures that users who prefer or require keyboard accessibility can easily use your applications.

These General Interface components support hot keys:

jx3.gui.Button

jx3.gui.ImageButton

jx3.gui.ToolbarButton

jx3.gui.Menu

If you aren't familiar with adding GUI components to your application, see General InterfaceGetting Started.

Allowed Keys for Hot Keys

When assigning a hot key to a menu or a button, use the following string format:

[ctrl+][alt+][shift+]n

The modifiers (ctrl, alt, shift) are optional and zero to three modifiers can be used. The value nis required as the last value and can be any of the following keys:

Alpha numeric characters: a-z, 0-9Punctuation keys in the string

; (semi-colon), (comma). (period)/ (forward slash)\ (back slash)

' (single quote)

20


' (single quote)[] (open and close brackets)- (hyphen)= (equals sign)` (back tick)

Function keys: F1-F15Special keys: enter, esc, tab, del, space, backspace, up, down, left, right, insert, home,end, pgup, pgdn

Use lowercase when typing hot key values in JavaScript code or in properties. Forexample, ctrl+alt+b.

Hot Key Examples:

ctrl+shift+enter

ctrl+6

ctrl+alt+s

ctrl+,

Although hot keys can be reused in your application, don't reuse them within thesame scope. For example, don't reuse the same hot key in the same dialog.

Some hot keys could be problematic. For example, if the hot key for a button is b orshift+b and the end user is typing b or a capital B (shift+b) in a text field, the button isactivated instead. Choose your hot keys carefully.

Hot Key Collisions

Be aware that some hot keys might already be in use. If you attempt to use these hot keys,collisions could occur. For example, General Interface Builder uses Tab and Windows usesAlt+Tab for application switching. To avoid collisions with hot keys already in use, be sure tothoroughly test your hot keys in your running application.

These are the possible areas of collision for hot keys:

Operating systemBrowserGeneral Interface BuilderGeneral Interface Framework

For information on operating system and browser hot keys, see the respective documentation.

General Interface Hot Keys

General Interface uses these hot keys:

Menu hot keys used by General Interface Builder. For a list of menu hot keys, see Tools >

21


1.

2. 3.

4. a. b.

1.

2.

Menu hot keys used by General Interface Builder. For a list of menu hot keys, see Tools > in General Interface Builder. Note that these menu hotIDE Settings > IDE Hot Keys

keys are customizable.Navigation hot keys used by General Interface Builder and General Interfaceapplications — tab, enter, space.

If you want to use General Interface Builder hot keys in your application, such as ctrl+n, yourhot key will only work in General Interface Builder if the focus is in the Live Component viewof the hot key component. Otherwise, the General Interface Builder hot key executes. Thenavigation hot keys should not be used.

Assigning Hot Keys to Buttons

Hot keys can be assigned to any of the following button components by modifying the KeyBinding property in the Properties Editor palette:

ButtonImageButtonToolbarButton

To assign a hot key to a button:

Open the folder of the Component Library palette.System > Form Elements

To add a ToolbarButton component, open the System > Menus andToolbars folder.

Drag and drop a component onto your application.ButtonSelect the component in the Live Component view of the work area or theButtonComponent Hierarchy palette.Modify the property as follows: Key Binding

Open the and click in the value field. Property Editor palette Key BindingType in a hot key, such as . It's recommend that you test the hotctrl+shift+enterkey before assigning it to be sure it's not already used.

To test the hot key:

Click anywhere in the Live Component view of the work area to give focus to yourapplication.

Don't click the button as this will activate it.

Press on the keyboard to test the button functionality.ctrl+shift+enter

Assigning Hot Keys to Menus

To assign a hot key to a menu, you need to add or modify the CDF @jsxkeycode attribute in theCDF document associated with the control.

To assign a hot key to a menu command:

22


1. 2. 3.

4.

5. 6.

1.

2. 3.

a. b. c.

To assign a hot key to a menu command:

Open the folder in the Component Libraries palette.System > Menus and ToolbarsDrag and drop a component onto your application.MenuEdit the CDF document associated with the control and add the @jsxkeycode attribute toeach menu command---New, Open, and Save. There are several ways to do this:

Edit the CDF document on disk and enter the XML URL in the Properties Editorpalette. Edit the CDF cache document and enter the XML Cache ID in the PropertiesEditor palette (The cache document isn't persisted). Edit the XML String property in the Properties Editor palette.In this example, you'll edit the property as follows: XML String

Select the component in the Component Hierarchy palette or the Live ComponentMenuview. Open the and click in the value field. Properties Editor palette XML StringAdd attributes to each menu command. Typically, the jsxexecute attribute@jsxkeycodewould execute a function. In this example, an alert is used for the jsxexecute attribute fortesting purposes to demonstrate that the hot key is working properly.

For example, your XML String value might look similar to this:

<data jsxid= >"jsxroot" <record jsxid= jsxtext= jsxkeycode="1" "New" "alt+shift+n" jsxexecute= />"alert('New menu is working');" <record jsxid= jsxtext= jsxkeycode="2" "Open" "shift+o" jsxexecute= />"alert('Open menu is working');" <record jsxid= jsxtext= jsxkeycode="3" "Save" "shift+s" jsxexecute= />"alert('Save menu is working');"</data>

Test the hot key before assigning it, to be sure that it is not already used.

To test the hot key:

Select the component in the Component Hierarchy palette and click the Re-FetchMenuData and Repaint button so that the CDF document in memory reflects the changesmade to the XML String property.Click anywhere in the Live Component view to give focus to your application.Use the hot key for each menu command to test the functionality and to display the alert:

Press for the New command. alt+shift+nPress for the Open command. shift+oPress for the Save command.shift+s

Hot Keys Registration and Deployment

When hot keys are assigned, they are registered with the closest ancestor DOM node that is a , or root block of a server (JSXROOT).jsx3.gui.Window, jsx3.gui.Dialog

Therefore, hot keys are global as there are no "protected" spaces. It is an error for two or more

23


Therefore, hot keys are global as there are no "protected" spaces. It is an error for two or morecontrols within the same scope to register the same hot key.

There are two choices for deploying applications with hot keys:

Body Hot Keys option checkedBody Hot Keys option unchecked

To set the Body Hot Keys option, choose . The defaultProject > Project Settings > Deploymentsetting for this option is unchecked.

The first deployment choice, Body Hot Keys option checked, is typically used for full-windowapplications. In this deployment scenario, if the hot key event bubbles up to the HTML bodyelement, it is then sent to the application. So even if the focus is in the browser window and notin the General Interface application, the application receives the hot key and executes it.

The second choice, Body Hot Keys option unchecked, is recommend for General Interfaceapplications deployed in a page with other General Interface applications. In this case, the hotkeys only function if the focus is within the General Interface portlet application. Thisdeployment prevents your application from responding to hot keys initiated in other GeneralInterface portlet applications on the page.

24


1. 2. 3.

1. 2.

3.

Chapter 5 Distributing an Application Across MultipleBrowser Windows

This chapter explains how to distribute a General Interface application across multiple browserwindows.

This chapter refers to the windowSwap sample located at .http://www.generalinterface.org

Basic Steps for Creating and Managing a WindowCreating and Managing a Browser WindowwindowSwap Example

Basic Steps for Creating and Managing a Window

To create an external browser window:

Instantiate the window with the or methods.createAppWindow() loadAppWindow()

Open the window with the method.Window.open()

Use the method to be sure that a portion of the window isWindow.constrainToScreen()

visible on the screen.

Other optional steps are:

Use the event to confirm that the window opened.Window.DID_OPEN

If the window doesn't have content yet, load the content as follows: Use the method to load content from a component serialization file:load()

myWin.getRootBlock().load("mycomp.xml");

Use the method to load a branch of the General Interface DOM:adoptChild()

myWin.getRootBlock().adoptChild(myApp.getJSXByName( "mycomp"));

Use the event to perform an operation when the user closes theWindow.WILL_CLOSE

window.

Note that some Internet Explorer security settings might prevent thecontent from displaying in the new window.

For more information, see and in General Interface APIjsx3.gui.Window jsx3.app.Server

Reference (Help > API Documentation).

http://www.generalinterface.org

25


Creating and Managing a Browser Window

General Interface provides the API to leverage the native browser window injsx3.gui.Window

distributing a General Interface application across multiple browser windows. The use ofseveral windows is particularly useful when using multiple monitors. In addition, in somecases, a browser window is a better design choice than a dialog, because it's visuallyindependent of the rest of the application.

The class, which allows rendering a branch of the General Interface DOM in ajsx3.gui.Window

separate browser window, must be created and managed using the class.jsx3.app.Server

Server Class APIs

You can create and access instances of the class with these methods in the Window

class:jsx3.app.Server

createAppWindow()

getAppWindow()

loadAppWindow()

For more information, see in General Interface API Reference (Help > APIjsx3.app.Server

Documentation).

createAppWindow() Method

The method creates a new instance for the specified servercreateAppWindow() jsx3.gui.Window

and places the window in the General Interface DOM. Because the methodcreateAppWindow()

doesn't open the window, you must call the method separately to open it.Window.open()

Depending on security settings and popup blockers, the method might not open aopen()

window. To determine if the window opened successfully, register for the Window.DID_OPENevent. For more information, see in General Interface API Reference.jsx3.gui.Window

getAppWindow() Method

The method is a convenience method that returns a previously created getAppWindow()

by name.jsx3.gui.Window

loadAppWindow() Method

The method creates and loads a new instance from aloadAppWindow() jsx3.gui.Window

component serialization file and places it in the General Interface DOM.

The component serialization file must have a Window object as the root object as shown in thefollowing example. The window in the example has some of these properties:

object type jsx3.gui.Windowname myWindowtitle bar title Hello Worldcontent Hello World

26


<?xml version= ?>"1.0"<serialization xmlns= >"urn:tibco.com/v3.0" <object type= >"jsx3.gui.Window" <variants jsxdependent= jsxresizable= jsxscrollable= />"1" "1" "0" <strings jsxname= jsxtitle= jsxwidth="myWindow" "Hello World" "880" jsxheight= />"600" <object type= >"jsx3.gui.Block" <variants jsxoverflow= jsxrelativeposition= jsxleft= jsxtop="3" "0" "0"

/>"0" <strings jsxname= jsxwidth= jsxheight= >"content" "100%" "100%" jsxtext= />"Hello World" </object> </object></serialization>

General Interface Builder has two examples of browser windows that are loaded fromserialization files:

API Help Choose to open API help inHelp > API Documentation > in separate windowan external browser window. If the API documentation is open in a dialog, you can alsoclick the button .Move to External Browser Window

System Log palette Click the button on the System Log paletteDocking Optionstoolbar and choose to open the system log in an external browser window.Window

windowSwap Example

The windowSwap application shown in the figure demonstrates how to distribute anapplication across multiple browser windows.

The windowSwap example includes some of these components:

Swap to/from Window button executes a function that swaps a branch of the GeneralInterface DOM to the external browser window and from the window back to the mainapplication areablkWindowSwapApp parent of the DOM branch to be swappedblkSwappablePane DOM branch to be swappedswapWin browser window

27


The next figure shows the General Interface DOM in the Component Hierarchy palette inGeneral Interface Builder.

When the user clicks the Swap to/from Window button, the JavaScript function is called. This function, shown below, creates and loads the window andeg.windowswap.swap()

swaps the content from the application to the browser window, swapWin.

28


jsx3.Package.definePackage("eg.windowswap", (pkg) {function

pkg.swap = () {function // get the pane to be swapped and its parent swapPane = pkg.APP.getJSXByName("blkSwappablePane");var currentParent = swapPane.getParent();var

(currentParent.getName() == "blkWindowSwapApp") {if // the parent is part of the main application, get orif // create the window w = pkg.APP.getAppWindow("swapWin");var (w == ) {if null w = pkg.APP.createAppWindow("swapWin"); w.setHeight(400); w.setWidth(500); w.setTitle("Swap Window"); }

// subscribe to the window closing event to thereturn // content to the application when the window is closed w.subscribe(jsx3.gui.Window.WILL_CLOSE, , .swap);this this

//now move the pane to the window w.getRootBlock().adoptChild(swapPane);

//and show the window it isn't already visibleif (!w.isOpen()) {if w.open(); } w.focus(); } {else // the parent is the root block of the windowelse if w = pkg.APP.getAppWindow("swapWin");var (w) {if // unsubscribe from the window closing event w.unsubscribe(jsx3.gui.Window.WILL_CLOSE, ,this .swap);this }

// move the content back to the application pkg.APP.getJSXByName("blkWindowSwapApp").adoptChild( swapPane);

// and close the window w.close(); } };

});

29


1.

2. 3. 4.

5. 6.

Chapter 6 Tutorial on Creating a Custom Add-in

This tutorial describes how to develop custom add-ins to use in your projects as you developyour applications.

Introduction to Custom Add-InsCreating a New Project and JavaScript ClassesRegistering the Class PathsCreating PrototypesCreating General Interface Builder Properties FilesCreating and Loading the Catalog FileDeploying the Custom Add-in

Introduction to Custom Add-Ins

Add-ins extend General Interface functionality. They are most often used when developersneed additional functionality that spans multiple projects, but that isn't common enough to beincluded in all projects.

These are the main types of add-ins:

System Add-ins provide common functionality that might not be required by all projects,but that is common enough to ship with the core General Interface framework. Charting,for example, is a system add-in that provides charting capabilities only to the projectsthat implement it.Custom User Add-ins are created by developers to provide enhanced functionality thatcan span multiple projects, but that isn't common enough to be included in all projects.

This tutorial demonstrates how to create a custom add-in, focusing on creating custom classesand configuration files.

Steps for Creating Custom Add-ins

In this tutorial you'll follow these basic steps to create a custom add-in:

Create a General Interface project for developing your add-in, then create the JavaScriptclasses that define the new GUI components.Create the prototypes for the new GUI components.Create files for custom properties, events and XSL parameters.Create a file for custom properties, events, and XSL parameters files. The catalog.xml

file describes the location of custom properties, events, and XSL parameterscatalog.xml

files.Create a JavaScript file, using the General Interface API, that loads .catalog.xml

Deploy the custom add-in by copying the project to your user add-ins directory,modifying the add-in's file, then enabling the new add-in, testing it, andconfig.xml

making it available for general use.

30


About Add-in Files and Folders

The add-in you'll create in this tutorial includes these files and folders.

Folder File Description

config.xml Add-in configuration file (at thetop level of the myAddindirectory)

js/my package.js JavaScript file that declares thepackage and loads the catalog file

js/my/example/ Container.js Container class

Widget.js Widget class

properties catalog.xml Describes the location of theproperties files for Container andWidget

Container.xml Properties file for the Containerprototype that appears in the PropertiesEditor palette after deployment

Widget.xml Properties file for the Widget prototypethat appears in the Properties Editorpalette after deployment

prototypes Container.xml Container prototype that appearsin the Component Librariespalette after deployment

Widget.xml Widget prototype that appears in theComponent Libraries palette afterdeployment

Creating a New Project and JavaScript Classes

In this step you'll create a new project for developing a custom add-in, then create the classes and :Container Widget

The class extends and includes a feature that allows only a Widget orContainer Block

Container component to be added as a child. If any other type of component is droppedon a Container, this message appears in the General Interface system log: The child

.object could not be accepted, because it is not of type container or widget

The class extends and includes a feature that allows it to be accepted onlyWidget Block

as a child of a Container prototype. If a Widget is dropped on any type of componentother than Container, this message appears in the General Interface system log: Widgetscan only be added to containers. You must first add a container before adding awidget.

After you create these classes you'll register their class paths in the General Interface Project

31


After you create these classes you'll register their class paths in the General Interface ProjectSettings dialog.

For more information about creating classes, see Class Inheritance and Introspection in theGeneral Interface Developer Guide.

32


1. 2.

3.

4. a.

b. c.

d.

To create the project and Container class:

Choose and create a new project called .Project > New Project myAddin

Choose File to open a new JavaScript file in the General> New > JavaScript FileInterface work area.

Copy and paste this code into the new JavaScript file, to create the Container class:

jsx3.require("jsx3.gui.Block");jsx3.lang. .defineClass("my.example.Container", jsx3.gui.Block, , Class function(Container,Container_prototype) { /** * main method */ Container_prototype.init = () {function .jsxsuper();this };

/** * Called before appending a child to the children list. Only allows * widgets and containers to be set as children of a container * @ { } to allow the set, to vetoreturn boolean true false */

Container_prototype.onSetChild = (objChild) {function ///jsx3.log(objChild.getName()); bSuccess = objChild my.example.Widget || objChild var instanceof instanceofmy.example.Container; (!bSuccess)if jsx3.log("The child object could not be accepted, because it is not oftype container or widget."); bSuccess;return };});

Save the file: Choose and open the folder of the project.File > Save js

Click the icon and create a folder named . Create New Folder my

Open the folder. my

Click the icon and create a folder named . New Folder example

33


4.

c.

d. e. f.

1.

2.

Click the icon and create a folder named . New Folder example

Open the folder. example

Type as the file name and click .Container.js Save

The fully qualified name for the new class ( ) is reflected in the path wheremy.example.Container

it is saved ( ).js/my/example/Container.js

To create the Widget class:

Create a new JavaScript file and copy and paste this code into the file:

jsx3.require("jsx3.gui.Block");jsx3.lang. .defineClass("my.example.Widget", jsx3.gui.Block, , Class function(Widget,Widget_prototype) { /** * main method */ Widget_prototype.init = () {function .jsxsuper();this }; /** * Called when an item is about to be set; returns the parentfalse if * is not of the appropriate type (container) * @ { } to allow the set, to vetoreturn boolean true false */ Widget_prototype.onSetParent = (objParent) {function bSuccess = my.example.Container && objParent var instanceofmy.example.Container; (!bSuccess)if jsx3.log("Widgets can only be added to containers. You must first add acontainer before adding a widget."); bSuccess;return };});

Save the file as in the same directory as .Widget.js Container.js

Registering the Class Paths

Next, you'll register the path to your new classes, so that General Interface can find and loadthem.

34


1.

2. 3. 4.

To register the class paths:

Choose to open the Classpath panel of the ProjectProject > Project Settings > ClasspathSettings dialog.

Click in the Path field and type .js/

Type in the Packages field and click Save.*my.example.

Click at the Restart Required prompt to restart General Interface Builder and applyOKthe changes.

Creating Prototypes

Now that you've created and registered the GUI classes, you can create prototypes of them touse in General Interface Builder. Prototypes are pre-built components, which are serializedinstances of GUI objects that adhere to the General Interface serialization format.

In this step you'll create the Container and Widget prototypes.

The Container prototype will have these characteristics:

A name, Container, that appears in the Component Hierarchy paletteA description that appears in a tooltip in the Component Hierarchy paletteThe object type, , which is the class of the prototypemy.example.Container

The jsxname, , which is the name of the component in the Componentmycontainerthing

Hierarchy paletteA width and height of 100%An overflow that scrolls

The Widget prototype will have these characteristics:

A name, Widget, that appears in the Component Hierarchy palette

A description that appears in a tooltip in the Component Hierarchy palette

35


1.

2. a. b. c. d.

A description that appears in a tooltip in the Component Hierarchy paletteAn object type, my.example.Widget, which is the class of the prototypeThe jsxname, , which is the name of the component in the Componentmywidgetthing

Hierarchy paletteA width and height of 100%An absolute positionPositioned zero pixels from the top and left of the parent containerA background color of #cccccc

After you've created these prototypes, deployed the add-in, and enabled the add-in for aproject, you can drag and drop the prototypes from the Component Libraries palette into theLive Component view of the work area.

See for descriptions of the XML elements inPrototype Serialization File Definitionsthe prototype serialization files.

To create the Container prototype:

Choose and copy and paste this code into the emptyFile > New > XML Documentdocument:

<?xml version= ?>"1.0"<serialization xmlns= >"urn:tibco.com/v3.0" <name><![CDATA[Container]]></name> <description><![CDATA[Can only contain a widget]]></description> <object type= >"my.example.Container" <variants jsxoverflow= />"1" <strings jsxname= jsxwidth= jsxheight= >"mycontainerthing" "100%" "100%" </object></serialization>

Save the file: Choose and navigate to the root of the folder. File > Save myAddinClick the *New Folde*r icon and create a folder named prototypes. Open the folder. prototypes

Type in the file name field and click .Container.xml Save

36


1.

2.

To create the Widget protoype:


<?xml version= ?>"1.0"<serialization xmlns= >"urn:tibco.com/v3.0" <name><![CDATA[Widget]]></name> <description><![CDATA[Can only be contained by a container]]></description> <object type= >"my.example.Widget" <variants jsxleft= jsxtop= jsxwidth= jsxheight= >"0" "0" "100" "100" jsxoverflow= jsxrelativeposition= />"1" "0" <strings jsxname= jsxbgcolor= />"mywidgetthing" "#cccccc" </object></serialization>

Save the file as in the folder.Widget.xml prototypes

XML Element Attribute Description

serialization General Interface serialization file root element. Thiselement as well as all descendant elements mustbelong to the namespace, .urn:tibco.com/v3.0

name Prototype name that appears in the ComponentLibraries palette

description Description in a tooltip that appears when hoveringover the prototype in the Component Libraries palette

object type Prototype class name

variants jsxleft Position of object from left side of container

jsxtop Position of object from top of container

jsxwidth Prototype width

jsxheight Prototype height

jsxoverflow Whether or not to scroll (1), hide (2), or expand (3)when content is too large

jsxrelativeposition Prototype positioning, such as relative (1) or absolute(0)

strings jsxname Name that appears in the Component Hierarchypalette

jsxbgcolor Background color

Creating General Interface Builder Properties Files

In this step you'll create Container and Widget properties files, to integrate the new classes and with General Interface Builder. These properties files can then be used byContainer Widget

the Properties, Events, and XSL Parameters palettes when editing instances of the new classes.

37


1.

2. a. b.

3. 4.

After custom properties are created and loaded by the General Interface system, they appear inthe Properties Editor palette when the component is selected. Then you can set properties foryour custom components in General Interface Builder, just as you do with General Interfacecomponents.

The properties file adheres to the Common Data Format (CDF). Properties are organized bycategories ( ) and each category has individual fields ( ) that correspond to rows ingroup record

the Properties Editor palette. For more information on CDF, see Common Data Format (CDF) inthe General Interface Developer Guide.

For examples of General Interface Builder files that define properties, events, and XSLparameters, see these directories in the GI_HOME directory:

GI_Builder\plugins\jsx3.ide.palette.events\templates

GI_Builder\plugins\jsx3.ide.palette.properties\templates

GI_Builder\plugins\jsx3.ide.palette.xslparams\templates

Note that you can also create a file, such as , that contains common properties andmaster.xml

then include that file in a properties file. For example: <record group="object"include="master.xml"/>

For examples of how this is done, see General Interface Builder properties files in .GI_Builder\plugins\jsx3.ide.palette.properties\templates

For definitions of attributes in the properties file, see Attribute Definitions for. The properties file, which adheres to CDF format,Prototype Properties Files

contains records that correspond to fields in the Properties Editor palette.

To create the properties file for Container:

Choose and copy and paste the code shown below thisFile > New > XML Documentprocedure into the empty document.Save the properties file:

Choose and navigate to the root of the folder. File > Save myAddinClick the icon and create a folder named properties.New Folder

Open the folder.propertiesType in the file name field and click .Container.xml Save

<?xml version= encoding= ?>"1.0" "UTF-8"

<data jsxid= >"jsxroot" <record group= jsxid= jsxtext= >"1" "object" "Object" <record docnoprop= eval= getter= jsxid="true" "0" "getClass" "jsxinstanceof" jsxtext= jsxtip="The JSX foundation class that this object"Object Type" is an instance of. 1"/>" uneditable="

<record docgetter= docnoprop= eval= jsxid= jsxtext="getId" "true" "0" "_jsxid" "ID" jsxtip= uneditable= />"The unique, system-assigned ID for this object." "1"

<record disallow= docgetter="\[\\u0022\u003C\u003E\u0027\u0026\\]" "getName" docsetter= eval="setName" "0"

38


jsxexecute="objJSX.setName(vntValue);jsx3.ide.onDomChangeSleep();" jsxid= jsxmask= jsxtext= jsxtip="Sets the name"jsxname" "jsxtext" "Name" assigned by the developer to identify this object."/> </record>

<record group= jsxid= jsxtext= >"1" "position" "Positioning" <record docdefault="Relative(<code>jsx3.gui.Block.RELATIVE</code>\)" docgetter= docsetter= eval= "getRelativePosition" "setRelativePosition" "1"jsxexecute= jsxid="objJSX.setRelativePosition(vntValue,true);"

jsxmask= jsxtext="jsxrelativeposition" "jsxselect" "Relative XY" jsxtip="Sets whether to place this object relatively or absolutely with respect to its container."> <enum jsxid= jsxtext= />"jsx3.gui.Block.ABSOLUTE" "Absolute" <enum jsxid= jsxtext= />"jsx3.gui.Block.RELATIVE" "Relative" </record>

<record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="If absolutely positioned,the default is 0. If relatively positioned, the default is empty." docgetter= docsetter= eval="getLeft" "setLeft" "0" jsxexecute="objJSX.setLeft(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue, true);" jsxid= jsxmask="jsxleft" "jsxtext" jsxtext= jsxtip="Sets the position of this object from left edge"Left" of container. If this object is absolutely positioned, this value is applied as an implied pixel or a percentage. For example, <code>10</code> or <code>15%</code>."/>

<record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="If absolutely positioned, the default is 0. If relatively positioned, the default is empty." docgetter= docsetter= eval="getTop" "setTop" "0" jsxexecute="objJSX.setTop(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask= jsxtext="jsxtop" "jsxtext" "Top" jsxtip="Sets the position of this object from top edge of container. If this object is absolutely positioned, this value is applied as an implied pixel or a percentage. For example, <code>10</code> or <code>15%</code>."/>

<record disallow= docdefault="[^cm^pt^\.^%^0-9^-]" "Empty" docgetter= docsetter= eval="getWidth" "setWidth" "0" jsxexecute="objJSX.setWidth(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask= jsxtext="jsxwidth" "jsxtext" "Width" jsxtip="Sets the width of the control as implied pixels or a percentage. For example, <code>100</code> or <code>25%</code>."/>

<record disallow= docdefault="[^cm^pt^\.^%^0-9^-]" "Empty" docgetter= docsetter= eval="getHeight" "setHeight" "0" jsxexecute="objJSX.setHeight(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask= jsxtext="jsxheight" "jsxtext" "Height" jsxtip="Sets the height of the control in pixels or percentage. For example,

39


<code>100</code> or <code>25%</code>."/>

<record disallow= docdefault="[^0-9^-]" "<code>1</code>" docgetter= docsetter= eval="getZIndex" "setZIndex" "1" jsxid= jsxmask= jsxtext="jsxzindex" "jsxtext" "Z-Index" jsxtip="If this object is absolutely positioned, sets the CSS z-index. The z-index sets the stack order of an element."/> </record>

<record group= jsxid= jsxtext= >"1" "myexamplefield" "Category Label for Container" <record jsxtip="This is a container. It can contain other containers as well as widgets. Click on the button to activate the custom editor mask." docgetter= docsetter= eval="getBackgroundColor" "setBackgroundColor" "0" jsxexecute="objJSX.setBackgroundColor(vntValue,true);" jsxid= jsxmask="jsxbgcolor" "jsxtext"

40


1.

2.

jsxtext= />"Field Label (BGColor)" </record></data>

When the Container properties file is loaded in the Properties Editor palette in GeneralInterface Builder, it looks like this:

To create the properties file for Widget:

Choose and copy and paste the code that follows thisFile > New > XML Documentprocedure into the empty document.Save the properties file as in the folder.Widget.xml properties

<?xml version= encoding= ?>"1.0" "UTF-8"

<data jsxid= >"jsxroot" <record group= jsxid= jsxtext= >"1" "object" "Object" <record docnoprop= eval= getter="true" "0" "getClass" jsxid= jsxtext="jsxinstanceof" "Object Type" jsxtip="The JSX foundation class that this object is an instance of." uneditable= />"1"

<record docgetter="getId" docnoprop= eval="true" "0" jsxid= jsxtext="_jsxid" "ID" jsxtip= uneditable= />"The unique, system-assigned ID for this object." "1"

<record disallow="\[\\u0022\u003C\u003E\u0027\u0026\\]" docgetter= docsetter= eval="getName" "setName" "0" jsxexecute="objJSX.setName(vntValue);jsx3.ide.onDomChangeSleep();" jsxid= jsxmask= jsxtext="jsxname" "jsxtext" "Name" jsxtip= />"Sets the name assigned by the developer to identify this object." </record>

41


<record group= jsxid= jsxtext= >"1" "position" "Positioning" <record docdefault="Relative(<code>jsx3.gui.Block.RELATIVE</code>\)" docgetter= docsetter= eval="getRelativePosition" "setRelativePosition" "1" jsxexecute="objJSX.setRelativePosition(vntValue,true);" jsxid= jsxmask= jsxtext="jsxrelativeposition" "jsxselect" "Relative XY" jsxtip="Sets whether to place this object relatively or absolutely with respect to its container."> <enum jsxid= jsxtext= />"jsx3.gui.Block.ABSOLUTE" "Absolute" <enum jsxid= jsxtext= />"jsx3.gui.Block.RELATIVE" "Relative" </record>

<record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="If absolutely positioned, the default is 0. If relatively positioned, the default is empty." docgetter= docsetter= eval="getLeft" "setLeft" "0" jsxexecute="objJSX.setLeft(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask= jsxtext="jsxleft" "jsxtext" "Left" jsxtip="Sets the position of this object from left edge of container. If this object is absolutely positioned, this value is applied as an implied pixel or a percentage. For example, <code>10</code> or <code>15%</code>."/>

<record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="If absolutely positioned, the default is 0. If relatively positioned, the default is empty." docgetter= docsetter= eval="getTop" "setTop" "0" jsxexecute="objJSX.setTop(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask="jsxtop" "jsxtext" jsxtext= jsxtip="Sets the position of this object from top edge"Top" of container. If this object is absolutely positioned, this value is applied as an implied pixel or a percentage. For example, <code>10</code> or <code>15%</code>."/>

<record disallow= docdefault="[^cm^pt^\.^%^0-9^-]" "Empty" docgetter= docsetter= eval="getWidth" "setWidth" "0" jsxexecute="objJSX.setWidth(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask= jsxtext="jsxwidth" "jsxtext" "Width" jsxtip="Sets the width of the control as implied pixels or a percentage. For example, <code>100</code> or <code>25%</code>."/>

<record disallow= docdefault="[^cm^pt^\.^%^0-9^-]" "Empty" docgetter= docsetter= eval="getHeight" "setHeight" "0" jsxexecute="objJSX.setHeight(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);" jsxid= jsxmask= jsxtext="jsxheight" "jsxtext" "Height" jsxtip="Sets the height of the control in pixels or percentage. For example, <code>100</code> or <code>25%</code>."/>

<record disallow= docdefault="[^0-9^-]" "<code>1</code>" docgetter= docsetter= eval="getZIndex" "setZIndex" "1" jsxid= jsxmask= jsxtext="jsxzindex" "jsxtext" "Z-Index"

42


jsxtip="If this object is absolutely positioned, sets the CSS z-index. The z-index sets the stack order of an element."/> </record>

<record group= jsxid= jsxtext= >"1" "myexamplefield" "Category Label for Widget" <record jsxtip="This is a widget. It can only be contained by a container." docgetter= docsetter= eval="getText" "setText" "0" jsxexecute="objJSX.setText(vntValue);objJSX.repaint();" jsxid= jsxmask= jsxtext= />"jsxtext" "jsxtext" "Field Label (Text)"

43


</record>

</data>

When the Widget properties file is loaded in the Properties Editor palette in General InterfaceBuilder, it looks like this:

Now that you've created a properties file for each prototype, you'll create a catalog file thatdescribes the location of these files to the General Interface system. You'll do this in Creating

.and Loading the Catalog File

44


Attribute Description

disallow Restricts user input using a regular expression.

docdefault Documented default value for the property, which appears in the spyglass. If"Empty" there isn't a default value.

docgetter Documented getter for the property, which appears in the spyglass.

docsetter Documented setter for the property, which appears in the spyglass.

docnoprop Set to if some of the documentation shouldn't appear in the spyglass. In thistrue

example, only the tip and the getter appear in the spyglass: docgetter="getId"docnoprop="true"

eval Determines if the user input should be evaluated as a number using a JavaScripteval before committing. If set to 1, user input is evaluated. If set to 0, user inputis not evaluated as a number and is treated as a String. For example, thePositioning Relative XY property has two choices, each of which evaluates to anumber, because . eval="1"

jsx3.gui.Block.ABSOLUTE evaluates to 0

jsx3.gui.Block.RELATIVE evaluates to 1

group Correspond to categories in the Properties Editor palette. In this example, thereare three groups---Object, Positioning, and Category Label.

jsxexecute JavaScript code to execute that updates the object after the user changes thevalue. This code has access to the contextual variables, (the reference toobjJSX

the JSX Object being edited) and (the value just entered by the user).vntValue

jsxid Required system attribute that uniquely identifies a CDF record, acts as a key,and must be a unique value.

jsxmask Name of a pre-built set of masks. For example, use for a text box and jsxtext

for a drop-down list of items. For masks, use the jsxselect jsxselect enum

element to specify the items in the list. For example, the Positioning property hasthese items:

<enum jsxid= jsxtext= />"jsx3.gui.Block.ABSOLUTE" "Absolute"<enum jsxid= jsxtext= />"jsx3.gui.Block.RELATIVE" "Relative"

jsxtext System attribute that defines the visible text (label) for the record in theProperties Editor palette.

jsxtip Description that displays in the spyglass when you hover over the property. UseHTML markup to format the description.

For more information about CDF, see the General Interface Developer Guide.

Creating and Loading the Catalog File

Now that you've created a properties file for the Container and Widget prototypes, you'll create to define the path to them. After creating the catalog file, you'll use the API catalog.xml

to create a JavaScript file that loads the catalog file.jsx3.ide.loadTemplateCatalog

45


1.

2. a. b.

1. 2.

3. a. b. c.

After the catalog file is created and loaded, General Interface reads it and loads the appropriateproperties file into the Properties Editor palette when a Container or Widget object is selected inthe user interface.

To create the catalog file:


<?xml version= encoding= ?>"1.0" "UTF-8"<data jsxid= >"jsxroot" <record jsxid= jsxtext= />"my.example.Container" "properties/Container.xml" <record jsxid= jsxtext= />"my.example.Widget" "properties/Widget.xml"</data>

Note that the path to the properties file is relative to the project directory.

Save the properties file:Choose and navigate to the folder.File > Save properties

Type in the file name field and click .catalog.xml Save

To load the catalog file:

Choose *File > New > JavaScript File t*o create a new JavaScript file.Copy and paste this code into the blank JavaScript file:

// is the declarationthis package (jsx3.ide)if

jsx3.ide.loadTemplateCatalog("prop","properties/catalog.xml",my.example.ADDIN);

The loadTemplateCatalog() method loads a template catalog for the Properties Editorpalette, Events Editor palette, or XSL Parameters palette. For more information, see the

method in the General Interface API Reference.jsx3.ide.loadTemplateCatalog()

Save the JavaScript file: Choose and navigate to the folder. File > Save jsOpen the folder. myType in the file name field and click .package.js Save

Deploying the Custom Add-in

In this step you'll make the project available as an add-in:

Copy the project to the Addins folder.Modify the add-in configuration file, which includes such data as add-in name space, filelocations, and so on. describes the values in theAdd-in Configuration File Definitionsconfiguration file.Enable your add-in for testing and test the add-in.Make your add-in available for general use.

To make the add-in available:

46


1. 2.

1.

2. 3.

4.

To make the add-in available:

Close General Interface Builder and the myAddin project.In the file system, copy the myAddin project from to the /JSXAPPS/myAddinworkspace

directory in your workspace directory. For example, .addins /addins/myAddinworkspace

To modify the configuration file:

Open the add-in configuration file in an editor./addins/myAddin/config.xml*workspace

The add-in configuration file is different from the project configurationfile. Modify the configuration file only in the copy of the add-in within the

directory, not the original project.addins

Select and delete the existing text.Copy and paste this code into {{config.xml:}}

<?xml version= ?>"1.0"<data jsxid= >"jsxroot" my.example<record jsxid= type= >"id" "string" </record> My Example Addin<record jsxid= type= >"name" "string" </record> ExampleAddin v1.0<record jsxid= type= >"description" "string" </record> This is an addin that<record jsxid= type= >"long_description" "string" integrates with the IDE by extending the properties editor palette</record> my.example.ADDIN<record jsxid= type= >"addin" "string" </record> 1.0<record jsxid= type= >"version" "string" </record> 3.4<record jsxid= type= >"jsxversion" "string" </record> js/:my.example.*<record jsxid= type= >"classpath" "string" </record>

<record jsxid= type= >"includes" "array" <record jsxid= type= >"0" "map" 1<record jsxid= type= >"load" "number" </record> script<record jsxid= type= >"type" "string" </record> js/my/package.js<record jsxid= type= >"src" "string" </record> </record> </record></data>

Save and close the file.

These are the values in the add-in configuration file.

47


1. 2.

a. b. c. d.

1.

jsxid Value Description

"id" Add-in namespace

"name" Displays in the Name column on the Add-ins panel of the Project Settingsdialog (Project > Project Settings)

"description" Displays in the Description column on the Add-ins panel of the ProjectSettings dialog (Project > Project Settings)

"long_description" Displays in a tooltip when hovering over the add-in on the Add-ins panelof the Project Settings dialog (Project > Project Settings)

"addin" Add-in ID in the form of packagename.ADDIN

"classpath" Path to the add-in classes

"load" If set to the JavaScript file specified in jsxid="src" is automatically1,

loaded at runtime

"type" Type of file to load, such as for a JavaScript filescript

"src" JavaScript file that initializes the add-in and registers the catalog file withGeneral Interface Builder

To enable myAddin for testing:

Create a new project ( ) for testing myAddin.Project > New ProjectEnable the myAddin add-in for the test project:

Choose . Project > Project Settings > Add-insClick the checkbox next to My Example Addin to enable it. OnClick the button. SaveClick at the Restart prompt to restart General Interface Builder.OK

To test myAddin:

Expand the folders in the Component Libraries palette.Addins > My Example Addin

48


1.

2.

3.

4.

5. 6.

7.

1.

2.

3.

Drag and drop the new Container prototype from the Component Libraries palette intothe Live Component view of the work area.Drop a component other than Widget onto Container. The action is vetoed and thismessage appears in the System Log palette: The child object could not be accepted,because it is not of type container or widget.

Drag and drop the new Widget prototype from the Component Libraries palette onto theContainer in the work area. The Container accepts the Widget.Delete Container and Widget.Try adding a Widget to a different type of container, such as Dialog or Layout. Theaction is vetoed and this message appears in the System Log palette: Widgets can onlybe added to containers. You must first add a container before adding a widget.

Select each of the Container and Widget components in the work area and confirm thatthe properties in the Properties Editor palette display correctly.

To make myAddin available for general use:

Deploy the applications that use the add-in to a web server as described in the "PostingApplication Files" section in the General Interface Developer Guide.Copy the folder to the folder on the same web server as the deployedmyAddin addinsapplication. The folder must be at the same level as the folder to beaddins JSXAPPSavailable at runtime.Test the deployed projects that use the myAddin add-in to be sure everything is workingas expected.

This completes the tutorial. For an example of a full-featured add-in, see the General InterfaceCharting add-in located in ./JSX/addins/chartingGI_HOME

49


Chapter 7 System Components

This chapter describes the System components in the Component Libraries palette.

BlocksContainersForm ElementsMatrix ComponentsMenus and ToolbarsMiscellaneous

Blocks

A block component is a generic container that displays HTML, including text and images. Ablock is rendered on-screen as an HTML element, although other HTML types arespan

supported. A block can serve as a background or as a divider for areas of the application with acommon function. Blocks can also display images or text in other components.

To avoid unexpected layout behavior in deployed applications, it's recommended touse Block as a container if it meets of these requirements:only one

The Block is owned by a layout manager, such as LayoutGrid, Tab, Stack, andSplitter.The Block is relatively positioned and has a width of 100%.The Block is absolutely positioned.

Name Icon Description

Block -100%

A simple, relatively positioned block that fills the entire component area.Useful as a container or background for other components.

Block -Absolute

An absolutely positioned block that is positioned at the top left of the parentGUI component.

BlockX An absolutely positioned block that can display XML data. An XSL file canbe specified to filter and modify the XML.

Image A relatively positioned image from a file. The file is referenced using the TagName property. The path to the image is defined by the attribute in thesrc

Attributes Editor.

Label A relatively positioned text label. Useful as a label for a Text Boxcomponent.

Text A relatively positioned text area that is useful for larger blocks of text.

50


Cross-browser Box Model

With the introduction of the new cross-browser box model in General Interface 3.2 and higher,padding, margin, and border properties are managed by the system, not the browser.

The new box model rules that relate to left, top and margin are:

If position is absolute, left and top are honored. Margin is ignored.If position is relative, margin is honored. Left and top are ignored.

Containers

A container is a component that does not display data and serves as a container for othercomponents.


Dialog A block with a border and caption bar. The caption bar has minimize,maximize, and close buttons.

IFrame An inline frame for including external objects, such as other non-GeneralInterface HTML documents.

Layout(Side/Side)

A background with two vertical panes that fills the entire component area.

Layout(Top/Over)

A background with two horizontal panes that fills the entire componentarea.

Splitter - H A horizontal divider that splits a pane into two areas. Users can click anddrag the divider vertically.

Splitter - V A vertical divider that splits a pane into two areas. Users can click anddrag the divider horizontally.

Stack A horizontal or vertical sliding pane with a caption bar for a stack group.

StackGroup - H

A background with two horizontal, sliding panes that fills the entirecomponent area. Each pane has a caption bar; clicking the caption bardisplays the area.

StackGroup - V

A background with two vertical, sliding panes that fills the entirecomponent area. Each pane has a caption bar; clicking the caption bardisplays the pane.

Tab A tab for a tabbed pane.

TabbedPane

A pane with three tabs. Each tab has a caption; clicking the captiondisplays the pane.

Form Elements

Form elements are GUI components for collecting user input.

51



Button A button with text. To define button behavior, configure the Executeevent.

Button -ImageButton

A button with an image instead of text. You can assign an image for thebutton as well as images for over, down, on, and disabled. To definebutton behavior, configure the Execute event.

CDFMappingContainer

A container that maps descendents to a CDF document.

Checkbox A tri-state checkbox field that can be selected, unselected, or both.

Color Picker An HSB color picker control, an instance of .jsx3.gui.ColorPicker

Date Picker A text field that, when clicked, displays a calendar control for selecting adate value. The date value is automatically specified in the correctformat. To select a date format, specify a value for the Format propertyby selecting from the lookup menu.

Multiselect A matrix that allows one or more items in a list to be selected. To definethe list of items, associate it with an XML string, file, or cache document.

RadioButton

A radio button with text label. To define button behavior, configure theSelect event. To define a group of radio buttons as mutually exclusive,specify the same value for the Group Name property.

Select A non-editable drop-down where only one option can be selected.Options are XML elements (CDF format) referenced by the XML CacheId, XML String, or XML URL property.

Select -Combo

A combination text field and drop-down list. Typing in the text fieldnarrows the list to display only possible matching values. The jsxidattribute of the select is persisted in the CDF data model while the

attribute is displayed in the combo box.jsxtext

Slider A horizontal slider control.

Text Area A multi-line text field with a scrollbar.

Text Box A simple text field.

Text Box -Password

A text box for entering sensitive values. Alphanumeric characters arerepresented by bullet characters.

Time Picker A clock for selecting the hour, minute, and AM or PM. Seconds,milliseconds, and a 24 hour clock can also be displayed.

52


Matrix Components

The Matrix component replaces Grid, List, and Column, which are deprecated. Matrixcombines the features of a grid, list, and tree in a single component. A matrix, which is similarto a spreadsheet, has a tabular structure with rows that can be selected and cells that can beeditable. Matrix components also provide built-in support for scrolling and pagination of largedata sets.The Matrix components include and jsx3.gui.Matrix jsx3.gui.Matrix.Column.

For more information, see .Using Matrix Components

Matrix

The Matrix components include these prototypes.


Grid A grid view with editable cells, a 2-pass paging model, and single cellselection. This paging model renders the outer container first, and theentire data set is rendered in a second pass. See for morePaging Modelsinformation.

List A list view with columns and sample data. List items are XML elements(CDF format) referenced by the XML Cache Id, XML String, or XML URLproperty. Users can sort data by clicking a column header. This list usesthe 2-pass paging model and supports multiple row selection.

MultiSelect A matrix that allows one or more items in a list to be selected and isrendered using a 2-pass paging model. To define the list of items,associate it with an XML string, file, or cache document.

PaginatedList

A matrix with a list and a paged paging model. This model renders theouter container first. The first and last panels are rendered during asecond pass. As the user scrolls, relevant panels are added and unusedpanels are collected. During scrolling, information is displayed using theScroll Info property. : The row height must be fixed. This prototypeNotealso uses paging tuners to optimize performance, such as number ofpooled panels, rows per panel, and number of panels in the paint queue.

Tree A tree view that supports drag-and-drop and has a stepped paging model.Data is only painted when the state of the on-screen parent row is toggledto open. Use the Matrix tree for a more robust component and fasterrendering. Use the lightweight Tree component (Miscellaneous > Tree) forsimpler trees that aren't deeply nested and all data is painted on loading.

Matrix Column

The Matrix Column components include the following prototypes:


53


Button A column of buttons. To define button behavior, configure the Executeevent in the Events Editor palette. Honors the (per-row@jsxdisabled

disabling of mask) and (per-row hiding of mask) CDF@jsxnomask

attributes.

Button -Delete

A column of Delete buttons with a delete icon. When a Delete button isclicked, the CDF record is deleted from the matrix. Note the Executeevent assigned to the ImageButtonMask in the Events Editor palette.Honors the (per-row disabling of mask) and @jsxdisabled @jsxnomask

(per-row hiding of mask) CDF attributes.

Button -ImageButton

A column of buttons with icons. Use the Image property to specify thepath to an icon file. To define button behavior, configure the Executeevent in the Events Editor palette. Honors the (per-row@jsxdisabled

disabling of mask) and (per-row hiding of mask) CDF@jsxnomask

attributes.

Button -ToolbarButton

A column of toolbar buttons with icons. Use the Image property tospecify the path to an icon file. To define button behavior, configurethe Execute event in the Events Editor palette. Honors the

(per-row disabling of mask) and (per-row@jsxdisabled @jsxnomask

hiding of mask) CDF attributes.

Checkbox A column of checkboxes that can be selected or unselected. A checkedcheckbox updates the CDF attribute to . An uncheckedchecked 1

checkbox evaluates to . Honors the (per-row disabling0 @jsxdisabled

of mask) and (per-row hiding of mask) CDF attributes.@jsxnomask

Date A column of dates. Renders a date according to a configurable dateformat. The data model can store the dates as epoch seconds, a stringparsable by the column date format, or a format recognized by theJavaScript method.Date.parse()

Date Picker Extends the Date column with a DatePicker edit mask, which is a textfield that when clicked displays a calendar control for selecting a datevalue. The date value is automatically specified in the correct format.To select a date format, specify a value for the Date Format property byselecting from the lookup menu.

Image A column of HTML images. Use the Path property to specify the imageattribute.

Mask - Block Example of using a block as an edit mask for a Matrix column. A blockwith a single child of type is supported out-of-the-box.jsx3.gui.Form

For more complex behavior, implement the methods , getMaskValue()

, and . See the APIsetMaskValue() getMaskFirstResponder()

documentation for .jsx3.gui.Matrix.BlockMask

Mask - Dialog Example of using a dialog as an edit mask for a Matrix column.

Menu Displays a column of menus, each menu with a drop-down list ofoptions. Options are XML elements (CDF format) referenced by theXML Cache Id, XML String, or XML URL property. Honors the

(per-row disabling of mask) and (per-row@jsxdisabled @jsxnomask

hiding of mask) CDF attributes.

54


Radio Button A column of radio buttons. Only one row may be selected at a time.Sets the CDF attribute specified in the Path property to radioed (1)when checked. Honors the (per-row disabling of mask)@jsxdisabled

and (per-row hiding of mask) CDF attributes.@jsxnomask

Select A column of drop-down lists. Options in the list are XML elements inthe CDF document referenced by the Path property. The jsxidattribute of the select is persisted in the CDF data model while the

attribute is displayed in the matrix cell.jsxtext

Select -Combo

A column of combination text fields and drop-down lists. Typing inthe text field narrows the list to display only possible matching values.The attribute of the select is persisted in the CDF data modeljsxid

while the attribute is displayed in the matrix cell.jsxtext

Text A column of uneditable text fields.

Text - HTML A column of uneditable text fields that renders a CDF attribute as rawHTML. Uses the Format Handler property for Firefox@unescape

support and the Value Template property for Internet@unescape

Explorer support.

Text -Number

A column of uneditable text fields that formats a number according toa number format. Supported format handlers include , @number

, , and @number,integer @number,percent @number,currency.

Text Area A column of multi-line editable text fields with scrollbars. The editmask can be larger than the data cell.

Text Field A column of editable text fields. Data specified in a field updates theCDF attribute referenced by the Path property.

Time Renders a time according to a configurable date format. The datamodel can store the dates as epoch seconds or a string formatrecognized by the method.JavaScript Date.parse()

Time Picker Extends the Time column with a TimePicker edit mask, which rendersa clock for selecting the hour, minute, and AM or PM. Seconds,milliseconds, and a 24 hour clock can also be displayed.

Menus and Toolbars

Menus and toolbars are GUI components for executing commands or JavaScript functions.


Menu A menu with a drop-down list of options. Options are XML elements (CDFformat) referenced by the XML Cache Id, XML String, or XML URL property.

MenuBar

A generic background for multiple menus.

Taskbar A taskbar with icons for maximized and minimized dialogs.

55


Toolbar A generic background for multiple toolbar buttons.

ToolbarButton

A toolbar button with an image and label. To define button behavior,configure the Execute event. To define a group of buttons as mutuallyexclusive, specify the same value for the Group Name property.

Miscellaneous

The Miscellaneous components include the following:


Sound A sound component that can be played programmatically in a GeneralInterface application.

SoundButton

A button that plays a sound when pressed.

Table A lightweight table component for fast, read-only rendering of large data sets.Because this is a lightweight component designed for fast performance, it hassome but not all of the features of . Use the Matrix componentjsx3.gui.Matrix

for more complex behaviors, such as editable data, rendering models, andpaging models. For more information, see .Using the Table Component

Tree A hierarchical tree control with custom icons. Trees are hierarchical structureswith nodes that can be expanded or collapsed. Items are XML elements (CDFformat) referenced by the XML Cache Id, XML String, or XML URL property.Use this lightweight component for simple trees that aren't deeply nested andall data is painted on loading. Use the Matrix tree for a more robustcomponent and faster rendering. The Matrix tree supports dynamically loadeddata, as well as drag and drop.

56


Chapter 8 Using the Table Component

This chapter describes how to use Table component in a General Interface application.

Introduction to the Table ComponentUser InteractionsTable Properties

Introduction to the Table Component

The Table component, , is a lightweight component designed for fast, read-onlyjsx3.gui.Table

rendering of large data sets. The Table component displays CDF data in an HTML table andsupports both single- and multiple-selection modes. Data can be sorted by clicking on columnlabels. Output and output formatting can be customized using a combination of XSLT, inlineCSS properties, or named CSS rules. The columns for this component are defined within theobject model and are not defined in the DOM as child objects.

To use the Table component, open the folder in the Component LibrariesMiscellaneouspalette, select the component, and drag it into the Live Component view of the workTablearea.

For more complex behaviors and editable cells, use the Matrix component. For moreinformation, see .Using Matrix Components

User Interactions

The Table component supports these user interactions:

Selection Click a data row to select a single row. Ctrl+click or Shift+click to select multiple rows. If the selection model is Single Row or Multi-row, the Change event will betriggered each time the user changes the row selection.

ExecuteDouble-click a row to execute it. If there is a jsxexecute property on the target CDFrecord, that code is executed, followed by the Execute event for the instance, if set.SpyglassHover over a row to fire any bound Spyglass code for the instance.ScrollingIf the list of rows is too long or column widths are too great, scroll horizontally orvertically using the scroll-wheel or by dragging the scrollbar.SortingClick a header cell to sort the table according to the given column. Only numeric andtext-based sorting are supported.

57


Table Properties

This section describes some of the Table component properties. For information on otherproperties, see General Interface GUI Property Reference or hover over a property name in theProperties Editor palette.

For more information on General Interface APIs for the Table component, see jsx3.gui.Tablein General Interface API Reference.

Column Definitions

All column-specific information for the Table component is defined by an instance propertyinstead of in the serialization file as is common with other components, such as Matrix. TheColumn property maps to a CDF document, which defines the metadata that determines howcolumns are rendered. Metadata includes width, column label, mapped attribute name, andattribute data type.

To define metadata for columns in a table, use the Column editor. Simply click the ColumnEditor button in the Properties Editor palette next to the Value field of the Columns propertyand enter Column Label, Width, Attribute Name, and Attribute Data Type values. Then clickthe Update button. Values in the Column editor are saved in CDF format.

When working in the Column editor, use the following buttons to add, delete, and reorderrows. Then click the button to save your changes.Update

Button Description

Adds a row after the last row.

58


Deletes the row.

Moves the row up.

Moves the row down.

Column Metadata

You can enter this metadata for a Table column:

Column Label the text/HTML to use for the column.Width the width of the column. Specify integers or percentage.Attribute Name the named attribute mapped to the column.Attribute Data Type the data type for the mapped attribute which is used in sorting.Select Text or Number.

Formatting Rows and Cells

You can format headers, rows, and cells in a table in these ways:

Inline CSS style propertiesNamed CSS rulesXSL templates

Multiple properties and rules are supported for inline CSS and CSS rules. You can also setstyles for alternate rows. Cell styles, however, are applied to all cells in the body of the table.For custom formatting of individual cells, specify an XSL template for the Value Templateproperty. Because the XSL template is shared by all columns, conditional output must behandled by the XSL template.

Also, if any custom formatting is required for HTML output-escaping, localization, and so on,the XML Transformers property provided by the interface should be usedjsx3.xml.Cacheable

instead of relying on a list of named resolvers as is currently supported by Matrix.

For more information, see Style, Class, Style (Alt), Class (Alt), and Value Template properties inGeneral Interface GUI Property Reference and in General Interface APIjsx3.gui.Table

Reference.

Specifying Column Header Height

Because browsers render the box profile differently, do specify a CSS height property whennotapplying styles to column label HTML of the Table component. Use CSS padding, border, andfont-size properties to control height instead of a CSS height property.

For example, if you want a header of 29 pixels, set the font size, padding, and border so that thesum of their heights equals 29 pixels. In the following column label example, the sum of theheights is equal to 29:

<div style='font-size:12px;padding:8px;border-right:solid 1pxgray;border-bottom:solid 1px gray'>Col 1</div>

12 (font)+ 16 (padding) + 1 (bottom border) = 29

The steps for setting column height include:

59


1.

2.

3.

Specify the height of the row that contains the column labels (the header) in the HeaderHeight property in the Properties Editor palette. Note that the Header Height propertyvalue should be equal to the sum of the heights of the CSS style properties: font size,border, and padding.Decide and calculate the height of the CSS style properties: font size, border, andpadding. Remember that the sum of these heights should be equal to the Header Heightproperty value. For example, if the Header Height property is set to 20, the height of fontsize, border, and padding should equal 20.Enter the CSS values in the Column Label field of the Column editor. Click the ColumnEditor button in the Properties Editor palette next to the Value field of the Columnsproperty to open the Column editor.

The next figure demonstrates a column header that is set properly. The Header Height propertyin the Properties Editor palette is 29 and the sum of the height of the CSS style properties equals29.

The next figure demonstrates a column header that is not set properly. The Header Heightproperty is 100 and the sum of the height of the CSS style properties equals 29.

60


61


Chapter 9 Using Matrix Components

This chapter describes how to use Matrix components in a General Interface application.

Introduction to Matrix ComponentsRendering ModelsPaging ModelsFine Tuning for PerformanceMatrix PropertiesContent Formatting and LocalizationProperties

Introduction to Matrix Components

The Matrix component, a composite of List, Grid, Column, and Tree components, is thestandard visual interface for the Common Data Format (CDF), providing grid and tree-gridfunctionality that mirrors the record and attribute structures used by the CDF.

The Matrix components include:

jsx3.gui.Matrix : A control with spreadsheet capabilityjsx3.gui.Matrix.Column : A column control for use as a child of a class.jsx3.gui.Matrix

In addition, the interface may be used by jsx3.gui.Matrix.ColumnFormat Matrix.Column

instances to format a cell of data during the afterpaint event for the given instance. StaticMatrix

implementations of the most common formatters are provided, including currency, number,and date.

The Matrix component replaces List, Grid, and Column, which have beendeprecated.

For definitions of Matrix properties, see and General Interface GUI PropertyMatrix PropertiesReference.

For more information about CDF, see the General Interface Developer Guide and the GeneralInterface API Reference.

Rendering Models

The Matrix component displays CDF data on-screen using a rendering model. The renderingmodel uses a context node, which is the reference or starting point, to begin rendering. Thecontext node itself isn't rendered, but its children or its descendants are painted.

In this CDF example, the default context node would be the element, because it has a valuedata

of for the attribute. The children, elements, would be rendered to thejsxroot jsxid record

screen. Specifying a context different than will change which element in the CDF willjsxroot

be used as the context.

62


be used as the context.

<data jsxid= xmax= ymax= >"jsxroot" "50" "50" <record jsxid= x= y= m= />"1" "4" "2" "5" <record jsxid= x= y= m= />"2" "14" "40" "15" <record jsxid= x= y= m= />"3" "42" "24" "3"</data>

There are three rendering models: shallow, deep, and hierarchical. Shallow and deep are flatmodels, while the hierarchical model is rendered as a tree. Shallow only paints direct childrenof the context node. Deep paints all descendants. Hierarchical paints all children, but can alsobe performance-tuned to paint a given number of generations at a time. Because this allowsnodes to be fetched only when a user expands a given branch, application performance is faster.

Use the lightweight Tree component (Miscellaneous > Tree) instead of the Matrixwhen your tree does not need multiple columns, formatters, and edit masks. Forexample, GI Builder uses a Matrix tree for the Properties Editor palette while using asimple tree for the Component Libraries palette.

Paging Models

The Matrix uses various paging models to improve overall rendering performance and simplifyperformance tuning tasks for the developer. Paging models determine how much and whendata is displayed. The key paging models include the following types.

Property Static Field Description

No paging Matrix.PAGING_OFF Paging is turned off. All data is painted at once withthe outer container.

2-pass Matrix.PAGING_2PASS The empty outer container is painted first. Then alldata is painted in a second pass.

Chunked Matrix.PAGING_CHUNKED The outer container is painted first. Chunked sets ofdata are painted on-screen during repeated passesuntil all data is painted. The chunk size can be tunedfor the use case. This is often determined by thenumber of records, screen size, column count, and soon.

Paged Matrix.PAGING_PAGED The outer container is painted first. The first and lastpanels are painted during a second pass. As the userscrolls, relevant panels are added and unused panelsare collected. Requires that row height beNote:fixed.

Stepped(hierarchical)

Matrix.PAGING_STEPPED This setting only applies to hierarchical models.When set, only expanded nodes are rendered. Thedata is fetched and painted on-screen when the userexpands a given node in the hierarchy.

63


Fine Tuning for Performance

The first step in choosing a rendering model is to choose a paging model. This is becausepaging models are affected and limited by the type of rendering model used. The followingtable details these constraints.

Rendering Model Available Paging Model

Hierarchical No pagingStepped

Shallow/Deep No paging2-passChunkedPaged

After you select a paging model, you can further refine the model by adjusting various tuners.Tuners provide greater control over how and when data is loaded. Note that tuners are notavailable for all models.

PagingModel

Available Tuners

2-pass Not available

Chunked Rows per Panel Number of rows in a panel.

Paged Panel Pool Size Number of panels allowed on-screen before destroying thepanel most distant from the current panel index.Rows per Panel Number of rows in a panel.Panel Queue Size Number of panels in the paint queue. As new panels areadded to the queue to be painted, less-relevant panels in the queue areremoved.

Stepped Not available

With the appropriate combination of rendering, paging, and tuning models, performance isgreatly improved. For example, a four-column table of 250 rows renders with the bestperformance with these settings:

Rendering Model: DeepPaging Model: PagedTuners:

64


Panel pool size: 5Rows per panel: 50Panel queue size: 3

Other factors might affect rendering performance, such as how often the instance is repainted,but this profile typically performs well.

For better performance, do not repaint the Matrix each time you add a column. For example, toadd ten columns to a Matrix named matrix1, use this code:

var m = myServer.getJSXByName("matrix1");( i=0;i<10;i++) {for var

m.load("some/url/ /the/column/prototype.xml", );for false}m.repaint();

Note that passing to the load command suppresses repainting.false

Matrix Properties

This section provides an overview of some of the Matrix properties. For more informationabout Matrix properties, see General Interface GUI Property Reference or hover over propertynames in the Properties Editor palette.

Row Heights

The first constraint on row height is the paging model. If is used, thenMatrix.PAGING_PAGED

row height will be fixed, regardless of whether or not the user wants to use a flexible height. Inall other cases, if the user does not specify a row height (null), then the default height,

is used. If the specified row height is zero, a flexible height isMatrix.DEFAULT_ROW_HEIGHT,

used. For a fixed row height, specify a positive integer in implied pixels, such as . All paging14

models support fixed and flexible heights except for , which only allowsMatrix.PAGING_PAGED

for fixed heights.

Text Wrapping

Text wrapping is managed by the column children and can be specified differently for the labelin the column header and the data cells. If no value is specified, text wrapping is turned off.When implementing paging, it's recommended to disable text wrapping or make the rowheight large enough so that the wrapped text is not hidden.

Borders and Padding

With the introduction of the new cross-browser box model, padding and border settings aremanaged by the class. Borders and padding that wrap the header row and the entirety of thedata rows are managed by the Matrix, while borders and padding that wrap the header cellsand the individual data cells are managed by the Matrix Column children.

65


Column Widths

The Matrix automatically provides a horizontal scrollbar when the aggregate width of itscolumns is greater than the overall Matrix width. However, a scale width flag can be set,causing the rendering engine to reduce column widths until all content fits exactly within theview constraints. When rendering with a scaled width, it is often useful to include a wild cardwidth, such as an asterisk (*) , on columns whose width should be flexible. Percentage andimplied pixel values are also supported. For example, 50% or 25.

Content Formatting and Localization

The Matrix control supports three main mechanisms for formatting content:

XSLTJavaScriptEdit Masks

Many factors affect which approach to use, such as performance, developer skill set, and codemaintenance.

XSLT

When using the XSLT approach to customize the data output, a cell value template can bespecified for each column. The cell value template is effectively an XSL template that is underthe control of the developer. This template receives the following parameters, which can beused by the developer to gain the necessary context to author the template (in addition to theimplied CDF record context under which the template will execute).

Parameter Name Description

jsx_cell_width The client width of the cell, in pixels, into which the value will bepainted. Note that the value is placed inside of a combinationTD/DIV

and that the property is the available width provided byclientwidth

the DIV.

jsx_row_number This is the true, on-screen row number for this row in the grid(1-based).

jsx_descendant_index The hierarchical level which the context record is a part of. If a directchild of the element, this value is 1. If a grandchild, the value isdata

2, and so on.

To specify a custom template, call the method ( ) on thesetValueTemplate() jsxvaluetemplate

given column child. For example, the following is a custom value template thatxsl:template

inserts a dollar symbol ($) in front of the mapped attribute for the column. Notice the wildcard,{0}, which will be replaced with the value of the column's mapped path. This is then followedby the on-screen row number that the cell is a child of:

66


< = >xsl:template xmlns:xsl "http://www.w3.org/1999/XSL/Transform"< name= />xsl:\param "jsx_row_number"$< select= />xsl:value-of "{0}"< select= />xsl:value-of "$jsx_row_number"</ >xsl:template

XSLT and Standard Value Templates

In addition to creating custom value templates, you have the option to use one of the standardvalue templates, which is a property of Matrix Column.

ValueTemplate

Description

@image Provides support for relatively addressed images. For example, if a CDF recordhas a attribute, the URL for this image can be relative to the applicationjsximg

directory. The system automatically resolves the URI to the appropriate runtimelocation for the image.

@unescape Unescapes any on-screen entities to render the tagged output, not the tagsthemselves. Use this template if a CDF attribute contains HTML. In InternetExplorer, this is used to disable output escaping. In Firefox, a format handler bythe same name (@unescape) is used to facilitate output escaping. ForImportant:cross-browser support, be sure to set this property for both the format handlerand the value template fields.

@empty Used when the column embeds an edit mask such as a menu or button.

JavaScript

In addition to XSLT, JavaScript can be used to further format the output of the cell data. Usingthe JavaScript approach, the cell data is painted on-screen first, and then a function is notifiedthat a given cell needs further formatting.

There are two ways to use JavaScript to format the output:

Use column formats provided by the interfacejsx3.gui.Matrix.ColumnFormat

Use a function literal

ColumnFormat Interface

The simplest way to do this is to use one of the standard column formats provided by the interface.jsx3.gui.Matrix.ColumnFormat

67


Formatter Description

@number,integer@number,percent@number,currency

Converts the numeric value in the cell to a localized number format. Forexample, for @number currency, if the cell's value is 25 it is converted to$25.00, if the application is using the default localization (us_en) and@number, currency is specified.

@datetime,short@datetime,medium@datetime,long@datetime,full

Converts the value to a localized DateTime format. For example, if thevalue in the CDF is 1158054271967, the long format is used, and theapplication is localized to the default localization (us_en). The output is:September 12, 2006 2:44:31 AM GMT-07:00.

@date,short@date,medium@date,long@date,full

Converts the value to a localized Date format. For example, if the valuein the CDF is 09/02/1970, the full format is used. If the application islocalized to the default localization (us_en), the output is: Wednesday,September 2, 1970.

@time,short@time,medium@time,long@time,full

Converts the value to a localized Time format. For example, if the valuein the CDF is 1158054271967, the short format is used. If the applicationis localized to the default localization (us_en), the output is: 2:44 AM.

@message,* See the class in General Interface APIjsx3.util.MessageFormat

Reference. Follow by the specific format in place of *.

@unescape Unescapes any on-screen entities in order to render the tagged output,not the tags themselves. Use this template if a CDF attribute containsHTML. In Firefox, this is used to disable output escaping, as thisfunction is not available to the embedded transformiix processor. InInternet Explorer, a value template by the same name (@unescape) isused to facilitate output escaping. For cross-browser support,Important:be sure to set this property for both the format handler as well as thevalue template fields.

@lookup Resolves to a lookup value associated with a bound edit mask (select -combo). This allows the human-readable text to display, while storingthe actual jsxid value in the underlying CDF.

To use the interface, call the method on the given columnColumnFormat setFormatHandler()

instance, passing the given formatter as a string.

For example,

instance.setFormatHandler("@number,currency");

To create a custom formatter, create a static implementation of the class.MatrixFormatHandler

For more information, see General Interface API Reference.

Function Literal

When even greater control is needed over the cell format, a function literal can be used with thesame signature used by the interface. For example, the following functionMatrix.ColumnFormat

could be used to convert the given value to a localized currency format. Although this is thesame as passing the , it provides greater control by allowing youMatrix.ColumnFormat.CURRENCY

to use your own method for localizing the currency.

For example,

68


For example,

var s = (element,cdfkey,matrix,matrixcolumn,rownumber,server) {function mf = jsx3.util.MessageFormat("{0,number,currency}");var new element.innerHTML = mf.format(element.innerHTML); };[instance].setFormatHandler(s.toString());

Edit Masks

An edit mask is any child of a Matrix Column in the DOM. Edit masks typically implement but can also be constructed from collections of objects. An edit mask allows thejsx3.gui.Form

user to enter a value in a Matrix cell. User edits are persisted to the CDF data source of theMatrix.

There are two types of edit masks:

Only visible when editing, such as a text boxAlways visible in every row, such as a checkbox or radio button

The edit masks in the Component Libraries palette include some of the following: Text Box,Text Area, Radio Button, Checkbox, and so on. More complex examples of creating edit masksusing a Block and Dialog are also provided as prototypes in the Component Libraries palette.

Edit Masks and Matrix Model Events

Model events are an abstraction layer for native browser events. They translate events from thedomain of the browser UI into events from the General Interface model domain. Model eventsare persistent in JSX serialization files and are thus a static binding from the UI definition toJavaScript code.There are three Matrix model events that affect edit masks:

Before EditAfter EditAfter Commit

The Before Edit and After Edit events are vetoable model events. A vetoable model event ispublished before an action is executed by the system. If the vetoable event evaluates to false, thesystem doesn't complete the action.

You can add your own custom logic to these events in the Events Editor palette. After adding aMatrix component to your application, select the Matrix component in the ComponentHierarchy palette and look for these events in the Events Editor palette. For documentation oncontext variables, hover the mouse over the event name in the Events Editor palette.

Before Edit

The Before Edit event is only published for edit masks that are visible when editing, such as textboxes.

The Before Edit event is a vetoable event that fires before a cell edit session begins. Whenever auser focuses in a Matrix cell, the Before Edit event executes. If the Before Edit event is vetoed,the edit session never starts. For example, the Matrix Grid prototype has this JavaScriptstatement in the Before Edit event:

69


1. 2.

jsx3.log('EVENT: (jsxbeforeedit). Record: ' + strRECORDID);

When a user selects a cell in the Name column of this Grid prototype, this JavaScript statementcauses the CDF record ID of the cell to print to the System Log palette. For more information oncontext variables, such as , hover the mouse over the event name in the EventsstrRECORDID

Editor palette.

Using Multiple Edit Masks

You can use multiple edit masks in a single column. For example, some cells might use textboxes, while other cells use drop-down lists. The Properties Editor palette in General InterfaceBuilder is a good example of using multiple edit masks in a column.

To use multiple edit masks in a column:

Add all edit masks to use as children of the Matrix Column.Write custom JavaScript logic in the Before Edit event to control under what conditionseach mask is shown.

In the following code example, a Matrix Column has two children. Text box (0) is the first childand select box (1) is the second child. This JavaScript code causes the select box to be shown forany CDF record with an attribute. Otherwise, the text box mask displays.enum

if ( .getParent().getRecord(strRECORDID). )this enum retVal = {objMASK: .getChild(1)};var thiselse retVal = {objMASK: .getChild(0)};var thisretVal;

In the previous code example, is the context variable, the this Matrix.Column getParent()

method returns the Matrix, and is a context parameter.strRECORDID

After Edit

The After Edit event is a vetoable event that fires after a user changes a value and moves focusto another cell, but before the edit is committed to the CDF data source. The After Edit event isuseful for restricting, filtering, and verifying user input.

For example, entering the following JavaScript statement in the After Edit event in the EventsEditor palette, would allow only user input starting with the letter :i

strNEWVALUE.indexOf("i") == 0

If a user types a word that doesn't begin with , the event is vetoed.i

After Commit

The After Commit event, a non-vetoable event, fires after an edit session is committed and theCDF is modified. It is safe to query the CDF document for the updated state using this event.

Rendering Combinations Best Practices

Follow these recommended rendering best practices for best rendering results:

If using the Column Format property, use @empty for the Value Template property.Using this combination prevents a visible blink that occurs between the first and secondrendering pass.

70


rendering pass.For form elements that are always visible, use @empty for the Value Template property.Using @empty prevents the form element value from printing next to the edit mask. Forexample, for a checkbox, you want the checkbox to render, but you don't want thecheckbox value rendered.For date columns, match the format used by the Date Picker edit mask with the ColumnFormat.

For more information, see and .XSLT and Standard Value Templates ColumnFormat Interface

Properties

This section discusses properties that can be configured for the Matrix and Matrix Columncomponents.

Matrix Properties

The following properties can be configured for Matrix components.

Property Description

Name The name of the matrix in the Component Hierarchy palette.

RenderingModel

The rendering model of the matrix, such as shallow, deep, and hierarchical.Shallow and deep are flat models, the hierarchical model is rendered as a tree.Shallow only paints direct children of the context node. Deep paints alldescendants. Hierarchical paints all children but can also beperformance-tuned to paint a given number of generations at a time. Becausethis allows nodes to be fetched only when a user expands a given branch,application performance is faster. For more information, see Rendering

.Models

RenderingCtx

The rendering context ( ) of the parent record whose children orjsxid

descendants will be painted. The context node, the reference or starting pointto begin rendering, isn't rendered.

SelectionModel

The selection model, such as single row, multiple rows, and not selectable.

PagingModel

The paging model for how and when objects are rendered on-screen, such as , and . For moreNo Paging, 2-pass, Chunked, Paged Stepped (Hierarchical)

information, see .Paging Models

Panel PoolSize

The maximum allowed number of pooled panels when the rendering model is.Paged

Rows PerPanel

The number of rows in a panel when the rendering model is .Paged

Panel QueueSize

The maximum allowed number of panels in the paint queue when therendering model is .Paged

Scroll Info The info label to display when scrolling a paged instance.

71


HeaderHeight

The height of the header in implied pixels. Set to if the column doesn't use a0

header.

Row Height The height of the data rows. The paging model, , supports only fixedPaged

row height. All other paging models support fixed and flexible heights. If arow height isn't specified ( ), the default height (null

) is used. If the specified row height is 0, flexibleMatrix.DEFAULT_ROW_HEIGHT

height is used. For a fixed row height, specify a positive integer in impliedpixels, such as .14

HeaderBorder

The border for the header row.

Body Border The border for the body. To set the border for an individual column, updatethe APIs for the given column.

Scale Width Whether or not the column width should be scaled to fit in the visible regionor if a horizontal scrollbar should be used. The Matrix automatically providesa horizontal scrollbar when the aggregate width of its columns is greater thanthe overall Matrix width. A scale width flag can also be set to reduce columnwidths until the content fits exactly within the view port constraints. Whenrendering with a scaled width, it's often useful to include a wild card width ( )*on those columns whose width should be flexible. Percentage and pixel valuesare also supported. Note that the unit identifier for pixels is implied andshould not be specified as px.

HideH-Scroller

Whether or not to hide the horizontal scrollbar. Set to to hide it.true

HideV-Scroller

Whether or not to hide the vertical scrollbar. Set to to hide it.true

Render Nav In a hierarchical tree view, whether or not to render the navigation controls onthe first column.

Close Icon In a hierarchical tree view, the 16x16 transparent GIF used to signal thatclicking the item collapses its contents.

Open Icon In a hierarchical tree view, the 16x16 transparent GIF used to signal thatclicking the item expands its contents.

Icon The icon to display in a hierarchical tree view.

Sort Path The attribute path to sort on, such as .@jsxtext

Sort DataType

The type of data for columns in this list or grid, such as text or a number.

SortDirection

Whether to sort in ascending (a-z) or descending (z-a) order.

Sortable Whether or not the Matrix will sort when a column header is clicked.

Resizable Whether or not the columns are resizable.

Reorderable Whether or not the columns can be reordered.

72


FixedColumns

The index (zero-based) of the first column that can be reordered. All columnsof a lesser index can't be reordered.

Can DragFrom

If , this object supports drag events and allows any contained record toEnabled

be dragged and dropped onto another container supporting drop.

Can Drag On If , this object can be the target of drop events.Enabled

Can Spy If , this object can be spyglassed. A spyglass displays HTML returnedtrue

from the event when a row in the Matrix is hovered over.jsxspy

Bound Menu A menu to display when a user right-clicks on a row in the Matrix. Specify the , the name of the menu component as displayed in the Componentjsxname

Hierarchy palette.

Tab Index Sets the tab index. When tabbing between controls, the index group that thiscomponent belongs to.

Focus Style The CSS styles to apply to a cell when it has cursor focus. For example, .color:red

Selection BG The URL of the background image to apply to the background of the selectedcell or row to show that it's selected. For example, jsx:///images/matrix/select.gif.

Spy Styles The CSS styles to apply to a cell when the mouse hovers over the cell aandspyglass is applied.

XML CacheId

The string identifier of the cached CDF document with data. This string,which is the XML document name, displays in the Local Data Cache palette.

XML String The XML string (CDF) with data.

XML URL The URL of the CDF document with data. The file can be local or remote.Paths can be relative or absolute.

XMLTransformers

A comma-separated list of XSLT transformers. The source XML is transformedin a series by each of the transformers listed here before being placed in theXML cache. Specify each transformer as a URI to an XSLT file or the XMLcache ID of an XSLT document.

ShareResources

Whether to delete the associated CDF document when the component isrecycled in the Component Hierarchy palette. If Share is specified, thedocument remains in cache after the component is recycled. The default valueis Cleanup.

Annotation The annotation comment visible in a spyglass when you hover the mouse overthe component in the Component Hierarchy palette.

Matrix Column Properties

The following properties can be configured for Matrix Column components:


Att Name The named attribute whose content will be displayed on-screen, such as .jsxtext

73


Att Type The data type for the attribute, such as text or number.

Sort AttName

The attribute path to sort on, such as .jsxtext

Sort AttType

The data type for the attribute, such as text or number.

Triggers A comma-separated list of named attributes that when modified by anothercolumn will trigger this column's related cell to repaint.

Sortable Whether or not this column is sortable.

Resizable Whether or not this column is resizable.

Width The width of the column as implied pixels or a percentage. Wildcards(*)are also supported. : Integer values take precedence over percentages.Note

ValueTemplate

The XSL template to generate the cell content. It must be a valid XSL templateor a system-defined template identified by one of these — , @image (jsximg)

, or . For more information, see @unescape, @empty @default Content Formatting.and Localization

FormatHandler

The reformatting method to use on the cell data after it has been paintedon-screen. You can also point to a named reformatter, including , @unescape

, and . For more@lookup, @message, @datetime, @date, @time @number

information, see .Content Formatting and Localization

Display Sets the CSS display property. When set to , the column isn't rendered.None

Caption The label for the column header.

Word Wrap Whether the text wraps or not. Setting to , wraps the text.true

Font Name The name of the font for rendering the label.

Font Size The pixel size of the font for rendering the label.

FontWeight

The weight of the font for rendering the label, either bold or normal. Thedefault value is .Normal

Color The color of the font for rendering the text. Specify as a predefined color name,RGB, or hexadecimal value. For example, , , or .red rgb(255,0,0) #ff0000

BG Color The RGB value of the background fill. Specify the value as predefined colornames, RGB, or hexadecimal values. For example, , , or red rgb(255,0,0) #ff0000

.

Background The CSS background definition. For example, .background-image:url(abc.gif);background-repeat:repeat-x

Padding The CSS padding value between the border and the contents of the cell. Specifya single value to use on all sides, such as , or a set of values separated by5

spaces for top, right, bottom, and left, such as .5 0 5 0

Border The CSS border definition. Specified as one or four value sets (top, right,bottom, and left). Specified as: style width color. For example, solid 1px

.red;dashed 2px red;double 3px black; solid 1px red;

74


Text Align The alignment of any contained object or text, such as , and .Left, Center Right

V-Align The valid CSS vertical alignment definition.

Cursor The valid CSS cursor definition, such as , , or .default wait col-resize

BoundMenu

A menu to display when a user right-clicks on the header with the mouse.Specify the , the name of the menu component as displayed in thejsxname

Component Hierarchy palette.

Tooltip The text to display when the mouse hovers over this header. Only text issupported.

Annotation The annotation comment visible in a spyglass when you hover the mouse overthe component in the Component Hierarchy palette.

75


1. 2. 3.

Chapter 10 Dojo Toolkit Integration

This chapter describes how to use the in General Interface applications.Dojo Toolkit

Loading and Deploying DojoDojo Widgets in General InterfaceDojo EventsAccessing Dojo Data from General InterfaceAccessing General Interface CDF Data from Dojo

Loading and Deploying Dojo

Use the General Interface class to load the Dojo Toolkit in your Generaljsx3.util.Dojo

Interface application.

jsx3.require("jsx3.util.Dojo");jsx3.util.Dojo.load();

Not all binary distributions of General Interface include Dojo. will loadDojo.load()

Dojo only if the necessary files are present in the General Interface installationdirectory.

Dojo widget integration with requires that the Dojo Toolkit be loaded. jsx3.gui.DojoWidget

calls , so you usually do not need to call this methodjsx3.gui.DojoWidget Dojo.load()

explicitly. However, you may want to load the Dojo Toolkit even if you are not using Dojowidgets, as in the following example.

jsx3.require("jsx3.util.Dojo");jsx3.util.Dojo.load();dojo.query("p").fadeOut();

Installing the Dojo Toolkit

Some binary distributions of General Interface include a pre-built version of Dojo. GeneralInterface assumes that Dojo will be installed in the standard directory containeddojo_toolkit/

in the General Interface installation directory, although this location can be overridden. Thecontents of this directory would typically be , and .dojo/ dojox/ dijit/

Dojo can be added to any General Interface build. Dojo itself is available in many pre-builtvarieties and as a source distribution. To add Dojo to General Interface,

Download any version of Dojo from http://www.dojotoolkit.orgOptionally, create a customized build of Dojo with the Dojo build scriptsPlace Dojo in the directory inside the General Interface installationdojo_toolkit/

directory.

You can also replace the Dojo build included in a General Interface distribution with a customDojo build using the same steps.

http://www.dojotoolkit.org/

http://www.dojotoolkit.org

76


General Interface requires Dojo 1.4, which is still in development as of the releasedate of General Interface 3.8. Until Dojo 1.4 is released use a nightly build or aSubversion snapshot of Dojo.

After these steps are completed, the General Interface classes and jsx3.util.Dojo

will function properly.jsx3.gui.DojoWidget

After installing Dojo the Dojo widget prototypes may not show up in theComponent Libraries palette in Builder. To install these prototypes copy thedirectory from the source distribution of GeneralGI_Builder/prototypes/Dojo

Interface.

Deploying and Loading Dojo

If your General Interface application uses Dojo, for example by including an instance of in a component file, you must deploy the Dojo directory along with thejsx3.gui.DojoWidget

rest of the General Interface deployment files. Copy to the deployment location.dojo_toolkit/

It should be in the same directory as .JSX/

You may override the default location ( ) where General Interface looks for Dojo.dojo_toolkit/

To do this set the to the relative path from the applicationjsx_dojo deployment parameterlaunch page to the Dojo directory. For example:

<script type= src="text/javascript" "JSX/js/JSX30.js" jsxapppath="JSXAPPS/myApp" jsx_dojo= >"../path/to/dojo"</script>

Alternatively, you can load the Dojo toolkit by adding a script tag in the HTML head of theapplication launch page. The attribute of the script tag should be the location of .src dojo.js

<head> <script type= src= >"text/javascript" "dojo-toolkit/dojo/dojo.js" </script></head>

Dojo Widgets in General Interface

General Interface Builder includes prototypes for a variety of Dojo widgets. These prototypesare available in the Dojo folder in the Component Libraries palette. Dojo widgets operate in thesame way as other General Interface widgets and can be dragged and dropped onto the Buildercanvas during application development. You can also configure Dojo widgets using theProperties Editor and Events Editor.

Dojo widget prototypes are not included in every binary distribution of GeneralInterface. To use Dojo widgets in your application make sure you are using thesource distribution of General Interface or a build that includes Dojo.

The following Dojo widgets are included with Builder and have been tested with General

http://www.generalinterface.org/docs/display/GIDOCS/Deployment+Parameters

77


The following Dojo widgets are included with Builder and have been tested with GeneralInterface.

ButtonCheck BoxColor PaletteCurrency Text BoxDate Text BoxEditorHorizontal SliderVertical SliderNumber SpinnerProgress BarRatingTime Text Box

The General Interface class wraps native Dojo widget objects andjsx3.gui.DojoWidget

provides a compatible API. The following example shows the vertical slider Dojo widget withina component file. Note how the object type is and the jsx3.gui.DojoWidget dijitClassName

property is equal to the Dojo type.

<object type= >"jsx3.gui.DojoWidget" <variants jsxheight= jsxwidth= />"200" "100" <strings dijitClassName= dijitvalue= />"dijit.form.VerticalSlider" "17"</object>

Dojo Widget Properties

The class acts as an adaptor between General Interface and the Dojojsx3.gui.DojoWidget

widget system. Each instance of introspects the properties of the Dojo class that itDojoWidget

wraps and injects itself with accessor and mutator methods for each property.

For example, the Dojo class defines a property, which is visible indijit.form.Button label

Builder in the Properties Editor under the Dojo category when you select a Dojo button in theComponent Hierarchy. The instance therefore defines the methods and DojoWidget getLabel()

. Note that these methods are not class method of but rather dynamicsetLabel() DojoWidget

methods that are created and injected only into instances of that define a DojoWidget label

property.

btnWidget.setLabel("My Button");

The method is a generic getter and setter method for all Dojo properties so the previousattr()

example is equivalent to

btnWidget.attr("label", "My Button");

The property of grants access to the native wrapped Dojo object. Thedijit DojoWidget

following example is equivalent to the pervious example as well.

btnWidget.dijit.attr("label", "My Button");

http://docs.dojocampus.org/dijit/form/Button

http://docs.dojocampus.org/dijit/form/CheckBox

http://docs.dojocampus.org/dijit/ColorPalette

http://docs.dojocampus.org/dijit/form/CurrencyTextBox

http://docs.dojocampus.org/dijit/form/DateTextBox

http://docs.dojocampus.org/dijit/Editor

http://docs.dojocampus.org/dijit/HorizontalSlider

http://docs.dojocampus.org/dijit/VerticalSlider

http://docs.dojocampus.org/dijit/form/NumberSpinner

http://docs.dojocampus.org/dijit/ProgressBar

http://docs.dojocampus.org/dijit/form/Rating

http://docs.dojocampus.org/dijit/form/TimeTextBox

78


Dojo Events

The Dojo Toolkit has a single event bus that it uses to send messages between applicationobjects. The Dojo methods and implement this bus. This isdojo.subscribe() dojo.publish()

different than the event model of General Interface in which application events are usuallypublished by any number of event dispatchers to any number of subscribers.

The object provides an adapter to the Dojo event hub within Generaljsx3.util.Dojo.hub

Interface. This object implements so it can be used like any otherjsx3.util.EventDispatcher

event dispatcher in a General Interface application. Use this object to publish events forbroadcast on the Dojo hub and to subscribe to events published on the Dojo hub.

The following example shows how to publish an event to the Dojo event hub.

jsx3.util.Dojo.hub.publish({subject:"eventId", greeting:"hello"});

The following example shows how to subscribe to events from the Dojo hub.

jsx3.util.Dojo.hub.subscribe("eventId", , (message) {null function ...});

Ordered parameters from the Dojo API are available for the message object. In the previousexample, you would use to access the first parameter that is passed to the publishmessage[0]

method.

Accessing Dojo Data from General Interface

Dojo data stores can be used in General Interface through their native API or via a CDFinterface provided by .jsx3.xml.DojoDataStore

To access a Dojo data store via a CDF interface, create an instance of jsx3.xml.DojoDataStoreand set its store and the query that retrieves the data from the source, as in the followingexample:

var cdf = jsx3.xml.DojoDataStore();cdf.setStore( dojox.data.JsonRestStore({target:"/RestData"});newcdf.setQuery("?price<10");

recordIds = cdf.getRecordIds();var firstRecord = cdf.getRecord(recordIds[0]);var

jsx3.xml.DojoDataStore is not a descendant of class , so it cannotjsx3.xml.Document

be used directly as the data source of Matrix and other descendants of . To use a Dojo data source to populate a Matrix, first constructjsx3.xml.Cacheable

an XML document by iterating over the records in a instance.DojoDataStore

79


Accessing General Interface CDF Data from Dojo

Dojo.data is a uniform data access layer that removes the concepts of database drivers, serviceendpoints, and unique data formats. With , all data is represented as an item or as anDojo.data

attribute of an item and can be accessed in a standard fashion. Items are returned from fetchesthat search for items with particular properties. For more information on data stores, refer to http://docs.dojocampus.org/dojo/data.

The Dojo data store allows a data-ready Dojo widget, such as a Dijit, todojox.data.CdfStore

use a CDF document as its data source. provides a fully compliant Dojodojox.data.CdfStore

data store interface for reading and modifying CDF documents.

dojox.data.CdfStore is part of the Dojo Toolkit. See forhttp://www.dojotoolkit.orgmore information.

There are several ways to initialize a :CdfStore

With the URI of a CDF documentWith the serialized contents of a CDF documentWith a nested JavaScript data structure

The following example shows a created with the URI of a CDF file:CdfStore

var store = dojox.data.CdfStore({url:"../data.cdf", label:"name"});new

You can initialize a store with an XML string, which is converted to a XML document and thenparsed as it would normally be:

var str = '<data jsxid="jsxroot">'+ '<record jsxtext="A"/>' + '<record jsxtext="B" jsxid="2" jsxid="2"/>' + '</data>';

store = dojox.data.CdfStore({xmlStr:str});var new

You can also initialize a store using a JavaScript object that, which is converted into an XMLdocument, as in the following example.

http://docs.dojocampus.org/dojo/data

http://www.dojotoolkit.org

80


var data = {jsxid:"jsxroot", record:[ { jsxid:"1", jsxtext:"My A Text" },{ jsxid:"2", record:[ { jsxid:"2a", jsxtext:"My Group A Text" },{ jsxid:"2b", jsxtext:"My Group B Text" } ] } ]};

store = dojox.data.CdfStore({data:data});var new

If the data is a URL, the file is loaded into the store the first time items are fetched. Fetching isusually an asynchronous action, so in addition to the query for items, a callback method ispassed, as in the following example.

store.fetch({query:"//record[@jsxid='6']", onComplete: (items){function console.info("test fetch newItem:", items[0]); }});

Make sure that you also pass an handler for the operation. See the onError Dojo documentationfor a complete set of arguments for a fetch.

Most data stores use different formats for their queries. As shown in the previous example, thequery for a fetch is a string in format, which is similar to the query syntax of XPath

and other methods in .Entity.selectNodes() jsx3.xml.*

By default Dojo data operations are asynchronous. When dealing with CDF data synchronousmode may be more convenient. In mode Dojo data query functions return values ratherSYNC

than requiring verbose callback functions. To create a in mode:CdfStore SYNC

var store = dojox.data.CdfStore(new {url:storeUrl, label:"name", mode:dojox.data.SYNC_MODE});

In mode, fetches will return an array, as in the following example.SYNC

var items = store.fetch({query:"//record"});

To lookup an item by its identity use .byId()

var item = store.byId("6");

When accessing or modifying item properties, use methods on the data store rather than on theindividual items. The following example shows the Dojo data convention.

var value = store.getValue(item, "myProperty");

http://docs.dojocampus.org/dojo/data/api/Read#fetch

81


A similar approach sets a property, as in the following example.

store.getValue(item, "myProperty", value);

It is not usually necessary to set all of these properties explicitly. Normally you can create astore and assign it to a data-enabled widget that then handles all of the fetching and display ofdata. Use the parameter to filter items in the store before displaying then in a widget.query

var store = dojox.data.CdfStore(new {url:"../data.cdf", label:"name"});

widget = widget({store:store, query:"*"}, "div");var new

82


Chapter 11 Working with Charts

This chapter describes how to use charting features in a General Interface application.

Introduction to ChartsEnabling the Charting Add-inBuilding ChartsDisplaying Data in ChartsImplementing Chart Events

Introduction to Charts

A General Interface application can include charts for visualizing data. Relationships andtrends in data sets are often easier to communicate in a chart than in other two-dimensionalcomponents, such as matrix views. Like Matrix components, charts display CDF data. Data canoriginate from any XML data source.

The charting features in General Interface are available in the Charting Add-in,which must be enabled in your project. For more information, see Enabling the

.Charting Add-in

You can build rich and dynamic charts by using prototype components, customizing defaultproperties, and adding child objects as needed. Components are provided for most commonchart types, including bar, column, area, line, pie, doughnut, scatter, and bubble. Prototypecomponents are useful for building individual charts, and also for building libraries ofcustomized components. For example, a developer can save a customized prototype componentthat defines a standard look and feel for all charts of a certain type.

Like all General Interface objects, charts are configured using properties and events. Propertiesallow you to specify layout, fill colors, transparency, and many other characteristics. Eventsallow a user to trigger a JavaScript event by clicking a chart component. Chart appearance andbehavior can be modified at runtime, in response to user input or data changes.

The following General Interface features are especially useful for building and displayingcharts:

At development time, the look and feel of a chart can be configured using visualproperties, significantly reducing development time.Chart prototype objects accelerate the process of building, modifying, and testing charts.At runtime, chart images are generated on the client rather than the server, reducingserver and network load.

For more information on charting properties and events, see .Charting Components

Basic Elements

All charts share a common set of basic building block.

83


The next figure shows a bar chart, which displays data in horizontal bars. The chart comparesproductivity by month for two data sets, Group A and Group B. In a chart, a data set like GroupB is called a series. Each chart must include at least one series.

A bar chart is one example of a Cartesian chart. Cartesian charts display data on an x-y plane,with the x-axis defining the horizontal dimension and the y-axis defining the verticaldimension. An axis can be linear, category, or logarithmic. For axis definitions, see Configuring

.Axes

Radial charts display data in radial coordinates, rather than x-y coordinates and do not haveaxes. General Interface Builder provides prototypes for both Cartesian and radial charts.

Charting Component Library

The Charting component library, which is a General Interface Builder add-in, containsprototype components for building charts. The Charting add-in must be enabled for the project.For more information, see .Enabling the Charting Add-in

As shown in the next figure, the Charting component library is organized into chart prototypes,other chart components, and data series:

Charting folder Contains one chart prototype component for each supported major andminor variation.Components folder Contains components for most other chart building blocks, includingaxes, labels, grid lines, and legends.Series folder Contains one data series prototype for each major chart variation.

84


Prototype Summaries

The Charting component library contains a prototype for each combination of major and minorchart variations. In the General Interface API, major variations correspond to the chart class andminor variations correspond to the type property.

This section summarizes each major variation and provides an example.

Area displays the trend of values over series or categories. By displaying the sum of theplotted values (stacked and stacked 100%), an area chart also shows the relationship of

parts to a whole. An area chart is similar to a line chart, with the area below each line

85


parts to a whole. An area chart is similar to a line chart, with the area below each linefilled in.

Bar compares values across categories (clustered), shows the relationship of individualitems to the whole (stacked), or compares the percentage each value contributes to a totalacross categories (stacked 100%).

Column compares values across categories (clustered), shows the relationship ofindividual items to the whole (stacked), or compares the percentage each valuecontributes to a total across categories (stacked 100%).

86


Line represents data as a series of points connected by a continuous line, with optionalmarkers displayed at each data point.

Plot represents data as a series of points, each with one value that determines its positionalong the x-axis, and one value that determines its position along the y-axis. Point chartsare useful for presenting scientific data.

87


Bubble charts are a variation, where the data points are represented by variable-sizemarkers. Magnitude is shown by category, rather than by series.

Pie shows the size of each data point in a single data series, proportional to the sum ofthe data points (pie). A pie chart is useful for showing proportions and emphasizing asignificant element in the data.

88


1. 2.

Doughnut charts are a variation, with more than one data series represented. Adoughnut chart is useful for comparing proportions among multiple data series.

Enabling the Charting Add-in

To work with charting features in General Interface Builder, you must enable the Chartingcomponent library add-in for your project. After the Charting add-in is enabled, you haveaccess to the charting components in the Component Libraries palette.

To enable the Charting add-in:

Choose to open the Project Settings dialog and click .Project > Project Settings Add-InsCheck the add-in.Charting

89


2.

3. 4.

5.

1.

2.

3.

Click to save the changes and close the dialog or click .Save ApplyClick in the Restart Required prompt and use the browser reload button to restartOKGeneral Interface Builder.Open the folder in the Component Libraries palette to see theAddins > Chartingcharting components.

Building Charts

In General Interface Builder, the process for creating and modifying charts is the same as forother GUI components. You build charts by dragging and dropping components from theComponent Libraries palette, modifying object properties, and configuring events.

For more information about charting properties and events, see .Charting Components

These steps summarize the process of building a chart:

Analyze source data. Source data must be in the CDF. For details, see the General Interface DeveloperGuide. If chart data is generic XML, it must be transformed into the CDF for usein the chart. Identify the CDF attributes to use for data series and axis labels, if applicable.

Enable the Charting add-in for your project, so charting components are available. See .Enabling the Charting Add-in

Choose a prototype component that best fits your data and what the chart shouldillustrate.The structure of and variations in source data, as well as the information you want toshow in the chart, determine the major variation of chart to use. The chart prototype you

90


3.

4.

5.

6.

show in the chart, determine the major variation of chart to use. The chart prototype youchoose should be suitable for displaying the specific data set. See Charting Component

for short descriptions of each major variation of a chart.LibraryTo view representative CDF data for a chart prototype component, first create aninstance of the prototype, then view the properties of the top-level chart component. TheXML String field contains sample CDF data for the chart.Add an instance of the chart prototype to a new GUI component or an existing GUIcomponent.For existing components, a Layout or Block component is useful for positioning thechart.Customize the chart component by adding or removing child objects and modifyingproperties. For detailed instructions on performing these tasks, see Chapter 4, Building aSimple Application.

For the chart component, specify the location of the CDF data using properties. For each data series, specify the CDF attributes to display in the chart.

Customize the chart component by defining events. For details, see Implementing Chart.Events

For a chart example, see the General Interface Chart Sample, /JSXAPPS/samples/chartworkspace

.

Chart Component Hierarchy

When you add a chart component to a General Interface Builder project, the chart hierarchyappears in the Component Hierarchy palette. The following shows the hierarchy of a typicalCartesian chart on the left, and a typical radial chart on the right.

The hierarchy is a shallow tree structure with the chart object at the root and all other chartcomponents, such as axes, series, and legend, on a single level directly under the root. Labelobjects can be nested under chart, series, legend, or axis objects.

It is possible to create an instance of a chart object or component using the General InterfaceAPI. However, it is usually more efficient to begin with a prototype component and customize

it as necessary. The API methods are useful for adding new series at runtime, if the chart has a

91


it as necessary. The API methods are useful for adding new series at runtime, if the chart has avariable number of series.

These restrictions apply when creating and organizing charts in the Component Hierarchypalette:

A chart component must have one or more series components, and the type of seriesmust match the type of chart.A Chart Label object can be added to a chart, a legend, an axis, or a Pie series. Thesecomponents can have at most one Chart Label child object.Cartesian charts must have one vertical axis and one horizontal axis.

The following sections describe how to configure chart components.

Configuring Axes

Most chart prototype components in General Interface Builder are Cartesian charts, whichdisplay data on an x-y plane. Cartesian charts must have both an x-axis and a y-axis defined.Axes can have labels, major and minor tick marks, and titles.

An axis in a Cartesian chart can be one of the following types:

Linear displays a range of linearly increasing values. By default, a linear axis displays arange of values large enough to contain the chart data and divides the range intobetween five and eleven intervals.

Category displays a range of discrete values, one for each category. A categorycorresponds to one row of data in a CDF file.

Logarithmic displays a range of linearly increasing values rendered in a logarithmicallyincreasing scale. Only positive values are displayed.

92


When an axis component is created, the type is fixed. To modify an axis, recycle the existingaxis component and add a new axis of the correct type to the chart.

Values

The type of axis determines how data values are assigned. For linear and logarithmic axes, datavalues are specified by each series. The series has two properties, X Field and Y Field, forspecifying the name of attributes in the CDF file. Depending on the axis configuration, one orboth of these properties may be required.

Other properties that configure axis values are Min Field (Area Series, Bar Series, ColumnSeries) for the CDF attribute that specifies the minimum value, and Magnitude Field (Bubbleseries) for the CDF attribute that specifies the magnitude value.

For a category axis, data values are specified once for the axis. The axis has a Label Fieldproperty for specifying the name of an attribute in the CDF file. The values of this attribute areused as axis values for all series in the chart.

Title

The axis title is specified by a Chart Label component that is a child of the axis component.When you create an axis component, the label component is automatically created. Axis titlesare displayed parallel to the chart axis. For details on configuring this component, see

.Configuring Labels

Labels

Axis labels appear next to the tick marks along a chart axis. Labels are optional and can bedisplayed or hidden using the Show Labels property for the axis.

Text

You can configure the position of axis labels relative to the axis and the text of axis labels. Axisproperties allow you to configure label position relative to the axis, including the gap betweenthe axis label and tick marks and position of axis labels relative to the axis. Label propertiesallow you to configure the label text, such as the text string, font, rotation, CSS class, andbackground color.

Functions

You can use the Label Function property to specify JavaScript for converting an axis value intoan axis label. The signature of the function is:

function (value : | ) : String Number String

For example, the following function formats axis labels by appending the degree symbol to axisvalues:

93


function degreeLabel(value) { value + "°";return}

This function formats axis labels in the format, using the axis value as the number of daysm/d

from January 1, 2007:

function date05Label(value) { t = Date(2007, 0, value);var new (t.getMonth() + 1) + "/" + t.getDate();return}

The following static functions are provided:

jsx3.chart.Axis.percent Appends the character to a linear axis value%

jsx3.chart.Axis.scientific Formats a linear axis value in scientific notation

The Label Function property value is actually a string value that evaluates to a function. Specifythe name of a static function, such as or an inline function of the form:Axis.percent

function (x) { x; }return

When setting this value in the Properties Editor palette or in JavaScript code, the specified valuemust be a string that evaluates to a function with this signature. Omit any quotation marks,because the field is assumed to be a string.

CSS Formatting

If axis labels require complex styling, use the Label CSS Class and Label CSS Styles properties.Label CSS Class and Label CSS Styles specify the CSS class and style attribute, respectively, toapply to each axis label.

For category axes, the Label Field property defines the category attribute in the CDF filecontaining chart data.

Major and Minor Tick Lines

Each axis includes small markers, or tick marks, with corresponding labels. Charts can havetwo kinds of tick marks, major and minor. Major tick marks are the markers along an axis thatcorrespond to an axis label. The text for an axis label can be an attribute in the chart CDF file.Minor tick marks evenly divide the distance between major tick marks, which helps usersvisualize the size of the interval.

For linear axes, major tick lines are drawn at the beginning of each interval. The Intervalproperty controls the frequency of major tick marks.

Position

Tick marks can be displayed on the outside or inside edge of an axis or centered on the linerepresenting the axis. Use the Mj Tick Placement property to configure the position of majortick marks, and the Mn Tick Placement property for minor tick marks.

Tick marks are optional in General Interface charts. To remove tick marks from an axis, specifya value of for one of these properties.none

The following example shows the vertical axis with Mj Tick Placement = and Mn Tickcross

Placement = . For the horizontal axis, Mj Tick Placement = and Mn Tick Placementnone outside

94


Placement = . For the horizontal axis, Mj Tick Placement = and Mn Tick Placementnone outside

= .inside

Length

In this example, the length of major tick marks on the horizontal axis is 3 pixels and the lengthof minor tick marks is 2 pixels. Use the Mj Tick Length and Mn Tick Length properties tospecify the length of major and minor tick marks.

Stroke

Mj Tick Stroke and Mn Tick Stroke define the outline of major and minor tick marks. Theseproperties take vector stroke values, which have this format:

color [width [alpha]]

where color is the marker color as a string or number, width is an integer value specifying thewidth of the line in pixels, and alpha specifies the marker transparency as a float value between0.0 and 1.0. Both width and alpha are optional.

For category axes, Mj Tick Alignment specifies the position of major tick marks relative to eachcategory. The default value, , places each category and its axis label between two majorbetween

ticks.

If is specified, the tick marks are aligned with each category and axis label.aligned

95


Configuring Data Series

A chart must include at least one series for displaying data. Each type of chart has acorresponding series type, which is the only type of series that can be added to the chart.

Data

To associate a CDF attribute with a series component, you specify the attribute name for aparticular series property. For Cartesian charts, use either the X Field or Y Field properties,depending on which axis should display series data. For area, bar, and column charts, you canalso specify a CDF attribute for the Min Field property to configure a minimum value. Forradial charts, use the Field property to identify the series. For more information on chart data,see .Displaying Data in Charts

Coloring

Series are configured with a default coloring scheme, which can be used without modification.You can also specify custom color and transparency values for series by modifying the Fill andFill Gradient properties for Cartesian charts or the Colors property for radial charts.

For example, the chart on the left has a blue series with a color and alpha value of #0099FF .4specified for the Fill property. The chart on the right has a Fill value of and a value of#0099FF 1

specified for the Fill Gradient property.#FFD700 45 1

Unlike other types of charts, the colored areas in a Pie chart represent categories. Fill values foreach slice are defined either in the chart or in each series. To specify fills, you can set the seriesColors property to an array of values. Another option is to set the seriesjsx3.vector.Fill

Color Function property to a function with the following signature:

function (record : jsx3.xml.Entity, index : ) : jsx3.vector.Fillint

The following example shows a function that fills Pie chart slices with one of 10 values on thegradient between black and red:

function sliceColorer(record, index) { r = .round((index % 10) * 255 / 9);var Math rgb = r << 16;var jsx3.vector.Fill(rgb);return new}

By default, the static function is used.PieChart.defaultColoring

96


Tooltip Functions

A series can use a static function to generate tooltip text. At runtime, the tooltip displaysinformation when the cursor moves over a data point. For example:

Each prototype series component has a default tooltip function specified. This example uses thedefault function, which displays the value of the currentjsx3.chart.BubbleSeries.tooltip

data point.

Point Renderers

Line, area, bubble, and point series can display a shape at each data point. The shape, which isrendered by a point renderer, can be one of the default shapes provided or a custom shape thatyou define. The default shapes are shown in the following example:

The Point Renderer property specifies the type of renderer for the series. To use a default shape,select the corresponding property from the context menu on the Properties Editor palette. Forexample,

97


Types

Both Line Series and Area Series components also have a Type property that controls how datapoints are connected. The following examples summarize the possible values for this property.

The line above an area series must be continuous, so and are nothorizontal vertical

supported for area series.

98


Configuring Grid Lines

Grid lines render colored lines and rectangles in the data area of a chart, aligned with the majorand minor tick marks of chart axes. The lines visually extend major and minor tick marks,providing users with reference points for interpreting data. A Cartesian chart can have anunlimited number of grid lines.

Display Properties

Grid lines are always rendered behind the chart axes. Use the Draw in Foreground property tocontrol whether grid lines display behind or in front of the data series. In the followingexample, this property is set to TRUE:

Depending on chart data and appearance settings, stacked 100% variations of Area, Bar,Column, and Line charts may require setting Draw in Foreground to TRUE.

Each grid line can render both horizontal and vertical lines and fills. For example:

The Layering property controls whether horizontal fills, major ticks, and minor ticks display infront of vertical fills and tick marks. In this example, the Layering property is set to "VerticalAbove Horizontal".

Data Area Stroke

The Border property specifies the stroke to use for outlining the data area of the chart. Thisproperty takes a vector stroke value. For details of how to specify a vector stroke value, see thedescriptions of Mj Tick Stroke and Mn Tick Stroke in .Configuring Axes

Grid Line Fill

To configure fill values for grid lines, use the Ver. Fill and Hor. Fill properties. These propertiestake one or more vector fill values, which have the following format:

color [alpha]

where color is the marker color as a string or number, and alpha specifies the marker

transparency as a float value between 0.0 and 1.0. alpha is optional.

99


transparency as a float value between 0.0 and 1.0. alpha is optional.

For example:

#CCCCCC, #DDDDDD

This example shows an array of two color values separated by a comma. When displayed in thechart, these values alternate at major tick marks. If additional color values are specified, the fillcycles through the values in the array at each major tick.

Grid Line Stroke

The Ver Major Stroke and Hor. Major Stroke properties control the stroke used between majortick lines. Similarly, the Ver Minor Stroke and Hor. Minor Stroke properties control the strokeused between minor tick lines. These properties take one or more vector stroke values. If anarray of stroke values is specified, the fill cycles through the values in the array at each majortick.

For details of how to specify a vector stroke value, see the descriptions of Mj Tick Stroke andMn Tick Stroke in .Configuring Axes

Configuring Legends

A legend displays a visual key to the series or categories in a chart. For Cartesian charts thelegend displays series information, and for radial charts the legend displays categoryinformation. A chart can have at most one legend.

When a legend component is added to a chart, the legend automatically displays the correctentries by introspecting the chart.

Position

To reposition the legend relative to the chart, modify the Legend Placement property for thechart. The default position is on the right side of the chart, centered vertically.

Size

The size of the legend is controlled by the Box Height and Line Height properties. Box Heightspecifies the size of each legend symbol, similar to a font size. Larger values increase thesymbol size without affecting the text string with the series name. Line Height specifies thespacing between each entry, so larger values create more white space between entries.

Text Appearance

The appearance of the text string with the series name is controlled by the Label CSS Class andLabel CSS Styles properties.

The legend title is specified by a Chart Label child object. When you create a Legend

100


The legend title is specified by a Chart Label child object. When you create a Legendcomponent, the label component is automatically created. For details on configuring thiscomponent, see .Configuring Labels

You can use the Padding and Margin properties to control the amount of white space inside thelegend box and between the legend box and the edge of the chart, respectively.

By default, the legend box has a white background. You can specify a vector fill value for theBackground Fill property to specify a background fill color. For details on how to specify avector fill value, see the descriptions of Ver. Fill and Hor. Fill in .Configuring Grid Lines

The Background Stroke property controls the outline of the legend box, and takes a vectorstroke value. For details on how to specify a vector stroke value, see the descriptions of Mj TickStroke and Mn Tick Stroke in .Configuring Axes

Configuring Labels

A Chart Label object defines style settings for a block of text. In addition to defining the title ofa chart component, this object also provides internal text labels for other components. Label isused for rendering legend titles, axis titles, and Pie chart series labels. When an object that canuse a label does not have one defined, no text is displayed.

The text of the label is specified by the Text property. The Font Face, Font Size, Font Weight,and Color properties can be used to apply manual formatting to the text string. You can alsospecify a CSS class for this purpose, although the effect of class settings may vary, dependingon whether the label is rotated.

Labels can be rotated either 90 or 270 degrees using the Rotation property.

Specifying Properties with Vector Values

The package determines how vectors are rendered.private jsx3.vector

Vector Fill

A class specifies how the interior of a vector shape is colored. The most basicjsx3.vector.Fill

vector fill value is a simple RGB color value. The class also supports morevector.Fill

advanced coloring options, such as opacity and gradient fill.

The constructor for is jsx3.vector.Fill function(color, alpha)

color { } is the color value, accepts a hex String or 24-bit integer value andString | int

defaults to #000000alpha { } is the opacity value, accepts valid values between 0 (transparent) and 1Number

(opaque) and defaults to 1.

Gradient fill cannot be specified in the constructor.

Several chart components, such as series and grid lines, have properties for storing stringrepresentations of a vector fill object. Storing a string representation instead of an actualinstance allows you to edit these values in the Properties Editor palette. The following is thesyntax of the string representation:

101


color [alpha]

where color can be either a string such as or . Specifying alpha, which can be a"#FF0000" "red"

float value between 0.0 and 1.0, is optional.

Gradient Vector Fill

Some prototype components support gradient vector fill objects. In these cases, the gradientinformation is also stored in an instance field as a string representation. If specified, thegradient string representation is combined with the fill string representation to create one

object. The string representation of a gradient is:jsx3.vector.Fill

color2 [angle [alpha2 [percent stop color,]*]]

The gradient is rendered starting from the main fill color/fill alpha and ending at color2/alpha2along the specified angle. Optional intermediate colors along the way are defined by percentand stop_color pairs. Pairs are separated by commas. For example, red 0 1 50% white, 75%

. color2 is a string (#FF0000) or predefined color name (red).black

angle specifies the angle of the gradient vector measured in degrees (between 0 and 360)counter-clockwise from 12 o'clock.alpha2 is an optional float value between 0.0 and 1.0.

Vector Stroke

A class specifies how the outline of a vector shape is drawn. The most basicjsx3.vector.Stroke

vector stroke definition consists of an RGB value and a width. The opacity property can also bespecified.

Several classes have fields that hold string representations of jsx3.chart jsx3.vector.Stroke

object. The syntax of the string representation is:

color [width [alpha]]

where color can be either a string such as or . Specifying alpha, which can be a"#FF0000" "red"

float value between 0.0 and 1.0, is optional. width is an integer value specifying the width of theline in pixels.

Displaying Data in Charts

A chart consists of one or more series, usually specified during development, and one or morecategories specified at runtime. It is also possible to dynamically generate series at runtime,using the General Interface APIs.

Charts display XML data that conforms to the CDF. With the exception of the attribute,jsxid

which is useful for implementing chart events, no other specific attributes are required.

By default, the CDF record structure is assumed to be flat, so only top-level records areincluded in the chart. If the data includes nested records, you can use JavaScript code to displaythe nested records. For an example, see .Implementing Chart Events

102


Working with Series Data

A series is a set of related data points represented by the same attribute repeated in multiplerows of a CDF file. For example:

<data> <record date= open= hi= low= close= />"2" "5" "6" "4.95" "5.85" <record date= open= hi= low= close= />"3" "5.75" "6.25" "5.60" "6.00" <record date= open= hi= low= close= />"4" "6.00" "6.55" "6.00" "6.50" <record date= open= hi= low= close= />"5" "7.25" "7.50" "6.80" "6.90" <record date= open= hi= low= close= />"6" "6.95" "6.95" "6.50" "6.80" <record date= />"7" <record date= />"8" <record date= open= hi= low= close= />"9" "6.80" "7.15" "6.75" "6.95" <record date= open= hi= low= close= />"10" "6.90" "6.95" "6.25" "6.30" <record date= open= hi= low= close= />"11" "6.25" "6.50" "5.75" "6.35" <record date= open= hi= low= close= />"12" "6.35" "6.50" "5.95" "6.40" <record date= open= hi= low= close= />"13" "6.25" "6.30" "5.95" "6.00"...</data>

Each row includes a set of attributes whose values are individual data points. This sample CDFcode could be used to generate four series in a chart, one for each of the , , and open hi low close

attributes. The attribute in this example could be used as a category label, since thisdate

attribute applies to every series in the row.

Working with Category Data

A row in the CDF file renders as a category in the associated chart. For example, only twocategories are shown in the following chart data:

<data> <record height= weight= ignored= />"173" "70" "31"

<record height= weight= ignored= />"185" "78" "33"</data>

The relationship between categories and series is that a series defines an addressing scheme forextracting data from each category. The following JavaScript code creates a series thatreferences the previous XML:

var series = jsx3.chart.PointSeries("Height v Weight");newseries.setXField("height");series.setYField("weight");

A category can specify any number of XML attributes such as and , which may orheight weight

may not be displayed as data points in a specific chart. A category can also include an attribute,such as , that acts as a label for the category. When the name of this attribute is specified fordate

the Label Field property of a category axis, the attribute values are displayed as axis labels. Youcan label a Pie series in the same way by specifying a value for the Category Field property.

Categories are automatically indexed and display at runtime in the order they occur in the chartCDF file. When an attribute is used as a category label, the attribute value does not affect the

index value.

103


index value.

Implementing Chart Events

Each element of a chart has a set of events that can be used to customize chart behavior. Youcan specify a JavaScript function that is executed when an end user triggers the event. Thefunction is defined in an included JavaScript file in your project. For more information oncharting events, see .Charting Components

For example, all data series include a Select event, which is triggered when an end user clicksthe series in the chart, and a Spyglass event, which is triggered when the cursor hovers over theseries. This section uses an example to show how these events are implemented in GeneralInterface Builder.

The following charts use the Spyglass event to display descriptive text. The top chart, MajorCategories, also uses the Select event to control data displayed in the bottom chart.

Select Event Example

The series component of the Major Categories chart has the following function associated withthe Select event in the Events Editor palette:

eg.chart.doDrillDown( .getChart(), strRECORDID);this

The function displays detail data for the selected series in the Minor CategoriesdoDrillDown

chart. In the project, the function is defined in an included JavaScript file as follows:

104


chart.doDrillDown = (objChart, strRecordId) {function (strRecordId == ) ;if null return

objMinorChart =var objChart.getServer().getJSXByName('minorCategories'); objMinorChart.clearXmlData();

objNode = objChart.getRecordNode(strRecordId);var childNodes = objNode.getChildNodes();var node = ;var null ((node = childNodes.next()) != ) {while null objMinorChart.insertRecordNode(node.cloneNode(), 'jsxroot', );false }

objMinorChart.repaint();};

The function takes a chart object, the Minor Categories chart, and a record ID string as input. Ituses the method to get a handle to the server instance for thejsx3.app.Model.getServer()

Minor Categories chart. The method is called to clear thejsx3.xml.Cacheable.clearXmlData()

cached CDF document providing the currently visible data.

Analyzing the CDF code that provides chart data is useful when defining the steps to obtaindetail data:

<data> <record jsxid= jsxtext= jsxvalue="1" "North East" "38" color= >"#003399" <record jsxid= jsxtext= jsxvalue="1-1" "New York" "17" color= />"#0033CC" <record jsxid= jsxtext= jsxvalue="1-2" "New Jersey" "10" color= />"#6666CC" <record jsxid= jsxtext= jsxvalue="1-3" "Pennsyl." "5" color= />"#0066FF" <record jsxid= jsxtext= jsxvalue="1-4" "Delaware" "4" color= />"#0099FF" <record jsxid= jsxtext= jsxvalue="1-5" "Others" "2" color= />"#33CCCC" </record>...</data>

The record ID, which is the value of the attribute provided by the user click, is passed tojsxid

the method. This method returns a objectjsx3.xml.CDF.getRecordNode() jsx3.xml.Entity

representing the object handle to the CDF record. The () method then returns allgetChildNodes

nested records in the series for display in the Minor Categories chart. The detail records areinserted into the cached CDF document for the chart, and the chart is repainted in the browser.

Spyglass Event Example

The series components for both the Major Categories and Minor Categories charts have thefollowing function associated with the Spyglass event in the Events Editor palette:

eg.chart.pieSpy( .getChart(), strRECORDID);this

105


The function calculates and displays the percentage, relative to 100%, represented by apieSpy

specific series. The formatted result is displayed in a spyglass window when the cursor hoversover the series. In the project, the function is defined in an included JavaScript file as follows:

chart.pieSpy = (objChart, strRecordId) {function objNode = objChart.getRecordNode(strRecordId);var siblings = objNode.getParent().getChildNodes();var

sum = 0;var node = ;var null ((node = siblings.next()) != ) {while null sum += parseFloat(node.getAttribute('jsxvalue')); }

"<b>" + objNode.getAttribute('jsxtext') + "</b>: " +return parseFloat(((100 * objNode.getAttribute('jsxvalue') sum).roundTo(0.1)).toString().substring(0,5)) + "%";};

As in the Select Event example, the record ID, which is the value of the attribute providedjsxid

by the user action, is passed to the method. All child nodes injsx3.xml. CDF.getRecordNode()

the series are retrieved, and the attribute for each row is totaled to obtain a sum forjsxvalue

the series. The percentage is calculated by comparing the value of the current node to this sum,then formatted for display in the chart.

For information on Charting events, see General Interface GUI Event Reference or hover overan event name in the Events Editor palette.

106


Chapter 12 Charting Components

This chapter describes the Charting components in the Component Libraries palette. To accessthese components, the Charting add-in must be enabled for the project. For more information,see .Enabling the Charting Add-in

Introduction to Charting ComponentsArea ChartArea SeriesBar ChartBar SeriesBubble SeriesCategory AxisChart LabelColumn ChartColumn SeriesGrid LinesLegendLinear AxisLine ChartLine SeriesLogarithmic AxisPie ChartPie SeriesPlot ChartPoint Series

Introduction to Charting Components

To have access to the charting components, the Charting add-in must be enabled in yourproject. For more information, see .Enabling the Charting Add-in

For more information on Charting, see .Working with Charts

For information on Charting events, see General Interface GUI Event Reference or hover overan event name in the Events Editor palette.

For information on Charting properties, see General Interface GUI Property Reference or hoverover a property name in the Properties Editor palette.

Area Chart

The following properties can be configured for all Area chart components:


107


Name The name of the chart in the Component Hierarchy palette.

Left The size of the blank space, in pixels, to leave at the left edge of the boundingbox. If absolutely positioned, the default is 0. If relatively positioned, the defaultis empty.

Top The size of the blank space, in pixels, to leave at the top edge of the boundingbox. If absolutely positioned, the default is 0. If relatively positioned, the defaultis empty.

Width The chart width in implied pixels or as a percentage. For example, or .100 25%

Height The chart height in implied pixels or as a percentage. For example, or .100 25%

RelativeXY

Whether to use relative or absolute positioning for the chart in relation to itscontainer. The default value is .Relative

Type The type of area chart, either , , or .overlay stacked stacked 100%

XMLCache Id

The string identifier of the cached CDF file with chart data. This string isdisplayed in the Local Data Cache palette.

XMLString

The XML string (CDF) with chart data.

XML URL The URL of the CDF file with chart data. The file can be local or remote. Paths canbe relative or absolute.

ShareResources

Whether to delete the associated CDF document when the chart component isrecycled in the Component Hierarchy palette. If Share is specified, the documentremains in cache after the component is recycled. The default value is Cleanup.

BG Color The RGB value of the chart background fill. Specify the value as predefined colornames, RGB, or hexadecimal values. For example, , , or .red rgb(255,0,0) #ff0000

BG Alpha The alpha value (opacity) of the chart background fill. Specify a value from 0.0(fully transparent) to (fully opaque). The default value is .1.0 1.0

BorderColor

The RGB color of the chart border. Specify as a predefined color name, RGB, orhexadecimal value. For example, , , or .red rgb(255,0,0) #ff0000

BorderWidth

The width, in pixels, of the chart border. The default value is .1

BorderAlpha

The alpha value (opacity) of the chart border. Specify a value from (fully0.0

transparent) to (fully opaque). The default value is .1.0 1.0

Padding The CSS padding value between the chart border and the contents of the chart.Specify a single value to use on all sides, such as , or a set of values separated by5


Data AreaPadding

The CSS padding value for the data area. Specify a single value to use on all sides,such as , or a set of values separated by spaces for top, right, bottom, and left,5

such as . The default value is .5 0 5 0 0

TitlePlacement

The location of the chart title, one of top, right, bottom, left. The default value is .top

108


LegendPlacement

The location of the legend, one of top, right, bottom, left. The default value is .right

BoundMenu

A menu to display when a user right-clicks on the chart with the mouse. Specifythe name of the menu component as displayed in the Component Hierarchypalette.

Area Series

The following properties can be configured for Area series components:


Name The name of the series in the Component Hierarchy palette.

SeriesName

The name of the series. This value is displayed as a text entry in the chart legend.

X Field The name of the attribute in each CDF record containing x-coordinate values.

Y Field The name of the attribute in each CDF record containing y-coordinate values.

MinField

The CDF record attribute containing the minimum y-value of the area. This field isoptional.

Type The form of the area series, which defines how to connect data points. The type, , draws straight lines between points. draws the horizontal portionsegment step

and then the vertical portion of the space between points. draws thereverseStep

vertical portion and then the horizontal portion of the space between steps. Thedefault value is .segment

Fill The vector fill to use for the series. The syntax is where iscolor [alpha] color

specified as a predefined color name, RGB, or hexadecimal value. For example, red, , or . is an optional float value between 0.0 and 1.0.rgb(255,0,0) #ff0000 alpha

Stroke The vector stroke to use for the series. The syntax is , where iscolor [alpha] color


FillGradient

The vector fill gradient used for points in the series. The syntax is color2 [angle. The gradient is rendered starting from the[alpha2 [percent stop color,]*]]

main fill color/fill alpha and ending at along the specified .color2/alpha2 angle

Optional intermediate colors along the way are defined by and percent stop_color

pairs. Pairs are separated by commas. For example, red 0 1 50% white, 75%. is specified as a predefined color name, RGB, or hexadecimal value.black color2

For example, , , or . specifies the angle of thered rgb(255,0,0) #ff0000 angle

gradient vector measured in degrees (between 0 and 360) counter-clockwise from12 o'clock. is an optional float value between 0.0 and 1.0.alpha2

PointRenderer

The optional shape displayed at each data point, in front of the line connecting thedata points. Either select one of the default shapes (circle, cross, diamond, box, ortriangle) from the property menu, or type the name of a custom point renderer.

109


PointRadius

The radius of the shapes to draw at each data point. The default value is 4.

Point Fill The vector fill to use for points. The syntax is , where iscolor [alpha] color


PointStroke

The vector stroke to use for points. The syntax is , wherecolor [width [alpha]]

color is specified as a predefined color name, RGB, or hexadecimal value. Forexample, , , or . width is an optional integer valuered rgb(255,0,0) #ff0000

specifying the width of the point in pixels. alpha is an optional float value between0.0 and 1.0.

PointGradient

The vector fill gradient to use for points. The syntax is color2 [angle [alpha2. The gradient is rendered starting from the main fill[percent stop color,]*]]

color/fill alpha and ending at color2/alpha2 along the specified angle. Optionalintermediate colors along the way are defined by percent and stop_color pairs.Pairs are separated by commas. For example, .red 0 1 50% white, 75% black

color2 is specified as a predefined color name, RGB, or hexadecimal value. Forexample, , , or . angle specifies the angle of the gradientred rgb(255,0,0) #ff0000

vector measured in degrees (between 0 and 360) counter-clockwise from 12o'clock. alpha2 is an optional float value between 0.0 and 1.0.

ColorFunction

A static function used to color per-category regions in a series. A categorycorresponds to one row in a CDF document.

Display Whether the series displays in the chart. The default value is , which specifiesblock

to display the series. If is selected, the series is not displayed in the chart butnone

remains in the Component Hierarchy palette.

TooltipFunction

A function that generates mouse-over tooltips for series shapes. The default valuevaries according to series type.

BoundMenu

A menu to display when a user right-clicks on the series with the mouse. Specifythe name of the menu component as displayed in the Component Hierarchypalette.

Bar Chart

This section describes properties shared by all Area chart components, including Bar, Bar-LinearY, Bar- Stacked, and Bar - Stacked 100%.

110





Top The size of the blank space, in pixels, to leave at the top edge of the boundingbox. If absolutely positioned, the default is . If relatively positioned, the default0

is empty.

Width The chart width in implied pixels or as a percentage. For example, or .100 25%

Height The chart height in implied pixels or as a percentage. For example, or .100 25%

RelativeXY

Whether to use relative or absolute positioning for the chart, in relation to itscontainer. The default value is Relative.

Type The type of bar chart, either clustered, stacked, or stacked 100%. The defaultvalue is .clustered

BarOverlap

The ratio of each bar or column that overlaps with the adjacent bar or column inthe same category. If this value is negative, a gap is inserted between adjacentbars or columns. The default value is .0.0

BarCoverage

The ratio of the width of each category that is occupied by bars. Specify a valuebetween 0.0 and 1.0. If this value is less than 1.0, bars are centered horizontally inthe category.

XMLCache Id


XMLString



ShareResources


BG Color The RGB value of the chart background fill. Specify as a predefined color name,RGB, or hexadecimal value. For example, , , or .red rgb(255,0,0) #ff0000


BorderColor


BorderWidth


BorderAlpha



111




Data AreaPadding



TitlePlacement

The location of the chart title, one of top, right, bottom, left. The default value istop.

LegendPlacement

The location of the legend, one of top, right, bottom, left. The default value isright.

BoundMenu


Bar Series

The following properties can be configured for Bar series components:



SeriesName




MinField

The CDF record attribute containing the minimum x-value of the bar. This field isoptional.

BarHeight

For linear and logarithmic axes, the height of each bar in pixels.

Fill The vector fill used for shapes in the series. The syntax is , wherecolor [alpha]

color is specified as a predefined color name, RGB, or hexadecimal value. Forexample, , , or . alpha is an optional float value betweenred rgb(255,0,0) #ff0000

0.0 and 1.0. If no value is specified, the default coloring scheme is used.

Stroke The vector stroke for outlining shapes in the series. The syntax is color [width, where color is specified as a predefined color name, RGB, or[alpha]]

hexadecimal value. For example, , , or . width is anred rgb(255,0,0) #ff0000

optional integer value specifying the width of the stroke in pixels. alpha is anoptional float value between 0.0 and 1.0.

112


FillGradient

The fill gradient used for shapes in the series. The syntax is color2 [angle [alpha2. The gradient is rendered starting from the main fill[percent stop color,]*]]

color/fill alpha and ending at color2/alpha2 along the specified angle. Optionalintermediate colors along the way are defined by percent and stop_color pairs.Pairs are separated by commas. For example, .red 0 1 50% white, 75% black

color2 is specified as a predefined color name, RGB, or hexadecimal value. Forexample, , , or . angle specifies the angle of the gradientred rgb(255,0,0) #ff0000

vector measured in degrees (between 0 and 360) counter-clockwise from 12 o'clock.alpha2 is an optional float value between 0.0 and 1.0.

ColorFunction


Display Whether the series displays in the chart. The default value is , which specifiesBlock

to display the series. If is selected, the series is not displayed in the chart butNoneremains in the Component Hierarchy palette.

TooltipFunction

A function that generates mouse-over tooltips for series shapes. The defaultfunction displays the x- and y-coordinates of the bar, along with the minimumx-value.

BoundMenu


Bubble Series

The following properties can be configured for Bubble series components:



SeriesName




MagnitudeField

The CDF record attribute containing the magnitude value.

Renderer The point renderer to use.

Fill The vector fill used for shapes in the series. The syntax is , where color [alpha]

is specified as a predefined color name, RGB, or hexadecimal value. Forcolor

example, , , or . is an optional float value betweenred rgb(255,0,0) #ff0000 alpha


Stroke The vector stroke for outlining shapes in the series. The syntax is color [width, where is specified as a predefined color name, RGB, or[alpha]] color

hexadecimal value. For example, , , or . is anred rgb(255,0,0) #ff0000 width

optional integer value specifying the width of the stroke in pixels. is analpha

optional float value between 0.0 and 1.0.

113


FillGradient

The vector fill gradient used for shapes in the series. The syntax is color2 [angle. The gradient is rendered starting from the[alpha2 [percent stop color,]*]]

main fill color/fill alpha and ending at color2/alpha2 along the specified angle.Optional intermediate colors along the way are defined by percent andstop_color pairs. Pairs are separated by commas. For example, red 0 1 50%

. color2is specified as a predefined color name, RGB, orwhite, 75% black

hexadecimal value. For example, , , or . angle specifiesred rgb(255,0,0) #ff0000

the angle of the gradient vector measured in degrees (between 0 and 360)counter-clockwise from 12 o'clock. alpha2 is an optional float value between 0.0and 1.0.

ColorFunction


Display Whether the series displays in the chart. The default value is , whichBlock

specifies to display the series. If is selected, the series is not displayed in theNone

chart but remains in the Component Hierarchy palette.

TooltipFunction

A function that generates mouse-over tooltips for series shapes. The defaultfunction displays the x- and y-coordinates of the bubble, along with themagnitude.

BoundMenu


Category Axis

The following properties can be configured for Axis - Category components:


Name The name of the axis in the Component Hierarchy palette.

Orientation The axis orientation, either horizontal (x-axis) or vertical (y-axis). The defaultvalue is .Horizontal

Width For vertical axes, the horizontal space in pixels between axis ticks, between ticksand tick labels, and between labels.

Label Field The CDF record attribute to use as the value of each category. This value can befurther transformed by the Label Function property.

PaddingLow

The number of category widths to use for padding the axis before the firstcategory. This value is usually between and .0.0 1.0

PaddingHigh

The number of category widths to use for padding the axis after the lastcategory. This value is usually between and .0.0 1.0

114


Mj TickAlignment

Specifies to display one major tick mark for each category, with the category andits axis label centered on the tick. If this value is , each category and itsBetween

axis label are aligned between two major ticks. The result is one more major tickmark than there are categories. The default value is . If isBetween Aligned

specified, there is one major tick mark for each category and the category and itsaxis label are centered on the tick.

Show Axis Whether to display the line representing the axis. The default value is . If true

is specified, only axis tick marks and labels, if specified, are displayed.false

Axis Stroke The vector stroke to use to render the line along the axis. The syntax is color where is specified as a predefined color name, RGB, or[width [alpha]] color


optional integer value specifying the width of the line in pixels. is analpha

optional float value between 0.0 and 1.0. The default value is .black 1 1

Mj TickLength

The length of each major tick in pixels. The default value is .0

Mj TickStroke

The vector stroke to use to render major tick marks. The syntax is color [width, where is specified as a predefined color name, RGB, or[alpha]] color




Mj TickPlacement

The location of major tick marks in relation to the line of the axis. A value of draws a tick from the axis line toward the quadrant of the axis, Insideoutside

draws a tick from the axis line away from the quadrant of the axis, Cross drawsa tick centered on the axis line, and None draws no major ticks.

Mn TickLength

The length of each minor tick in pixels. The default value is .0

Mn TickStroke

The vector stroke to use to render the minor tick marks. The syntax is color, where is specified as a predefined color name, RGB, or[width [alpha]] color




Mn TickPlacement

The location of minor ticks relative to the axis line. See the Mj Tick Placementproperty for details. The default value is .none

Mn TickDivisions

The number of minor tick divisions between each major tick. The actual numberof minor ticks between major ticks is one fewer than this value. The defaultvalue is .0

ShowLabels

Whether to display axis labels at each major tick. If false is specified, only axistick marks and the axis line, if specified, are displayed.

Label Gap The number of pixels between major ticks and major tick labels. The defaultvalue is 0.

LabelPlacement

The location of major tick labels. A value of displays labels next to the axisaxis

line, displays labels outside of the data area in the quadrant of the axis, and low

displays labels outside of the data area in the quadrant opposite the axis.high

The default value is .axis

115


LabelFunction

A function that converts an axis value, string or number, to an axis label string.This value is a string value that evaluates to a function, but quotation marks arenot necessary. If no function is specified, the axis value is converted to a stringand displayed. Specify a user-defined or a default function. User-definedfunctions must be in the following format:

function (x) { x; }.return

For example:


The following functions are provided:

Axis.percent — appends the % character to a linear axis valueAxis.scientific — formats a linear axis value in scientific notation Whenprogrammatically setting this property using JavaScript, specify theargument to as a string that evaluates to aAxis.setLabelFunction()

function in the required format.

Label CSSClass

The CSS class to apply to each major tick label.

Label CSSStyles

The CSS style attribute to apply to each major tick label. Multi-line text is notrecommended.

BoundMenu

A menu to display when a user right-clicks on the axis with the mouse. Specifythe name of the menu component as displayed in the Component Hierarchypalette.

Chart Label

The following properties can be configured for Chart Label components:

Property Type Description

Name string The name of the label in the Component Hierarchy palette.

Width int The optional, manually set width of the label in pixels.

Height int The optional, manually set height of the label in pixels.

Text/HTML string The text to render in the label.

Rotation int The angle for rendering the label, one of , , and NONE CLOCKWISE

. The default value is . If or COUNTERCLOCKWISE NONE CLOCKWISE

is specified, the label text should display on aCOUNTERCLOCKWISE

single line.

Font Name string The name of the font for rendering the label.

Font Size string The point size of the font for rendering the label.

116


FontWeight

string The weight of the font for rendering the label, either bold ornormal. The default value is .Normal

Color string The color of the font for rendering the label. Specify as apredefined color name, RGB, or hexadecimal value. For example,

, , or .red rgb(255,0,0) #ff0000

CSS Class string The CSS class to use to render the label text.

BG Color string The fill color of the background rectangle. Specify as apredefined color name, RGB, or hexadecimal value. For example,

, , or .red rgb(255,0,0) #ff0000

BorderStroke

VectorStroke The vector stroke for the outline of the background rectangle.The syntax is , where is specified ascolor [width [alpha]] color

a predefined color name, RGB, or hexadecimal value. Forexample, , , or . width is an optionalred rgb(255,0,0) #ff0000

integer value specifying the width of the line in pixels. alpha isan optional float value between 0.0 and 1.0.

BG Alpha float The alpha value (opacity) of the background rectangle. Specify avalue from (fully transparent) to (fully opaque). The0.0 1.0

default value is .1.0

Text Align string The alignment of label text in the background rectangle, one of , , or .center left right

Padding string The CSS padding string specifying the space between the labelbackground and the label text in pixels. Specify a single value touse on all sides, such as , or a set of values separated by spaces5

for top, right, bottom, and left, such as .5 0 5 0

Display string Whether the label displays in the chart. The default value is , which specifies to display the label. If is selected, theBlock None

label is not displayed in the chart but remains in the ComponentHierarchy palette.

BoundMenu

string A menu to display when a user right-clicks on the label with themouse. Specify the name of the menu component as displayed inthe Component Hierarchy palette.

Column Chart

The following properties can be configured for all Column chart components:




117



Width The chart width in implied pixels or as a percentage. For example, 100 or 25%.

Height The chart height in implied pixels or as a percentage. For example, 100 or 25%.

RelativeXY

Whether to use relative or absolute positioning for the chart, in relation to itscontainer. The default value is .Relative

Type The type of column chart, , , or . The default valueclustered stacked stacked 100%

is .clustered

ColumnOverlap

The ratio of each bar or column that overlaps with the adjacent bar or column inthe same category. If this value is negative, a gap is inserted between adjacentbars or columns. The default value is .0.0

ColumnCoverage

The ratio of the width of each category that is occupied by bars or columns.Specify a value between 0.0 and 1.0. If this value is less than 1.0, columns arecentered horizontally in the category.

XMLCache Id


XMLString



ShareResources

Whether to delete the associated CDF document when the chart component isrecycled in the Component Hierarchy palette. If Share is specified, the documentremains in cache after the component is recycled. The default value is .Cleanup



BorderColor


BorderWidth


BorderAlpha





Data AreaPadding



118


TitlePlacement

The location of the chart title - top, right, bottom, left. The default value is .top

LegendPlacement


BoundMenu


Column Series

The following properties can be configured for Column series components:



SeriesName




MinField

The CDF record attribute containing the minimum y-value for the column. Thisfield is optional.

ColumnWidth

The width of each column in pixels. This value is used only if the x-axis of the chartis linear or logarithmic.

Fill The fill used for shapes in the series. The syntax is , where color iscolor [alpha]

specified as a predefined color name, RGB, or hexadecimal value. For example, red, , or . alpha is an optional float value between 0.0 and 1.0. Ifrgb(255,0,0) #ff0000

no value is specified, the default coloring scheme is used.

Stroke The stroke for outlining shapes in the series. The syntax is ,color [width [alpha]]

where is specified as a predefined color name, RGB, or hexadecimal value.color

For example, , , or . is an optional integer valuered rgb(255,0,0) #ff0000 width

specifying the width of the stroke in pixels. is an optional float valuealpha

between 0.0 and 1.0.

FillGradient

The fill gradient used for shapes in the series. The syntax is color2 [angle [alpha2. The gradient is rendered starting from the main fill[percent stop color,]*]]

color/fill alpha and ending at along the specified . Optionalcolor2/alpha2 angle

intermediate colors along the way are defined by and pairs.percent stop_color

Pairs are separated by commas. For example, . red 0 1 50% white, 75% black

is specified as a predefined color name, RGB, or hexadecimal value. Forcolor2

example, , , or . specifies the angle of the gradientred rgb(255,0,0) #ff0000 angle

vector measured in degrees (between 0 and 360) counter-clockwise from 12 o'clock. is an optional float value between 0.0 and 1.0.alpha2

ColorFunction


119


Display Whether the series displays in the chart. The default value is , which specifiesBlock

to display the series. If is selected, the series is not displayed in the chart butNone

remains in the Component Hierarchy palette.

TooltipFunction

A function that generates mouse-over tooltips for series shapes. The defaultfunction displays the x- and y-coordinates of the column, along with the minimumx-value.

BoundMenu


Grid Lines

The following properties can be configured for Grid Lines components:


Name The name of the grid lines component in the Component Hierarchy palette.

Draw inForeground

Whether to render grid lines in front of any data series. The default value is .false

Layering Whether horizontal fills, major ticks, and minor ticks and rendered abovevertical equivalents. The default value is .Horizontal Above Vertical

Border The vector stroke to use for outlining the data area. The syntax is color [width, where is specified as a predefined color name, RGB, or[alpha]] color




Ver Fill The vector fill between vertical major tick marks. The syntax is ,color [alpha]

where is specified as a predefined color name, RGB, or hexadecimalcolor

value. For example, , , or . is an optional floatred rgb(255,0,0) #ff0000 alpha

value between 0.0 and 1.0. You can also specify a comma-separated list ofvalues. For example, . The fill cycles through thered .5, blue .5, green 1

values in the array at each major tick.

Ver MajorStroke

The vector stroke to use between vertical major tick lines. The syntax is color, where is specified as a predefined color name, RGB, or[width [alpha]] color


optional integer value specifying the width of the tick line in pixels. is analpha

optional float value between 0.0 and 1.0. You can also specify acomma-separated list of values. For example, .red 1 .5, blue 2 .5, green 1 1

The fill cycles through the values in the array at each major tick.

120


Ver MinorStroke

The vector stroke to use between minor vertical tick lines. The syntax is color, where is specified as a predefined color name, RGB, or[width [alpha]] color




The fill cycles through the values in the array at each minor tick.

Hor Fill The vector fill between horizontal major tick marks. The syntax is color, where is specified as a predefined color name, RGB, or[alpha] color

hexadecimal value. For example, , , or . is anred rgb(255,0,0) #ff0000 alpha

optional float value between 0.0 and 1.0. You can also specify acomma-separated list of pair values. For example, .red .5, blue .5, green 1

The fill cycles through the values in the array at each major tick.

Hor MajorStroke

The vector stroke to use between horizontal major tick lines. The syntax is color, where is specified as a predefined color name, RGB, or[width [alpha]] color




Major tick lines cycle through the values in the array.

Hor MinorStroke

The vector stroke to use to mark the minor horizontal tick lines. The syntax is , where is specified as a predefined color name,color [width [alpha]] color

RGB, or hexadecimal value. For example, , , or . isred rgb(255,0,0) #ff0000 width

an optional integer value specifying the width of the tick line in pixels. isalpha

an optional float value between 0.0 and 1.0. You can also specify acomma-separated list of values. For example, .red 1 .5, blue 2 .5, green 1 1

Minor tick lines cycle through the values in the array.

Display Whether grid lines display in the chart. The default value is , whichBlock

specifies to display grid lines. If is selected, grid lines are not displayed inNone

the chart, but the component remains in the Component Hierarchy palette.

BoundMenu

A menu to display when a user right-clicks on the grid line with the mouse.Specify the name of the menu component as displayed in the ComponentHierarchy palette.

Legend

The following properties can be configured for Legend components:


Name The name of the legend in the Component Hierarchy palette.

Width The horizontal space to dedicate to the legend and its margin. This value isused only if the Legend Placement property for the chart has a value of orright

.left

121


Height The vertical space to dedicate to the legend and its margin. This value is usedonly if the Legend Placement property for the chart has a value of or top bottom

.

Box Height The diameter of the colored boxes to render for each legend entry in pixels.

Line Height The vertical space to use for each legend entry in pixels.

Label CSSClass

The CSS class to apply to each legend entry.

Label CSSStyles

The CSS style attribute to apply to each legend entry.

Padding The CSS padding string specifying the space between the legend backgroundand the legend content in pixels. Specify a single value to use on all sides, suchas , or a set of values separated by spaces for top, right, bottom, and left, such5

as .5 0 5 0

Margin The CSS margin string specifying the space between the legend backgroundand its bounding area. Specify a single value to use on all sides, such as , or a5

set of values separated by spaces for top, right, bottom, and left, such as 5 0 5.0

BackgroundFill

The vector fill for the background of the legend. The syntax is ,color [alpha]

where is specified as a predefined color name, RGB, or hexadecimalcolor

value. For example, , , or . is an optional floatred rgb(255,0,0) #ff0000 alpha

value between 0.0 and 1.0.

BackgroundStroke

The vector stroke for the background of the legend. The syntax is color [width, where is specified as a predefined color name, RGB, or[alpha]] color




Display Whether the legend displays in the chart. The default value is , whichBlock

specifies to display the legend. If is selected, the legend is not displayed inNone

the chart but remains in the Component Hierarchy palette.

BoundMenu

A menu to display when a user right-clicks on the legend with the mouse.Specify the name of the menu component as displayed in the ComponentHierarchy palette.

Linear Axis

The following properties can be configured for Axis - Linear components.



Orientation The axis orientation, either horizontal (x-axis) or vertical (y-axis). The defaultvalue is .Horizontal

122



AutoAdjust

Whether to adjust the displayed Minimum Value, Maximum Value, and Intervalproperties according to the chart data. Only values not explicitly set will beautomatically calculated. The default value is .true

Base AtZero

Whether to base the axis range at zero when the Auto Adjust property is set totrue. If this value is true and all the data points are either greater than zero orless than zero, then one end of this axis will be zero. The default value is .true

MinimumValue

The manually set minimum value to display on the axis. Intervals always beginfrom this value.

MaximumValue

The manually set maximum value to display on the axis.

Interval The manually set interval value. The axis displays major ticks at min + n *interval.

Show Axis Whether to display the line representing the axis. The default value is . If true

is specified, only axis tick marks and labels, if specified, are displayed.false

Axis Stroke The vector stroke to use to render the line along the axis. The syntax is color, where is specified as a predefined color name, RGB, or[width [alpha]] color



optional float value between 0.0 and 1.0. The default value is black 1 1.

Mj TickLength

The length of each major tick in pixels. The default value is 0.

Mj TickStroke

The vector stroke to use to render major tick marks. The syntax is color [width, where is specified as a predefined color name, RGB, or[alpha]] color




Mj TickPlacement

The location of major tick marks in relation to the line of the axis. A value of draws a tick from the axis line toward the quadrant of the axis, outside inside

draws a tick from the axis line away from the quadrant of the axis, drawscross

a tick centered on the axis line, and draws no major ticks.none

Mn TickLength

The length of each minor tick in pixels. The default value is 0.

Mn TickStroke

The vector stroke to use to render the minor tick marks. The syntax is color, where is specified as a predefined color name, RGB, or[width [alpha]] color




Mn TickPlacement

The location of minor ticks relative to the axis line. See the Mj Tick Placementproperty for details. The default value is .none

123


Mn TickDivisions

The number of minor tick divisions between each major tick. The actual numberof minor ticks between major ticks is one fewer than this value. The defaultvalue is 0.

ShowLabels

Whether to display axis labels. If false is specified, only axis tick marks and theaxis line, if specified, are displayed.


LabelPlacement





LabelFunction



For example:





Label CSSClass

The CSS class to apply to each major tick label. Uses the

Label CSSStyles

The CSS style attribute to apply to each major tick label. Multi-line text is notrecommended.

BoundMenu


Line Chart

The following properties can be configured for all Line chart components:


124







RelativeXY


Type The type of line chart. Possible values are , , and .overlay stacked stacked 100%

XMLCache Id


XMLString



ShareResources

Whether to delete the associated CDF document when the chart component isrecycled in the Component Hierarchy palette. If is specified, the documentShare

remains in cache after the component is recycled. The default value is .Cleanup



BorderColor


BorderWidth


BorderAlpha





Data AreaPadding



TitlePlacement


125


LegendPlacement


BoundMenu


Line Series

The following properties can be configured for all Line series components:



SeriesName




Type The form of the line series, which defines how to connect data points. segmentdraws straight lines between points. draws only the horizontalhorizontal

distance between points at the y-coordinate of the second point. drawsvertical

only the vertical distance between points at the x-coordinate of the second point. draws the horizontal portion and then the vertical portion of the spacestep

between points. draws the vertical portion and then the horizontalreverseStep

portion of the space between steps. The default value is .segment

InterpolateValues

Whether to display a continuous line when data points are missing. If false isspecified, the line is discontinuous over missing data points. The default value is

.false

Stroke The vector stroke to use for the series. The syntax is ,color [width [alpha]]

where is specified as a predefined color name, RGB, or hexadecimal value.color

For example, , , or . is an optional integer valuered rgb(255,0,0) #ff0000 width

specifying the width of the point in pixels. is an optional float valuealpha


PointRenderer

The optional shape displayed at each data point, in front of the line connectingthe data points. Either select one of the default shapes (circle, cross, diamond,box, or triangle) from the property menu, or type the name of a custom pointrenderer object.

PointRadius

The radius of the shapes to draw at each data point. The default is 4.

Point Fill The vector fill to use for points. The syntax is: , where iscolor [alpha] color

specified as a predefined color name, RGB, or hexadecimal value. For example, , , or . is an optional float value between 0.0 andred rgb(255,0,0) #ff0000 alpha

1.0.

126


PointStroke

The vector stroke to use for points. The syntax is , where color [width [alpha]]

is specified as a predefined color name, RGB, or hexadecimal value. Forcolor

example, , , or . is an optional integer valuered rgb(255,0,0) #ff0000 width

specifying the width of the point in pixels. is an optional float valuealpha


PointGradient

The gradient to use for points. The syntax is color2 [angle [alpha2 [percent. The gradient is rendered starting from the main fill color/fillstop color,]*]]

alpha and ending at along the specified . Optionalcolor2/alpha2 angle

intermediate colors along the way are defined by and pairs.percent stop_color

Pairs are separated by commas. For example, . red 0 1 50% white, 75% black

is specified as a predefined color name, RGB, or hexadecimal value. Forcolor2

example, , , or . specifies the angle of the gradientred rgb(255,0,0) #ff0000 angle

vector measured in degrees (between 0 and 360) counter-clockwise from 12o'clock. is an optional float value between 0.0 and 1.0.alpha2

ColorFunction





TooltipFunction

A function that generates mouse-over tooltips for series shapes. The defaultfunction displays the x- and y-coordinates of the data point.

BoundMenu


Logarithmic Axis

The following properties can be configured for Axis - Logarithmic components:



Orientation The axis orientation, either horizontal (x-axis) or vertical (y-axis). The defaultvalue is Horizontal.


AutoAdjust

Whether to adjust the displayed Minimum Exponent and Maximum Exponentproperties according to the chart data. Only values not explicitly set will beautomatically calculated. The default value is .false

Base AtZeroExponent

Whether to set Minimum Exponent equal to 0 when the Auto Adjust property isset to true.

127


MinimumExponent

The manually set minimum exponent to display on the axis. The minimumdisplayed value is the Exponent Base value raised to the power of MinimumExponent.

MaximumExponent

The manually set maximum exponent to display on the axis. The maximumdisplayed value is the Exponent Base value raised to the power of MaximumExponent.

ExponentBase

The base of the exponent to use.

Show Axis Whether to display the line representing the axis. The default value is true. Iffalse is specified, only axis tick marks and labels, if specified, are displayed.

Axis Stroke The vector stroke to use to render the line along the axis. The syntax is color, where color is specified as a predefined color name, RGB, or[width [alpha]]


optional integer value specifying the width of the line in pixels. alpha is anoptional float value between 0.0 and 1.0. The default value is black 1 1.

Mj TickLength

The length of each major tick in pixels. The default value is 0.

Mj TickStroke

The vector stroke to use to render major tick marks. The syntax is color [width, where color is specified as a predefined color name, RGB, or[alpha]]


optional integer value specifying the width of the line in pixels. alpha is anoptional float value between 0.0 and 1.0.

Mj TickPlacement

The location of major tick marks in relation to the line of the axis. A value of draws a tick from the axis line toward the quadrant of the axis, outside inside

draws a tick from the axis line away from the quadrant of the axis, drawscross

a tick centered on the axis line, and draws no major ticks. The default valuenone

is .outside

Mn TickLength

The length of each minor tick in pixels. The default value is 0.

Mn TickStroke

The vector stroke to use to render the minor tick marks. The syntax is color, where color is specified as a predefined color name, RGB, or[width [alpha]]


optional integer value specifying the width of the line in pixels. alpha is anoptional float value between 0.0 and 1.0.

Mn TickPlacement

The location of minor ticks relative to the axis line. See the Mj Tick Placementproperty for details. The default value is none.

Mn TickDivisions

The number of minor tick divisions between each major tick. The actual numberof minor ticks between major ticks is one fewer than this value. The defaultvalue is 0.

ShowLabels

Whether to display axis labels. If false is specified, only axis tick marks and theaxis line, if specified, are displayed.


128


LabelPlacement





LabelFunction



For example:





Label CSSClass

The CSS class to apply to each major tick label.

Label CSSStyles

The CSS style attribute to apply to each major tick label.

BoundMenu


Pie Chart

The following properties can be configured for all Pie chart components:



Left The size of the blank space, in pixels, to leave at the left edge of the boundingbox. If absolutely positioned, the default is . If relatively positioned, the default0

is empty.

Top The size of the blank space, in pixels, to leave at the top edge of the boundingbox. If absolutely positioned, the default is . If relatively positioned, the default0

is empty.

129


Width The chart width in implied pixels or as a percentage. For example, .100 or 25%

Height The chart height in implied pixels or as a percentage. For example, .100 or 25%

RelativeXY

Whether to use relative or absolute positioning for the chart, in relation to itscontainer. The default value is Relative.

InnerRadius

The radius of the inner circle of the chart as a ratio of the radius of the outermostseries. Specify a value from to . The default value is .0.0 1.0 0.0

SeriesPadding

The amount of padding between series, as a ratio of the width of a series. Thedefault value is .0

TotalAngle

The angle, in degrees, equal to 100% of the sum of the values in a series. A valueof 360 renders a traditional pie chart, and smaller values render a pie chart with aslice missing. A series can override this value using the series Total Angleproperty. The default value is .360

StartAngle

The initial angle of the first slice in each series. A value of 0 points north andincreasing values continue clockwise. A series can override this value using theseries Start Angle property. The default value is .0

CategoryField

The name of the attribute in each CDF record containing category values. Thesevalues are displayed as entries in a legend.

Colors A comma-separated array of vector fill values used to color in the slices in eachseries. The syntax for each value is , where color is specified as acolor [alpha]

predefined color name, RGB, or hexadecimal value. For example, , red

, or . alpha is an optional float value between 0.0 and 1.0. Ifrgb(255,0,0) #ff0000

no value is specified, the default coloring scheme is used. A series can overridethis value using the series Colors property.

SeriesStroke

The vector stroke for outlining each series. The syntax is ,color [width [alpha]]

where color is specified as a predefined color name, RGB, or hexadecimal value.For example, , , or . width is an optional integer valuered rgb(255,0,0) #ff0000

specifying the width of the stroke in pixels. alpha is an optional float valuebetween 0.0 and 1.0. A series can override this value using the series Strokeproperty.

ColorFunction

A function, specified instead of the series Colors property, that returns aVectorFill for a particular slice. A series can override this value using the seriesColor Function property. If no value is specified, the default coloring scheme isused.

XMLCache Id


XMLString



ShareResources


130




BorderColor


BorderWidth


BorderAlpha





Data AreaPadding



TitlePlacement

The location of the chart title, one of top, right, bottom, left. The default value istop.

LegendPlacement

The location of the legend, one of top, right, bottom, left. The default value isright.

BoundMenu


Pie Series

The following properties can be configured for all Pie series components:



SeriesName

The name of the series.

Field The attribute of the CDF record containing the value, which is the size of a slicerelative to other slices in this series.

TotalAngle

The angle equal to 100% of the sum of the values in a series, in degrees. Thisvalue overrides the chart Total Angle property for this series.

StartAngle

The initial angle of the first slice in each series. This value overrides the chartStart Angle property for this series.

Colors A comma-separated array of vector fill values used to color in the slices in eachseries. This value overrides the chart Colors property for this series.

131


Stroke The vector stroke for outlining each series. The syntax is ,color [width [alpha]]

where color is specified as a predefined color name, RGB, or hexadecimal value.For example, , , or . width is an optional integer valuered rgb(255,0,0) #ff0000

specifying the width of the stroke in pixels. alpha is an optional float valuebetween 0.0 and 1.0. This value overrides the chart Series Stroke property for thisseries.

ColorFunction

A function, specified instead of the series Colors property, that returns aVectorFill for a particular slice. This value overrides the chart Color Function forthis series. For an example, see .JSXAPPS/samples/chart

LabelPlacement

The quadrant for rendering the chart label, if any. Valid values are top, right,bottom, and left. The default value is bottom.

LabelOffset

The number of pixels of offset from the outside edge of the series to the insideedge of the label. The default value is 0.




TooltipFunction

A function that generates mouse-over tooltips for series shapes. The defaultfunction displays the value of the category as a percent rounded to the nearestinteger.

BoundMenu


Plot Chart

The following properties can be configured for all Plot chart components:







RelativeXY


MaxRadius

The largest point radius to display in the chart. Any point that exceeds this sizeis constrained to this value. The default value is 30.

132


MagnitudeMethod

For points in a series (Plot - Point charts) or a category (Plot - Bubble charts),whether point magnitude is proportional to the chart radius, chart diameter, orthe area of a point.

XMLCache Id


XMLString


XML URL The URL of the CDF file with chart data. The file can be local or remote. Pathscan be relative or absolute.

ShareResources

Whether to delete the associated CDF document when the chart component isrecycled in the Component Hierarchy palette. If is specified, the documentShare

remains in cache after the component is recycled. The default value is .Cleanup



BorderColor


BorderWidth


BorderAlpha



Padding The CSS padding value between the chart border and the contents of the chart.Specify a single value to use on all sides, such as , or a set of values separated5

by spaces for top, right, bottom, and left, such as .5 0 5 0

Data AreaPadding

The CSS padding value for the data area. Specify a single value to use on allsides, such as , or a set of values separated by spaces for top, right, bottom, and5

left, such as . The default value is .5 0 5 0 0

TitlePlacement


LegendPlacement


BoundMenu


Point Series

The following properties can be configured for all Point series components:


133



SeriesName




Magnitude The magnitude of each point in the series.

Renderer The name of the point renderer to use.

Fill The vector fill used for shapes in the series. The syntax is , wherecolor [alpha]

color is specified as a predefined color name, RGB, or hexadecimal value. Forexample, , , or . alpha is an optional float value betweenred rgb(255,0,0) #ff0000


Stroke The vector stroke for outlining shapes in the series. The syntax is color [width, where color is specified as a predefined color name, RGB, or[alpha]]


optional integer value specifying the width of the stroke in pixels. alpha is anoptional float value between 0.0 and 1.0.

FillGradient

The fill gradient used for shapes in the series. The syntax is color2 [angle. The gradient is rendered starting from the[alpha2 [percent stop color,]*]]

main fill color/fill alpha and ending at color2/alpha2 along the specified angle.Optional intermediate colors along the way are defined by percent andstop_color pairs. Pairs are separated by commas. For example, red 0 1 50%

. color2 is specified as a predefined color name, RGB, orwhite, 75% black

hexadecimal value. For example, , , or . angle specifiesred rgb(255,0,0) #ff0000

the angle of the gradient vector measured in degrees (between 0 and 360)counter-clockwise from 12 o'clock. alpha2 is an optional float value between 0.0and 1.0.

ColorFunction





TooltipFunction

A function that generates mouse-over tooltips for series shapes. The defaultfunction displays the x- and y-coordinates of the point.

BoundMenu


134


Chapter 13 Creating GUI Classes in General Interface

This document describes and presents examples on how to create GUI classes in GeneralInterface.

About GUI ClassesExercise 1 on Basic SpinnerExercise 2 on Spinner with Up and Down ButtonsExercise 3 on Spinner with Up and Down Image ButtonsExercise 4 on Editable Grid

About GUI Classes

General Interface provides numerous ways for developers to customize the look, feel, andbehavior of the existing GUI controls. In some cases, however, a control may not exist or mustbe modified so extensively that it makes sense to create an entirely new class. By leveraging thebase class, , developers can simplify many of the difficult steps with GUIjsx3.gui.Template

class development, including cross-browser layout differences. The template engine alsoemploys HTML syntax for its templates, making the development process familiar todevelopers.

Background

General Interface employs a model-view-controller (MVC) architecture. For each on-screenobject (the "view") there is a corresponding state model that describes it (the "model"). Logicalfunctions synchronize the two (the "controller"). For example, consider a slider widget with themodel shown in the following table.

Model for Slider Widget

Property Name Value

length 200

value 25

orientation horizontal

name myslider

When it is time to paint the model, the corresponding view is generated as HTML.

Note: Some content in the following code has been removed for readability.

135


<span onmousewheel= onkeydown= style=";" ";">"position:absolute;width:200px;height:15px;"

<div style= >"position:relative;width:200px;height:7px;padding:4px 0px 4px 0px;;" <div onclick= style=";" " width:198px;height:5px;background:gray;border:inset

/>1px;" <div onmousedown= style=";"

>"position:absolute;width:15px;height:15px;left:50px;top:0px;" <div style=" width:15px;height:15px;

/>background:url(JSX/images/slider/top.gif);" </div> </div></span>

The HTML is then sent to the browser (the view delegate---basically a helper that can renderthe HTML) and it renders as follows:

If the user interacts with the view by dragging the slider handle, the controller is notified of therelevant events, including , , and . The controller then updates themousedown mousemove mouseup

model based upon its own processing rules. In this case, assume the slider has been dragged toposition 50.

Example Position

Property Name Value

value 50

The system then synchronizes the model to the view (which is sent to the browser to reflect theupdated state), and the cycle continues.

Like all architectures, MVC is merely an organizing schema---a way to describe objects andtheir relationships to help better understand and build complex systems. By abstracting theview and the model, you are able to envision your Web application not as a tangle of HTML,but rather a group of higher-level objects. Being freed to imagine the model, you can moreeasily architect appropriate business solutions.

The remainder of this document describes how to create custom GUI classes according to MVCprinciples. The exercises become progressively more complex as the various capabilities of thetemplate language are described. All of the examples describe how to create a basic spinnercontrol.

Exercise 1 on Basic Spinner

This example describes how to create a basic spinner control.

136


I. Create a Functional Specification

It is important to create a solid functional specification. With a good specification, it is notnecessary to waste time modifying and re-factoring code. Requirements for the basic spinnerinclude an HTML text input control with enhanced features and functionality to allow for keyinput and listening for and events. When the up arrow key is pressed, thekeydown mousewheel

control will increment its value. The mouse wheel will have a similar effect when wheeled upby the user. By default, the control will have a single-pixel gray border. The next table showsthe complete list of properties, and the following table shows the associated events andbehaviors.

Example 1 Controls

Property Name Value

position relative

left

top

width 60 (pixels)

height 20 (pixels)

border solid 1px gray

vertical-align middle

font-name

font-size 20

value 1

Example 1 Events and Behaviors

Property Name Value

Key Up Increments the text field

Key Down Decrements the text field

Mousewheel Up Increments the text field

Mousewheel Down Decrements the text field

Change Persists the value after focus is lost

value 1

The default control will appear as follows:

137


1. a.

b.

c.

d.

2.

II. Define the class

Authoring a GUI class requires a working knowledge of HTML, XML, and JavaScript.However, given the functional separation that MVC provides, it is possible to divide the tasksamong team members who are appropriately skilled for each portion.

The following steps show how to create the GUI class.

Create a new JavaScript file. Require the template engine and any interfaces. The new spinner control willeventually be used as a form field in a General Interface application, so theinterface, , will also be included in the require statement. Refer tojsx3.gui.Form

the documentation for for a complete list of all methods providedjsx3.gui.Form

by the interface. Define the new class using . Refer to the super class (defineClass

), and any interfaces ( ). While is ajsx3.gui.Template.Block jsx3.gui.Form SPINNER

pointer to the class, is a pointer to the class prototype. These names arespinner

arbitrary and merely serve as a useful alias while defining the class. Also note thename for the new class: . my.Spinner1

Include an method. This is the constructor that allows the class to beinit

instantiated. It is object oriented and should therefore make a call to .jsxsuper

Users can instance the class by calling: new my.Spinner1("somename");

Subclass the method to convert the template's HTML markup (togetTemplateXML

be created) into the corresponding JavaScript functions needed by the class. TheXML is defined inline within the JavaScript and uses an apostrophe escape.

jsx3.require("jsx3.gui.Template","jsx3.gui.Form"); //a)jsx3.lang. .defineClass("my.Spinner1" //b)Class,jsx3.gui.Template.Block,[jsx3.gui.Form], (SPINNER,spinner) {function spinner.init = (strName) { //cfunction .jsxsuper(strName);this };spinner.getTemplateXML = () { //dfunction ['<transform ',return ' xmlns="http://gi.tibco.com/transform/" ', ' xmlns:u="http://gi.tibco.com/transform/user" version="1.0">', ' <model/>' , ' <template/>' , '</transform>'].join(""); };* });

Define any model defaults for the GUI control. The spinner will implement a defaultvalue of 1 if no value is specified. Because the control implements the jsx3.gui.Forminterface, its value is stored using the field. This means that any call to the jsxvalue

method (a mix-in method provided by ) will return 1 if the givengetValue jsx3.gui.Form

instance does not define a value.

138


2.

3.

jsx3.require("jsx3.gui.Template","jsx3.gui.Form");jsx3.lang. .defineClass("my.Spinner1"Class,jsx3.gui.Template.Block,[jsx3.gui.Form], (SPINNER,spinner) {function spinner.init = (strName) {function .jsxsuper(strName);this }; spinner.jsxvalue = 1; spinner.getTemplateXML = () {function ['<transform ',return ' xmlns="http://gi.tibco.com/transform/" ', ' xmlns:u="http://gi.tibco.com/transform/user" version="1.0">', ' <model/>' , ' <template/>' , '</transform>'].join(""); }; });

The system serializes all simple model properties. This means that serializing an instanceby calling its method will result in the property value, 1, being serialized,toXML

regardless of whether or not it was explicitly declared on the instance.

Author the HTML prototype to reflect the requirements in the functional specification:

<input type= value="text" "1" onchange= onkeydown= onkeyup= onmousewheel=";" ";" ";" ";"style="position:relative;left:;top:;width:60px;height:20px;margin:0px;border:solid 1px gray;font-name:;font-size:10px;vertical-align:middle;" />

Next, replace every HTML attribute, event, or style property value that should be made with a replacement variable (denoted by curly braces). For example, to allowdynamic

the font-size property to be dynamically replaced with the model property, ,jsxfontsize

change the explicit style declaration from this:

font-size:10px;

to this:

font-size:{jsxfontsize};

The HTML now appears as follows.

<input type= value="text" "{jsxvalue}" onchange= onkeydown="{onchange}" "{onkeydown}" onkeyup= onmousewheel="{onkeyup}" "{onmousewheel}"style="position:{$position};left:{jsxleft};top:{jsxtop}; width:{jsxwidth|60};height:{jsxheight|20};margin:{jsxmargin}; border:{border|solid 1px gray};font-name:{jsxfontname};font-size:{jsxfontsize};vertical-align:middle;" />

Note the following items:

The position property uses the variable { }. The prefix is reserved by$position $

the system to define a pre-built set of system variable resolvers that are provided

139


3.

4.

the system to define a pre-built set of system variable resolvers that are providedby the template engine. contains a full list of pre-built resolvers.System ResolversBy using these you can greatly simplify creating your template. For example, the {

} resolver will return either or , depending upon the$position relative absolute

value of the property.jsxrelativeposition

The width, height, and border declarations include a default value. This ensuresthat the control is at least 60 pixels wide by 20 pixels tall with a single-pixel grayborder. Default values are denoted using a pipe character. Refer to Control

for implementation details on .Statements @defaultvalue

Event declarations such as tell the system that you haveonkeydown="{onkeydown}"

a controller method named that should be notified of the event.onkeydown keydown

Step explains this further.10The value field for the text input uses the { } variable. This means thatjsxvalue

when the control is painted on-screen its value will be equal to this.jsxvalue.This is how all template variables work and is the preferred method for matchingproperties on the model to properties in the view template. In other words, {

} points to and { } points to . Thisjsxfontsize this.jsxfontsize x.y.z this.x.y.z

simple pattern ensures proper synchronization between model and view. The class appears as follows:

jsx3.require("jsx3.gui.Template","jsx3.gui.Form");jsx3.lang. .defineClass("my.Spinner1"Class,jsx3.gui.Template.Block,[jsx3.gui.Form], (SPINNER,spinner) {function spinner.init = (strName) {function .jsxsuper(strName);this }; spinner.jsxvalue = 1; spinner.getTemplateXML = () {function ['<transform xmlns="http://gi.tibco.com/transform/" ' ,return ' xmlns:u="http://gi.tibco.com/transform/user"version="1.0">' , ' <model/>' , ' <template>' , ' <input type="text" value="{jsxvalue}" ' , ' onchange="{onchange}" onkeydown="{onkeydown}" ' , ' onkeyup="{onkeyup}" onmousewheel="{onmousewheel}" ' , ' style="position:{position};left:{jsxleft};top:{jsxtop};' , ' width:{jsxwidth|60};height:{jsxheight|20};margin:{jsxmargin};' , ' border:{border|solid 1pxgray};font-name:{jsxfontname};', ' font-size:{jsxfontsize};vertical-align:middle;" />' , ' </template>' , '</transform>'].join(""); };});

The last step is to define the controller functions. As previously explained, any eventdeclared in the template using the standard variable syntax (such as

) will automatically call the prototype class function of theonkeydown="{onkeydown}"

same name. This means if you declare an event in your template, you shouldonkeydown

also declare the JavaScript controller . By naming the controllers appropriately,onkeydown

the on-screen view will be able to locate the corresponding in-memory controller. When

140


4.

the on-screen view will be able to locate the corresponding in-memory controller. Whenfound, an instance of and a reference to the target GUI object will bejsx3.gui.Event

passed to the controller. The controller can then update the model and the view bycalling the method. This single call updates the named property on thesetProperty

model and projects the update to the on-screen view. Note how the methodsetValue

utilizes this function call. This is a final critical step that all controller methods shoulduse to ensure a complete feedback loop from model to view. The final class is as follows(the and methods have been removed for readability):init compile

jsx3.require("jsx3.gui.Template","jsx3.gui.Form");jsx3.lang. .defineClass("my.Spinner1"Class,jsx3.gui.Template.Block,[jsx3.gui.Form], (SPINNER,spinner) {function // ** init and compile methods removed readability **for //add the controller logic here... spinner.onkeydown = (objEvent,objGUI) {function (objEvent.upArrow()) .up();if this (objEvent.downArrow()) .down();else if this }; spinner.onkeyup = (objEvent,objGUI) {function .jsxvalue = objGUI.value;this }; spinner.onchange = (objEvent,objGUI) {function .jsxvalue = objGUI.value;this }; spinner.onmousewheel = (objEvent,objGUI) {function wd = objEvent.getWheelDelta();var (wd > 0) .up();if this (wd < 0) .down();else if this }; spinner.up = () {function .setValue(parseInt( .getValue())+1);this this }; spinner.down = () {function .setValue(parseInt( .getValue())-1);this this }; spinner.setValue = (strValue) {function //tell the engine to update the model and synchronize the view .setProperty("jsxvalue",strValue);this };});

Exercise 2 on Spinner with Up and Down Buttons

This example describes how to create a spinner control that includes up and down buttons.

I. Define the control

This exercise adds up and down image buttons to increment or decrement the value of theinput box. The control otherwise remains unchanged.

141


1.

2.


All controllers remain the same for this class. This is an important point that reflects theflexibility provided by an MVC architecture. Because this exercise merely adds features to theview, there is no need to modify any of the existing controller methods. Only the view templateand a few additional model defaults need to be changed, because the updated spinner widgetmust define more HTML elements to create the up and down images.

The following steps show how to add the up and down controls.

Add two additional model defaults. The new spinner control will use up and downimages borrowed from the class. The URL for the up and downjsx3.gui.TimePicker

images is saved as a complex object ( and ). The Generalthis.arrow.up this.arrow.down

Interface serializer ignores this property when the object is serialized as XML, becausethere is no need to save it, as it is only used when painting the arrows at runtime. Theclass appears as follows:

jsx3.require("jsx3.gui.Template","jsx3.gui.Form");

jsx3.lang. .defineClass("my.Spinner1"Class,jsx3.gui.Template.Block,[jsx3.gui.Form], (SPINNER,spinner) {function

spinner.init = (strName) {function .jsxsuper(strName);this };

spinner.jsxvalue = 1; .arrow = {};this .arrow.up = "url(" + jsx3.resolveURI("jsx:///images/jsxtimepicker/" +this "spin_up.gif") + ")"; .arrow.down = "url(" + jsx3.resolveURI("jsx:///images/jsxtimepicker/" +this "spin_down.gif") + ")";

spinner.getTemplateXML = () {function ['<transform xmlns="http://gi.tibco.com/transform/" ' ,return ' xmlns:u="http://gi.tibco.com/transform/user" version="1.0">' , ' <model/>' , ' <template/>' , '</transform>'].join(""); };

});

Expand the definition for the HTML template. Note that the input box is nested inside aspecial box, . This is an adapted SPAN object provided by the template engineinlinebox

that allows the GUI control to have layout (width and height) even if it is relativelypositioned or flowed inline with text. This enables you to position the control eitherrelatively or absolutely without having cross browser differences corrupt the layout.

142


2.

<inlinebox style="position:{$position};left:{jsxleft}; top:{jsxtop};width:{jsxwidth|60};height:{jsxheight|20};margin:{jsxmargin};border:{jsxborder|solid 1px gray};vertical-align:middle;"> <input type= value= onchange="text" "{jsxvalue}" "{onchange}" onkeydown= onkeyup="{onkeydown}" "{onkeyup}" onmousewheel="{onmousewheel}" style="position:absolute;left:0px;top:0px; width:100%-12px;height:100%;border:{iborder|0px;solid 1px gray;0px;0px;}; font-name:{jsxfontname};font-size:{jsxfontsize};" /> <span onclick="{up}" style="position:absolute;right:11px;top:0px; width:11px;height:8px;overflow:hidden;cursor:\pointer; background-image:{*arrow.up*};"></span> <span onclick="{down}" style="position:absolute;right:11px;top:8px; width:11px;height:8px;overflow:hidden;cursor:\pointer; background-image:{*arrow.down*};"></span></inlinebox>

Note the following items:

Use simple dot notation when referring to complex fields. For example, to reference theinstance/prototype field, arrow.up, use a variable named {arrow.up}. In general any fieldcan be referenced this way.The and events were defined in the previous exercise when the controllerup down

methods were declared. These methods already existed and were used by othermethods, such as and . Simply referring to these by name (foronkeydown onmousewheel

example, ) makes them callable when a event occurs in the view.onclick="{up}" click

Exercise 3 on Spinner with Up and Down Image Buttons

This example describes how to create the same spinner control as in Exercise 2 on Spinner with using the tag.Up and Down Buttons attach


The use case for this control is exactly the same as for Exercise 2; however, in this exercise theup and down image buttons are generated using the tag.attach


The template for this class requires fewer HTML tags than the previous example to render itsup and down buttons. Instead, it uses the tag to paint the HTML for a specific set ofattach

descendant objects. (Refer to for a list of all statements that you can use inControl Statementsyour template.)

The next figure shows the Component Hierarchy palette in GI Builder and how the spinneruses the children to render its arrows.ImageButton

143


Component Hierarchy with Spinner Controls

The following template can render the above DOM structure.

<inlinebox style="position:{$position};left:{jsxleft}; top:{jsxtop};width:{jsxwidth|60};height:{jsxheight|20};margin:{jsxmargin};border:{jsxborder|solid 1px gray};vertical-align:middle;"> <input type= value= onchange="text" "{jsxvalue}" "{onchange}" onkeydown= onkeyup="{onkeydown}" "{onkeyup}" onmousewheel="{onmousewheel}" style="position:absolute;left:0px;top:0px; width:100%-12px;height:100%;border:{iborder|0px;solid 1px gray;0px;0px;}; font-name:{jsxfontname};font-size:{jsxfontsize};" /> <attach select= >"new jsx3.util.List(this.getChildren()).iterator()" <drawspace boxtype= position="'box'" "'absolute'" top="$$target.getChildIndex() * 8"left= width= height= />"$$parentwidth - 11" "11" "8" </attach></inlinebox>

Every attach tag requires a statement that returns an instance of .select jsx3.util.Iterator

This provides flexibility when deciding which descendant objects should paint. In the aboveexample the statement returns all child objects (these are the two child select ImageButtons

shown in the DOM). No error checking is in place; however, you can implement error checkingto ensure that the control only paints children of type .jsx3.gui.ImageButton

When attaching descendants, you can use a tag to send additional sizing anddrawspace

processing directives to the children. This provides a way for a parent control to force theposition and content of any painted descendants. Although this is not always necessary, it is auseful convenience. All fields on the tag are calculated. This means that stringsdrawspace

should be escaped where appropriate:

boxtype="'box'"

Because all fields are calculated, any valid JavaScript can be used. For example, the top value iscalculated based upon the child index of the target child.

top="$$target.getChildIndex() * 8"

The variable is always available within and tags and points to the$$target attach for-each

144


The variable is always available within and tags and points to the$$target attach for-each

current object in the iteration. In this case, the child at index 0 will render at position 0, the childat position 1 will render at position 8. lists all contextual system variablesContextual Variables(those beginning with ). You can embed these variables within your own code and use them$$

for your own calculations. For example, the variable defines the width of the$$parentwidth

drawspace into which the given HTML tag will paint. In the above markup, it determineswhere to draw the left position of the children:ImageButton

left="$$parentwidth - 11"

Exercise 4 on Editable Grid

This exercise describes how to create an editable grid (similar to a spreadsheet) that allowsvariable number of rows and columns.


The data source for the grid is an XML document in Common Data Format (CDF). Each recordin the CDF document has an associated on-screen row in the grid. The columns are definedusing JSON, which allows you to specify for each column the column label, column width, andCDF attribute to which the column will map.

When users click a cell in the grid, a text input overlays the cell, allowing the grid to be editable.Both before-edit and after-edit model events are exposed, allowing you to intercept, cancel, andmodify user edits as they happen. Navigation is supported with the tab, enter, and arrow keys.The header row is fixed, while the remaining rolls scroll when necessary, both horizontally andvertically. The next figure sows the control.

Editable Grid Control

145


II. Define Common Patterns

The editable grid class takes advantage of the tag. This allows the templatefor-each iterator

to only specify a bare minimum of markup, while generating a variable number of rows andcolumns. Typically, any time you need to create a control that will display repeating lists ofdata (such as tables, pick-lists, or grids), you use a iterator.for-each

For example, assume that the following XHTML markup is in your template:

<table> <tbody> hello<tr><td><text> </text></td></tr> </tbody> </table>

To paint exactly four rows of data, you can implement the following selector query. Note howthe select statement returns an instance of .jsx3.util.Iterator

<table> <tbody> <for-each select= >"jsx3.util.List.wrap([1,2,3,4]).iterator()" hello<tr><td><text> </text></td></tr> </for-each> </tbody> </table>

Although the above selector hard codes the contents of the iterator (such as 1,2,3,4), it iscommon to use a more dynamic approach for your class. For example, if your GUI classimplements the and interfaces (as in this example), the classjsx3.xml.Cacheable jsx3.xml.CDF

has access to common methods such as . This allows you to paint as many rows as yougetXML

have CDF records in the XML document used by the control. For example:

<table> <tbody> <for-each select= >"this.getXML().selectNodeIterator('//record')" hello<tr><td><text> </text></td></tr> </for-each> </tbody> </table>

Beyond simply iterating over a collection of items, the tag also provides a pointer tofor-each

the active item in the iteration: . For example, assume that you not only want to paint a$$target

table row for each record, but you also want to output the value of the attribute:jsxtext

<table> <tbody> <for-each select= >"this.getXML().selectNodeIterator('//record')" $$target.getAttribute('jsxtext')<var id= >"mytext" </var> {mytext}<tr><td><text> </text></td></tr> </for-each> </tbody> </table>

You may need to nest iterators to handle a variable number of both rows andfor-each

146


You may need to nest iterators to handle a variable number of both rows andfor-each

columns. For example, the class used for this exercise has a variable named items that storescolumn profile information in the following JSON format:

this.columns = {}; .columns.items = [{attribute:"jsxid",caption:"ID",width:"25"},this {attribute:"jsxtext",caption:"Name",width:"*"}]

When it is time to paint the component, a corresponding method wraps the array and returnsan iterator.

grid.getIterableColumns = () {function jsx3.util.List.wrap( .columns.items).iterator();return this };

Though useful, nested loops introduce a new challenge in that the variable is$$target

intercepted by the nested (inner) . This means that if the inner loop must access thefor-each

target of the outer loop, you must cache a pointer to the variable before the inner loop$$target

begins. For example, note how a custom variable named is used to do this:myrecord

<table> <tbody> <for-each select= >"this.getXML().selectNodeIterator('//record')" $$target<var id= >"*myrecord*" </var> <tr> <for-each select= >"this.getIterableColumns()" *myrecord*.getAttribute($$target.attribute)<var id= >"mytext"</var> {mytext}<td><text> </text></td> </for-each> </tr> </for-each> </tbody> </table>

III. Optimize the Template

An important feature of the Template class is its ability to optimize developer code. If, forexample, a event occurs in the browser, the Template will automatically adjust the sizeresize

of the control to reflect this change. And if the Template determines that the event didresize

not affect the true size of the painted instance, it will exit early to spare the unnecessaryprocessing time. However, there are times when you, the developer, will know of optimizationsthat the Template class simply cannot handle given that it is a generic tool. For example, thesample class used for this exercise uses a single HTML input in order to make the grid editable.This reduces the amount of HTML needed to create a large, editable grid, since the single inputcan be overlaid on top of a grid cell when it is time to edit.

The Template engine is capable of positioning the single text input when a given cell receivesfocus. The handler for the class locates the position of the cell in relation to the HTML elementthat contains both it and the input mask, using the method :getRelativePosition

var objPos = jsx3.html.getRelativePosition(objDataContainer,objCell);objPos.target = objCell;

When the true position for the cell is determined, the position is cached (along with a few

147


When the true position for the cell is determined, the position is cached (along with a fewadditional values) and the Template engine is notified of the change:

this._setTargetProfile(objPos);

At this point, any template variable that implements the trigger is notified to"beforeedit"

update its cached value. The Template class then automatically applies the updated value toany tag in the template that implements the given variable. For example, consider the followingmodel declarations used by the grid class:

<model> <var id= triggers= >"mask_value" "beforeedit" return this._getTargetProfile().value; </var> <var id= triggers= >"mask_left" "beforeedit" return isNaN(this._getTargetProfile().L)? -100:this._getTargetProfile().L; </var> <var id= triggers= >"mask_top" "beforeedit" return isNaN(this._getTargetProfile().T)? -18 :this._getTargetProfile().T; </var> <var id= triggers= >"mask_width" "beforeedit" return this._getTargetProfile().W || 100; </var> <var id= triggers= >"mask_height" "beforeedit" return this._getTargetProfile().H || 18; </var> <var id= triggers= >"mask_display" "beforeedit afteredit" return this._getTargetProfile().display || ;"none" </var> </model>

When the model variables are updated, the Template class next attempts to apply these updatesto every HTML element that uses one. In this case, the variables , , mask_value mask_left

, , , and are used to update the value, display,mask_top mask_width mask_height mask_display

and position of the single input box.

The following input definition appears in the template for the class:

<input u:id= type= class= {mask_value}""txt_editmask" "text" "" value=" onkeydown= onblur="{onkeydown}" "{onblur}" style="position:absolute;padding:3 0 0 1;background-color:#ffffff; z-index:2;color:blue;left:{mask_left};top:{mask_top}; width:{mask_width};height:{mask_height};font-family:{$fontname}; font-size:{$fontsize};display:{mask_display};border:solid 1px gray;" />

Although the template engine simplifies the act of updating the user interface, it can also beinefficient, because the engine does not know in advance which tags implement whichvariables. When the input mask has been positioned, the engine continues to scan theremainder of the template, in case other HTML elements also use the newly-updated variables.To avoid this, you can tell the engine to exit early when you know that there is no need for it tocontinue scanning the remaining HTML elements. For example, note how the tag tells theif

engine to exit early when there is a flag on the cached profile:

148


<input u:id= type= class= {mask_value}""txt_editmask" "text" "" value=" onkeydown= onblur="{onkeydown}" "{onblur}" style="position:absolute;padding:3 0 0 1;background-color:#ffffff; z-index:2;color:blue;left:{mask_left};top:{mask_top}; width:{mask_width};height:{mask_height};font-family:{$fontname}; font-size:{$fontsize};display:{mask_display};border:solid 1px gray;" /> <if test= >"this._getTargetProfile().target" <return/></if>

The final class definition for the editable grid is as follows:

jsx3.require("jsx3.gui.Template","jsx3.xml.Cacheable","jsx3.xml.CDF");

jsx3.lang.Class.defineClass("my.Grid",jsx3.gui.Template.Block,[jsx3.xml.Cacheable,jsx3.xml.CDF],

(GRID,grid) {function

//init grid.init = (strName) {function .jsxsuper(strName);this };

// defaults grid.columns = {}; grid.columns.items = [{attribute:"jsxtext",caption:"Text",width:"*"}];

// template xml grid.getTemplateXML = () {function ['',return '<transform xmlns="http://gi.tibco.com/transform/"xmlns:u="http://gi.tibco.com/transform/user" version="1.0">' , ' <model>' , ' < id="mask value" triggers="beforeedit"> .var return thisgetTargetProfile().value;</ >' ,var ' < id="mask left" triggers="beforeedit"> isNaN( .var return thisgetTargetProfile().L) ? -100 : . getTargetProfile().L;</ >' ,this var ' < id="mask top" triggers="beforeedit"> isNaN( .var return thisgetTargetProfile().T) ? -18 : . getTargetProfile().T;</ >' ,this var ' < id="mask width" triggers="beforeedit"> . getTargetProfile().Wvar return this|| 100;</ >' ,var ' < id="mask height" triggers="beforeedit"> .var return thisgetTargetProfile().H || 18;</ >' ,var ' < id="mask display" triggers="beforeedit afteredit"> .var return thisgetTargetProfile().display || "none";</ >' ,var ' </model>' , ' <template dom=" ">' ,static ' <inlineboxstyle="position:{$position};left:{$left};top:{$top};width:{$width};height:{$height};margin:{$margin};">', //scrollable data rows ' <div u:id="datarows"style="position:absolute;left:0px;top:20px;width:100%;height:100%-20px;overflow:auto;z-index:1;"onscroll="{onscroll}">', //textbox edit mask ' <input u:id="txt_editmask" type="text" class="" value="{mask_value}"onkeydown="{onkeydown}" onblur="{onblur}" ', ' style="position:absolute;padding:3 0 0

149


1;background-color:#ffffff;z-index:2;color:blue;left:{mask_left};top:{mask_top};width:{mask_width};height:{mask_height};font-family:{$fontname};font-size:{$fontsize};display:{mask_display};border:solid1px gray;" />', //exit the template early the mask is targeting a cell;ifwhen that happens, merely show the mask above and exit early ' < test=" ._getTargetProfile().target">< /></ >' ,if this return if ' <table u: =" " u:id="datarows_table" index="0"protected trueonmousedown="{onmousedown}"style="position:absolute;left:0px;top:0px;width:100%;font-size:{$fontsize};font-family:{$fontname};table-layout:fixed;"cellspacing="0" border="0"><tbody u:id="tb_b" u: =" ">' ,protected true ' < -each select=" .getIterableRecords()">' ,for this ' < id="rowid"> .getId() + \'_\' +var this$$target.getAttribute(\'jsxid\')</ >',var ' < id="rowtarget">$$target</ >',var var ' <tr id="{rowid}" u:id="tr_b" u: =" ">',protected true ' < -each select=" .getIterableColumns()">' ,for this ' < id="celltext">rowtarget.getAttribute($$target.attribute) ||var" "</ >',var ' < id="columnwidth">$$target.width</ >',var var ' <td u:id="td_b" u: =" "protected truestyle="width:{columnwidth};padding:3px;border-right:solid 1pxlightblue;border-bottom:solid 1px lightblue;"><text>{celltext}</text></td>', ' </ -each>',for ' </tr>', ' </ -each>',for ' </tbody></table>', ' </div>', //fixed header row ' <div u:id="header"style="position:absolute;left:0px;top:0px;width:100%;height:20px;border:{myborder|solid1pxgray};z-index:2;background-color:{headerbg};color:{headercolor};overflow:hidden;">', ' <table u: =" " u:id="header_tbl"protected truestyle="position:absolute;left:0px;top:0px;width:100%;font-size:{$fontsize};font-weight:bold;table-layout:fixed;"cellpadding="3" cellspacing="0" border="0"><tbody u:id="tb_h" u: =" ">' ,protected true ' <tr u:id="tr_h" u: =" ">',protected true ' < -each select=" .getIterableColumns()">' ,for this ' < id="headertext">$$target.caption</ >',var var ' < id="columnwidth">$$target.width</ >',var var ' <td u:id="td_h" u: =" "protected truestyle="width:{columnwidth};white-space:nowrap;text-align:center;">', ' <text>{headertext}</text>', ' </td>', ' </ -each>',for ' </tr>', ' </tbody></table>', ' </div>', ' </inlinebox>' , ' </template>' , '</transform>'].join(""); };

// 6) define the CONTROLLER functions grid.onmousedown = (objEvent,objGUI) {function this.onbeforeedit(objEvent,objEvent.srcElement().parentNode,objEvent.srcElement()); };

150


grid.onscroll = (objEvent,objGUI) {function //called when the data rows are scrolled .getRenderedBox("header_tbl").style.left = -objGUI.scrollLeft + "px";this };

grid.onblur = (objEvent,objGUI) {function //handle the primitive event (onblur) the prototype (instance) eventwith .onafteredit(objEvent,objGUI);this };

grid.onkeydown = (objEvent,objGUI) {function objCell = ._getTargetProfile().target;var this intCellIndex = objCell.cellIndexvar objRow;var

((objEvent.enterKey() && !objEvent.shiftKey()) || objEvent.downArrow()) {if //commit the value; advance edit to the next cell down .onafteredit(objEvent,objGUI);this

// the current row isn't the last row, apply edit mask to the next row downif objRow = (objCell.parentNode != objCell.parentNode.parentNode.lastChild) ? objCell.parentNode.nextSibling : objCell.parentNode.parentNode.firstChild; } (objEvent.upArrow() || (objEvent.enterKey() && objEvent.shiftKey())) {else if //commit the value; advance edit to the next cell up .onafteredit(objEvent,objGUI);this

// the current row isn't the first row, apply edit mask to the next row up;if objRow = (objCell.parentNode != objCell.parentNode.parentNode.firstChild) ? objCell.parentNode.previousSibling : objCell.parentNode.parentNode.lastChild; } (objEvent.rightArrow()) {else if //commit the value; advance edit to the next cell down .onafteredit(objEvent,objGUI);this objRow = objCell.parentNode;var intCellIndex = objRow.lastChild == objCell ? 0 : intCellIndex+1; } (objEvent.leftArrow()) {else if //commit the value; advance edit to the next cell up .onafteredit(objEvent,objGUI);this objRow = objCell.parentNode;var intCellIndex = objRow.firstChild==objCell ?objRow.lastChild.cellIndex : intCellIndex-1; }

//begin the edit session the target cellfor (objRow)if .onbeforeedit(objEvent,objRow,objRow.childNodes[intCellIndex]);this };

grid._getTargetProfile = () {function //when an edit event happens, a target profile is created that describes thecontext ._jsxtargetprofile || {};return this };

grid._setTargetProfile = (objP) {function //when an edit event happens, a target profile is created that describes the

151


context ._jsxtargetprofile = objP;this };

grid.onbeforeedit = (objEvent,objRow,objCell) {function //use a sleep delay to stop repeated clicks and key strokes from taxingperformance jsx3.sleep( () {function ._onbeforeedit(objEvent,objRow,objRow.childNodes[objCell.cellIndex]);this },"my.GRID", );this };

grid._onbeforeedit = (objEvent,objRow,objCell) {function //get the id the row that was clickedfor strCdfId = objRow.getAttribute("id").substr( .getId().length+1);var this strAttName = .columns.items[objCell.cellIndex].attribute;var this strValue = .getRecordNode(strCdfId).getAttribute(strAttName);var this

//allow the before-edit event to be cancelled objReturn = .doEvent(jsx3.gui.Interactive.BEFORE_EDIT,var this {objEVENT:objEvent,strID:strCdfId,objCELL:objCell,strVALUE:strValue}); (objReturn !== ) {if false //determine information about the target cell being edited (left, top, etc) objThis = .getRendered(objRow);var this objDataContainer = .getRenderedBox("datarows",objThis);var this objMask = .getRenderedBox("txt_editmask",objThis);var this

//query the system the location of the target table cellfor objPos = jsx3.html.getRelativePosition(objDataContainer,objCell);var //when running on firefox, builds earlier than 3.6.1 have a bug (!(jsx3.getVersion() < "3.6.1" && /fx/.test(jsx3.CLASS_LOADER.getType()))) {if objPos.L = objPos.L + objDataContainer.scrollLeft; objPos.T = objPos.T + objDataContainer.scrollTop; }

objPos.value = strValue || ""; objPos.display = "block"; objPos.target = objCell; objPos.id = strCdfId; objPos.attribute = strAttName;

//cache the information about the target ._setTargetProfile(objPos);this .syncProperty("beforeedit", );this true //give cursor focus to the edit mask (the text input) objMask.focus(); } };

grid.onafteredit = (objEvent,objGUI) {function //get the profile object objP = ._getTargetProfile();var this

//get the value entered by the usernew objReturn;var

152


(objP.value != objGUI.value) {if //allow the edit to be cancelled/modified objReturn = .doEvent(jsx3.gui.Interactive.AFTER_EDIT,this {objEVENT:objEvent,strID:objP.id,objCELL:objP.target, strVALUE:objGUI.value}); (objReturn !== ) {if false //update the data model .insertRecordProperty(objP.id,objP.attribute,objGUI.value, );this false

//update the view objP.target.innerHTML = jsx3.util.strEmpty(objGUI.value) ? " " : objGUI.value; } }

//reset the mask (hide it) ._setTargetProfile({value:""});this .syncProperty("afteredit", );this true

//fire the commit event (not cancellable)final (objReturn !== )if false .doEvent(jsx3.gui.Interactive.AFTER_COMMIT,this {objEVENT:objEvent,strID:objP.id,objCELL:objP.target, strVALUE:\(objReturn != && objReturn.strVALUE ?null objReturn.strVALUE : objGUI.value)}); };

grid.setColumns = (arrColumns) {function //call to change the columns to render the table. The schema is as follows.:for .columns.items = arrColumns;this //the GI serializer only saves scalar types .encodeColumns(arrColumns);this .repaint();this };

grid._getColumns = (arrColumns) {function ._columns || "";return this };

grid.encodeColumns = (arrColumns) {function //serialize the columns array as a string so the GI class serializer a = ;var ( i=0;i<arrColumns.length;i++) {for var cur = arrColumns[i];var a.push("{attribute:\"" + cur.attribute + "\",caption:" + jsx3.util.strEscapeJSON(cur.caption) + ",width:\"" + cur.width + "\"}"); } ._columns = "[" + a.join(",") + "]";this };

grid.onAfterAssemble = () {function //when a serialized object is restored GI (deserialized), method isin thiscalled; (!jsx3.util.strEmpty( ._columns))if this .columns.items = jsx3.eval( ._columns);this this };

153


grid.getIterableRecords = () {function objCDF = .getXML();var this objCDF ? objCDF.selectNodeIterator("//record") :return ( jsx3.util.List()).iterator();new };

grid.getIterableColumns = () {function jsx3.util.List( .columns.items.length ?return new this .columns.items : ).iterator();this

154


};

});

155


Chapter 14 Forms in General Interface

This chapter provides an introduction to forms in General Interface.

Native HTML FormsForm Element ControlsForm Properties

Native HTML Forms

The following options are supported to integrate your General Interface application withservices that expect submissions via HTML forms:

jsx3.net.Form - This is a completely programmatic implementation of an HTML form.This class does not support file upload in Firefox due to a browser limitation.jsx3.gui.NativeForm - This is a GI DOM implementation of an HTML form and sogenerally requires less JavaScript code than . This class supports filejsx3.net.Form

upload (via POST) on all browsers.

jsx3.gui.NativeForm extends so that it is part of the GI DOM. It is included injsx3.app.Model

the Component Libraries palette (under Form Elements), and you can drag and drop it intoyour General Interface component. As with a native HTML form, form fields that are DOMchildren of a become part of that form. When the form is submitted, alljsx3.gui.NativeForm

constituent fields are submitted with the form. The renders as a element inNativeForm <form>

HTML and most functionality is provided by the native browser implementation.

Form Element Controls

The following element controls are compatible with :NativeForm

jsx3.gui.TextBox (Text Box, Text Area, Number Input, and Password)jsx3.gui.NativeSelect - Note that is not compatible with .jsx3.gui.Select NativeForm

jsx3.gui.FileUpload

jsx3.gui.NativeHidden - Use this control to submit values that do not have a visualrepresentation.jsx3.NativeButton - You can use a to submit a form by writing anjsx3.gui.Button

event handler on the button. However, only a can submit a CGI parameter.NativeButton

jsx3.gui.RadioButton

jsx3.gui.CheckBox

jsx3.gui.DatePicker - The text displayed in the date picker is the value submitted withthe form.

In each case, except , the name of the submitted form field (CGI parameter) is equalRadioButton

to the Name property of the GI object. In the case of , the form field is the GroupRadioButton

Name property and only one value is submitted for all radio buttons that share the same GroupName.

156


Form Properties

The following properties of control how the form is submitted:NativeForm

Method (GET or POST). MultipartActionTargetTarget IFrame

The Method property must be POST and Multipart must be true if your form includes a fileupload field.

The property is the URL of the service to which to submit the form. This can be anActionabsolute or a relative URL. If it is relative, then the URL is resolved relative to the applicationdirectory ( ).jsx3.app.Server.resolveURI()

Do not ignore cross domain issues. You can submit to another domain/schema/port,however, you will only be able to read the response from the submission if the URLscheme, domain, and port are exactly the same as the URL of the page hosting theGeneral Interface application.

The Target and Target IFrame properties control where the response from the submission isdisplayed. In most cases it is best to submit the form invisibly and process the responseprogramatically. In this case, set Target to Invisible IFRAME. You can also have the responserender in a native pop-up window (Target = New Window) or have it replace the page hostingthe GI application (Target = Current Window). Using the Target IFrame property you can havethe response render in an instance of .jsx3.gui.IFrame

The following components can aid in creating accessible HTML forms.

jsx3.gui.Label - renders a native element. In HTML forms a label is associated<label>

with a form field. Set the For Control property of the label to the name of a GI form fieldto associate it with that field. Using labels helps screen readers and other accessibilitysoftware make better sense of the form.<fieldset>, and through (all instances of ) - add<legend> <h1> <h6> jsx3.gui.Block

semantic meaning to form layout and elements that can improve accessibility.

The following figure shows a form being built in General Interface Builder.

157


Here is the source code for the form displayed above: form.xml

http://www.generalinterface.org/docs/download/attachments/6685707/form.xml?version=1&modificationDate=1265062420000

158


Appendix A System Resolvers

System resolvers help simplify authoring HTML templates by obviating the need to declarelocal variables. The following table describes the system resolvers, the instance property towhich they map, and relevant triggers.

159


System Resolvers

Name Type Description Trigger

$id attribute Renders the field as .jsxid id="{$id}"

Always applied to the root node in thetemplate regardless of developer choice.This ensures that the model and vieware always synchronized.

$label attribute Renders the field as jsxname

label="{$label}"

jsxname

$position box Renders the jsxrelativeposition field as position:{$position};

jsxrelativeposition

$left box Renders the field as jsxleft

when the position isleft:{$left};

absolute and when specified

jsxleft

$top box Renders the field as } ;jsxtop top:{$top

when the position is absolute and whenspecified

jsxtop

$width box Renders the field as jsxwidth

}width:{$width

jsxwidth

$height box Renders the field as jsxheight

}height:{$height

jsxheight

$zindex css Renders the field as jsxzindex

}z-index:{$zindex

jsxzindex

$color css Renders the field as jsxcolor

}color:{$color

jsxcolor

$fontname css Renders the field as jsxfontname

}font-family:{$fontname

jsxfontname

$fontsize css Renders the field as jsxfontsize

}font-size:{$fontsize

jsxfontsize

$fontweight css Renders the field as jsxfontweight

}font-weight:{$fontweight

jsxfontweight

$display css Renders the field as jsxdisplay

}display:{$display

jsxdisplay

$visibility css Renders the field as jsxvisibility

}visibility:{$visibility

jsxvisibility

$style-group box Renders the value of the field at the end of thejsxstyleoverride

existing style declaration. This providesa mechanism for injecting multiplestyles into a single tag.

jsxstyleoverride

160


$classname attribute Renders the field as jsxclassname

. If the given classclass="{$classname}"

has a static field named , the value of this fieldDEFAULTCLASSNAME

will be appended, meaning a class like . that implements a jsx3.gui Block

property with the value, jsxclassname

, would render as "customstyle"

class="jsx30block customstyle"

jsxclassname

$bgcolor css Renders the value of the jsxbgcolorfield as background-color:{$bgcolor};

jsxbgcolor

$bg css Renders the value of the field as jsxbg

background:{$bg};

jsxbgcolor jsxbg

$padding box Renders the value of the jsxpaddingfield as padding:{$padding};

jsxpadding

$margin box Renders the value of the fieldjsxmargin

as margin:{$margin};jsxmargin

$border box Renders the value of the fieldjsxborder

as border:{$border};jsxborder

$textalign css Renders the value of the jsxtextalignfield as text-align:{$textalign};

jsxtextalign

$overflow css Renders the value of the jsxoverflowfield as overflow:{$overflow};

jsxoverflow

$attribute-group box Similar to , this resolver$style-group

allows a list of attributes to be injectedinto a given tag. This is a special type ofresolver that must be declared as a childof the target HTML node, since it affectsthe attribute list for the node. Forexample,

<div value="12" style= >"color:red;" <attribute-group> {$attribute-group} </attribute-group></div>

Any attribute on a General Interfaceobject, using the API, willsetAttribute

be reflected by this resolver.

161


$tagname box Allows the HTML tag name to beupdated. This is a special type ofresolver that must be declared as a childof the target HTML node, since it affectsthe tag name of the given node. Forexample,

<span style= >"color:red;" <tagname> {$tagname} </tagname></span>

jsxtagname

$text box Renders the value of the jsxtext field as atext node child of the given HTML node.This is a special type of resolver thatmust be contained by a node.<text/>

For example,

<span style= >"color:red;" {$text}<text> </text></span>

jsxtext

$index attribute Renders the value of the fieldjsxindex

as . If this field hastabindex="{$index}"

no value, the default (0) will be used

jsxindex

$tip attribute Renders the value of the field as jsxtip

.title="{$tip}"

jsxtip

$disabled attribute Renders the value of the jsxenabledfield as .disabled="{$disabled}"

jsxenabled

$onblur event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onchange event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onclick event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$ondblclick event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onfocus event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

162


$onkeydown event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onkeypress event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onkeyup event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onmousedown event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onmousemove event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onmouseout event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onmouseover event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onmouseup event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

$onmousewheel event Renders the given event listener on theHTML tag if the control is not set to jsxenabled = false;

jsxenabled

163


Appendix B Control Statements

When authoring a template, you use a combination of HTML and control statements to helpwith conditional processing ( and ). You can use any HTML node such as spanfor-each if-else

or div where noted below. Any node not listed by name in the table is assumed to be an HTMLnode that should be painted.

164


Control Statements

Node Name Can be a Parent of Description

transform model | template |

@xmlns | @xmlns:u |

version

The root node for the template. Declare asfollows (the namespace declarations must beincluded, but are removed in some of the usageexamples for readability):

<transform xmlns= "http://gi.tibco.com/transform/"

=xmlns:u "http://gi.tibco.com/transform/user"version= >"1.0" </transform>

@xmlns [http://gi.tibco.com/]

transform/

This is the namespace declaration for thetemplate. All element nodes within the templatebelong to this namespace.

@xmlns:u [http://gi.tibco.com/]

transform/user

Use to add custom attributes to a given HTMLtag in your template without having the givenattribute render to the view.

version 1.0 This is the template version. General Interfacerelease 3.6 supports version 1.0.

model var | import Contains all locally declared variables (resolvers)used by the template when painting. It isunnecessary to declare this tag if you do notneed any special formatting for your template.

165


var

[parent

::model]

#text | @id | @name |

@type | @triggers |

@defaultvalue

Declares a variable resolver in the model.Although it is often easier to implicitly defineresolvers by simply using them within thetemplate, it is sometimes useful to explicitlydeclare them in the model in order to retain fullcontrol over how the given resolver is run. Forexample:

<transform> <model> <var id="mycolor" name="background-color" type="css" triggers="jsxcolor" defaultvalue= >"red" return this.jsxcolor; </var> </model> <template> <span style=" background-color: {mycolor};"> whirled peas<text> </text> </span> </template></transform>

@id #text This is the ID for the variable. It should beunique for the template. It should not begin witha , because the system owns this prefix to$

identify its own variable resolvers.

166


var

[parent

::model]/

@name

#text The name attribute is used when the variable isrendered as final HTML. For css and box typevariables, this is the CSS property name. Forattributes and events, this is the attribute orevent name. For example, this structure

<transform> <model> <var id="mycolor" name="background-color" type="css" triggers="jsxcolor" defaultvalue= >"red" return this.jsxcolor; </var> </model> <template> <span style=" background-color: {mycolor};"> whirled peas<text> </text></span> </template></transform>

generates this HTML:

<span style= >" background-color:red;" whirled peas</span>

167


var

[parent

::model]/

@type

box | attribute |

event | css (default)

The variable type lets the template engine knowhow a given variable should be projected intothe view. For example, to add a src attribute toan img tag, declare its type as attribute:

<transform> <model> <var id= name="url" "src" type="attribute" triggers= >"url" return this.url; </var> </model> <template> <img src= />"{url};" </template></transform>

The template engine also allows for implicitvariable declarations by simply using a variableinline. For example, the following syntax isexactly equivalent to the explicit declarationabove:

<transform> <template> <img src= />"{url};" </template></transform>

var

[parent::

model]/

@triggers

#text Template variables can implement a triggersfield to let the template engine know whichupdates to the model should trigger changes inthe view. For example, when updating the urlproperty on a GUI object ( ), athis.url = 'x'

controller function can call . ThissetProperty

compound method first updates the model withthe new value and then triggers an update to theview to ensure that the model and view remainsynchronized.

function setURL(strURL) { .setProperty("url", strURL);this}

Given the method call above, the followingtemplate would be triggered to update the urlvariable. The tag would then be updated toimg

reflect the new value .url on-screen

168


<transform> <model> <var id= name="url" "src" type="attribute" triggers= >"url" return this.url; </var> </model> <template> <img src= />"{url};" </template></transform>

The triggering system is many-to-many. ANote:single template variable can implement multipletriggers and a single trigger can be applied tomultiple variables. For example, in the followingtemplate both variables are updated when the

trigger is fired, because both implement the url

trigger.url

<transform> <model> <var id= name="url" "src" type="attribute" triggers="url triggera tribbgerb"> return this.url;</var> <var id= name="fullurl" "path" type="attribute" triggers= >"url" return this.fullurl;</var> </model> <template><img src="{url};" path= />"{fullurl}" | </transform> </template>

169


var

[parent::

model]/

@defaultvalue

#text <<Is this fixed?>> The field is useddefaultvalue

to assign a variable default when its resolverfunction returns null. Therefore, the followingtwo variable declarations are equivalent:

<var id= name="url" "src" type= >"attribute" return this.url != null ? this.url : ;"abc.gif" </var>

or

<var id= name="url" "src" type="attribute" defaultvlaue= >"abc.gif" return this.url; </var>

Default values can also be implicitly declaredinline within the body of the template using apipe character (|). Therefore, the followingimplicit declaration is equivalent to the twoexplicit declarations above:

<img src= />"{url|abc.gif}"

If no field is used and the resolverdefaultvalue

function returns null, it will result in the givenproperty being removed from the object whenpainted, while an empty string results in anempty value. For example, a variable named

that returns null (and with no 'src'

field) would result in the followingdefaultvalue

HTML:

<img/>

While an empty string wouldbe expressed as follows:

<img src=""/>

170


inlinebox HTML | for-each |

attach | var |

drawspace | if |

if-else | left | top |

width | height |

position | border |

padding | margin |

text | empty |

attribute-group |

style-group | @u:id

The tag is an HTML span tag with ainlinebox

CSS display property appropriate to the targetbrowser environment. Using this tag allows aGUI control to have layout (width and height)even if it is relatively positioned or flowed inlinewith text. This enables the control to bepositioned either relatively or absolutely withouthaving cross browser differences corrupt thelayout. Use this tag instead of an HTML span ifyou anticipate needing to flow the object inlinewith other text while retaining its width andheight.

import @resolver | @set |

@library

This allows for re-use of common resolvers andis used to import variable resolvers declared andused by other widget libraries and classes. . Forexample, the following statement imports thevariable resolver named :$color

<import resolver= />"$color"

Variable resolvers can belong to a namespace. Ifyou create a variable named and the"color"

resolver belongs to the class my.Spinner, thenanother class can import the variable resolver byusing the following declaration:

<import resolver="color" set= />"my.Spinner"

To import every resolver from another class,pass the name of the class as the library name:

<import library= />"my.Spinner"

System resolvers (those beginning with ) do"$"

not need to be imported. This means that simplyusing a system resolver is the appropriate wayto declare its import. For example, note how the

resolver must be explicitly imported fromurl

the class named , while the systemmy.Spinner

resolver, , does not:$position

<transform> <model> <import resolver="color" set= />"my.Spinner" </model <template> <img src="{url};" style="position: {$position}"/> </template></transform>

171


template HTML | @onbeforeinit |

@oninit |

@onbeforepaint |

@onpaint |

@onbeforeresize |

@onresize |

@onbeforeresizechild

| @dom | @recalc

Contains the HTML template

@onbeforeinit text/javascript Called immediately before the template profile iscreated for a given GUI widget. The templateprofile is a list of variables that are merged withthe template to render the final HTML.

@oninit text/javascript Called immediately after the templates profile iscreated

@onbeforepaint text/javascript Called immediately before paint. If this methodreturns an alternate string of text/HTML, thecontrol will not attempt to paint and will insteaduse the provided string.

@onpaint text/javascript Called after the HTML has been painted andrendered by the browser. Called in a separatecall stack from the paint method.

@onbeforeresize text/javascript Called immediately before a event.resize

Return a Boolean false to cancel the resize for thecontrol.

@onresize text/javascript Called immediately after a event. Theresize

object's dimensions will have been updated inboth the model and view, but its descendantobjects may not have been resized yet.

@onbeforeresize

child

text/javascript Called immediately before a child is resized. Themethod will be passed one parameter: areference to the child about to be resized. Returna Boolean False to cancel the resize for the child.

@recalc true|false (default) Called immediately after the HTML has beenpainted and rendered by the browser, causingthe resize engine to apply any dynamic positioncalculations to the painted control. Use thisfeature in your template if you declare any <var>elements within the section that<template>

affect box properties like left, top, width,padding, border, etc.

172


@dom dynamic | static

(default)

Some templates result in different HTMLoutput. For example, a template with if/elseconditional statements, may create an on-screenDOM that differs each time it is rendered. Insuch a situation, specify that the HTML contentis dynamic and therefore must be located usingnamed IDs. In other words when the DOM isdynamic, then each HTML node in the templateneeds a corresponding unique ID, using the usernamespace. For example:

<template dom = >"dynamic" <span u:id= >"someid" <if-else> <if test= >"isInput()" <input u:id="myinput" value="{mytext}" type= />"text" </if> <else> <span u:id= >"myspan" {mytext}<text> </text></span> </else> </if-else> </span></template>

If your template uses a for-each iterator, itNote:must use a static DOM.

173


var

[ancestor::

template]

text/javascript | @id Declares a local variable within the body of thetemplate. This allows a given variable to bedynamically updated during execution. Forexample:

<for-each select= >"this.getMyRows()" <var id= >"rowid" $$target.getAttribute(\'jsxid\') </var> <var id= >"rtext" $$target.getAttribute(\'jsxtext\') </var> <div id= >"{rowid}" {rtext}<text> </text> </div></for-each>

declarations in the body of the templatevar

execute differently than declarations madevar

within the model. This means that a variable thatreturns the color would be declared like this,red

if declared within the model:

<transform> <model> return <var id= >"abc" "red" </var> </model> <template> {abc}<span><text> </text> </span> </template></transform>

However, when declared within the template, alocal variable declaration will not be stored as aglobal function, and therefore should not use areturn statement:

<transform> <template> <var id= >"abc" "red"</var> <span> {abc}<text> </text> </span> </template></transform>

174


HTML HTML | for-each |

attach | var |

drawspace | if |

if-else | left | top |

width | height |

position | border |

padding | margin |

text | empty |

attribute-group |

style-group | @u:id |

@u:\protected

Any valid HTML tag can be used in a template.All attributes on the tag will be rendered on thetag except for those belonging to the

namespace.http://gi.tibco.com/transform/user<<What should this URL be changed to?>>

@u:\protected true Use on an HTML tag to denote that itsdimensions should not be managed by theGeneral Interface layout engine. The tag can stilluse the replacement variable engine, but itslayouts will be unaffected. For example, thefollowing template:

<input u:\protected="true" style="width:100%;height:100%; color:{mycolor};"/>

results in the following HTML when painted

<input style="width:100%; height:100%;color:red;"/>

However, if the attribute had notu:\protected

been used, the layout engine would havereplaced the percentages with absolute pixelvalues to reflect the dimensions allowed by thecontaining HTML tag. For example,:

<input style="width:80px; height:235px;color:red;"/>

http://gi.tibco.com/transform/user

175


left text/javascript Can be used to specify the left position of anHTML node. For example:

<span style= >"position:absolute;" $$parentwidth - 10<left> </left></span>

The syntax above is not required, but canNote:be used for greater control over layout, since itaccepts any valid JavaScript statement.However, it generally more common to simplydeclare the style inline and have the systemautomatically handle the calculation. Forexample, note how the CSS accepts thecalculated value, 100% - 10:

<span style="position:absolute; left:100%-10px;"></span>

Replacement variables can be used in bothsituations. Whether expanded:

<span style= >"position:absolute;" {$left}<left> </left></span>

or inline:

<span style="position:absolute; left:{$left};"></span>

Two custom style properties are also providedfor convenience when doing calculations: rightand bottom. These simplify left and topdeclarations that use calculations. For example,the following two style declarations areequivalent:

<span style="position:absolute; *right:10px;*"></span>

or

<span style="position:absolute; *left:100%-10px;*"></span>

top text/javascript See the description for left.

width text/javascript See the description for left.

height text/javascript See the description for left.

176


position absolute | relative

(default)

Can be used to specify the relative/absoluteposition of an HTML node. For example:

<input style= >"color:blue;" relative<position> </position></input>

The template engine does not require theexpanded syntax, but can be used for greatercontrol over layout, since it accepts any validJavaScript statement. However, it is generallymore common to simply declare the style inlineand have the system automatically handle thecalculation. For example:

<input style="position:relative; color:blue"/>

Replacement variables can be used in bothsituations. Whether expanded:

<input style= >"color:blue;" {$position}<position> </position></input>

or inline:

<input style="position:{$position}; color:blue;"/>

Unlike the calculated fields, , , , andleft top width

, this field is treated as a string, assumingheight

the value is either relative, absolute, or the valueof a given replacement variable. Only relativeand absolute are accepted as values by thelayout engine; however, the variablereplacement engine accepts any value. Forexample, note how the type attribute is declaredas (not box) and the specific node is specifiedcss

as protected ( :u:\protected)

<transform> <model> <var id= type="myposition" "css" name= >return ;"position" "fixed" </var> </model> <template> <div u:\protected="true" style= >"position:{myposition};" {abc}<text> </text> </div> </template></transform>

177


empty true Use when a given node should render as anempty node. Note that , , and nodesimg br input

are automatically tagged and need not specifythis value. For example:

<input type= >"text" true<empty> </empty></input>

will render as:

<input type= />"text"

attribute-group #text Use to inject a group of attributes (that is, ) into an HTML node insrc="a.gif" width="1"

the template. For example:

<img> <attribute-group> {myAttListVar}</attribute-group></img>will render as:<img src= width= />"a.gif" "1"

style-group #text Similar to attribute-group. Use to inject a groupof CSS styles (that is,

) into an HTMLcolor:blue;font-weight:bold;

node in the template. Consider the expandedsyntax:

<img> {someVarWithStyles}<style-group> </style-group></img>

And the inline syntax:

<img style="font-size:10px; style-group:{someVarWithStyles};"/>

This is how the tag renders:

<img style=" font-size:10px; color:blue;font-weight:bold ;"/>

178


border #text See the description for position. The value forthis node is best expressed in the simplifiedGeneral Interface notation, using the pattern,

, as the four compass"style-width-color"

positions are defined for the border, beginningwith north. For example:

<span> solid 1px red;<border> dashed 2px red;0px; solid 1px red;</border></span>

Note that when using a replacement variable forthe border, it is easier to simply declare it inline:

<span style= >"border:{$border};"</span>

Due to the way that the template engine parsesstyles, you should NOT specify complex borderdeclarations or CSS border variants such as

and inline, as in theborder-top border-color

following example:

<span style="border:0px; solid 1px gray; 0px;0px;"/>

However, you can implicitly define a variable asa way to inline a complex style. Note that thepipe character ( |) is used to separate the namedvariable from its default value (the value to useif the given variable returns null). By wrappingthe complex border declaration within avariable, the template engine will parse thevalues correctly. The variable name in such casesis unimportant and need only be unique amongother variables declared in the template.

<span style="border: {myborder|0px; solid 1px gray;0px;0px;};"></span>

179


padding #text See the descriptions for position and border.Also note that the value for this node is bestexpressed in the simplified General Interfacenotation, using implied pixel units. For example,to specify 8 pixel padding, use 8. To specify eachside individually, use the four compass positionsstarting at north and moving clockwise. Forexample:

<span> 8 2 2 8<padding> </padding></span>

Or inline:

<span style="padding:8 2 2 8;"</span>

CSS syntax can be used inline, but it must usepixels and it must not use any padding variantssuch as . Forpadding-top and padding-left

example:

<span style= >"padding:8px;"</span>

margin #text See the description for padding.

tagname #text See the description for position. Use todynamically replace the tagname for a givenHTML node. For example, if a given nodeshould render as a DIV or a SPAN, use thefollowing to allow this property to be dynamic,using a replacement variable:

<span> {$tagname}<tagname> </tagname></span>

text #text Use to wrap any text content in your template.All text content must come first before anydescendant nodes and must be wrapped in asingle text tag. For example, this templatestructure:

<span> Hello world<text> </text></span>

renders as the following HTML:

<span>Hello world</span>

180


for-each HTML| var | for-each |

drawspace | if |

if-else | @select

Use to add an iterator to the template. Forexample, assume the given template shouldoutput a table row for each CDF record in itscached XML document:

<table> <tbody> <for-each select= >"this.getIterableRecords()" <var id= >"myid" $$target.getAttribute( )"jsxid" </var> <var id= >"mytext" $$target.getAttribute( )"jsxtext" </var> <tr id="{myid}> <td><text> {mytext} </text></td> </tr> </for-each> </tbody></table>

Note that the select statement must return aninstance of . For example,jsx3.util.Iterator

the method (a controllergetIterableRecords

method) can be expressed as follows:

widget.getIterableRecords = () {function objCDF = .getXML();var this objCDF ?return objCDF.selectNodeIterator ("//record") : ( jsx3.util.List()).new iterator();};

181


attach drawspace | @select Use to attach descendant content. Similar to afor-each iterator, the select statement expects aninstance of . The contextjsx3.util.Iterator

variable, is available within the attach$$target

tag, meaning any variable declaration can accessthe current item in the iterator by using it. Forexample:

<div> <attach select= "(new jsx3.util.List( this.getChildren())). iterator()"> <drawspace top= "$$target.getChildIndex()*8" /> </attach>

</div>

drawspace @parentwidth |

@parentheight | @left

|@top | @width |

@height | @position

Use to modify the drawspace. A drawspace tagcan either be a child of an attach tag (as a way tomodify the default drawspace that would besent to a given child). The drawspace tag canalso be used. See attach and @left for usageexamples.

182


continue Use inside of a conditional tag ( ) toif/if-else

skip execution of a given iteration. For example,the following skips a iterationfor-each

whenever the given target (a CDF record) doesnot implement a attribute.jsxid

<table> <tbody> <for-each select= >"this.getIterableRecords()" <var id= >"myid" $$target.getAttribute( )"jsxid" </var> <if test= >"jsx3.util.strEmpty(myid)" <continue/> </if> <var id= >"mytext" $$target. getAttribute( )"jsxtext" </var> <tr id="{myid}> <td> {mytext}<text> </text> </td> </tr> </for-each> </tbody></table>

break Similar to continue, except that the entire loop isexited early, not just the iteration.

183


return Similar to break and continue, except that thefunction is completely exited. Useful forintercepting normal processing of a templateand exiting early for improved runtimeperformance. A local variable, , defines theMODE

mode the template is being run in. This variablecan be queried at any time to know which actionis being invoked by the template engine:

paint, update, create,dimension, and paintchild

For example, you can abort the event forupdate

your template (assuming you know that there isno reason to continue resizing descendantobjects):

<if test="MODE=='update' && someCondition()"> <return/></if>

if-else if | else Use to wrap a complex conditional (choice). Forexample:

<if-else> <if test= >"somevalue == 1" a<span><text> </text></span> </if> <if test= >"somevalue == 2" b<span><text> </text></span> </if> <else> c<span><text> </text></span> </else></if-else>

if HTML | break |

continue | var |

for-each | attach |

drawspace | if |

if-else | return |

@test

Use to wrap a simple condition. For example:

<if test= >"$$target==false" <break/></if>

else HTML | break |

continue | var |

for-each | attach |

drawspace | if |

if-else | return

See the description for .if-else

184


@parentwidth text/javascript Sets the parentwidth on the drawspace. Thevalue is calculated and accepts any validJavaScript. For example, to tell all children thattheir allowed drawspace is exactly 100 pixelswide, use the following:

<div><attach select= "(new jsx3.util.List (this.getChildren())) .iterator()"> <drawspace parentwidth= />"100" </attach></div>

@parentheight text/javascript See the description for @parentwidth.

@left text/javascript The attributes, left, top, width, height, border,margin, position, and padding, can be set on adrawspace node to force the next HTML nodeinto a particular position, regardless of itssetting. For example, the following SPAN will beplaced at left position 12, even though itspecifies that it render at position 10:

<div style="width:100%; height:100%;"> <drawspace left= />"12" <span style= >"left:10px;" </span></div>

@top text/javascript See the description for @left.

@width text/javascript See the description for @left.

@height text/javascript See the description for @left.

@border text/javascript See the description for @left. In the followingexample, note how the border is wrapped inapostrophes, because it is a string:

<div> <attach select= "(new jsx3.util.List (this.getChildren())) .iterator()"> <drawspace border= />"'solid 1px gray'" </attach></div>

@margin text/javascript See the description for @left.

@position text/javascript See the description for @left.

185


@padding text/javascript See the description for @left.

@padding text/javascript See the description for @left.

186


Appendix C Contextual Variables

The system provides contextual variables to give additional information that is available onlywhen the template is run. For example, because the system manages layouts, the drawspacechanges (decreases) as each nested tag claims its dimensions. In this example, the

field is used to define how much width is available to render within. Each$$parentwidth

variable listed in the table is available within the section. This means if you declare<template/>

a variable ( ) or drawspace ( ), you can use this value in your calculations.<var/> <drawspace/>

187


Contextual Variables

Name Description Sample Use

$$parentwidth provides the width of thecontaining drawspace

Force the next HTML tag to be rendered to behalf as small as the available width:

<drawspace width= />"$$parentwidth * .5"

$$parentheight provides the height of thecontaining drawspace

Render the HTML tag10 pixels from thebottom of its container:

<span style= >"position:absolute;" $$parentheight - 10<top> </top><span>

The syntax above is not required, but you canuse it for greater control over layout. It is morecommon to simply declare the style inline andhave the system automatically handle it, as inthe following example:

<span style=>"position:absolute;top:100%-10;"

</span>

188


$$target provides a pointer to theactive element within agiven for-each or attachiteration. If nested loops areused within the template, itis possible to cache thisvalue to avoid collisions

Loop through each CDF record and render adiv for each one. Use the jsxid from eachrecord in the iteration to generate the id foreach div and the field for the div textjsxtext

content:

<for-each select= >"this.getMyRows()" <var id= >"rowid" $$target.getAttribute(\'jsxid\') </var> <var id= >"rowtext" $$target.getAttribute(\'jsxtext\') </var> <div id= >"{rowid}" {rowtext}<text> </text></div></for-each>

A locally declared variable can be used tocache the when doing nested$$target

iterations:

<for-each select= >"this. getMyRows()" <var id= >"rowid" $$target.getAttribute(\'jsxid\') </var> <var id= >"mytarget" $$target</var> <div id= >"{rowid}" <for-each select= >"this. getMyCols()" <var id= >"rowtext" mytarget.getAttribute(\'jsxtext\') </var> {rowtext}<text> </text> </for-each> </div></for-each>

Documents

title component guide - TIBCO Software General Interface - Enterprise Edition Component Guide Software Release 3.9.1 April 2012