template gui classes

8/8/2019 Template Gui Classes

1/54

TIBCO General Interface GUI Classes

Creating GUI Classes in TIBCO General Interface | 1

Creating GUI Classes in TIBCO General

Interface

This documen t describes and p resents examples on how to create GUI classes in

TIBCO General Inter face.

Topics

About GUI Classes, page 2

Exercise 1: Basic Spinner, page 4

Exercise 2: Spinner with Up and Down Buttons, page 11

Exercise 3: Spinner with Up and Down Image Buttons, page 14

Exercise 4: Editable Grid, page 16

A ppendix A , System Resolvers, page 27

Appendix B, Control Statements, page 32

Appendix C, Contextual Variables, page 53


2/54


3/54


About GUI Classes | 3

The HTML is then sent to the brow ser (the view d elegatebasically a helper that

can render th e HTML) and it renders as follows:

If the u ser interacts with the view by dragging the slider han dle, the controller isnotified of the relevant events, includ ing mou sedow n, mousem ove, and

mouseup . The controller then u pd ates the mod el based u pon its own p rocessing

rules. In th is case, assume th e slider h as been d ragged to position 50 (Table 2).

The system then synchronizes the mod el to the view (which is sent to the browser

to reflect the up da ted state), and the cycle continues.

Like all architectures, MVC is merely an organizing schemaa way to describeobjects and their relationships to h elp better u nd erstand an d build complex

systems. By abstracting the view an d th e mod el, you are able to envision your

Web app lication not as a tang le of HTML, but rath er a grou p of higher-level

objects. Being freed to imagine the model, you can more easily architect

appropriate business solutions.

The remainder of this documen t describes how to create custom GUI classes

according to MVC p rinciples. The exercises become progressively more complexas the va rious capabilities of the temp late language are d escribed. All of the

examples d escribe how to create a basic spinner control.

Table 2 Example Position

Property Name Value

value 50


4/54


4 | Creating GUI Classes in TIBCO General Interface

Exercise 1: Basic Spinner

This examp le describes how to create a basic spinner control.

I. Create a Functional Specification

It is imp ortan t to create a solid fun ctional specification. With a good sp ecification,

it is not necessary to waste time modifying and re-factoring code. Requiremen ts

for the basic spinner includ e an H TML text inp ut control with en hanced features

and functionality to allow for key inp ut and listening for keydow n andmou sewh eel events. When the up a rrow key is pressed, the control will increment

its value. The mouse wheel will have a similar effect wh en wheeled up by the

user. By defau lt, the control will have a single-pixel gray bord er. Table 2 shows the

comp lete list of controls, and Table 3 show s the associated events and behavior.

Table 3 Example 1 Controls

Property Name Valueposition relative

left

top

width 60 (pixels)

height 20 (pixels)

border solid 1px gray

vertical-align middle

font-name

font-size 20

value 1


5/54


Exercise 1: Basic Spinner | 5

The default control will appear as follows:

II. Define the class

Auth oring a GUI class requires a w orking know ledge of HTML, XML, and

JavaScript. However, given th e functional separation that MVC provides, it is

possible to divide the tasks among team mem bers who are app ropriately skilled

for each p ortion.

The following steps show how to create the GUI class.

1. Create a new JavaScript file.

a. Require the template engine and any interfaces. The new spinner control

will eventu ally be used a s a form field in a General Interface app lication,so the interface, jsx3.gui.Form , will also be includ ed in the requ ire

statemen t. Refer to the d ocumen tation for jsx3.gui.Form for a complete

list of all method s provided by th e interface.

b. Define the new class using defineClass . Refer to the super class

(jsx3.gui.Template.Block ), and any interfaces (jsx3.gui.Form ). While

SPINNER is a pointer to th e class, spinner is a pointer to th e class

prototyp e. These nam es are arbitrary and merely serve as a useful alias

Table 4 Example 1 Events and Behavior

Property Name ValueKey Up Increments the text field

Key Down Decrements the text

field

Mou sew heel Up Increm ents th e text field

Mousewheel Down Decrements the textfield

Change Persists the value after

focus is lost

value 1


6/54



while defining the class. Also note the n ame for the new class:

my.Spinner1.

c. In clu d e an init meth od. This is the constructor tha t allows the class to be

instantiated. It is object oriented and shou ld therefore make a call tojsxsuper. Users can instance the class by calling: new

my.Spinner1("somename");

d. Subclass the getTemplateXML method to convert the temp late's HTML

mar kup (to be created) into the correspon ding JavaScript fun ctions need ed

by the class. The XML is defined inline w ithin the JavaScript and uses an

apostrophe escape.

jsx3.require("jsx3.gui.Template","jsx3.gui.Form"); //a)

jsx3.lang.Class.defineClass("my.Spinner1" //b)

,jsx3.gui.Template.Block

,[jsx3.gui.Form]

,function(SPINNER,spinner) {

spinner.init = function(strName) { //c

this.jsxsuper(strName);

};

spinner.getTemplateXML = function() {//d

return ['',

' ' ,

' ' ,

''].join(""); };

});

2. Define any model defaults for the GUI control. The spinner will implement a

default value of 1 if no value is specified. Because the control imp lements th e

jsx3.gui.Form interface, its value is stored using the jsxvalue field. This

mean s that any call to the getValue method (a mix-in m ethod p rovided by

jsx3.gui.Form ) will return 1 if the given instance does not define a va lue.

jsx3.require("jsx3.gui.Template","jsx3.gui.Form");

jsx3.lang.Class.defineClass("my.Spinner1"


,[jsx3.gui.Form]


spinner.init = function(strName) {


};


7/54



spinner.jsxvalue = 1;

spinner.getTemplateXML = function() {

return ['',

' ' ,

' ' ,

''].join("");

};

});

The system serializes all simp le model p roperties. This mean s that serializing

an ins tance by calling its toXML meth od w ill result in the property value, 1,

being serialized, regardless of whether or not it was explicitly d eclared on th e

instance.

3. Author the HTML prototype to reflect the requirements in the functional

specification:

Next, replace every HTML attribute, event, or style property va lue that sh ould

be made dynamic with a replacement variable (denoted by curly braces). For

example, to allow th e font-size property to be dynam ically replaced w ith the

model property, jsxfontsize , change the explicit style declaration from th is:

font-size:10px;

to this:

font-size:{jsxfontsize};

The HTML now app ears as follows.


8/54



Note the following items:

The position property uses the variable {$position} . The $ prefix is reserved

by the system to define a p re-built set of system variable resolvers tha t are

provided by the template engine. Appendix A on page 27 contain s a full list ofpre-built resolvers. By u sing these you can greatly simp lify creating you r

temp late. For example, the {$position} resolver w ill return either relative

or absolute , depend ing up on the value of the jsxrelativeposition p roperty.

The width, height, and border declarations include a default value. This

ensures th at the control is at least 60 pixels w ide by 20 pixels tall with a

single-pixel gray border. Default values are d enoted using a pipe character.

Refer to Appendix B on page 32 for imp lementation d etails on@defaultvalue .

Event declarations such as onkeydown="{onkeydown}" tell the system th at

you have a controller method named onkeydown that shou ld be notified of the

keydow n event. Step 4 explains this further.

The value field for the text input uses the {jsxvalue} variable. This m eans

that w hen th e control is painted on -screen its value will be equal to

this.jsxvalue. This is how all template variables work an d is the p referredmethod for matching properties on the mod el to prop erties in the view

template. In other word s, {jsxfontsize} points to this.jsxfontsize an d

{x.y.z} points to this.x.y.z . This simp le patt ern ensures prop er

synchronization between model and view.

The class ap pears as follows:




,[jsx3.gui.Form]




};


spinner.getTemplateXML = function() {

return ['' ,

' ' ,

' ' ,

'


9/54



'

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;"

/>' ,

' ' ,

''].join("");

};

});

4. The last step is to define the controller functions. As previously explained, any

event declared in the template using the stand ard var iable syntax (such as

onkeydown="{onkeydown}" ) will autom atically call the p rototype class

function of the same name. This means if you d eclare an onkeydown event in

your temp late, you shou ld a lso declare the JavaScript controller onkeydown .

By naming the controllers app ropriately, the on-screen view will be able to

locate the correspond ing in-memory controller. When found , an instance of

jsx3.gui.Event and a reference to the target GUI object will be passed to the

controller. The controller can then u pd ate the model and the view by calling

th e setProperty method. This single call updates the n amed property on the

mod el and p rojects the up da te to the on-screen view. Note how th e setValue

method utilizes this function call. This is a final critical step that all controller

meth ods shou ld use to ensu re a comp lete feedback loop from mod el to view.

The final class is as follows (the init an d compile methods ha ve been

removed for readability):




,[jsx3.gui.Form]


// ** init and compile methods removed for readability **

//add the controller logic here...

spinner.onkeydown = function(objEvent,objGUI) {if(objEvent.upArrow()) this.up();

else if(objEvent.downArrow()) this.down();

};

spinner.onkeyup = function(objEvent,objGUI) {

this.jsxvalue = objGUI.value;

};

spinner.onchange = function(objEvent,objGUI) {

this.jsxvalue = objGUI.value;};


10/54



spinner.onmousewheel = function(objEvent,objGUI) {

var wd = objEvent.getWheelDelta();

if (wd > 0) this.up();

else if(wd < 0) this.down();};

spinner.up = function() {

this.setValue(parseInt(this.getValue())+1);

};

spinner.down = function() {

this.setValue(parseInt(this.getValue())-1);

};

spinner.setValue = function(strValue) {

//tell the engine to update the model and synchroniz e the

view

this.setProperty("jsxvalue",strValue);

};

});


11/54


Exercise 2: Spinner with Up and Down Buttons | 11

Exercise 2: Spinner with Up and Down Buttons

This example describes how to create a spinner control that includes up an d d ownbuttons.

I. Define the control

This exercise add s up and dow n image buttons to increment or d ecrement the

value of the inp ut box. The control otherw ise remains u nchanged .


All controllers remain the sam e for this class. This is an important p oint that

reflects the flexibility provided by an MVC architectu re. Because th is exercise

merely adds features to th e view, there is no need to mod ify any of the existing

controller methods. Only the view template and a few ad ditional model defaults

need to be changed, because the up dated spinner widget m ust d efine more

HTML elements to create the up an d dow n images.

The following steps show how to add the up and dow n controls.

1. Add two add itional model defaults. The new spinner control will use up and

dow n images borrowed from the jsx3.gui.TimePicker class. The URL for

the up and d own images is saved as a comp lex object (this.arrow.up an d

this.arrow.down ). The Gen eral Interface serializer ignores this p roperty

when the object is serialized as XML, because there is no need to save it, as it is

only used w hen painting the arrows at runtime. The class app ears as follows:




,[jsx3.gui.Form],function(SPINNER,spinner) {



};


this.arrow = {};

this.arrow.up = "url(" +

jsx3.resolveURI("jsx:///images/jsxtimepicker/" +"spin_up.gif") + ")";


12/54



this.arrow.down = "url(" +

jsx3.resolveURI("jsx:///images/jsxtimepicker/" +

"spin_down.gif") + ")";

spinner.getTemplateXML = function() {return ['' ,

' ' ,

' ' ,

''].join("");

};

});

2. Expand the definition for the HTML template. Note that the inpu t box is

nested inside a special box, inlinebox . This is an ad ap ted SPAN object

provid ed by the template engine that allows the GUI control to have layout

(width and height) even if it is relatively positioned or flowed inline with text.

This enables you to p osition the control either relatively or absolutely withou t

having cross browser d ifferences corrup t the layout .


13/54


Exercise 2: Spinner with Up and Down Buttons | 13

Note th e following items:

Use simple dot notation when referring to complex fields. For example, to

reference the instance/ prototyp e field, arrow.up , use a variable nam ed

{arrow.up}. In gen eral any field can be referenced this w ay.

The up and down events were defined in the previous exercise when the

controller method s were declared. These methods already existed and w ere

used by other method s, such as onkeydown an d onmousewheel . Simp ly

referring to these by nam e (for examp le, onclick="{up}" ) makes them

callable when a click event occurs in the view.


14/54



Exercise 3: Spinner with Up and Down Image Buttons

This example d escribes how to create the sam e spinn er control as in Exercise 2 onpage 11 using the attach tag.


The use case for this contro l is exactly the sam e as for Exercise 2; how ever, in th is

exercise the up and dow n image buttons are generated using the attach tag.


The temp late for this class requires fewer H TML tags than the p revious example

to render its up and dow n buttons. Instead, it uses the attach tag to paint the

HTML for a specific set of descendant objects. (Refer to Appendix B on page 32for a list of all statements that you can use in you r temp late.)

Figure 1 shows the Com ponent H ierarchy p alette in GI Builder and how the

spinner uses the ImageButton children to rend er its arrow s.

Figure 1 Component Hierarchy with Spinner Controls7

The following tem plate can render the above DOM structure.


15/54


Exercise 3: Spinner with Up and Down Image Buttons | 15

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};" />

Every attach tag requ ires a select statement that returns an instance of

jsx3.util.Iterator. This provid es flexibility w hen d eciding w hich descendan t

objects shou ld paint. In the above example the select statemen t return s all childobjects (these are th e two child ImageButtons shown in the DOM). No error

checking is in place; how ever, you can imp lement error checking to ensu re that

the control only paints children of type jsx3.gui.ImageButton .

When attaching descendan ts, you can u se a drawspace tag to send add itional

sizing and processing d irectives to the children. This provid es a way for a parent

control to force the position and content of any p ainted d escend ants. Although

this is not alw ays necessary, it is a u seful convenience. All fields on the d raw space

tag are calculated . This mean s that strings should be escaped where app ropriate:

boxtype="'box'"

Because all fields are calculated , any valid JavaScript can be used . For example,

the top va lue is calculated based u pon the child ind ex of the target child.

top="$$target.getChildIndex() * 8"

The $$target variable is always available within attach an d for-each tags and

points to the cur rent object in the iteration. In this case, the child at index 0 willrender at position 0, the child at p osition 1 will render a t position 8. Appendix C

on page 53 lists all contextual system variables (those beginning w ith $$). You can

embed these variables within your own code and use them for your own

calculations. For example, the var iable $$parentwidth defines the width of the

drawspace into which the given HTML tag will paint. In the above marku p, it

determ ines where to draw the left position of the ImageButton children:

left="$$parentwidth - 11"



16/54



Exercise 4: Editable Grid

This exercise describes how to create an ed itable grid (similar to a spread sheet)that allows variable nu mber of rows and columns.


The data sou rce for the grid is an XML document in Common Data Format (CDF).

Each record in the CDF docum ent has an associated on -screen row in th e grid.

The colum ns are d efined using JSON , which allows you to specify for each

colum n the colum n label, colum n width , and CDF attribute to wh ich the colum n

will map .

When users click a cell in th e grid, a text inpu t overlays the cell, allowing the grid

to be ed itable. Both before-edit an d after-edit m odel events are exposed, allowing

you to intercept, cancel, and mod ify user ed its as they happ en. Navigation is

sup ported w ith the tab, enter, and arrow keys. The header row is fixed, while the

remaining rolls scroll when necessary, both h orizontally and vertically. Figure 2

show s the control.

Figure 2 Editable Grid Control7

Exercise 4: Editable Grid | 17


17/54



II. Define Common Patterns

The editable grid class takes advantage of the for-each iterator tag. This allows

the temp late to only specify a bare minimu m of marku p, while generating a

variable num ber of rows and colum ns. Typically, any time you need to create acontrol that w ill display repeating lists of data (such as tables, pick-lists, or grids),

you use a for-each iterator.

For examp le, assum e that the following XHTML marku p is in your template:

hello

To paint exactly four row s of data, you can imp lement the following selector

query. Note how the select statement retu rns an instan ce ofjsx3.util.Iterator.

hello

Although the above selector hard codes the contents of the iterator (such as

[1,2,3,4]), it is common to u se a more dynamic approach for you r class. For

example, if your GUI class implements the jsx3.xml.Cacheable an d

jsx3.xml.CDF interfaces (as in th is examp le), the class has access to comm on

methods such as getXML . This allows you to p aint as many row s as you have CDF

records in th e XML docum ent u sed by the control. For example:

hello

Beyond simply iterating over a collection of items, the for-each tag alsoprovides a pointer to the active item in the iteration: $$target . For example,

assum e that you n ot only wan t to paint a table row for each record, but you also

wan t to output the value of the jsxtext attribute:

$$target.getAttribute('jsxtext')

{mytext}



18/54



You m ay need to nest for-each iterators to hand le a variable num ber of both

rows an d colum ns. For examp le, the class used for this exercise has a variablenam ed items that stores column p rofile information in the following JSON

format:

this.columns = {};

this.columns.items = [{attribute:"jsxid",caption:"ID",width:"25"},

{attribute:"jsxtext",caption:"Name",width:"*"}]

When it is time to paint the component, a corresponding method wrap s the array

and returns an iterator.

grid.getIterableColumns = function() {

return jsx3.util.List.wrap(this.columns.items).iterator();

};

Though u seful, nested loops introdu ce a new challenge in that the $$target

variable is intercepted by the nested (inner) for-each . This means that if the

inner loop m ust access the target of the ou ter loop, you mu st cache a pointer to

th e $$target variable before the inner loop begins. For examp le, note how a

custom variable namedmyrecord is used to d o this:

$$target

myrecord.getAttribute($$target.attribute){mytext}

III. Optimize the TemplateAn im portant feature of the Temp late class is its ability to op timize developer

code. If, for example, a resize event occurs in the browser, the Template will

au tomat ically adjust the size of the control to reflect this change. And if the

Temp late determ ines that th e resize event did not affect the true size of the

painted instance, it will exit early to spare the un necessary processing time.

However, there are times when you, the developer, will know of optimizations

that th e Temp late class simp ly cannot han dle given that it is a generic tool. For



19/54


|

example, the sam ple class used for this exercise uses a single HTML inpu t in

order to make the grid ed itable. This redu ces the am oun t of HTML needed to

create a large, editable grid, since the single inpu t can be overlaid on top of a grid

cell when it is time to edit.The Temp late engine is capable of positioning the single text inpu t w hen a given

cell receives focus . The handler for the class locates the position of the cell in

relation to the HTML element th at contains both it and the inp ut m ask, using the

method getRelativePosition :

var objPos =

jsx3.html.getRelativePosition(objDataContainer,objCell);

objPos.target = objCell;

When the tru e position for the cell is determined , the position is cached (along

with a few additional values) and the Temp late engine is notified of the change:

this._setTargetProfile(objPos);

At this point, any template variable that imp lements the beforeedit trigger is

notified to up da te its cached value. The Temp late class then autom atically app lies

the up dated value to any tag in the temp late that imp lements the given variable.

For examp le, consider the following m odel declarations u sed by the grid class:

return this._getTargetProfile().value;

return isNaN(this._getTargetProfile().L)? -100

:this._getTargetProfile().L;

return isNaN(this._getTargetProfile().T)? -18:this._getTargetProfile().T;

return this._getTargetProfile().W || 100;

return this._getTargetProfile().H || 18;

return this._getTargetProfile().display || "none";

When the mod el variables are upd ated, the Temp late class next attemp ts to app ly

these up dates to every HTML element th at uses one. In this case, the variables

mask_value,mask_left ,mask_top ,mask_width,mask_height, and

mask_display are used to u pd ate the value, display, and position of the single

input box.



20/54


|

The following inp ut d efinition app ears in the temp late for the class:

Although the tem plate engine simp lifies the act of upd ating the u ser interface, it

can also be inefficient, because the engine d oes not know in advance which tags

implement w hich variables. When the inpu t m ask has been p ositioned, the engine

continues to scan the remainder of the temp late, in case other H TML elementsalso use the n ewly-up da ted variables. To avoid th is, you can tell the engine to exit

early when you know that there is no need for it to continue scanning the

remaining H TML elements. For example, note how the if tag tells the engine to

exit early w hen there is a flag on the cached profile:

The final class definition for th e editable grid is as follows:jsx3.require("jsx3.gui.Template","jsx3.xml.Cacheable","jsx3.xml.CD

F");

jsx3.lang.Class.defineClass("my.Grid",jsx3.gui.Template.Block,[jsx

3.xml.Cacheable,jsx3.xml.CDF],function(GRID,grid) {

//init

grid.init = function(strName) {


};

// defaults

grid.columns = {};

grid.columns.items =

[{attribute:"jsxtext",caption:"Text",width:"*"}];

// template xml

grid.getTemplateXML = function() {

return ['',



21/54


|

'' ,

' ' ,

' return

this._getTargetProfile().value;' ,

' r eturn

isNaN(this._getTargetProfile().L) ? -100 :

this._getTargetProfile().L;' ,

' re turn

isNaN(this._getTargetProfile().T) ? -18 :

this._getTargetProfile().T;' ,

' return

this._getTargetProfile().W || 100;' ,

' return

this._getTargetProfile().H || 18;' ,

' return this._getTargetProfile().display ||

"none";' ,

' ' ,

' ' ,

' ' ,

//scrollable data rows

' ',

//textbox edit mask

' ',//exit the template early if the mask is targeting a

cell; when that happens, merely show the mask above and exit early

' ' ,

' '

, ' ' ,

' this.getId() + \'_\' +

$$target.getAttribute(\'jsxid\')',

' $$target ',

' ',

' ' ,

' rowtarget.getAttribute($$target.attribute) ||

""',

' $$targ et.width','


22/54


|

lightblue;border-bottom:solid 1px

lightblue;">{celltext}',

' ',

' ',

' ',

' ',

' ',

//fixed header row

' ',

' '

,

' ',

' ' ,

' $$tar get.caption',

' $$ta rget.width',

'

',

' {headertext}',

' ',

' ',

' ',

' ',

' ',

' ' ,

' ' ,

''].join("");

};

// 6) define the CONTROLLER functions

grid.onmousedown = function(objEvent,objGUI) {

this.onbeforeedit(objEvent,objEvent.srcElement().parentNode,objEve

nt.srcElement());

};

grid.onscroll = function(objEvent,objGUI) {

//called when the data rows are scrolled

this.getRenderedBox("header_tbl").style.left =

-objGUI.scrollLeft + "px";

};

grid.onblur = function(objEvent,objGUI) {

//handle the primitive event (onblur) with the prototype

(instance) eventthis.onafteredit(objEvent,objGUI);

};



23/54


|

grid.onkeydown = function(objEvent,objGUI) {

var objCell = this._getTargetProfile().target;

var intCellIndex = objCell.cellIndex

var objRow;

if((objEvent.enterKey() && !objEvent.shiftKey()) ||

objEvent.downArrow()) {

//commit the value; advance edit to the next cell down

this.onafteredit(objEvent,objGUI);

//if the current row isn't the last row, apply edit mask to

the next row down

objRow = (objCell.parentNode !=

objCell.parentNode.parentNode.lastChild) ?

objCell.parentNode.nextSibling :

objCell.parentNode.parentNode.firstChild;

} else if(objEvent.upArrow() || (objEvent.enterKey() &&

objEvent.shiftKey())) {

//commit the value; advance edit to the next cell up


//if the current row isn't the first row, apply edit mask to

the next row up;

objRow = (objCell.parentNode !=

objCell.parentNode.parentNode.firstChild) ?

objCell.parentNode.previousSibling :

objCell.parentNode.parentNode.lastChild;

} else if(objEvent.rightArro w()) {

//commit the value; advance edit to the next cell down


var objRow = objCell.parentNode;

intCellIndex = objRow.lastChild == objCell ? 0 :

intCellIndex+1;

} else if(objEvent.leftArrow()) {

//commit the value; advance edit to the next cell up


var objRow = objCell.parentNode;

intCellIndex = objRow.firstChild==objCell

?objRow.lastChild.cellIndex :

intCellIndex-1;

}

//begin the edit session for the target cell

if(objRow)

this.onbeforeedit(objEvent,objRow,objRow.childNodes[intCellIndex])

;

};

grid._getTargetProfile = function() {

//when an edit event happens, a target p rofile is created that

describes the context

return this._jsxtargetprofile || {};

};



24/54


grid._setTargetProfile = function(objP) {

//when an edit event happens, a target pro file is created that

describes the context

this._jsxtargetprofile = objP;

};

grid.onbeforeedit = function(objEvent,objRow,objCell) {

//use a sleep delay to stop repeated clicks and key strokes

from taxing performance

jsx3.sleep(function() {

this._onbeforeedit(objEvent,objRow,objRow.childNodes[objCell.cellI

ndex]);

},"my.GRID",this);

};

grid._onbeforeedit = function(objEvent,objRow,objCell) {

//get the id for the row that was clicked

var strCdfId =

objRow.getAttribute("id").substr(this.getId().length+1);

var strAttName =

this.columns.items[objCell.cellIndex].attribute;

var strValue =

this.getRecordNode(strCdfId).getAttribute(strAttName);

//allow the before-edit event to be cancelled

var objReturn = this.doEvent(jsx3.gui.Interactive.BEFORE_EDIT,

{objEVENT:objEvent,strID:strCdfId,objCELL:objCell,strVALUE:strValu

e});

if(objReturn !== false) {

//determine information about the target cell being edited

(left, top, etc)

var objThis = this.getRendered(objRow);

var objDataContainer =

this.getRenderedBox("datarows",objThis);

var objMask = this.getRenderedBox("txt_editmask",objThis);

//query the system for the location of the target table cell

var objPos =

jsx3.html.getRelativePosition(objDataContainer,objCell);

//when running on firefox, builds earlier than 3.6.1 have a

bug

if(!(jsx3.getVersion() < "3.6.1" &&

/fx/.test(jsx3.CLASS_LOADER.getType()))) {

objPos.L = objPos.L + objDataContainer.scrollLeft;

objPos.T = objPos.T + objDataContainer.scrollTop;

}

objPos.value = strValue || "";

objPos.display = "block";

objPos.target = objCell;

objPos.id = strCdfId;



25/54


objPos.attribute = strAttName;

//cache the information about the target

this._setTargetProfile(objPos);

this.syncProperty("beforeedit",true);

//give cursor focus to the edit mask (the text input)

objMask.focus();

}

};

grid.onafteredit = function(objEvent,objGUI) {

//get the profile object

var objP = this._getTargetProfile();

//get the new value entered by the user

var objReturn;

if(objP.value != objGUI.value) {

//allow the edit to be cancelled/modified

objReturn = this.doEvent(jsx3.gui.Interactive.AFTER_EDIT,

{objEVENT:objEvent,strID:objP.id,objCELL:objP.target,

strVALUE:objGUI.value});

if(objReturn !== false) {

//update the data model

this.insertRecordProperty(objP.id,objP.attribute,objGUI.value,fals

e);

//update the view

objP.target.innerHTML = jsx3.util.strEmpty(objGUI.value) ?

"" : objGUI.value;

}

}

//reset the mask (hide it)

this._setTargetProfile({value:""});

this.syncProperty("afteredit",true);

//fire the final commit event (not cancellable)

if(objReturn !== false)

this.doEvent(jsx3.gui.Interactive.AFTER_COMMIT,

{objEVENT:objEvent,strID:objP.id,objCELL:objP.target,

strVALUE:(objReturn != null && objReturn.strVALUE ?

objReturn.strVALUE : objGUI.value)});

};

grid.setColumns = function(arrColumns) {

//call to change the columns to render for the table. The

schema is as follows.:

this.columns.items = arrColumns;

//the GI serializer only saves scalar types

this.encodeColumns(arrColumns);

this.repaint();

};



26/54


grid._getColumns = function(arrColumns) {

return this._columns || "";

};

grid.encodeColumns = function(arrColumns) {

//serialize the columns array as a string so the GI class

serializer

var a = [];

for(var i=0;i


27/54


Appendix A System Resolvers

System resolvers help simplify authoring H TML temp lates by obviating the need

to declare local variables. Table 5 describes the system resolvers, the instance

property to w hich they map , and relevant triggers.

Table 5 System Resolvers

Name Type Description Trigger

$id at tr ibu te Renders the jsxid field a s id="{$id}" .

Always applied to the root node in the

temp late regardless of developer choice.

This ensures that the mod el and view are

always synchronized.

$label at tr ibu te Renders the jsxname field as

label="{$label}"

jsxname

$position box Ren der s th e jsxr elativ ep osition field as

position:{$position};

jsxrelativeposition

$left box Renders the jsxleft field as

left:{$left}; wh en the position is

absolute and when specified

jsxleft

$top box Renders the jsxtop field as top:{$top} ;

when the position is absolute and when

specified

jsxtop

$width box Renders the jsxwidth field as

width:{$width}

jsxwidth

$height box Renders the jsxheight field as

height:{$height}

jsxheight

$zindex css Renders the jsxzindex field as

z-index:{$zindex}

jsxzindex

$color css Renders the jsxcolor field as

color:{$color}

jsxcolor

$fontname css Renders the jsxfontname field as

font-family:{$fontname}

jsxfontname

28 | Appendix A System Resolvers


28/54


$fontsize css Renders the jsxfontsize field as

font-size:{$fontsize}

jsxfontsize

$fontweight css Renders the jsxfontweight field a s

font-weight:{$fontweight}

jsxfontweight

$display css Renders the jsxdisplay field a s

display:{$display}

jsxdisplay

$visibilitycss Renders the jsxvisibility field a svisibility:{$visibility}

jsxvisibility

$style-group box Renders the value of the

jsxstyleoverride field at the end of the

existing style d eclaration. This prov ides a

mechan ism for injecting m ultiple styles into

a single tag.

jsxstyleoverride

$classname attr ibu te Ren ders th e jsxclassname field asclass="{$classname}" .

If the given class has a static field nam ed

DEFAULTCLASSNAME , the valu e of this field

will be appended , meaning a class like

jsx3.gui .Block that implements a

jsxclassname prop erty with the value,

"customstyle" , would render as

class="jsx30block customstyle"

jsxclassname

$bgcolor css Renders the value of the jsxbgcolor field

as background-color:{$bgcolor};

jsxbgcolor

$bg css Renders the value of the jsxbg field a s

background:{$bg};

jsxbgcolor jsxbg

$padding box Renders the value of the jsxpadding field

as padding:{$padding};

jsxpadding

$margin box Renders the value of the jsxmargin field

asmargin:{$margin};

jsxmargin

$border box Renders the value of the jsxborder field

as border:{$border};

jsxborder

$textalign css Renders the value of the jsxtextalign

field a s text-align:{$textalign};

jsxtextalign

Table 5 System Resolvers (Contd)


System Resolvers | 29


29/54


$overflow css Renders the value of the jsxoverflow

field as overflow:{$overflow};

jsxoverflow

$attribute-group box Similar to $style-group , this resolver

allows a list of attributes to be injected into a

given tag. This is a special type of resolver

that m ust be declared as a child of the target

HTML node, since it affects the attribu te list

for the node. For examp le,

{$attribute-gro

up}

Any att ribute on a General Interface object,

using the API, setAttribute will be

reflected by this resolver.

$tagname box Allow s the H TML tag nam e to be u pd ated .

This is a special type of resolver that m ust

be declared as a child of the target HTML

nod e, since it affects the tag nam e of the

given nod e. For examp le,

{$tagname}

jsxtagname

$text box Ren der s th e valu e of th e jsxtext field as a

text node child of the given H TML nod e.

This is a special type of resolver that m ust

be contained by a nod e. For

example,

{$text}

jsxtext

$index attribute Renders the value of the jsxindex field a s

tabindex="{$index}" . If this field has

no valu e, the default (0) will be used

jsxindex

$tip attribute Renders the value of the jsxtip field a s

title="{$tip}" .

jsxtip



30 | Appendix A System Resolvers


30/54


$disabled attribute Renders the value of the jsxenabled field

as disabled="{$disabled}" .

jsxenabled

$onblur even t Renders the g iven even t listener on the

HTML tag if the control is not set to

jsxenabled = false;

jsxenabled

$onchange even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$onclick even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$ondblclick even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$onfocus even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$onkeydown even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$onkeypress even t Renders the g iven even t listener on theHTML tag if the control is not set to

jsxenabled = false;

jsxenabled

$onkeyup even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$onmousedown even t Renders the g iven even t listener on the

HTML tag if the control is not set tojsxenabled = false;

jsxenabled

$onmousemove even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled

$onmouseout even t Renders the g iven even t listener on the


jsxenabled = false;

jsxenabled



System Resolvers | 31


31/54


$onmouseover even t Renders the g iven even t list ener on the


jsxenabled = false;

jsxenabled

$onmouseup even t Renders the g iven even t list ener on the


jsxenabled = false;

jsxenabled

$onmousewheel even t Renders the g iven even t list ener on the

HTML tag if the control is not set tojsxenabled = false;

jsxenabled



32 | Appendix B Control Statements


32/54


Appendix B Control Statements

When au thoring a temp late, you use a combina tion of HTML and control

statemen ts to help with conditional processing (for-each an d if-else ). You can

use any HTML node such as span or d iv wh ere noted below. Any nod e not listed

by name in Table 6 is assumed to be an HTML node that should be painted.

Table 6 Control Statements

Node Name Can be a Parent of Description

transform model | template |

@xmlns | @xmlns:u |

@version

The root nod e for the temp late. Declare as follows (the nam espace

declarations must be includ ed, but are rem oved in some of the

usage examp les for read ability):

@xmlns http://gi.tibco.co

m/t

ransform/

This is the nam espace declaration for the temp late. All elemen t

nodes w ithin the template belong to this namespace.

@xmlns:u http://gi.tibco.co

m/t

ransform/user

Use to add custom attributes to a given HTML tag in your

template without having the given attribute render to the view.

version 1.0 This is the tem plate v ersion. General Interface release 3.6

sup por ts version 1.0.

model var | import Contains all locally declared va riables (resolvers) used by the

temp late when p ainting. It is unn ecessary to declare this tag if

you d o not need any special formatting for your temp late.

Control Statements | 33
http://gi.tibco.com/transform/http://gi.tibco.com/transform/http://gi.tibco.com/transform/http://gi.tibco.com/transform/userhttp://gi.tibco.com/transform/userhttp://gi.tibco.com/transform/userhttp://gi.tibco.com/transform/userhttp://gi.tibco.com/transform/http://gi.tibco.com/transform/


33/54


var[parent

::model]

#text | @id | @name

|@type | @triggers |

@defaultvalue

Declares a var iable resolver in th e mod el. Although it is often

easier to implicitly define resolvers by simp ly using them w ithin

the tem plate, it is sometimes useful to explicitly declare them in

the mod el in order to retain full control over how the given

resolver is run. For example:

return this.jsxcolor;

whirled

peas

@id #text This is the ID for the va riable. It should be un ique for the

template. It should not begin with a $ , because the system ow ns

this pr efix to identify its own variable resolvers.

var[parent

::model]/@

name

#text The name attribute is used w hen the variable is rendered as final

HTML. For css and box type variables, this is the CSS prop erty

nam e. For attribu tes and even ts, this is the attribute or event

name. For example, this structure

return this.jsxcolor;

whirled

peas

generates th is HTML:

whirled

peas

Table 6 Control Statements (Contd)




34/54


var[parent

::model]/@type

box | attribute |

event | css(default)

The variable type lets the temp late engine know h ow a given

variable should be projected into the view. For examp le, to add a

src attribute to an img tag , declare its type as attribute:

return this.url;

The temp late engine also allows for imp licit variable declarations

by simp ly using a var iable inline. For examp le, the following

syntax is exactly equ ivalent to th e explicit declaration above:




bl 6 l ( d)


35/54


var[parent

::model]/@triggers

#text Template variables can implemen t a triggers field to let the

template engine know wh ich u pd ates to the model should trigger

changes in the view. For examp le, when u pd ating the url

property on a GUI object (this.url = 'x' ), a cont roller

function can call setProperty . This comp ound method first

up dates the model with the new value and then triggers an

up date to the view to ensure that the mod el and view remain

synchronized.

function setURL(strURL) {

this.setProperty("url", strURL);

}

Given the method call above, the following template would be

triggered to upd ate the url variable. The img tag would then be

up dated to reflect the new url value on-screen .

return this.url;

Note:The triggering system is many-to-many. A single template

variable can imp lement multiple triggers and a single trigger can

be app lied to mu ltiple variables. For example, in the following

template both variables are upd ated wh en the url trigger is

fired, because both implement the url trigger.

return

this.url;

return

this.fullurl;




T bl 6 C t l St t t (C td)


36/54


var[parent

::model]/@defaultval

ue

#text The defaultvalue field is used to assign a variable default

wh en its resolver fun ction return s null. Therefore, the followingtwo variable declarations are equivalent:

return this.url != null ? this.url :

"abc.gif";

or

return this.url;

Default values can also be imp licitly declared inline within th e

body of the temp late using a pipe character ("|"). Therefore, the

following implicit declaration is equivalent to th e two explicit

declarations above:

If no defaultvalue field is used and th e resolver function

returns n ull, it will result in th e given prop erty being removed

from the object when p ainted, while an empty string results in an

emp ty value. For examp le, a variable named 'src' that returns

nu ll (and with no defaultvalue field) w ould r esult in thefollowing HTML:

While an empty string would be expressed as

follows:






37/54


import @resolver | @set |

@library

This allows for re-use of common resolvers and is used to import

variable resolvers declared and used by other widget librariesand classes. . For examp le, the following statement imports the

variable resolver named $color :

Variable resolvers can belong to a namespace. If you createa variable nam ed "color" and the resolver belongs to theclass my.Spinner, then another class can impor t the variableresolver by using th e following d eclaration:

To imp ort every resolver from another class, pass the name of the

class as the library n ame:

System resolvers (those beginning w ith "$") do not need to beimported. This means that simply using a system resolver is the

app ropriate way to declare its imp ort. For example, note how the

url resolver mu st be explicitly impor ted from th e class named

my.Spinner, while the system resolver, $position , does not:


38/54


@oninit text/javascript Called immed iately after the temp lates profile is

created

@onbeforep

aint

text/javascript Called immediately before paint. If this method returns an

alternate string of text/ HTML, the control will not attempt to

paint and will instead use the provided string.

@onpaint text/javascript Called after the HTML has been painted and rendered by the

brow ser. Called in a separate call stack from th e paint m ethod .

@onbeforer

esize

text/javascript Called imm ediately before a resize event. Return a Boolean false

to cancel the resize for the control.

@onresize text/javascript Called imm ediately after a resize event. The object's dim ensions

will have been up dated in both the model and view, but its

descendant objects may not have been resized yet.

@onbeforer

esizechild

text/javascript Called immediately before a child is resized. The method will be

passed one par ameter: a reference to the child abou t to be resized.Return a Boolean False to cancel the resize for the child.

@recalc true|false

(default)Called immediately after the HTML has been painted and

rendered by the brow ser, causing the resize engine to app ly any

dynam ic position calculations to the painted control. Use this

feature in your template if you declare any elements

within the section that affect box p roperties like

left, top, width, padding, border, etc.

Table 6 Control Statements (Cont d)





39/54


@dom dynamic | static

(default)

Some tem plates result in d ifferent HTML outp ut. For example, a

template with if/else conditional statements, may create anon-screen DOM th at differs each time it is rend ered. In such a

situation, specify that th e HTML content is dyn amic and

therefore mu st be located u sing named IDs. In other w ords w hen

the DOM is dynam ic, then each HTML node in the temp late

needs a corresponding u nique ID, using the user nam espace. For

example:

{mytext}

Note: If your temp late uses a for-each iterator, it must u se a static

DOM.

Table 6 Control Statements (Cont d)





40/54


var[ancest

or::template]

text/javascript |

@id

Declares a local variable within the body of the temp late. This

allows a given variable to be dynamically upd ated d uringexecution. For example:

$$target.getAttribute(\'jsxid\')

$$target.getAttribute(\'jsxtext\')

{rtext}

var declarations in the body of the template executedifferently than var declarations m ade w ithin th e mod el.This means that a variable that retu rns the color red wouldbe declared like this, if declared w ithin the model:

return "red"

{abc}

How ever, when declared w ithin the temp late, a local variabledeclaration will not be stored as a global fun ction, and therefore

should not u se a return statement:

"red"

{abc}

( )





41/54


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 H TML tag can be used in a temp late. All attributes on

the tag will be rendered on the tag except for those belonging tothe http:/ / gi.tibco.com/ transform/ user namespace.

@u:protect

ed

true Use on an H TML tag to denote that its dimensions should n ot be

man aged by the General Interface layout en gine. The tag can still

use the rep lacement variable engine, but its layout s will be

un affected. For examp le, the following temp late:

results in the following H TML wh en pain ted

How ever, if the u:protected attribute had not been used, the

layout engine wou ld have replaced th e percentages with absolute

pixel values to reflect the dimensions allowed by the containing

HTML tag. For examp le,:





42/54


left text/javascript Can be u sed to sp ecify the left position of an HTML node. For

example:

$$parentwidth - 10

Note:The syntax above is not required , but can be used for

greater contr ol over layou t, since it accepts an y valid JavaScript

statement. How ever, it generally more comm on to simp ly declare

the style inline and have the system autom atically hand le the

calculation. For example, note h ow the CSS accepts the calculated

value, 100% - 10:

Replacement variables can be used in both

situations. Whether expanded:

{$left}

or inline:

Two custom style properties are also provided for convenience

wh en doing calculations: right and bottom. These simplify left

and top d eclarations that u se calculations. For examp le, the

following tw o style declarations are equivalent:

or

top text/javascript See the description for left.





43/54


width text/javascript See the description for left.

height text/javascript See the description for left.





44/54


position absolute | relative

(default)

Can be u sed to sp ecify the r elative/ absolute p osition of an H TML

node. For example:

relative

The temp late engine does not required th e expand ed syntax, but

can be used for greater control over layou t, since it accepts any

valid JavaScript statement. However , it is generally more

common to simply declare the style inline and have the systemautomatically hand le the calculation. For examp le:

Replacement variables can be used in both situations. Whether

expanded:

{$position}

or inline:

Unlike the calculated fields, left , top ,width , and height , this

field is treated as a string, assuming th e value is either relative,absolute, or the value of a given rep lacement variable. Only

relative and absolu te are accepted as values by the layout engine;

how ever, the variable replacement engine accepts any va lue. For

example, note how the typ e attribute is declared as css (not box)

and the specific node is specified as protected (u:protected) :

return "fixed";

{abc}





45/54


empty true Use when a given node should render as an empty node. Note

that img , br , and input nodes are au tomatically tagged andneed not specify this value. For examp le:

true

will render as:

attribute-grou

p

#text Use to inject a group of attributes (that is, src="a.gif"

width="1" ) into an HTML node in the template. For examp le:

{myAttListVar}

will render as:

style-group #text Similar to attribute-group. Use to inject a group of CSS styles

(that is, color:blue;font-weight:bold; ) into an HTML

node in th e template. Consider th e expand ed syntax:

{someVarWithStyles}

And the inline syntax:

This is how the tag rend ers:





46/54


border #text See the description for position. The value for this node is best

expressed in th e simplified General Interface notation, using th epattern, style-width-color , as the four compass positions

are d efined for the border, beginning with north. For examp le:

solid 1px red;dashed 2px red;0px;solid

1px red;

Note that when using a rep lacement variable for the bord er, it is

easier to simply d eclare it inline:

Due to the w ay that the tem plate engine parses styles, you should

not sp ecify comp lex bord er declarations or CSS bord er variant s

such as border-top an d border-color inline:

How ever, you can imp licitly define a variable as a way to inline a

comp lex style. Note that the pipe character ( | ) is used to

separate the nam ed variable from its default value (the value to

use if the given variable retur ns nu ll). By wrapp ing the complex

border declaration within a variable, the template engine will

par se the values correctly. The var iable name in such cases is

unim portant and need only be unique among other variables

declared in the template.



47/54





49/54


drawspace @parentwidth |

@par entheight | @left

| @top | @width |

@height | @position

Use to modify the d rawspace. A draw space tag can either be a

child of an attach tag (as a w ay to m odify the default draw spacethat w ould be sent to a given child). The dr awsp ace tag can also

be used. See attach and @left for u sage examp les.

continue Use inside of a conditional tag (if/if-else ) to skip execution

of a given iteration. For example, the following skips a for-each

iteration whenever the given target (a CDF record ) does not

implement a jsxid attribute.

$$target.getAttribute("jsxid")

$$target.getAttribute("jsxtext")


50/54


return Similar to break and continue, except that the function is

completely exited. Useful for intercepting nor mal p rocessing of atemplate and exiting early for improved run time performance. A

local variable, MODE , defines the m ode the tem plate is being run

in. This variable can be qu eried at an y time to know wh ich action

is being invoked by the template engine:

paint,update, create, dimension, and paintchild

For examp le, you can abort the up date event for your temp late

(assuming you know that there is no reason to continue resizing

descendant objects):

if-else if | else Use to wrap a complex conditional (choice). For example:

a

b

c

if HTML | break |

continue | var |

for-each | attach |

drawspace | if |

if-else | return | @test

Use to wrap a simple condition. For examp le:

else HTML | break |

continue | var |

for-each | attach |

drawspace | if |

if-else | return

See the d escription for if-else .






51/54


@p aren tw id th text/ javascrip t Sets th e p aren tw id th on the d raw sp ace. Th e valu e is calcu lated

and accepts an y valid JavaScript. For examp le, to tell all childr enthat their allowed drawsp ace is exactly 100 pixels wide, use the

following:

@p arentheight text/ javascrip t See the description for @parentw id th.

@left text/ javascript The attributes, left, top, width and height, border, margin,

position, and p add ing, can be set on a d rawspacenod e to force

the next HTML node into a p articular position, regard less of its

setting. For example, the following SPAN w ill be placed at left

position 12, even thou gh it specifies that it render at position 10:

@top text/ javascript See the description for @left.

@width text/ javascript See the descrip tion for @left.

@height text/ javascript See the descrip tion for @left.

@bord er text/ javascript See the d escription for @left. In the follow ing example, note how

the border is wrapp ed in apostrophes, because it is a string:

@margin text/ javascript See the description for @left.

@position text/ javascript See the description for @left.

@padding text/ javascript See the description for @left.






52/54


@padding text/ javascript See the description for @left.

p

Contextual Variables | 53

Appendix C Contextual Variables


53/54


When the temp late is run , the system p rovides contextua l variables to give

additional information that is available only when the temp late is run. For

example, because the system m anages layouts, the draw space changes

(decreases) as each n ested tag claims its d imensions. In this examp le, the

$$parentwidth field is used to define how mu ch width is available to rend er

within. Each var iable listed in Table 7 is available within th e section.

This means if you d eclare a variable () or drawsp ace ( ), youcan use this value in you r calculations.

Table 7 Contextual Variables

Name Description Sample Use

$$parent

width

provides the width of the

containing d rawspace

Force the next HTML tag to be

rend ered to be half as small as the

available wid th:

$$parent

height

provides the height of the

containing d rawspace

Render the H TML tag10 pixels from

the bottom of its container:

$$parentheight -

10

The syntax above is not required , but

you can u se it for greater control

over layout. It is more common to

simply d eclare the style inline and

have the system automatically

handle it, as in the following

example:

54 | Appendix C Contextual Variables

Table 7 Contextual Variables (Contd)

Name Description Sample Use


54/54


$$target provides a pointer to the act ive

element within a given for-each orattach iteration. If nested loop s are

used within the tem plate, it is

possible to cache th is value to

avoid collisions

Loop th rough each CDF record and

rend er a div for each one. Use thejsxid from each record in the

iteration to generate the id for each

div and the jsxtext field for the

div's text content:

$$target.getAttr

ibute(\'jsxid\')$$target.getAt

tribute(\'jsxtext\')

{rowtext

}

A locally d eclared variable can beused to cache the $$target when

doing nested iterations:

$$target.getAttr

ibute(\'jsxid\')

$$target

mytarget.getAt

tribute(\'jsxtext\')

{rowtext}

template gui classes

Documents