Using Zen - InterSystems Documentation

Using Zen
Version 2007.1
04 June 2007
InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Using Zen
Caché Version 2007.1 04 June 2007
Copyright © 2007 InterSystems Corporation
All rights reserved.
This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from
the following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at
www.w3c.org. The primary document development tools were special-purpose XML-processing applications built
by InterSystems using Caché and Java.
and
Caché WEBLINK, Distributed Cache Protocol, M/SQL, N/NET, and M/PACT are registered trademarks of InterSystems
Corporation.
and
InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of
InterSystems Corporation.
All other brand or product names used herein are trademarks or registered trademarks of their respective companies
or organizations.
This document contains trade secret and confidential information which is the property of InterSystems Corporation,
One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation
and maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any other
purpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system or
translated into any human or computer language, in any form, by any means, in whole or in part, without the express
prior written consent of InterSystems Corporation.
The copying, use and disposition of this document and the software programs described herein is prohibited except
to the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation covering
such programs and related documentation. InterSystems Corporation makes no representations and warranties
concerning such software programs other than those set forth in such standard software license agreement(s). In
addition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use of
such software programs is limited in the manner set forth in such standard software license agreement(s).
THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY
INTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER
SOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE
LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLE
UPON REQUEST.
InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the
right, in its sole discretion and without notice, to make substitutions and modifications in the products and practices
described in this document.
For Support questions about any InterSystems products, contact:
InterSystems Worldwide Customer Support
Tel: +1 617 621-0700
Fax: +1 617 374-9391
Email: support@InterSystems.com

Table of Contents
Preface ................................................................................................................................................ 1
1 Introducing Zen .............................................................................................................................. 3
1.1 The Zen Demo ....................................................................................................................... 3
1.2 Supported Browsers ............................................................................................................... 4
1.3 Benefits of Zen ....................................................................................................................... 4
1.4 Background Reading .............................................................................................................. 5
2 Zen Tutorial .................................................................................................................................... 7
2.1 Hello World ............................................................................................................................ 7
2.2 Creating a Zen Application .................................................................................................... 9
2.3 Creating a Zen Page ............................................................................................................. 10
2.3.1 Step 1: New Page Wizard .......................................................................................... 10
2.3.2 Step 2: XData Contents Block ................................................................................... 13
2.3.3 Step 3: Client-Side Method ....................................................................................... 15
2.3.4 Step 4: Viewing the HTML Output ............................................................................ 17
2.3.5 Step 5: Server-Side Method ....................................................................................... 17
2.4 Creating a Zen Report .......................................................................................................... 20
2.5 Zen Naming Conventions .................................................................................................... 22
2.6 Zen Sample Applications ..................................................................................................... 23
2.7 Zen Wizards ......................................................................................................................... 24
3 Zen Client and Server .................................................................................................................. 25
3.1 Zen and Caché Server Pages ................................................................................................ 25
3.2 Zen Pages at Runtime .......................................................................................................... 27
4 Zen Application Concepts ............................................................................................................ 31
4.1 Zen Applications .................................................................................................................. 31
4.2 Zen Pages ............................................................................................................................. 33
4.3 Zen Components .................................................................................................................. 34
5 Zen Component Concepts ........................................................................................................... 37
5.1 Page ...................................................................................................................................... 38
5.2 Layout .................................................................................................................................. 39
5.3 Style ..................................................................................................................................... 40
5.4 Behavior ............................................................................................................................... 40
5.5 Customization ...................................................................................................................... 41
6 Zen Layout .................................................................................................................................... 43
6.1 XData Contents .................................................................................................................... 44
Using Zen
iii

6.2 Pages .................................................................................................................................... 45
6.3 Titles ..................................................................................................................................... 45
6.3.1 Simple Titles .............................................................................................................. 46
6.3.2 Complex Titles ........................................................................................................... 47
6.4 Groups .................................................................................................................................. 48
6.4.1 Layout Strategy .......................................................................................................... 48
6.4.2 Simple Group Components ........................................................................................ 48
6.4.3 Menu Components ..................................................................................................... 49
6.4.4 Complex Group Components .................................................................................... 50
6.4.5 Group Layout and Style Attributes ............................................................................ 50
6.5 Template Pages ..................................................................................................................... 53
6.6 Panes .................................................................................................................................... 54
6.7 Generated HTML ................................................................................................................. 56
7 Zen Style ........................................................................................................................................ 57
7.1 Component Style Attributes ................................................................................................. 57
7.2 Enclosing Element ..................................................................................................... 60
7.3 XData Style .......................................................................................................................... 61
7.4 Inheritance of Styles ............................................................................................................ 62
7.5 Cascade of Styles ................................................................................................................. 63
7.6 Overriding Built-in Styles .................................................................................................... 65
7.6.1 Finding the CSS Style Name ..................................................................................... 66
7.6.2 Overriding a CSS Style Rule ..................................................................................... 67
7.7 Applying New Styles ........................................................................................................... 69
8 Zen Tables ..................................................................................................................................... 71
8.1 .......................................................................................................................... 72
8.2 Data Sources ........................................................................................................................ 73
8.2.1 Specifying an SQL Query .......................................................................................... 74
8.2.2 Generating an SQL Query ......................................................................................... 74
8.2.3 Referencing a Class Query ........................................................................................ 76
8.2.4 Using a Callback Method .......................................................................................... 76
8.3 Query Parameters ................................................................................................................. 80
8.4 Table Columns ..................................................................................................................... 81
8.5 Table Style ............................................................................................................................ 83
8.6 Conditional Style for Rows or Cells .................................................................................... 85
8.7 Snapshot Mode ..................................................................................................................... 87
8.7.1 Fetching Data From the Server .................................................................................. 88
8.7.2 Navigating Snapshot Tables ....................................................................................... 89
8.8 Column Filters ..................................................................................................................... 90
8.9 Column Links ....................................................................................................................... 93
8.10 User Interactions ................................................................................................................ 95
iv
Using Zen

8.10.1 Navigation Buttons .................................................................................................. 95
8.10.2 Navigation Keys ....................................................................................................... 95
8.10.3 Sorting Tables .......................................................................................................... 96
8.10.4 Selecting Rows and Columns .................................................................................. 96
8.11 Table Refresh ..................................................................................................................... 98
8.12 Table Touchups .................................................................................................................. 99
9 Zen and SVG ............................................................................................................................... 101
9.1 SVG Component Layout .................................................................................................... 102
9.1.1 ............................................................................................................. 102
9.1.2 ............................................................................................................. 109
9.1.3 ............................................................................................................ 109
9.1.4 ....................................................................................................................... 109
9.2 SVG Component Attributes ............................................................................................... 110
9.3 Meters ................................................................................................................................ 112
9.3.1 Providing Data for Meters ....................................................................................... 112
9.3.2 Meter Attributes ....................................................................................................... 113
9.3.3 ............................................................................................................ 115
9.3.4 ..................................................................................................... 116
9.3.5 ................................................................................................................ 117
9.3.6 .................................................................................................................. 119
9.3.7 ......................................................................................................... 119
9.3.8 .......................................................................................................... 121
9.4 Charts ................................................................................................................................. 121
9.5 .............................................................................................................. 122
9.6 .................................................................................................................... 125
10 Zen Charts ................................................................................................................................ 127
10.1 Types of Chart .................................................................................................................. 129
10.1.1 Line Charts ............................................................................................................. 129
10.1.2 Bar Charts .............................................................................................................. 131
10.1.3 Difference Charts ................................................................................................... 133
10.1.4 High/Low Charts .................................................................................................... 134
10.1.5 Scatter Diagrams .................................................................................................... 136
10.1.6 Pie Charts ............................................................................................................... 137
10.2 Providing Data for Charts ................................................................................................ 141
10.2.1 Limiting the Data Set ............................................................................................. 142
10.2.2 Using a JavaScript Method .................................................................................... 143
10.2.3 Using a Data Controller ......................................................................................... 144
10.3 Chart Attributes ................................................................................................................ 145
10.3.1 Layout and Style .................................................................................................... 145
10.3.2 Plot Area ................................................................................................................ 146
Using Zen
v

10.3.3 Markers .................................................................................................................. 148
10.3.4 Legends .................................................................................................................. 149
10.3.5 Titles ...................................................................................................................... 150
10.3.6 User Selections ...................................................................................................... 151
10.4 Chart Axes ........................................................................................................................ 152
11 Zen Forms ................................................................................................................................. 155
11.1 Forms and Controls .......................................................................................................... 155
11.2 User Interactions .............................................................................................................. 158
11.3 Defining a Form ............................................................................................................... 158
11.4 Providing Values for a Form ............................................................................................ 161
11.5 Detecting Modifications to the Form .............................................................................. 162
11.6 Validating a Form ............................................................................................................. 162
11.7 Errors and Invalid Values ................................................................................................. 163
11.8 Processing a Form Submit ............................................................................................... 164
11.9 User Login Forms ............................................................................................................ 166
11.10 Dynamic Forms .............................................................................................................. 166
12 Zen Controls ............................................................................................................................. 169
12.1 Control Attributes ............................................................................................................. 170
12.2 Control Methods .............................................................................................................. 173
12.3 Buttons ............................................................................................................................. 174
12.3.1 ................................................................................................................. 174
12.3.2 ................................................................................................................. 174
12.3.3 ................................................................................................................ 175
12.4 Text ................................................................................................................................... 176
12.4.1 ................................................................................................................... 176
12.4.2 ..................................................................................................................... 176
12.4.3 .............................................................................................................. 177
12.4.4 ............................................................................................................ 177
12.5 Simple Choices ................................................................................................................ 178
12.5.1 ............................................................................................................ 178
12.5.2 .......................................................................................................... 179
12.5.3 ........................................................................................................ 180
12.5.4 .............................................................................................................. 180
12.5.5 ........................................................................................................ 183
12.6 Lists .................................................................................................................................. 184
12.6.1 .................................................................................................................. 185
12.6.2 ............................................................................................................... 188
12.6.3 ....................................................................................................... 189
12.6.4 .......................................................................................................... 191
12.6.5 ........................................................................................................ 195
vi
Using Zen

12.7 Calendars .......................................................................................................................... 202
12.7.1 ............................................................................................................. 202
12.7.2 ............................................................................................................. 205
12.8 Hidden Items .................................................................................................................... 207
12.9 Spreadsheet ...................................................................................................................... 207
12.9.1 Data Set ............................................................................................. 208
12.9.2 Methods ............................................................................................. 210
12.9.3 ............................................................................................................. 212
12.9.4 ........................................................................................................ 213
12.9.5 Attributes ........................................................................................... 215
13 Model View Controller ............................................................................................................. 219
13.1 Architecture ...................................................................................................................... 219
13.1.1 Data Model ............................................................................................................ 220
13.1.2 Data Controller ...................................................................................................... 222
13.1.3 Data View ............................................................................................................... 225
13.2 Constructing a Model ....................................................................................................... 228
13.2.1 Step 1: Type of Model ............................................................................................ 228
13.2.2 Step 2: Object Data Model .................................................................................... 229
13.3 Binding a to an Object Data Model .................................................................... 230
13.3.1 Step 1: Data Controller .......................................................................................... 231
13.3.2 Step 2: Data View .................................................................................................. 231
13.3.3 Step 3: Initial Results ............................................................................................. 232
13.3.4 Step 4: Saving the Form ......................................................................................... 232
13.4 Adding Behavior to the ....................................................................................... 234
13.4.1 Step 1: Opening a New Record .............................................................................. 234
13.4.2 Step 2: Creating and Deleting Records .................................................................. 236
13.5 with an Object Data Model ........................................................................ 238
13.5.1 Step 1: is Easy .................................................................................. 238
13.5.2 Step 2: Converting to ....................................................................... 239
13.5.3 Step 3: Automatic Control Selection ..................................................................... 241
13.6 with an Adaptor Data Model ...................................................................... 244
13.6.1 Step 1: Generating the Form .................................................................................. 245
13.6.2 Step 2: Property Parameters ................................................................................... 246
13.6.3 Step 3: Adding Behavior to the ........................................................ 247
13.6.4 Step 4: Virtual Properties ....................................................................................... 249
13.7 Data Model Classes .......................................................................................................... 251
13.7.1 Data Model Class Properties ................................................................................. 252
13.7.2 Data Model Class Parameters ................................................................................ 252
13.7.3 Data Model Property Parameters ........................................................................... 253
13.7.4 Object Data Model Callback Methods ................................................................... 254
Using Zen
vii

13.7.5 Virtual Properties ................................................................................................... 256
13.7.6 Controller Actions .................................................................................................. 258
13.7.7 Data Model Series .................................................................................................. 258
13.7.8 Custom Data Model Classes .................................................................................. 260
14 Navigation Components ........................................................................................................... 261
14.1 Links ................................................................................................................................ 263
14.1.1 ..................................................................................................................... 263
14.1.2 .......................................................................................................... 265
14.1.3 ........................................................................................................ 266
14.2 Menus ............................................................................................................................... 267
14.2.1 ........................................................................................................... 268
14.2.2 , , and ........................................................................ 270
14.2.3 ................................................................................................... 271
14.3 Tabs .................................................................................................................................. 271
14.3.1 ............................................................................................................ 272
14.3.2 ..................................................................................................... 275
14.3.3 ...................................................................................................................... 278
14.4 Expanding Group ............................................................................................................. 279
15 Popup Windows and Dialogs ................................................................................................... 285
15.1 Modal Groups .................................................................................................................. 285
15.1.1 Static Modal Groups .............................................................................................. 286
15.1.2 Dynamic Modal Groups ........................................................................................ 288
15.1.3 Built-in Modal Groups ........................................................................................... 291
15.1.4 The show Method .................................................................................................. 295
15.1.5 Attributes ...................................................................................... 296
15.2 Popup Windows ............................................................................................................... 298
15.3 Dialogs ............................................................................................................................. 299
15.3.1 File Selection Dialog Window ............................................................................... 300
15.3.2 Color Selection Dialog Window ............................................................................ 300
15.3.3 Creating a Dialog Window ..................................................................................... 301
15.3.4 Creating a Dialog Window Template ..................................................................... 302
16 Other Zen Components ........................................................................................................... 305
16.1 HTML Content ................................................................................................................. 305
16.2 Framed Content ................................................................................................................ 307
16.3 Page Timer ....................................................................................................................... 308
16.4 Field Sets .......................................................................................................................... 309
16.5 Color Selector .................................................................................................................. 311
16.6 Repeating Group .............................................................................................................. 313
16.7 Dynamic Tree ................................................................................................................... 316
viii
Using Zen

16.7.1 Defining a Tree Using a Global ............................................................................. 316
16.7.2 Defining a Tree Using a Callback .......................................................................... 317
16.7.3 Attributes ........................................................................................... 320
16.8 Dynamic View .................................................................................................................. 322
16.8.1 Defining a View Using a Callback ......................................................................... 322
16.8.2 Attributes .......................................................................................... 324
17 Custom Components ................................................................................................................ 327
17.1 Building Composite Components .................................................................................... 328
17.1.1 The composite Property ......................................................................................... 330
17.1.2 Composites and Panes ........................................................................................... 330
17.2 Overriding Component Style ........................................................................................... 331
17.3 Creating Custom Components ......................................................................................... 331
17.3.1 Package and Namespace ........................................................................................ 333
17.3.2 Base Class .............................................................................................................. 333
17.3.3 Zen Component Wizard ........................................................................................ 334
17.4 Custom Style .................................................................................................................... 334
17.4.1 XData SVGStyle .................................................................................................... 336
17.4.2 XData SVGDef ...................................................................................................... 336
17.4.3 Zen Color Definitions ............................................................................................ 337
17.5 Custom Properties ............................................................................................................ 337
17.5.1 Naming Conventions ............................................................................................. 337
17.5.2 XML Projection ..................................................................................................... 338
17.5.3 setProperty Method ................................................................................................ 338
17.5.4 Datatype Parameters .............................................................................................. 338
17.5.5 Datatype Classes .................................................................................................... 340
17.6 Custom Methods .............................................................................................................. 342
17.6.1 %DrawHTML ........................................................................................................ 343
17.6.2 Helper Methods for %DrawHTML ....................................................................... 344
17.6.3 Identifying HTML Elements ................................................................................. 346
17.6.4 Finding HTML Elements ....................................................................................... 347
17.6.5 Setting HTML Attribute Values ............................................................................. 348
17.6.6 Attaching Event Handlers to HTML Elements ..................................................... 348
17.6.7 HTML for Dynamic Components ......................................................................... 350
17.7 Examples of Custom Components ................................................................................... 351
17.8 Creating Custom Meters .................................................................................................. 353
17.8.1 Custom Meters in XData Contents ........................................................................ 354
17.8.2 Odometer Meter Example ...................................................................................... 354
17.8.3 Clock Meter Example ............................................................................................ 356
18 Zen Application Programming ................................................................................................ 361
18.1 Zen Classes as CSP Classes ............................................................................................. 361
Using Zen
ix

18.2 Zen Application Classes ................................................................................................... 362
18.3 Zen Page Classes .............................................................................................................. 363
18.3.1 Zen Page Parameters .............................................................................................. 363
18.3.2 Zen Special Variables ............................................................................................. 364
18.3.3 Zen Runtime Expressions ...................................................................................... 368
18.3.4 Zen Page Properties ............................................................................................... 371
18.3.5 Zen Utility Methods .............................................................................................. 371
18.3.6 Client-Side Functions and Variables ...................................................................... 372
18.3.7 Zen Page URI Parameters ...................................................................................... 373
18.3.8 Zen Page Event Handling ...................................................................................... 374
18.4 Zen Properties on Client and Server ................................................................................ 374
18.5 Zen Methods .................................................................................................................... 375
18.5.1 Synchronous and Asynchronous Methods ............................................................. 376
18.5.2 Server-Side Callback Methods .............................................................................. 376
18.5.3 Server-Only Methods ............................................................................................. 378
18.5.4 Type Conversion for Server-Side Methods ............................................................ 378
18.5.5 Background Tasks on the Server ............................................................................ 379
18.5.6 Client-Side Page Callback Methods ...................................................................... 379
18.5.7 Client-Side Page Methods ..................................................................................... 380
18.5.8 Client-Side Component Methods .......................................................................... 381
18.6 Zen Page Contents ........................................................................................................... 381
18.6.1 Defining Page Contents Using XML ..................................................................... 382
18.6.2 XML Namespaces .................................................................................................. 382
18.6.3 Defining Page Contents Programmatically ............................................................ 382
18.6.4 Zen Layout Handler ............................................................................................... 383
18.7 Sample Development Project ........................................................................................... 384
19 Zen Security .............................................................................................................................. 391
19.1 Controlling Access to Applications .................................................................................. 391
19.2 Controlling Access to Pages ............................................................................................. 392
19.3 Controlling Access to Components .................................................................................. 392
20 Zen Localization ....................................................................................................................... 395
20.1 CSP Localization ............................................................................................................. 395
20.1.1 Localization Practices ............................................................................................ 395
20.1.2 Message Dictionary ............................................................................................... 396
20.1.3 $$$Text Macros ..................................................................................................... 396
20.2 Zen Localization .............................................................................................................. 400
20.2.1 Localization for Built-In Components ................................................................... 400
20.2.2 Localization for Custom Components ................................................................... 401
21 Zen Reports ............................................................................................................................... 403
x
Using Zen

21.1 Building a Report ............................................................................................................. 405
21.2 Zen Report Parameters ..................................................................................................... 410
21.3 XData ReportDefinition ................................................................................................... 413
21.3.1 The %val Variable .................................................................................................. 414
21.3.2 ................................................................................................................. 414
21.3.3 .............................................................................................................. 414
21.3.4 .............................................................................................................. 415
21.3.5 ........................................................................................................... 415
21.3.6 .................................................................................................................. 418
21.4 XData ReportDisplay ....................................................................................................... 421
21.4.1 Dimension and Size ............................................................................................... 423
21.4.2 ................................................................................................................. 423
21.4.3 ........................................................................................................... 424
21.4.4 ......................................................................................................... 427
21.4.5 .......................................................................................................... 427
21.4.6 ................................................................................................................... 427
21.5 Layout and Display Elements .......................................................................................... 427
21.5.1 .................................................................................................................. 429
21.5.2 .................................................................................................................. 429
21.5.3 and .......................................................................................... 430
21.5.4 ..................................................................................................................... 430
21.5.5 .................................................................................................................... 431
21.5.6 ..................................................................................................................... 432
21.5.7 ...................................................................................................................... 433
21.5.8 ......................................................................................................................... 434
21.5.9 .......................................................................................................... 434
21.5.10 ................................................................................................................. 434
21.6 Charts in Zen Reports ...................................................................................................... 436
21.7 Stylesheet Control Elements ............................................................................................ 437
21.7.1 ........................................................................................................................ 437
21.7.2 .................................................................................................................... 438
21.7.3 ................................................................................................................... 438
21.8 Zen Reports from a Web Browser .................................................................................... 438
21.8.1 Sample XHTML Output ........................................................................................ 439
21.8.2 Sample XML Data View ........................................................................................ 440
21.9 Configuring Zen for PDF Output ..................................................................................... 440
21.10 Troubleshooting Zen Reports ......................................................................................... 441
21.11 Zen Reports from a Command Line .............................................................................. 443
22 Zen Wizards .............................................................................................................................. 445
22.1 New Zen Application Wizard ........................................................................................... 445
Using Zen
xi

22.2 New Zen Component Wizard ........................................................................................... 446
22.3 New Zen Page Wizard ...................................................................................................... 447
22.4 New Zen Report Wizard ................................................................................................... 448
22.5 Studio Assist ..................................................................................................................... 450
22.6 Zen Chart Wizard ............................................................................................................. 450
22.7 Zen Element Wizard ......................................................................................................... 452
22.8 Zen Method Wizard ......................................................................................................... 453
22.9 Zen Style Wizard .............................................................................................................. 455
Index ............................................................................................................................................... 459
xii
Using Zen

List of Figures
How to Access the Sample Zen Code in Studio ................................................................................ 24
How Caché Server Pages Work ......................................................................................................... 26
How Zen Pages Work ........................................................................................................................ 30
Zen Application with Pages and Components ................................................................................... 32
Zen Page Synchronized on Client and Server at Runtime ................................................................ 33
Defining the Look and Feel of a Zen Page ........................................................................................ 34
Use of Panes on a Zen Page .............................................................................................................. 55
Cascade of Style Definitions ............................................................................................................. 65
Layout Conventions for Zen Charts ................................................................................................ 128
How Zen Plots Pie Charts by Item .................................................................................................. 139
How Zen Plots Pie Charts by Series ................................................................................................ 140
Zen Pie Chart from Both Items and Series ...................................................................................... 141
Data Series Count and Size ............................................................................................................. 143
Class Inheritance Among Form and Control Components .............................................................. 157
Data Model for the Dynamic Grid Control ..................................................................................... 210
Model View Controller Architecture ............................................................................................... 220
Data Model Classes ......................................................................................................................... 221
Data Controller and Data View Classes .......................................................................................... 223
Data Model with Name-Value Pairs ................................................................................................ 258
Data Model with Data Series .......................................................................................................... 259
Zen Navigation Components ........................................................................................................... 263
Base Classes for Custom Components ............................................................................................ 334
Sample Log of Zen Events .............................................................................................................. 372
How a Zen Report Class Produces a Report ................................................................................... 404
XSL-FO to PDF Transformation Log ............................................................................................. 442
XSL-FO Prior to PDF Rendering .................................................................................................... 443
Using Zen
xiii

List of Tables
Naming Conventions ......................................................................................................................... 22
Component Concepts ........................................................................................................................ 38
Group Layout and Style Attributes .................................................................................................... 51
Component Style Attributes .............................................................................................................. 57
Where and How to Override Built-in Styles ..................................................................................... 68
QueryInfo Properties ......................................................................................................................... 78
predicate Values ............................................................................................................ 86
SVG Component Attributes ............................................................................................................ 110
Meter Component Attributes ........................................................................................................... 113
Chart Layout and Style Attributes ................................................................................................... 146
Chart Axis Attributes ....................................................................................................................... 152
Form Component Attributes ............................................................................................................ 158
Form Submit Sequence ................................................................................................................... 165
Control Component Attributes ........................................................................................................ 170
List Box Component Attributes ....................................................................................................... 189
Combo Box Component Attributes ................................................................................................. 193
Display Sequence .................................................................................................... 201
Controls Based on Property Types ............................................................................ 244
Data Model Class Parameters ......................................................................................................... 253
Data Model Property Parameters .................................................................................................... 253
Object Data Model Callback Methods ............................................................................................ 255
Custom Data Model Class Methods ................................................................................................ 260
Menu Cell Attributes ....................................................................................................................... 268
Tab Group Attributes ....................................................................................................................... 275
Options for Extending Zen .............................................................................................................. 328
Extending Zen with Composite Components ................................................................................. 328
Extending Zen with Custom Components ...................................................................................... 332
Custom Component Base Classes ................................................................................................... 333
Datatype Classes ............................................................................................................................. 340
Component Class Method Conventions .......................................................................................... 343
Extending Zen with Custom Meters ............................................................................................... 353
Application Class Elements ............................................................................................................ 362
Page Class Parameters ..................................................................................................................... 364
Special Variables on the Server Side ............................................................................................... 365
Client-Side Functions and Variables ............................................................................................... 373
Page Class Method Conventions ..................................................................................................... 375
Page Class Server-side Callback Methods ...................................................................................... 377
xiv
Using Zen

Page Class Server Methods ............................................................................................................. 378
Page Class Client-side Callback Methods ....................................................................................... 380
Page Class Client-side Methods ...................................................................................................... 380
Page Class Client-side Component Methods .................................................................................. 381
Report Class Parameters .................................................................................................................. 411
Report Display Attributes ................................................................................................................ 428
Using Zen
xv

Preface
This book is intended for Web application developers. It describes how to use Zen, the InterSystems
framework for Web application development.
General Information
The first several chapters in the book provide the general information required to become productive
with Zen. Readers who are new to Zen should read the following chapters in sequence:
• Introducing Zen
• Zen Tutorial
• Zen Client and Server
• Zen Application Concepts
Experienced Zen programmers can choose specific topics from among the remaining chapters.
Introducing Zen Components
Zen provides a large set of Web page components and a variety of mechanisms for laying them out
on the page. The following chapters provide information that applies to all Zen components:
• Zen Component Concepts
• Zen Layout
• Zen Style
Essential Zen Components
The following chapters provide details about the most essential built-in Zen components:
• Zen Tables
• Zen and SVG
• Zen Charts
• Zen Forms
• Zen Controls
Complex Zen Components
The following chapters describe the more complex Zen components, and explain how to extend the
Zen component library with custom code.
Using Zen 1

Preface
• Model View Controller
• Navigation Components
• Popup Windows and Dialogs
• Other Zen Components
• Custom Components
Developing Zen Applications
The following chapters describe additional programming issues relating to Zen:
• Zen Application Programming
• Zen Security
• Zen Localization
• Zen Reports
• Zen Wizards
2 Using Zen

1
Introducing Zen
Welcome to Zen!
The Zen application framework provides a simple way to rapidly create complex, data-rich Web
applications by assembling pre-built object components. These components automatically create
standard HTML and JavaScript needed to render complex Web applications. Moreover, they provide
a common object model that is shared between the user’s browser and the application logic running
on the server.
Zen is based on InterSystems’ successful Caché Server Page (CSP) and Caché Object Database technologies.
These technologies offer a robust, scalable, and portable platform for hosting Web applications.
Zen does not replace or deprecate Caché Server Pages in any way. Instead, Zen makes the development
of web-based applications easier while building upon the basic features provided by CSP: performance,
data access, security, localization, and configuration.
1.1 The Zen Demo
Zen includes a sample application, which you can try out as follows:
1. Start your browser. You may use Firefox or Internet Explorer.
2. Enter this URI:
http://localhost:57772/csp/samples/ZENDemo.Home.cls
Where 57772 is the Web server port number that you have assigned to Caché.
If you are unsure of the port number, start the System Management Portal. At the top of the page,
click About. View the Web Server Port setting.
Using Zen 3

Introducing Zen
1.2 Supported Browsers
The browser you use with Zen must support SVG (Scalable Vector Graphics). Zen supports the following
browsers:
• Firefox 1.5 or later. This download is available from:
http://www.mozilla.com/firefox/
Support for SVG is built into Firefox.
• Internet Explorer 6.0 or later.
IE 6.0 does not support SVG natively, so you must download the free SVG Viewer from this
Adobe site:
http://www.adobe.com/svg/
Note:
InterSystems recommends that you use Firefox as your primary development browser, and
reserve Internet Explorer for compatibility testing. Firefox offers better JavaScript and HTML
troubleshooting options and can help track down programming problems. This is especially
true if you use some of the many developer plug-ins available for Firefox.
1.3 Benefits of Zen
The benefits of using Zen include:
• Rapid Development—Assembling applications from pre-built components is a proven method for
creating user interfaces rapidly. Zen makes it possible to use this approach for Web-based applications.
• Simplicity—Zen uses a standard HTML client, so there are no additional client components
required. There is no “middle” tier between server and client, so Zen applications are much easier
to develop, deploy, and support.
• Extensive Library of Components—The Zen library comes with a large set of pre-built components.
These include all the standard control types as well as data-aware combo boxes, tables, grids, tabs,
tree controls, menus, and grouping components.
• Object Database Integration—Zen is tightly integrated with the underlying Caché object database.
The Zen client and server communicate by sending objects back and forth. Underlying details
such as encryption and data marshalling are handled automatically using proven Caché technology.
4 Using Zen

Background Reading
• Code Generation—Much of the code and business logic is generated automatically from higherlevel
models, ensuring consistency and rapid development.
• Extensibility—You can easily modify the look and feel of Zen applications by using standard CSS
style sheets; by supplying different property values for the Zen components; or by creating your
own custom components.
• Integrated use of SVG—Zen lets you add interactive graphics to Web applications by means of a
set of SVG (Scalable Vector Graphics) components. These components include pre-built charts
and meters. In addition, you can create new graphical components.
• Client Independence—Zen applications run in either Firefox or Internet Explorer. The Zen components
insulate applications from the differences in behavior of these browsers.
• Security—Zen offers tight integration with the security model provided by the Caché object
database.
• Form Handling—The Zen framework lets you define forms that contain a variety of controls for
displaying and editing of data. The framework includes extensible support for loading data into
forms; validating the contents of forms; and saving form contents.
• Page Layout—Zen includes an extensible framework for specifying the grouping and layout of
components on a Web page.
• Event Management—Zen applications can easily define how their components respond to user
events. All events are handled by invoking methods that can be defined to run within the client
browser or on the data server.
• Multilingual Support—For applications that must support multiple languages, Zen includes a
mechanism that tracks which titles and captions need to be localized, and automatically builds a
database of these values. This database can be exported as XML and given to a translator for
conversion into other languages. At runtime, Zen automatically displays pages in the user’s preferred
language.
• Document Output—Zen includes an extensible framework for specifying the data contents and
display layout of reports in XHTML or PDF format.
1.4 Background Reading
Before using Zen, you need a good understanding of the following topics:
• HTML, JavaScript, and Cascading Style Sheets (CSS).
Many excellent books are available through the Internet and commercial bookstores.
• Caché, Caché Objects, Caché Server Pages, and Caché SQL.
Using Zen 5

Introducing Zen
Depending on your level of experience, you might want to review the following books from the
InterSystems online documentation category Caché Development Guides:
- Using Caché Objects
- Using Caché ObjectScript
- Using Caché Server Pages (CSP)
- Using Caché SQL
6 Using Zen

2
Zen Tutorial
This chapter describes how to create some simple Web pages using Zen. The chapter is organized as
a step-by-step tutorial. Topics include:
• Hello World
• Creating a Zen Application
• Creating a Zen Page
• Creating a Zen Report
• Zen Naming Conventions
• Zen Sample Applications
2.1 Hello World
The following steps display “Hello world!” on a Zen page:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4.
Choose File > New or Ctrl-N or the
5. Click the Custom tab.
6. Click the New Zen Page icon.
icon.
7. Click OK.
Using Zen 7

Zen Tutorial
8. For Package Name choose ZENDemo.
9. In the Class Name field, type:
hello
10. For Application Name choose ZENDemo.Application.
11. Click Next.
12. Click Finish.
13. Position the cursor at the start of this line:
14. Press Enter.
15. Move the cursor up to the blank line.
16. Type a left angle bracket:
<
A context-sensitive list of XML elements displays.
17. Click button.
18. Press Enter.
19. Type a space. A context-sensitive list of XML attributes displays.
20. Click caption.
21. Press Enter.
22. Type:
23.
24.
Hello world!"/>
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the
icon.
icon.
Your simple new Zen page displays “Hello world!” on the face of a button.
25. Also try steps 13–24 with:
If you encounter difficulties during this exercise, return to The Zen Demo and Supported Browsers in
the previous chapter. These topics provide useful background information for getting started with Zen.
8 Using Zen

Creating a Zen Application
2.2 Creating a Zen Application
A Zen application class extends %ZEN.application to provide application-wide styling behavior. In this
exercise you will create a Zen new application class, as follows:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4.
Choose File > New or Ctrl-N or the
5. Select the Custom tab.
6. Click the New Zen Application icon.
icon.
7. Click OK.
The Zen Application Wizard presents the fields shown in the following table. For this exercise,
enter the values shown in the right-hand column of the table.
Field
Package Name
Class Name
Application Name
Description
Meaning
The package that will contain
the new application class.
The class name of the new
application class.
The logical name of the
application.
Any text that you want to use
to describe the application.
Value to Enter
MyApp
MyNewApp
My New Zen Application
This is my first new Zen
application.
Click Finish.
8. The Zen Application Wizard creates and displays a skeletal application class. It includes some
pre-defined class parameters and an XData Style block as follows:
Using Zen 9

Zen Tutorial
/// This is my first new Zen application.
Class MyApp.MyNewApp Extends %ZEN.application
{
/// This is the name of this application.
Parameter APPLICATIONNAME = "My New Zen Application";
/// This is the URL of the main starting page of this application.
Parameter HOMEPAGE = "";
/// This Style block contains application-wide CSS style definitions.
XData Style
{
}
}
9.
Choose Build > Compile or Ctrl-F7 or the
icon.
2.3 Creating a Zen Page
A Zen page class extends %ZEN.Component.page to define the contents and behavior of a Web page.
In this exercise you will create a new Zen page class in several steps.
2.3.1 Step 1: New Page Wizard
Create the new class as follows:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4.
Choose File > New or Ctrl-N or the
5. Select the Custom tab.
6. Click the New Zen Page icon.
icon.
7. Click OK.
The Zen Page Wizard presents the fields shown in the following table. For this exercise, enter the
values shown in the right-hand column of the table.
10 Using Zen

Creating a Zen Page
Field
Package Name
Class Name
Application
Page Name
Domain
Description
Page type
Meaning
The package that will
contain the page class.
The page class name.
The package and class
name of the application
that this page belongs to.
The logical name of this
page within its application.
The domain this page will
use for localization of
caption text.
Any text that you want to
use to describe the page.
Regular page, or subclass
of a template page class.
Value to Enter
MyApp
MyNewPage
MyApp.MyNewApp
My Home Page
For this exercise, leave the Domain field
empty.
My very first Zen page class.
For this exercise, leave the Page type
field with its default selection of Page.
Click Next.
8. The wizard prompts you to select an initial page layout, for example:
• Column 2 — two columns, plus space for a title along the top
• Title Page — space for a title along the top
• Default — no pre-defined layout
For this exercise, click Title Page. Then click Finish.
9. The New Page Wizard creates and displays a skeletal Zen page with pre-defined class parameters
and the XML blocks XData Style and XData Contents, as follows:
Using Zen 11

Zen Tutorial
/// My very first Zen page class.
Class MyApp.MyNewPage Extends %ZEN.Component.page
{
/// Class name of application this page belongs to.
Parameter APPLICATION = "MyApp.MyNewApp";
/// Displayed name of this page.
Parameter PAGENAME = "My Home Page";
/// Domain used for localization.
Parameter DOMAIN = "";
/// This Style block contains page-specific CSS style definitions.
XData Style
{
/* style for title bar */
#title {
background: #C5D6D6;
color: black;
font-family: Verdana;
font-size: 1.5em;
font-weight: bold;
padding: 5px;
border-bottom: 1px solid black;
text-align: center;
}
}
/// This XML block defines the contents of this page.
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
}
Title
The XML blocks in this page class work together as follows:
• XData Style defines a style rule called #title that defines a background color, padding,
borders, and font characteristics for HTML output.
• XData Contents provides an XMLNamespace keyword. The value
http://www.intersystems.com/zen enables the Studio Assist type-ahead feature for
built-in Zen components. You first experienced this feature during the Hello World exercise.
• XData Contents uses the element to define a page object.
• XData Contents uses the element to define a simple HTML excerpt for display in the
browser. The id value title creates the connection between the html object and the #title
rule from XData Style. The html object formats a string of text, Title. The resulting output
functions as a simple title bar for the page.
• XData Contents provides an empty . Later exercises add components here.
12 Using Zen

Creating a Zen Page
10.
Choose Build > Compile or Ctrl-F7 or the
11.
Choose View > Web Page or the icon.
Your new Zen page displays as follows:
icon.
If you encounter difficulties when displaying any Zen page from Studio, you can display the page by
opening a browser session and entering a URI in this format:
http://localhost:57772/csp/samples/MyApp.MyNewPage.cls
Where:
• 57772 is the Web server port number assigned to Caché
• samples is the namespace that contains the Zen page class (all-lowercase)
• MyApp.MyNewPage is the Zen page package and class name (case-sensitive)
2.3.2 Step 2: XData Contents Block
In this exercise you will modify the element to add a simple button to the page. You can do
this by typing text into the XData Contents block, or by using templates to generate a element
with the correct syntax. This exercise uses both techniques:
1. In Studio, open the page class.
2. Select the text Title within the element. Replace Title with a meaningful string, for
example:
Zen Exercise Results
3. Remove this line just after the element:
Place the cursor between and .
4. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Templates dialog.
Choose Zen Element Wizard. Click OK.
5. In the drop-down list of XML elements, choose button. Click Next. Add properties as follows:
• In the caption row, click Edit. Enter a string value and click OK. For example:
Using Zen 13

Zen Tutorial
Press Me
• In the id row, click Edit. Enter a string value and click OK. For example:
myButton
• In the onclick row, click Edit. Type a short JavaScript expression. For this exercise, use the
following expression:
zenPage.btnClick();
Click OK.
6. Click Finish. The XData Contents block now looks like this:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
Zen Exercise Results
}
New additions to this XData Contents block accomplish the following:
• Define a button object as a child of the vgroup object. This places the button at the top lefthand
corner of the display, under the title. The button is an instance of the
%ZEN.Component.button class.
• The id value myButton provides a way to find the button object programmatically.
• The caption value Press Me indicates the text that will be displayed on the button when the
page appears.
• The onclick value zenPage.btnClick(); is a JavaScript expression that will be executed
on the client when a user clicks this button.
• At present, when you click this button it does nothing. The next exercise changes this.
7.
8.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the icon.
Your new Zen page displays as follows:
icon.
14 Using Zen

Creating a Zen Page
2.3.3 Step 3: Client-Side Method
In the previous step you added this JavaScript expression to your definition:
zenPage.btnClick();
This expression executes a method called btnClick in an object called zenPage. zenPage is the
JavaScript variable that represents the page object on the client side. btnClick is available to the
JavaScript page object only if you define it in your Zen page class as a client-side method.
In this exercise, you will add a JavaScript client-side method to your Zen page class, as follows:
1. In Studio, open the page class.
2. Position the cursor just below the closing curly brace of the XData Contents block.
3. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Template dialog.
Choose Zen Method Wizard. Click OK. The following dialog displays:
Edit the dialog as follows:
• Enter the name btnClick
• Choose is an instance method
• Choose runs on the client
• Enter a description.
• Uncheck the Try/Catch checkbox.
• Click Finish. Your new method appears in the page class as follows:
Using Zen 15

Zen Tutorial
///What to do if the user clicks this button.
Method btnClick() [Language = JavaScript]
{
// TODO: implement
alert('Client Method');
}
4. Change the code within curly braces so the method now looks like this:
5.
6.
///What to do if the user clicks this button.
Method btnClick() [Language = JavaScript]
{
alert('Hello, World!');
}
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the
icon.
icon.
7. Click the “Press Me” button. Your JavaScript alert message displays:
8. Click OK to close the popup.
Some important things to notice about the btnClick method:
• It is defined as an instance method (it does not use the ClassMethod keyword).
• Its Language keyword is set to JavaScript. This means that the implementation of this method
uses JavaScript. Studio syntax-colors and validates this method as JavaScript.
• When this class is compiled, the btnClick method will not be available as a callable method on
the server. It will, however, be made available as an instance method of the zenPage object on
the client.
• The class compiler resolves inheritance. This means that you can define JavaScript methods within
a super class and they will automatically be available to any subclasses. While this is possible to
accomplish in traditional JavaScript, it is also very tedious and error-prone. A lot of the power of
Zen comes from this ability to support inheritance on both the server and client.
• The body of this method uses the standard JavaScript alert method to display a message on the
client.
• At runtime, this method is run within the client (browser) environment.
• The method is defined within the same logical unit (that is, the class) as the page definition that
references it. This makes pages easy to develop and maintain.
16 Using Zen

Creating a Zen Page
2.3.4 Step 4: Viewing the HTML Output
While viewing your Zen page in the browser, use the View Source option to look at the HTML served
by the Zen page. You will see that the Zen page consists of the following elements, from top to bottom:
• A standard HTML header
• A set of included elements such as pre-generated JavaScript (for library components) and CSS
(stylesheet) files.
• Some generated JavaScript utility code (for error detection, timeout management, encrypted server
calls, etc.)
• JavaScript class definitions for any user-defined classes used on this page (such as the page object
itself).
• JavaScript code to create any client-side objects defined by the page. This is a client-side version
of the same objects defined in the page’s XData Contents block.
• HTML needed to display any components that generate HTML (such as the button component).
• If needed, additional JavaScript code to “finalize” the client-side object model.
2.3.5 Step 5: Server-Side Method
In this exercise, you will make a simple modification in your new Zen page. This modification
demonstrates the ability to invoke server logic from within a client page, as follows:
1. In Studio, open the page class.
2. Using techniques from the previous exercises, add a new button inside the XData Contents block.
Give the new button the attribute values listed in the following table.
Attribute
id
caption
onclick
Value to Enter
myButtonToo
No, Me!
zenPage.BtnClickMe();
Your XData Contents block should now resemble this one:
Using Zen 17

Zen Tutorial
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
Zen Exercise Results
}
3. Position the cursor just below the closing curly brace of the XData Contents block.
4. Choose Tools > Templates > Templates or press Ctrl-T to display the Studio Template dialog.
Choose Zen Method Wizard. Click OK. The following dialog displays:
Edit the dialog as follows:
• Enter the name BtnClickMe
• Choose is an instance method
• Choose runs on the server
• Enter a description.
• Uncheck the Try/Catch checkbox.
• Click Finish. Your new method appears in the page class as follows:
///When the user clicks the button, ask
///the server which version it is running.
Method BtnClickMe() [ZenMethod]
{
// TODO: implement
&js
Quit
}
18 Using Zen

Creating a Zen Page
5. Change the code within curly braces so the method now looks like this:
///When the user clicks the button, ask
///the server which version it is running
Method BtnClickMe() [ZenMethod]
{
Set msg = $ZVERSION
&js
Quit
}
6.
7.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the icon.
Your new Zen page displays as follows:
icon.
8. Click the “No, Me!” button. The following popup message appears. It displays the text returned
by the ObjectScript $ZVERSION utility. This text is a full description of the Caché version that
you are running:
9. Click OK to close the popup.
10. Use the View Source option of your browser to look at the HTML.
Some important things to notice about the BtnClickMe method:
• It is defined as an instance method.
• It omits the Language keyword. This means that this method will use the default server scripting
language (ObjectScript or Caché Basic, in this case ObjectScript).
• It executes on the server but (as further notes explain) it also sends a hyperevent to the client.
• It uses the ZenMethod keyword. The ZenMethod keyword means that this is a server-side method
that can be called from the client. Even when this method is called from within the client (browser)
environment, it is still executed on the server.
Using Zen 19

Zen Tutorial
• The method assigns the value of the $ZVERSION utility to the variable msg, then sends msg to
the client so that the user can see the value in a JavaScript alert popup. The statement:
&js< alert('#(msg)#'); >
is an example of embedded JavaScript syntax. While executing your BtnClickMe method on
the server, Zen finds the snippet of JavaScript code between &js< and > and sends this snippet
to the client for execution.
Note:
This behavior is provided by the CSP hyperevent mechanism. For details see the book
Using Caché Server Pages (CSP).
• Within the embedded JavaScript, the syntax:
#(msg)#
is the convention for transferring the value of the variable msg from ObjectScript code executing
on the server to embedded JavaScript executing on the client. For details, see Zen Runtime
Expressions.
• The client-side zenPage object can invoke your server-side BtnClickMe method.
Because you defined BtnClickMe as an instance method, the server needs the current client-side
object’s complete state to be able to execute the method.
When zenPage invokes your server-side method, the client-side implementation of BtnClickMe
gathers up any argument and object context information available on the client side, serializes the
entire page object and sends it through to the server, then invokes the server-side method, all using
the CSP session-encrypted hyperevent mechanism.
• BtnClickMe does not return a value. This is intentional. When you use CSP hyperevents, a method
with no return value automatically runs asynchronously (does not wait for a response). This way,
the user interface does not appear to “freeze” as it would if it had to wait for a method to return a
value.
2.4 Creating a Zen Report
A Zen report page extends %ZEN.Report.reportPage to display a database report. Zen reports support
a variety of useful output formats including XHTML and PDF. In this exercise you will copy and
modify an existing Zen report class and view it as XHTML.
If you have a new Caché installation, you must first generate data records for the SAMPLES namespace.
You only need to do this once per Caché installation. Enter the following URI in the browser:
http://localhost:57772/csp/samples/ZENDemo.Home.cls
20 Using Zen

Where 57772 is the Web server port number that you have assigned to Caché.
Now begin the report exercise as follows:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4. Choose Tools > Copy Class.
Creating a Zen Report
5. The Class Copy dialog presents the fields shown in the following table. For this exercise, enter
the values shown in the right-hand column of the table.
Field
Copy Class
To
Meaning
The class to copy.
The new class to create.
Value to Enter
ZENApp.MyReport
MyApp.MyNewReport
Check the Replace Instances of Class Name box.
Click OK.
6. The new class definition for MyApp.MyNewReport displays in Studio.
7.
8.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the
icon.
9. The report displays a report title and header block, followed by a table of information for each
sales person in the database:
icon.
Using Zen 21

Zen Tutorial
2.5 Zen Naming Conventions
Zen programs are case-sensitive. If you are not experienced with case-sensitive programming, case
might be your biggest adjustment in using Zen. Remember that a is not the same as A.
The following naming conventions apply throughout the Zen code. These conventions use case to
distinguish between different categories of method or property. myMethodName and MyMethodName
are not the same name.
Naming Conventions
Convention
Client-side methods are defined using the Language=JavaScript
key phrase, and are written in JavaScript. They can be called from
the client and, when called, run on the client. These names start
with a lowercase letter and use an initial capital letter for each
successive word (in-word capitalization). The same is true of
client-only properties.
Zen methods are defined using the keyword ZenMethod. They
can be called from the client, but are executed on the server.These
methods are written in ObjectScript or Basic, but they may include
embedded JavaScript that calls back to the client. Their names
start with an uppercase letter and use in-word capitalization.
Server-side methods use no special keyword. They are written
in ObjectScript or Basic. They are available to be called from code
that is executing on the server and, when called, they run on the
server.These method names start with the % character. Server-only
properties use this naming convention too.
Typically, Zen class names start with lowercase and use in-word
capitalization, similar to the conventions for client-side methods
and properties. The exceptions to this rule include some of the
server-only utility classes, which begin with an uppercase letter.
Attribute and property names start with lowercase and use in-word
capitalization, except for event handlers and callbacks.
Attributes that identify event handlers for components follow the
JavaScript convention of all-lowercase.
Attributes that identify server-side callbacks for components start
with On (capital letter O) and use in-word capitalization.
Example
myMethodName
MyMethodName
%MyMethodName
tablePane
filterOp
onmousedown
OnCreateDataSet
22 Using Zen

Zen offers many built-in variables, as described in Zen Application Programming. The most important
of these are the two variables that represent the Zen page object on the client and server sides. These
two variables conform to Zen naming conventions for client and server identifiers, as follows:
• In JavaScript code that runs on the client side, the page object is zenPage
• In ObjectScript or Basic code that runs on the server side, the page object is %page
Zen Sample Applications
2.6 Zen Sample Applications
If you are an experienced Caché user, you are already familiar with the SAMPLES namespace. In
particular, the sample application Cinema is a favorite with users learning about Caché Server Pages
(CSP). Zen offers a large number of sample pages, organized into four packages in the SAMPLES
namespace.
If you have a new Caché installation, you must first generate data records for the SAMPLES namespace.
You only need to do this once per Caché installation. Enter the following URI in the browser:
http://localhost:57772/csp/samples/ZENDemo.Home.cls
Where 57772 is the Web server port number that you have assigned to Caché.
Now you can view the Zen sample code at any time by following these steps:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4. In the Workspace window, choose the Namespace tab and open the Classes category.
Packages ZENApp, ZENDemo, ZENMVC, and ZENTest are available for you to explore.
Using Zen 23

Zen Tutorial
How to Access the Sample Zen Code in Studio
2.7 Zen Wizards
Zen supplies a rich set of application programming wizards that you can run from within Caché Studio.
The exercises in this chapter use several of them. For a complete list and description of the available
options, see the chapter Zen Wizards at the end of this book.
24 Using Zen

3
Zen Client and Server
Zen is a client/server Web technology. The terms client and server are commonly used. This chapter
explains how Zen uses these terms. The topics in this chapter are:
• Zen and Caché Server Pages — A Zen application uses CSP technologies to serve Web pages to
the client browser. This topic summarizes the CSP client/server relationship.
• Zen Pages at Runtime — This topic extends the Zen and CSP discussion to explain how Zen
responds to HTTP requests. Zen responses to XML or SVG follow a similar sequence.
3.1 Zen and Caché Server Pages
Important:
This topic briefly outlines material that fills several chapters in Using Caché Server
Pages (CSP). If you are new to CSP, please study the detailed explanations in the
other book.
Using Caché Server Pages (CSP) describes the relationship between the client and server in CSP
applications. It outlines the flow of events between issuing the HTTP request and displaying the page
in the browser. Zen applications and Zen pages are CSP pages, so all of this information also applies
to Zen.
The following diagram summarizes the interactions between the CSP client and server.
Using Zen 25

Zen Client and Server
How Caché Server Pages Work
Numbers in the previous diagram highlight the flow of events on the client and server while CSP
processes an HTTP request. The sequence is as follows:
1. The browser (or similar Web client) makes an HTTP request.
2. If the Web server determines that this is a CSP request, it dispatches the request to the CSP
Gateway installed on the Web Server.
Alternatively, if the request is for a static file (such as an .html or .jpg file), the Web server finds
the file within the local file system and sends its contents back to the client.
3. The CSP Gateway repackages the request and sends it to the correct Caché server.
26 Using Zen

4. The Caché server decodes the message, determines which event handling class (part of your
application) should process the event, and invokes the OnPage method in that class.
Zen pages are CSP pages, so each Zen page class has an OnPage method. However, Zen pages
offer a much wider selection of potential actions than CSP pages, with a correspondingly rich set
of methods that CSP pages do not provide.
5. The Caché server returns the output of the OnPage method to the CSP Gateway as an HTTP
response.
6. The CSP Gateway hands the HTTP response to the Web server (actually, Caché streams the
response back to the Web Server via the CSP Gateway).
7. The Web server returns the response to the Web browser which then processes the response. In
the case of HTML, it displays the page. There may be other results depending on what type of
data the response contains.
Zen applications use CSP technologies to:
• Filter and respond to HTTP requests.
• Manage sessions and session lifecycle.
• Manage user identity, authentication, and access control.
• Provide the hyperevent mechanism used to call server methods from the client.
• Call from the server to execute code securely on the client.
Zen Pages at Runtime
Important:
If you make use of the CSP session preserve mode, be aware that the server-side Zen
page (%page) and application (%application) objects are not preserved between
server requests.
3.2 Zen Pages at Runtime
A Zen page automatically responds to HTTP requests from a browser and serves up a complete HTML
document to satisfy such a request. Zen pages can also satisfy other types of requests, such as for XML
or SVG content. The behavior for XML or SVG is documented in later chapters. It is similar to the
HTML behavior documented in this chapter.
The following sequence displays a Zen page in a browser window:
1. The Web browser sends an HTTP request that names a specific Zen page. The Caché server
receives the request and automatically routes it to the Zen page class.
Note:
CSP handles this step. Details appear in the previous topic.
Using Zen 27

Zen Client and Server
2. The page class invokes its %OnBeforeCreatePage callback method. This method provides the
opportunity for the application to perform any setup work that may be required before
%CreatePage begins execution.
3. The page class creates an instance of itself on the Caché server.
The page class invokes its class method %CreatePage. This method creates the set of component
objects and adds these objects as children of the page object.
When a Zen page class contains a description of the page in XML format (as described in later
chapters) Zen automatically generates a %CreatePage method whenever the class is compiled.
The compiler uses the information in XData Contents to generate the method.
Alternatively, a programmer may omit the XData Contents block and implement %CreatePage
manually. This more complex option gives the opportunity to create dynamic page content.
4. The page class invokes its %OnAfterCreatePage callback method. In this method, the application
can modify the content generated by %CreatePage in any way that is needed.
After %OnAfterCreatePage completes execution, there is a page object in memory that contains
some number of child component objects. This page object is a document object model (DOM)
that will be used to draw the HTML needed to display the page.
5. The page object constructs an HTML document from its DOM.
The page invokes its %DrawHTML method. Every Zen page and component object has a
%DrawHTML method that knows how to render the object as HTML. In the case of a Zen page,
the %DrawHTML method supplies:
• The page title.
• Any meta-HTML tags needed by the page.
• Any content needed to support hyperevents (the mechanism used to make in-page calls back
to the server).
• Include statements for any required JavaScript or CSS include files.
• JavaScript needed to define the set of client component classes used on the page.
• JavaScript needed to create and initialize the set of client component objects used on the page.
That is, a client-side version of the server-side page object is created.
• Default CSS style definitions defined by the component classes.
• CSS style definitions defined by the application class.
• CSS style definitions defined by the page class. (This order is important as it allows the
application settings to override defaults and page settings to override application settings).
• The HTML content of every component on the page (obtained by invoking the %DrawHTML
method for every component on the page).
28 Using Zen

Zen Pages at Runtime
As with %CreatePage, for the most part a Zen programmer can ignore %DrawHTML. Caché
generates and invokes it automatically. The important fact about %DrawHTML is when it occurs.
%DrawHTML is the last step before the page leaves the server.
The Zen programmer must ensure that all adjustments to the page are complete before the end of
%OnAfterCreatePage. After that, Caché draws whatever is in the DOM.
6. The Caché server delivers the HTML document to the client, and the browser displays the HTML
document.
Note:
CSP handles this step. Details appear in the previous topic.
The following diagram illustrates the sequence described above. This Zen diagram builds on the CSP
diagram from the previous topic. It using regular numbers for CSP steps and highlights the Zen steps
with larger, bold numbers such as:
Using Zen 29

Zen Client and Server
How Zen Pages Work
30 Using Zen

4
Zen Application Concepts
A Zen application specifies the full set of activities that can result when a Zen client and server interact.
These activities may consist of displaying Web pages, issuing queries to a database, writing data to
disk, and more. When you create a Zen application, you create a suite of Zen classes that specify these
activities. The language you use for these classes is Caché ObjectScript — with embedded snippets
of XML, HTML, SVG, and JavaScript as needed.
If you are new to Caché objects and the ObjectScript programming language, the discussion in this
chapter will make most sense after you have mastered the supporting material available in other books.
The best starting points are Using Caché Objects and Using Caché ObjectScript.
The examples in this book use ObjectScript, but you can also use Caché Basic as your programming
language. See Using Caché Basic.
4.1 Zen Applications
A Zen application consists of the following parts:
An Application class
Page classes
Every Zen application has an application class. This is a class derived from %ZEN.application
that provides application-wide behavior such as a common style sheet. The style sheet is
specified as an XML block embedded within the class.
An application consists of one or more pages. Each page is a class derived from
%ZEN.Component.page which is, in turn, a subclass of both %CSP.Page and
%ZEN.Component.component.
Using Zen 31

Zen Application Concepts
Component classes
Every page contains components. Components provide “look and feel” and permit the user
to interact with the page. All components are derived from %ZEN.Component.component.
They include buttons, tables, list boxes, text fields, panels — essentially any item that can be
displayed on a page.
Zen Application with Pages and Components
This architecture works as follows:
• A Zen application consists of page classes.
• Every Zen page identifies the application that it belongs to.
• Every Zen page consists of a page object and a set of component objects.
• The set of components for a page is defined using a block of XML embedded into the page class.
• The page class can also define a set of methods that provide additional behavior, such as
responding to user actions. These methods can run within the browser, or on the server, depending
on how the code is written.
• When the client sends a page request, the page object and all of its constituent component objects
are instantiated on the Caché server. This is the object tree.
• This object tree can be further modified by user code on the Caché server.
32 Using Zen

• The object tree generates all the CSS (style sheet), JavaScript (client logic) and HTML (layout
instructions) needed to display the page within the client browser. Alternatively, a page could
generate XML or SVG.
• On the client browser, the same object tree is automatically recreated as a set of JavaScript objects.
• Properties and methods of the object tree are thus available to the client.
• As the user interacts with a page, events are fired that invoke the various methods of the client
object tree. Some of these methods execute within the browser, while others can be defined to run
back on the server (for database access, etc.).
• Zen automatically manages any calls that a page makes back to the server, including session
context, security, and synchronizing changes between the client and the server.
• Users create Zen applications by assembling classes (both pre-built and user-defined) into larger
functional units: components are assembled into pages, and pages are assembled into applications.
Zen Page Synchronized on Client and Server at Runtime
Zen Pages
4.2 Zen Pages
A Zen page class consists of:
• A contents definition—An XML block embedded within the page class. It defines the set of
components that make up the page, along with their settings. It is possible to define the contents
of a page programmatically, but in most cases an XML block is more convenient.
Using Zen 33

Zen Application Concepts
• Style overrides—An XML block embedded within the page class. It defines page-specific overrides
of CSS styles for the components on this page.
• Event-handling methods—A page class typically contains a number of methods that handle events
associated with a page, such as when the user interacts with a component. Some of these methods
may run on the server and some on the client. Later chapters provide details.
Defining the Look and Feel of a Zen Page
4.3 Zen Components
Zen component classes define the behavior and layout of the page. Every Zen component has the following
characteristics:
• Defines a set of properties and methods that determine its runtime state and behavior.
• Defines how its initial HTML is drawn (if any). It is also possible to define components that only
render themselves using client-side, dynamic HTML.
• Defines a standard CSS style sheet that specifies how it should appear on the page. Applications
can selectively override these styles without having to modify the pre-built components.
34 Using Zen

• Defines settings that adjust the appearance or behavior of a component. A Zen component class
formally exposes certain settings so that it is easy to dynamically modify these setting values
while designing a Zen page.
• New component classes can be derived from existing classes. Zen automatically provides inheritance
for the client JavaScript classes it creates.
• New components are automatically ready for use within a page’s XML content definition.
Component classes vary in complexity from simple wrappers for native HTML controls to full-featured
calendar and grid controls. Components include the following specialized types:
• Controls display data and allow for user input (such as text or button controls).
• Groups contain sets of other components (such as groups, tab groups, menus, and forms).
• Panes display rich information (such as a tables retrieved from queries).
• Other components simply display data on the page.
Zen Components
Using Zen 35

5
Zen Component Concepts
Components provide layout, style, and behavior for the page. The following table defines these
commonly used terms. These definitions are important because each Zen component provides a large
number of attributes that you can manipulate as you program the application. Some of these attributes
affect layout, some style, and some behavior. With a strong grounding in these concepts, you can
manipulate attributes fluently to get the results you want from Zen components.
Using Zen 37

Zen Component Concepts
Term
Page
Illustration
Component Concepts
Summary
The rectangular display in a browser window.
Layout
The position of each component, and of each
group of components, on the page.
Style
The visual appearance of components,
regardless of their position on the page.
Behavior
An application action that results from user
input, a timer, or some other event.
5.1 Page
A page is initially empty. It fills with components as you add them. A layout strategy is necessary to
determine where these components appear on the page.
38 Using Zen

Layout
5.2 Layout
As Zen constructs a page for display, it adds components individually, one after another, according to
the description that you have provided in the page class. The user is not aware of the page construction
process. The user only sees that a page appears. However, as a Zen programmer, you must understand
the construction process so that your pages lay themselves out exactly as you intend.
Components are contained within groups: a special type of component that can contain zero or more
components. A group is responsible for the placement of its components on the page. The page is itself
a group. Zen generates standard HTML table elements based on the group definition. You can cause
components to line up vertically or horizontally, by enclosing them within a vertical or horizontal
group. Generally, the largest width or height of any component in a group determines the overall width
or height of the group on the page. A spacer component is available to help insert additional space
between components in the group. The entire group places itself on the page as one component.
Certain components permit layers, similar to sheets of paper that occupy one position in a stack. Only
one layer is revealed at one time, based on user clicks. Menus and tabs work on this principle.
Other components may have variable size, depending on their state. For example, if an expando list
is closed, it contains only one item and is short. If the list is opened, it may contain many items; then
it is long. The opened list could push aside other components later in the layout, causing a shift in the
physical geography of the page. Or, the containing group may have a fixed size larger than the maximum
expected list size, allowing the list to expand and contract within the larger boundary without affecting
the page layout.
For details about the built-in Zen component expando, see Navigation Components.
Zen manages layout by generating HTML and CSS style statements based on the inputs that you provide
Zen. Essentially there are three ways to specify your layout intentions to Zen:
• Let the containing group lay out its components.
• Provide CSS style statements to Zen.
• Use client-side JavaScript to dynamically change the geography of the page.
For details, see the chapter Zen Layout.
Scalable Vector Graphics (SVG) components are handled differently from other types of page content.
For details see the chapter Zen and SVG.
Using Zen 39

Zen Component Concepts
5.3 Style
Style determines the visual appearance of a component. Zen manages style by generating standard
CSS statements based on the inputs that you provide Zen.
There are many style attributes that you can set for each component. These include background color,
size, fill patterns, line width, and font family, just to name a few. You can accept the default styles.
You can also override styles at the component, page, or application level.
For details, see the chapter Zen Style.
5.4 Behavior
Behavior refers to an internal or external application action that is triggered by user input, a timer, or
some other type of event. Behavior encompasses a wide range of topics in this book, from processing
user clicks and key presses to automatically generating tables based on database queries.
Component behavior is unique per component. Subsequent chapters provide details as they discuss
each type of Zen component. These chapters include:
• Zen Tables
• Zen and SVG
• Zen Charts
• Zen Forms
• Zen Controls
• Model View Controller
• Navigation Components
• Popup Windows and Dialogs
• Other Zen Components
• Custom Components
40 Using Zen

Customization
5.5 Customization
Zen serves a wide audience range. At one end is the programmer who wants to use Zen to quickly
assemble a user interface for a data-rich Web application. This programmer rapidly places Zen components
on the page with the goal of allowing the user to see and manipulate the underlying data.
At the other end of this range is the programmer who wants to use Zen for pinpoint control of the
layout, style, and behavior of each component on the page. This programmer may react to introductory
topics with this phrase: “But I want to...”
Everyone can relax.
Zen provides ample opportunities for customization. In addition to the wide range of variations available
by manipulating layout, style, and behavior of built-in components, you can create new components,
or even replace the Zen layout handler with custom code. For details, see the chapter Custom Components.
On the other hand, customization is entirely optional. Everyone should begin by reading the next several
chapters. Come to appreciate the power, ease, and flexibility of Zen. Then, after understanding what
Zen provides, make your own decision about whether or not to extend it. The option is always there.
Using Zen 41

6
Zen Layout
Previous chapters have introduced Zen components as classes. It is true that components are classes.
All Zen components extend the class %ZEN.Component.component. However, when you place Zen
components on the page, your primary programming language is usually not ObjectScript. It is XML.
This chapter explains how to lay out Zen pages using XML:
• The chapter begins with an XData Contents example
• The next several topics discuss the XML elements in the example:
- — The top-level container element
- — Allows you to place HTML directly on the page
- — Creates a horizontal row of components
- — Creates a vertical column of components
- — Creates space between groups
- — Subdivides the page into regions
• The chapter ends by discussing:
- How to organize XData Contents using template pages
- The HTML page that Zen generates from XData Contents
Using Zen 43

Zen Layout
6.1 XData Contents
When you prepare a Zen page class for an application, you place components on the page by providing
an XData Contents block. XData Contents is a well-formed XML document that describes the layout
and (optionally) style and behavior of the page.
Each XML element in the document corresponds to a component class of the same name. The following
sample XData Contents block includes the XML elements , , , ,
, and . These XML elements represent the Zen classes %ZEN.Component.page,
%ZEN.Component.html, %ZEN.Component.hgroup, and so on.
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
My Title
}
When you compile the class that contains the previous XData Contents block, Zen generates the code
that displays this page in the browser. At runtime, this code instantiates the indicated component classes
as children of the page object. Zen handles these details automatically and transparently, as described
in the chapter Zen Application Concepts.
As the programmer laying out an XData Contents block, you do not work with component classes
directly. You work with the XML projection of the component classes. For each component, this
projection consists of:
• An XML element with the same name as the class (, , , etc.)
• XML attributes, which are properties of that class (width, height, etc.)
This convention gives you the power of the Zen runtime environment for serving Zen pages, without
requiring you to understand the underlying mechanisms in detail. You use the XML projection to place
components on the page, and Zen generates the HTML that displays these components in the browser.
44 Using Zen

Pages
6.2 Pages
The XData Contents block contains one element that acts as the top-level container for all the
XML elements in the block. A is a group component with the standard group attributes and
the unique attributes listed in the following table.
Attribute
title
xmlns
Description
Use this attribute to store page title text. This text is not automatically used
on the page, but the attribute is available should you want to refer to this text
programmatically. If you do not specify a value for title it takes its value from
the page class parameter PAGETITLE.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
The title value can be a literal string, or it can contain a Zen #()# expression.
See Zen Runtime Expressions.
Allows you to include an XML namespace declaration for the .
As you add custom components, chances increase that there will be conflicts
between components in different namespaces. Adding the xmlns attribute
prevents this.
6.3 Titles
The first item most pages need is a title bar. The title bar answers the user’s implicit question: “Where
am I” Zen offers several elements that can serve this purpose. They work in entirely different ways:
• for simple titles
• for complex titles
• A custom component to use as your title bar
Using Zen 45

Zen Layout
6.3.1 Simple Titles
draws a title box along with an optional subtitle. You can use to provide a
simple title for any component, including the page itself. Simply make the first child
component inside the component whose title you want it to be. For example:
Components like have a caption attribute and so do not need to provide a label.
is most useful and appropriate for a or . has the attributes listed
in the following table.
Attribute
title
subtitle
titleStyle
Description
Title text.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
The title value can be a literal string, or it can contain a Zen #()# expression.
See Zen Runtime Expressions.
(Optional) Subtitle text.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
The subtitle value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
(Optional) String containing a CSS style statement such as:
"color:red; background: yellow;"
There is also a element that omits the subtitle and titleStyle attributes.
46 Using Zen

Titles
6.3.2 Complex Titles
The element permits you to insert an arbitrary HTML excerpt on the Zen page. You can use
the component to output title text in the appropriate font and size. You can use to
quickly produce a title when you are first drafting the page. Simply enclose the desired HTML tags
inside and . For example:
Welcome to My Application!
You are Here:
The real power of the element comes from its optional OnDrawContent attribute.
OnDrawContent identifies a server-side callback method that provides HTML content by using &html
or by using the WRITE command. If defined, this callback is invoked on the server when this component
is drawn. The value of OnDrawContent must be the name of a server-only method in the page class
that contains this component. This method must accept an optional %String as input and return a
%Status data type. What is significant about this feature is that server-side methods normally consist
of ObjectScript code, whereas a callback referenced by OnDrawContent may consist of ObjectScript
code plus as much HTML as you wish to embed within &html or WRITE.
Thus, a page class that contains an XData Contents block with this line:
must also contain a server-side callback method called DrawMessage that meets the above criteria.
The following example is from the ZENApp.HelpDesk class in the SAMPLES namespace:
Method DrawMessage(pSeed As %String) As %Status
{
#; create a random message
Set tColors = $LB("red","green","blue","black","orange")
Set tColor = $LG(tColors,$R($LL(tColors))+1)
Set tMsgs = $LB("Fresh coffee in kitchen!",
"Company share price has gone up.",
"The boss is coming!",
"Customer crisis!",
"Lunch Time!")
Set tMsg = $LG(tMsgs,$R($LL(tMsgs))+1)
&html
}
Quit $$$OK
For more detail, see the Other Zen Components chapter, topic.
Using Zen 47

Zen Layout
6.4 Groups
A group component extends %ZEN.Component.group. A group component is the only type of component
that can contain child components. That is why components such as pages, panes, menus, forms, and
composites all inherit from %ZEN.Component.group.
6.4.1 Layout Strategy
Each group is responsible for the layout of its children on the page. A group can have a horizontal or
vertical layout. With the exception of and , every Zen group and page has vertical
layout by default. You can reset to horizontal layout by providing the layout attribute for the group.
layout may have the following values:
• "horizontal" — Lay out components horizontally. When Zen generates the page, it constructs
an HTML table row to contain the child components.
• "vertical" — Lay out components vertically. When Zen generates the page, it constructs an
HTML table column to contain the child components.
• "" or omitted — Default to vertical layout.
6.4.2 Simple Group Components
The following table lists group components such as you have seen in previous code examples. These
are all derived from %ZEN.Component.group.
Component
Description
The basic group. Used to create a group of components, either for layout
purposes or to treat a set of components as a logical unit (for example
making them hidden or visible as a unit). The attributes of the group
component control the layout of its child components.
A horizontal group, identical to a component with its layout
property set to "horizontal". For example:
A specialized group component with layout set to "vertical" and cellVAlign
set to "top".
48 Using Zen

Groups
Component
Description
A specialized group component with an additional attribute, paneName,
that references an XData block outside XData Contents.
The is not a group component, but it is useful within groups.
Use with a width value to inject additional space in a horizontal
group, or height for additional space within a vertical group.
A vertical group, identical to a component with its layout property
set to "vertical". For example:
6.4.3 Menu Components
Menu components are groups derived from the %ZEN.Component.group class. Being a group permits
the menu to contain child components. A later chapter, Navigation Components, describes how to use
menus.
Component
Description
A specialized form of group that displays a set of menu choices.
A with layout set to "horizontal".
A specialized whose tabs present menus.
An item within a
A separator within a .
Defines a group of components that are used as a tab within a
or .
A specialized group that contains components (which
themselves contain components). One tab at a time is visible.When
the user selects a new tab, its contents become visible and the
other tabs are hidden.
A with layout set to "vertical".
Using Zen 49

Zen Layout
6.4.4 Complex Group Components
The Zen library contains a number of other classes derived from %ZEN.Component.group. The following
table lists these group components. Later chapters describe them in full.
Component
Description
A specialized form of the group component that lets the user show
or hide the members of a group by clicking on a small icon: a plus
sign to expand (show) the group, or a minus sign to contract (hide)
the group.
A group that wraps its members within an HTML
element. The draws an outer box around the children
and displays a title within this box. creates a visual panel
that organizes a large form.
A form is defined as a group, so that it can contain child
components.
Defines a set of components that act together as a modalGroup.
This is a set of components that are initially not displayed but can
later be displayed with modal behavior.
A specialized group that defines the layout for a single entry, then
lays out multiple entries of this type based on data supplied by a
runtime query.
6.4.5 Group Layout and Style Attributes
The following table lists the XML attributes that apply to all group components. These attributes can
affect the positioning or appearance of components in the groups.
50 Using Zen

Groups
Group Layout and Style Attributes
Attribute
Zen
component
attributes
cellAlign
Description
Groups have the same general-purpose attributes as any Zen
component. The next chapter, Zen Style, describes them.
Specifies horizontal alignment for child components within the group
table.The possible values are "left", "right", "center", and "even". cellAlign
behavior depends on the layout strategy for the group:
• Horizontal — A cellAlign value of "left" or "right" places the child
components towards the left or right edges of the group, respectively.
"center" places the child components in the horizontal center of the
group with additional space added on either side of the children.
"even" places the child components in the horizontal center of the
group, with no additional space added.
• Vertical — cellAlign specifies the default vertical alignment used by
the elements containing the child components. "even" is the
same as "center" in this case. An individual child component can
override cellAlign by setting its own align value. For align, see
Component Style Attributes.
When specifying cellAlign, also set the height or width property of the
group, to control how the group takes up the space provided by its container.
For vertical alignment, set cellVAlign instead of cellAlign.
cellSize
How much space (in the direction specified by the layout strategy) to
allot to the elements used to contain each child component within
the layout table. Possible values are:
• "same" — Attempt to allot the same amount of space to each component.
• "stretch" — Allot space to each component based on its relative
value of slice. For slice, see Component Style Attributes.
cellStyle
String containing a CSS style statement such as:
"color:red; background: yellow;"
Zen applies this style to the elements used to contain each child
component within the layout table. An individual child component can
override cellStyle by setting its own containerStyle value. For
containerStyle, see Component Style Attributes.
Using Zen 51

Zen Layout
Attribute
cellVAlign
Description
Specifies vertical alignment for child components within the group table.
The possible values are "top", "bottom", "middle", and "even". cellVAlign
behavior depends on the layout strategy for the group:
• Vertical — A cellVAlign value of "top" or "bottom" places the child
components towards the top or bottom edges of the group, respectively.
"middle" places the child components in the vertical center of
the group with additional space added above and below the children.
"even" places the child components in the vertical center of the
group, with no additional space added.
• Horizontal — cellVAlign specifies the default horizonal alignment
used by the elements containing the child components. "even"
is the same as "middle" in this case. An individual child component
can override cellVAlign by setting its own valign value. For valign,
see Component Style Attributes.
When specifying cellVAlign, also set the height or width property of the
group, to control how the group takes up the space provided by its container.
For horizontal alignment, set cellAlign instead of cellVAlign.
disabled
groupClass
groupStyle
If true, this group and its children are disabled. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
Name of a CSS style class. When Zen lays out this group, it assigns this
value to the HTML class attribute.
String containing a CSS style statement such as:
"color:red; background: yellow;"
When Zen lays out this group, it assigns this value to the HTML
style attribute.
labelPosition
layout
Specifies where labels should be displayed for components within this
group. Possible values are "top" and "left". "top" places the labels above
the components; "left" places the labels to the left of the components.
The layout strategy used by this group: "horizontal" or "vertical". If
omitted, the default is vertical.
52 Using Zen

Template Pages
6.5 Template Pages
You can define an abstract page class that provides the characteristics that you want on all your pages
for the application, then define all application pages as children of the abstract template class. This
would be your template page class:
Class MyApp.TemplatePage Extends %ZEN.Component.page [ Abstract ]
{
/// Class details here
}
All your page classes would look like this:
Class MyApp.AnotherPage Extends MyApp.TemplatePage
{
/// Class details here
}
Template pages offer a convenient way to organize Zen applications for a consistent look and feel. To
view an example of this practice, start Studio, and in the SAMPLES namespace, open the page classes
ZENApp.Chart and ZENApp.HelpDesk. Each of these pages inherits from the template page
ZENApp.TemplatePage, which you can also view.
The effect of class inheritance on XData Contents is one of simple replacement. The child class uses
the child XData if it is present, and if not, it uses the parent XData.
Parent Defines
XData Contents
Yes
Yes
No
No
Child Defines
XData Contents
No
Yes
No
Result
Child inherits XData Contents from the parent.
Child uses its own XData Contents definition.
The page is empty.
Inheritance works a bit differently for style. Style involves a cascade of decisions that may coexist
without overriding or replacing each other. Thus, the simple rules for inheritance of XData Contents
are not always true for inheritance of XData Style. To understand how Zen applies style, see the next
chapter, Zen Style.
Using Zen 53

Zen Layout
6.6 Panes
You can organize your page layout into panes for convenience. A is a specialized group
component with an additional attribute, paneName, that references an XData block outside XData
Contents. At compile time, Zen substitutes the appropriate XData block wherever the element
appears in XData Contents.
Consider the following Zen page. This sample was introduced at the beginning of this chapter. It
organizes a page into three panes — menuPane, tablePane, and detailPane:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
My Title
}
The reference to a specific pane looks like this:
At compile time, Zen resolves this reference by finding an XData block in the page class whose name
matches paneName. In the example above, the value of paneName is menuPane, so Zen looks for an
XData block called menuPane. Zen substitutes this block for the reference. At display time,
whatever is contained within the XData menuPane block appears on the page in the position occupied
by the element . The following is a conceptual view of the result.
54 Using Zen

Panes
Use of Panes on a Zen Page
The following XData block defines the menuPane referenced by the sample :
XData menuPane
{
}
If you are using template pages, you can place a reference in the parent class and allow it to
resolve in either the parent class or the child class. Suppose the reference in the child class is:
The following table discusses the options for inheritance.
Using Zen 55

Zen Layout
Parent Defines
XData myPane
Yes
Yes
No
No
Child Defines
XData myPane
No
Yes
No
Result
Child inherits XData myPane from the parent.
Child uses its own XData myPane definition. The
parent may reference and allow this reference
to resolve in the child class. This common practice
is illustrated in the ZENApp.HelpDesk sample class.
Any reference to
in either class is ignored.
6.7 Generated HTML
The generated code from XData Contents expresses the Zen page as an HTML table, using the standard
HTML elements , , , and . Vertical groups become columns in the table; horizontal
groups become rows. If you are familiar with encoding HTML by hand, you probably recognize this
technique for ensuring the position of items on the page.
Zen groups are easy and convenient to set up, and require no coding in HTML. Rather than arranging
HTML , , , and elements into complex nests, all you need to do is place your
Zen components into groups. Groups handle all the layout details for you.
56 Using Zen

7
Zen Style
The previous chapter, Zen Layout, explained how to place Zen components on the page. To do this,
you provide an XData Contents block in the page class and fill it with XML elements that represent
Zen components.
This chapter explains how to specify styles for Zen components. You can do this by:
• Setting style attributes while placing XML elements in the XData Contents block.
• Applying cascading style sheet (CSS) style definitions in an XData Style block.
• Referencing external CSS files in a variety of ways.
7.1 Component Style Attributes
All Zen components provide the XML attributes listed in the following table. These attributes control
how a component behaves within its enclosing group.
Component Style Attributes
Attribute
align
condition
Description
Possible values are "left", "right", or "center". This becomes the align
value for the element that contains the child component in the
generated HTML.
Server-side expression that, if true, allows this component to be
added to the set of page components. This server-only attribute is
not defined on the client side.
Using Zen 57

Zen Style
Attribute
containerStyle
Description
Overrides the parent group’s cellStyle, to provide extra padding or
alignment values for the element that contains the child component
in the generated HTML.
containerStyle is a string containing a CSS style statement such as:
"color:red; background: yellow;"
enclosingClass
enclosingStyle
Name of a CSS style class. When Zen lays out this group, it applies
this style to the component’s enclosing element.
String containing a CSS style statement such as:
"color:red; background: yellow;"
When Zen lays out this group, it applies this style to the component’s
enclosing element.
height
hidden
id
import
CSS length value (integer or percentage). This becomes the height
value for the element that contains the child component in the
generated HTML.
If true, the component is hidden (placed on the page, but not displayed).
If the status of a component is hidden, its label text (if any)
is also hidden. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
The hidden value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
This value can be used to select a CSS style definition for the
component. It becomes the id value for the component’s enclosing
element.
Comma-separated list of additional component classes that this
component needs to have defined on the client side. Use the full
package and class name for each class in the list. Use import for
cases in which the client needs classes that are not directly defined
in the original object tree. The correct format is as follows:
import="ZENDemo.Component.demoMenu,ZENTest.customComponent"
This server-only attribute is not defined on the client side.
58 Using Zen

Component Style Attributes
Attribute
label
labelClass
labelStyle
Description
A text label for the component. The component simply supplies the
label text. Displaying this label is the responsibility of the component’s
parent group.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its
text into other languages. See Zen Localization.
Name of a CSS style class. When Zen lays out this group, it applies
this style to the label displayed for the component.
String containing a CSS style statement such as:
"color:red; background: yellow;"
When Zen lays out this group, it applies this style to the label displayed
for the component.
name
slice
title
valign
width
Specifies the name of the component.Typically, this is used to identify
a control within a form. See Zen Forms.
Used when this component’s parent group has a cellSize value of
"stretch", slice is an integer value indicating the size of this component
relative to other components within the group. Zen computes this
size by dividing this component’s slice value by the sum of all slice
values for all child components in the same group. The minimum
value for slice is 0.
Help text that displays when the user hovers the mouse over this
component (or its label).
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its
text into other languages. See Zen Localization.
Possible values are "top", "bottom", or "middle". This becomes the
valign value for the element that contains the child component
in the generated HTML.
CSS length value (integer or percentage). It may be "*" to indicate
that the element should take up the remaining space in the layout
table.This becomes the width value for the element that contains
the child component in the generated HTML.
Using Zen 59

Zen Style
You can apply component style attributes while placing the component in the XData Contents block.
The following example applies the style attributes valign, height, and width to the Zen components
and :
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
My Title
}
7.2 Enclosing Element
To facilitate use of CSS styles as well as dynamic HTML, every Zen component that you place on a
Zen page is enclosed within an element on the generated HTML page. This is the enclosing
for the component.
If you have assigned a specific value to the component’s id attribute, this becomes the HTML id of
the enclosing . This convention makes it possible to directly select the enclosing element from
a CSS style sheet. For example, suppose you define a button as follows:
You could then used the following CSS definition in your page’s XData Style block, to set the color
of this button:
XData Style
{
#myButton input {
color: red;
}
}
It is also possible to work with a component’s enclosing programmatically. Every component
has a client-side getEnclosingDiv method that returns the HTML element that Zen is using as
the component’s enclosing . For example:
60 Using Zen

XData Style
Method GiveMyButtonStyleToAbc() [ Language = javascript ]
{
var comp = zenPage.getComponentById('abc');
var div = comp.getEnclosingDiv();
}
// div is an HTML div element
div.className = 'myButton';
7.3 XData Style
Any Zen component class, page class, or application class can provide an XData Style block to define
CSS styles. The Zen Tutorial chapter introduced XData Style when it displayed the skeleton class
generated by the New Zen Application wizard, as follows:
/// This is my first new Zen application.
Class MyApp.MyNewApp Extends %ZEN.application
{
}
/// This is the name of this application.
Parameter APPLICATIONNAME = "My New Zen Application";
/// This is the URL of the main starting page of this application.
Parameter HOMEPAGE = "";
/// This Style block contains application-wide CSS style definitions.
XData Style
{
}
To define styles for the application class shown above, you would add CSS statements between the
tag and the closing tag.
The following example shows an XData Style block in a page class. This class defines styles in the
XData Style block and then references them from XData Contents by using the id attribute with components.
The following example defines and then references the styles title, vg1, and vg2.
Using Zen 61

Zen Style
/// My very first Zen page class.
Class MyApp.MyNewPage Extends %ZEN.Component.page
{
}
/// Class name of application this page belongs to.
Parameter APPLICATION = "MyApp.MyNewApp";
/// Displayed name of this page.
Parameter PAGENAME = "My Home Page";
/// Domain used for localization.
Parameter DOMAIN = "";
/// This Style block contains page-specific CSS style definitions.
XData Style
{
/* style for title bar */
#title {
background: #C5D6D6;
color: black;
font-family: Verdana;
font-size: 1.5em;
font-weight: bold;
padding: 5px;
border-bottom: 1px solid black;
text-align: center;
}
}
#vg1 {
border-right: 1px solid black;
background: #E0E0FF;
height: 600px;
}
#vg2 {
}
/// This XML block defines the contents of this page.
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
Title
}
7.4 Inheritance of Styles
The effect of class inheritance on XData Style is one of simple replacement.
62 Using Zen

Cascade of Styles
Parent Defines
XData Style
Yes
Yes
No
No
Child Defines
XData Style
No
Yes
No
Result
Child inherits XData Style from the parent.
Child uses its own XData Style definition.
Some parent of both classes probably defines XData
Style. If not, the browser applies its own style
defaults.
A class that inherits from another class overrides its parent’s XData Style. Thus, a custom component
that provides XData Style overrides the XData Style in the base component class. A page class that
provides XData Style overrides the XData Style in its template page class.
However, this behavior does not cross over the boundaries of class inheritance. A is a component,
but no component actually inherits from . So a component that appears on a page within
an application does not override the XData Style block in either the page class or the application class.
The XData Style blocks provided by the component class, page class, and application class all coexist,
subject to the rules described in the next topic, Cascade of Styles.
7.5 Cascade of Styles
When a Zen page constructs itself, it collects all the CSS style information that you have provided for
each component on the page, and applies it to the component. There may be many sources for this
information: page classes, application classes, and component classes. Zen applies the information in
these sources in the following order. Note that when conflicts exist, the styles that are defined last take
precedence:
1. Styles defined by the CSS file for the Zen component library, ZEN_Component.css
2. Styles defined by base component classes.
The default styles for the built-in Zen components are provided via an XData Style block in the
corresponding %ZEN.Component class (or one of its parents). However, if you want to change
the style of a built-in Zen component, do not edit the class directly. Either subclass the component
to create a custom component, or override the corresponding style definitions in the page or
application class.
3. Styles defined by subclasses of base component classes (that is, custom components).
Using Zen 63

Zen Style
Any subclass of %ZEN.Component.component can provide an XData Style block. If the child has
an XData Style block, this replaces the XData Style from the parent class. If not, the child inherits
XData Style from the parent.
4. Styles defined within the application class for the current application. These may come from any
of the following sources. Styles from each source are evaluated in the sequential order as shown:
• An XData Style block containing CSS statements
• A reference to an external CSS file using the CSSINCLUDES parameter.
5. Styles defined within the template page class (if there is one for the current page). These may
come from any of the following sources. Styles from each source are evaluated in the sequential
order as shown:
• A reference to an external CSS file using the CSSINCLUDES parameter
• An XData Style block containing CSS statements
• Style attributes in XData Contents. For an individual component, these may provide:
- Simple values for HTML attributes, such as "300" for height
- Literal CSS statements, such as "color:red; background: yellow;")
- The name of a CSS style that is defined somewhere in the cascade of styles
6. Styles defined within the page class. For example:
• A reference to an external CSS file using the CSSINCLUDES parameter
• An XData Style block containing CSS statements
• Style attributes in XData Contents. For an individual component, these may provide:
- Simple values for HTML attributes, such as "300" for height
- Literal CSS statements, such as "color:red; background: yellow;")
- The name of a CSS style that is defined somewhere in the cascade of styles
Thus, when it comes to style, “page” overrides “application” overrides “component.” Within each of
these categories, “child” overrides “parent.”
64 Using Zen

Overriding Built-in Styles
Cascade of Style Definitions
This order of precedence makes it easier to ensure a consistent “look and feel” for your application.
You can override the style definition within the application class (for an application-wide style override),
within a template page class (to override a value for a suite of pages) or within an ordinary page class
(to override a value for a specific page).
However, it is important to note that this order of precedence does not exactly match the hierarchy of
these objects when ZEN constructs the page for display. Compare this discussion and diagram with
the chapter Zen Application Concepts, topic Zen Applications.
7.6 Overriding Built-in Styles
Suppose you want to override the style of a built-in Zen component such as . There is no
requirement to do this, but once you get your table onto the page, you might discover that you want
to change its appearance. If so, you must override the CSS styles for . To accomplish this,
you need to know:
• The name of the CSS style definition that you want to change
• Where, in the cascade of styles, you want to interject changes to this style
Using Zen 65

Zen Style
• Which technique you want to use to apply changes to the style:
- Referencing an external CSS file from a Zen class
- Providing an XData Style block in a Zen class
The following XData Style block changes the background color, border style, and font family choices
for a CSS rule called table.tpTable. How did the developer choose this rule to change How does
this XData Style block fit into the cascade of styles And why did the developer choose to provide an
XData Style block rather than an external CSS file The next several topics provide answers.
XData Style
{
table.tpTable {
background: green;
border: 1px solid red;
font-family: courier new;
}
}
7.6.1 Finding the CSS Style Name
You can determine which CSS rules to override for a specific Zen component as follows:
1. Somewhere in the inheritance tree for each Zen component, there is an XData Style block that
defines the CSS rules for this component. To find the correct one, usually you must know something
about the inheritance of the component class. For example, %ZEN.Component.tablePane inherits
from %ZEN.Component.simpleTablePane. It is the simpleTablePane class that contains the relevant
XData Style block. There is no XData Style block in the tablePane class.
You can use the online class documentation to trace inheritance. Start the documentation in one
of the following ways:
• From Studio, choose Tools > Class Browser. Under the %ZEN.Component package, find the
class you are interested in. Right-click on the class name and choose Documentation.
• Start the InterSystems online documentation. Scroll to the bottom of the documentation home
page and choose Class Reference Information. Choose the %SYS namespace and
%ZEN.Component package. Click on the class name.
Once you have found the documentation page for the class of interest, see if it inherits from another
Zen component class. If so, the XData Style block is probably in the parent class. You can click
on the parent class name to navigate to its documentation page.
2. When you know the class name of the component you want to research, you need to view its CSS
style definitions. You can do this in one of the following ways:
66 Using Zen

• In Studio, run the Zen Style Wizard to see if the component or its parent are listed. The Zen
Style Wizard is the easiest way to modify styles. It does not include every style, but lists the
most popular styles for modification. simpleTablePane is there, with the entry:
table.tpTable
Described as:
Main table for tablePane
• In Studio, in the %SYS namespace and %ZEN.Component package, open the component class
for viewing. Find its XData Style block or that of its parent, and see what CSS rules it contains.
• Examine the CSS file for the Zen component library. The file is located as follows, where
C:\CacheSys is the name of your installation directory:
C:\CacheSys\CSP\broker\ZEN_Component.css
Search for the component name in the code comments. The styles that follow (until the next
component name) are those for the component. For example:
/* %ZEN.Component.simpleTablePane */
/* table */
table.tpTable {
background: white;;
border: 1px solid black;
font-family: arial;
width: 100%;
table-layout: fixed;
empty-cells: show;
}
/* ...etc... */
Overriding Built-in Styles
7.6.2 Overriding a CSS Style Rule
Once you have found the CSS rule that applies to the component whose appearance you want to
modify, you can override the CSS rule in one of two ways:
• Referencing an external CSS file from a Zen application, or page class
• Providing an XData Style block in a Zen application, page, or custom component class
To effectively predict the results of your changes, keep in mind the order of precedence rules described
in the previous topic, Cascade of Styles. The following table restates these rules in terms of the results
that you are trying to accomplish.
Using Zen 67

Zen Style
Where and How to Override Built-in Styles
What to Accomplish
Application-wide
styling rules. You can
override these styles
in template pages or
in individual page
classes.
Styles that apply to a
group of pages within
an application. You
can override these
styles in individual
page classes.
Where to Interject Style Changes
Place the revised CSS rule in an external CSS file and reference
from the application class using the CSSINCLUDES class
parameter. The value of CSSINCLUDES can be a
comma-separated list of multiple CSS files.
Place an XData Style block in the application class and place
the revised CSS rule definition within it.You can either type rule
syntax into XData Style or use the Zen Style Wizard for
convenient style editing. If there are style conflicts between XData
Style and CSSINCLUDES for the application, XData Style takes
precedence.
Create a template page class. Ensure that all the pages you want
to have consistent style are subclasses of this template page.
Place the revised CSS rule in an external CSS file and reference
from the template page class using the CSSINCLUDES class
parameter. The value of CSSINCLUDES can be a
comma-separated list of multiple CSS files.
Place an XData Style block in the template page class and place
the revised CSS rule definition within it.You can either type rule
syntax into XData Style or use the Zen Style Wizard for
convenient style editing. If there are style conflicts between XData
Style and CSSINCLUDES for the template page class, XData
Style takes precedence.
Styles that apply to
only one page within
an application.
Place the revised CSS rule in an external CSS file and reference
from the page class using the CSSINCLUDES class parameter.
The value of CSSINCLUDES can be a comma-separated list of
multiple CSS files.
Place an XData Style block in the page class and place the
revised CSS rule definition within it. You can either type rule
syntax into XData Style or use the Zen Style Wizard for
convenient style editing. If there are style conflicts between XData
Style and CSSINCLUDES for the page class, XData Style takes
precedence.
68 Using Zen

Applying New Styles
What to Accomplish
Styles that apply to
all instances of a
particular component.
Where to Interject Style Changes
Any styles defined in application or page classes automatically
override styles defined in component classes, so for stylistic
consistency and control you should make changes near the end
of the cascade, in the application or page class, rather than in
the component class.
However, if you wish, you may create a custom components that
is a subclass of the built-in Zen component whose styles you
wish to change. Place an XData Style block in the custom
component class and place the revised CSS rule definition within
this XData Style.You can either type rule syntax into XData Style
or use the Zen Style Wizard for convenient style editing.
In any case, do not edit the XData Style block in a built-in Zen
component class or its parent. Do not edit the built-in stylesheet
ZEN_Component.css. Changes of this kind will be lost next time
you upgrade the Caché server version.
7.7 Applying New Styles
The above topics explain how to modify styles that are already in use by a built-in Zen component. If
you want to define an entirely new CSS style (with a new name) and apply that style to a component,
there are additional steps to perform. In that case you must not only subclass the component and define
the CSS style, but also reference that CSS style from the portion of the subclass that renders the component
on the page as HTML. A later chapter, Custom Components, covers these steps in detail.
Using Zen 69

8
Zen Tables
A Zen table is data-driven. It takes the resultset returned by an SQL query and displays it as an HTML
table. There are a number of ways to generate the resultset for a Zen table. You can specify an SQL
statement, reference a pre-defined SQL query, or provide Zen with the inputs it needs to generate an
SQL query for you.
Once you have the data, you can style the resulting table in any way you wish. The following figure
shows a simple example. This table uses “zebra” patterning for alternate rows. The user has entered
data in the table header to filter the results that the table displays. In this case, the user has selected
only entries whose names begin with X, with Active status, who are also Assistants.
This chapter explains how to work with Zen tables as follows:
• How to place a table on a Zen page
• How to work with the table programmatically after it is on the Zen page
• How to identify the data source for a Zen table
Using Zen 71

Zen Tables
• How to supply parameters for the table query, if needed
• How to specify column details, including filters and links
• General style properties that Zen tables can have
• How to define data-specific styling for rows and columns
• How snapshot mode supports multipage tables and simplifies refresh operations
• How a Zen table handles user interactions
• What happens during table refresh operations, and how to request them
8.1
is the XML projection of the versatile %ZEN.Component.tablePane class. To place a table
on a Zen page, place a component inside the page class XData Contents block.
As you read this chapter, you will encounter descriptions of the various component and auxiliary
classes that Zen supplies to support tables. The following list summarizes the XML elements that you
will use to represent these classes in XData Contents. The most important of these is :
• — Draws an HTML table based on an SQL query. Each row in the resultset is displayed
as a row in the table. A may contain the following elements, as needed:
- — Each element provides one of the parameters required to construct
the query.
- — Each element specifies layout, style, and behavior details for a particular
column in the resulting table. elements are optional when all columns in
the resultset are displayed. However, sometimes a needs to select which of the
columns in the resultset should be displayed. When this is the case, elements are
required.
- — Each element defines one data-specific detail that applies to
rows and cells within the table. For example, cells that contain a certain value might display
a certain background color, such as red to indicate an error condition. The specific cells that
contain this value might be different each time the table refreshes; Zen keeps track of these
details for you and colors all cells appropriately.
• — Automatically provides a standard set of buttons for moving through the
pages of a multipage table.
• — An alternative to , this element provides extra buttons
to help users navigate large, multipage tables.
72 Using Zen

Data Sources
has the following general-purpose attributes.
Attribute
dataSource
Description
Specifies which columns from the %ResultSet to display, and in what order.
Possible values are:
• "query" — All columns referenced by the query appear, in order from
left to right.
• "columns" — Only the columns explicitly defined as entries
within the appear, in order from left to right.
When you omit dataSource from the , Zen uses the value
"query" by default, unless there are entries defined, in which
case Zen ignores any dataSource value and uses "columns".
initialExecute
If initialExecute is true, the query associated with this is
executed when the table is first displayed. Otherwise the
will execute the query only on demand. The default is true.
initialExecute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
offers many additional attributes that you can use to configure layout, style, and behavior.
The following topics describe them.
8.2 Data Sources
A element must indicate a data source for the table in one of the following ways:
• Specifying an SQL statement
• Providing a simple description that Zen uses to generate an SQL statement
• Referencing a class query that generates an SQL statement
• Referencing a callback method that generates an SQL statement
The following topics describe each option in detail. Regardless of which option you use, all techniques
support the maxRows attribute. It controls the size of the data returned.
Using Zen 73

Zen Tables
Attribute
maxRows
Description
The maximum number of rows to fetch. For ordinary tables this is the
maximum number of rows to display. For snapshot tables, maxRows is
the maximum size of the snapshot and pageSize is the number of rows to
display per page. The default value for maxRows is 100.
8.2.1 Specifying an SQL Query
A can provide a complete SQL statement as the value of its sql attribute. Zen executes
this SQL statement to provide the contents of the table.
The following is an example of a simple SQL statement:
You may provide any input parameter values using elements inside the .
The attribute is the XML projection of the %ZEN.Component.tablePane property sql.
Unlike most other %ZEN.Component.tablePane properties, the sql property cannot be set from the
client at runtime. It can only be set from XData Contents. This is because sql is an encrypted attribute.
The sqlvalue is encrypted (using the current session key) when it is sent to the client. If this value is
returned to the server, it is automatically decrypted.
This prevents users from seeing the definition of an SQL statement if they view page source within
their browser and prevents client logic from constructing arbitrary queries. For security reasons, query
activities should always be restricted to the server.
8.2.2 Generating an SQL Query
Constructing SQL queries can be tedious, so the supports attributes that allow you to
automatically generate the query based on a simple description. Basically, this is similar to using a
callback method (as described in a later topic) except that Zen generates the callback method for you,
based on your description of the query.
Attribute
groupByClause
Description
(Optional) An SQL GROUP BY clause such as "Year,State". The
groupByClause value can be a literal string, or it can contain a Zen
#()# expression. See Zen Runtime Expressions.
74 Using Zen

Data Sources
Attribute
orderByClause
tableName
whereClause
Description
(Optional) An SQL ORDER BY clause such as "Name,State". If not
provided, then whenever the user clicks on a column header, the next
query contains the appropriate ORDER BY clause based on the user’s
choice. The orderByClause value can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
The name of the SQL table that provides the data for the table. This
value is used in the FROM clause for the generated query. The
tableName value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
(Optional) An SQL WHERE clause such as "Name='Elvis'". If not
provided, then if any column filters are defined in this table, a WHERE
clause is created based on the current filter values. The whereClause
value can be a literal string, or it can contain a Zen #()# expression.
See Zen Runtime Expressions.
To have the generate an SQL query, you must do the following:
1. Provide a value for the tableName attribute.
2. Do not provide values for the sql, queryClass, queryName, or OnCreateResultSet. All of these
attributes take precedence over the behavior described in this topic.
After you satisfy the first two conditions, Zen assumes a "columns" value for dataSource.
3. Define the names of one or more columns by providing elements inside the .
There must be at least one column defined or a “Missing SELECT list” error will result.
4. You can add query parameters by providing elements inside the .
5. You can add clauses for the generated query by providing the attributes
groupByClause, orderByClause, or whereClause, or by allowing defaults to prevail as described
in the table above.
The following is a simple example:
This example generates an SQL statement similar to the following:
SELECT ID,Name FROM MyApp.Employee
Using Zen 75

Zen Tables
Zen executes this query to provide the contents of the table. In the example, the ID column is marked
as hidden. This means that its value is fetched (it can be used for conditions or actions) but not displayed.
For details about hidden and other attributes, see the Table Columns topic.
Note:
A generated SQL query can be useful for tables with column filters.
8.2.3 Referencing a Class Query
A can reference a pre-existing class query to obtain a %ResultSet object. The following
attributes support this approach.
Attribute
queryClass
queryName
Description
The name of the class containing the query.You must also provide a value
for queryName.
The name of the class query that will provide the %ResultSet for this
. You must also provide a value for queryClass.
You may provide any input parameter values for the query by placing elements inside
the . For example:
8.2.4 Using a Callback Method
A can generate a table using an application-defined %ResultSet object. The following
attributes support this approach.
76 Using Zen

Data Sources
Attribute
OnCreateResultSet
OnExecuteResultSet
showQuery
Description
The name of a server-side callback method to call to create a
%ResultSet object. The OnCreateResultSet value must be the
name of a server-only method defined in the page class whose
XData Contents references the component.
The name of a server-side callback method to call to execute the
%ResultSet object returned by the method identified by
OnCreateResultSet. The OnExecuteResultSet value must be the
name of a server-only method defined in the page class whose
XData Contents references the component.
showQuery works only if a callback method is used to generate
the table, and only if this method sets the queryText property of the
QueryInfo object to contain the text of the query. The next topic,
Data Sources, explains the details. Of the various components
that use callback methods to generate SQL queries, only
and support the showQuery attribute.
If showQuery is true, the Zen page displays the SQL query used
to provide the contents of the or
component. This is useful for troubleshooting purposes, during
application development. The default showQuery value is false.
showQuery has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
The showQuery value can be a literal string, or it can contain a
Zen #()# expression. See Zen Runtime Expressions.
Consider the following example:
The corresponding server-side callback method is defined within the page class as follows. The callback
method must return a new instance of %ResultSet object that is executed and processed by the tablePane.
It must also return a status code by reference to indicate if there were any errors encountered in creating
the %ResultSet object.
Method CreateRS(Output pSC As %Status,
pInfo As %ZEN.Auxiliary.QueryInfo) As %ResultSet
{
Set pSC = $$$OK
Set tRS = ##class(%ResultSet).%New()
// ... method activities here ...
Quit tRS
}
Using Zen 77

Zen Tables
As you can see from the method signature in the example above, the callback method receives information
from the tablePane class via a %ZEN.Auxiliary.QueryInfo object; some information is also passed
back via this object. For details about this object, see the following table.
QueryInfo Properties
Property
columnExpression
columns
filterOps
filters
filterTypes
groupByClause
orderByClause
parms
queryExecuted
queryText
Description
The colExpression values from each in the .
columnExpression organizes these values as a multidimensional array
subscripted by colName.
The colName values from each in the .
columns organizes these values as a multidimensional array
subscripted by column number (1–based).
The filterOp values from each in the . filterOps
organizes these values as a multidimensional array subscripted by
colName.
The filterValue values from each in the .
filters organizes these values as a multidimensional array subscripted
by colName.
The filterType values from each in the .
filterTypes organizes these values as a multidimensional array
subscripted by by colName.
The groupByClause value for the , if supplied.
The orderByClause value for the , if supplied.
Multidimensional array, subscripted by parameter number (1–based).
This array contains any input values provided by
elements within the .
Set this property to true in the method identified by
OnCreateResultSet, to indicate that the newly created %ResultSet
has already been executed and you do not want the method
identified by OnExecuteResultSet to be called. The default is false.
The method identified by OnCreateResultSet can set this value to
the actual query text, to be displayed if the showQuery value is true.
78 Using Zen

Data Sources
Property
rowCount
Description
If this value is set by the callback, upon return the rowCount property
contains the number of rows returned by the query. After the query
is executed, rowCount could be different from rows.
Note that rowCount is a string, and not numeric, as its value might
be "" or "100+". Any number of rows greater than 100 is represented
as "100+". When testing rowCount from JavaScript, if you
want to convert to a numeric value use parseInt for base 10:
rowCount = parseInt(rowCount,10);
rows
sortColumn
sortOrder
tableName
whereClause
The number of rows requested. For tables, this is the maxRows
value.
The colName of the current sort column selected by the user.
The table’s current sort order (usually determined by user clicks)
such as "asc" or "desc".
The tableName value.
The whereClause value for the , if supplied.
Just like tablePane, the control components dataCombo and dataListBox can also use a callback method
to generate a %ResultSet. repeatingGroup can do this as well. Some of the properties in the QueryInfo
object apply only to tablePane queries. dataCombo, dataListBox, and repeatingGroup ignore any tableonly
properties, including those for columns, filters, and sorting. Only tablePane and dataCombo
support queryText.
The following is a more detailed example of using a callback method to create a %ResultSet. The
callback method constructs a dynamic SQL statement in response to current values of tablePane
properties sortOrder and sortColumn. The tablePane automatically passes these values to the callback
method as the corresponding properties of the input %ZEN.Auxiliary.QueryInfo object.
Also note how the method places the SQL statement text in the queryText property of QueryInfo before
exiting. If the showQuery value is true, this table will display itself, plus the query that
generated it.
Using Zen 79

Zen Tables
Method CreateRS(Output tSC As %Status,
pInfo As %ZEN.Auxiliary.QueryInfo) As %ResultSet
{
Set tRS = ""
Set tSC = $$$OK
Set tSELECT = "ID,Name,Title"
Set tFROM = "MyApp.Employee"
Set tORDERBY = pInfo.sortColumn
Set tSORTORDER = pInfo.sortOrder
Set tWHERE = ""
// Build WHERE clause based on filters
If ($GET(pInfo.filters("Name"))'="") {
Set tWHERE = tWHERE _ $SELECT(tWHERE="":"",1:" AND ") _
"Name %STARTSWITH '" _ pInfo.filters("Name") _ "'"
}
If ($GET(pInfo.filters("Title"))'="") {
Set tWHERE = tWHERE _ $SELECT(tWHERE="":"",1:" AND ") _
"Title %STARTSWITH '" _ pInfo.filters("Title") _ "'"
}
Set sql = "SELECT " _ tSELECT _ " FROM " _ tFROM
Set:tWHERE'="" sql = sql _ " WHERE " _tWHERE
Set:tORDERBY'="" sql =
sql _ " ORDER BY " _tORDERBY _ $SELECT(tSORTORDER="desc":" desc",1:"")
Set tRS = ##class(%ResultSet).%New()
Set tSC = tRS.Prepare(sql)
Set pInfo.queryText = sql
}
Quit tRS
8.3 Query Parameters
When you are working with SQL queries to generate the data for a Zen table, you sometimes need to
provide values for query input parameters, defined as characters within the query. To do this, use
elements within the element.
Attribute
value
Description
Specifies the parameter value:
The value supplied for a parameter can be a literal string, or it can contain
a Zen #()# expression. See Zen Runtime Expressions.
Previous topics showed examples of using the element, including the following class
query example:
80 Using Zen

Table Columns
When you work with %ZEN.Component.tablePane programmatically, you work with
elements as members of the tablePane parameters property, a list collection. Each in the
becomes a member of the parameters collection in tablePane, associated with an ordinal
position: 1, 2, 3, etc.
You can change the value of query parameters at runtime, from the client, by setting values in the
parameters collection property of the tablePane object. The following example changes the value of
the first parameter to Finance, re-executes the query on the server, and updates the contents of the
tablePane to display the new results:
Method changeParams() [ Language = javascript ]
{
// find the tablePane component
var table = this.getComponentById('table');
table.setProperty('parameters',1,'Finance');
}
8.4 Table Columns
Previous topics explained that draws an HTML table based on an SQL query. Each row
in the query resultset is displayed as a row in the table. A may also contain one or more
elements. These select which of the columns in the query resultset should be displayed in
the table. elements also specify layout, style, and behavior for each column.
Previous topics showed several examples of using the element, including the following
example, in which elements help Zen to automatically construct an SQL query:
The element is the XML projection of the %ZEN.Auxiliary.column class. supports
the general-purpose attributes described in the following table.
Using Zen 81

Zen Tables
Attribute
cellTitle
colExpression
colName
header
hidden
OnDrawCell
seed
Description
Text specifying the tooltip message for any cell within the column.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
If the table is automatically constructing an SQL query, this is the SQL
expression used to get the value of this column. For example:
colExpression="Customer->Name"
The name of the SQL data column that this column is associated with.
The colName value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
If not specified, the column is displayed without a data value. Typically
this technique is used to display a link action in a row.
Text specifying the column header.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
The header value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
If true, this column is not be displayed. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
The hidden value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
The name of a server-side callback method that provides HTML content
for cells within this column. If defined, this callback is invoked on the
server when this component is drawn. It provides HTML content by using
&html or the WRITE command.
The OnDrawCell value must be the name of a server-only method defined
in the page class whose XData Contents references the
component.
Allows you to pass some arbitrary value to the OnDrawCell callback.
82 Using Zen

Table Style
Attribute
style
title
width
Description
CSS style value to be applied to the cells (HTML elements) within
this column. For example: "color: red;"
The style value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
Text specifying the tooltip displayed when the user moves the mouse
over the column header.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
The HTML style value for Zen tables is "fixed". This means that each
column has a specific width value in the generated HTML page. Zen
determines these values as follows:
• You can specify a width value for any column.
• If you do not specify a width, Zen assigns a width that is proportional
to the size of the contents of that column (relative to other columns
in the table).
The width value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
also provides attributes that support dynamic filtering, linking, and sorting of the Zen table.
Later topics describe these special-purpose attributes.
When you work with %ZEN.Component.tablePane programmatically, you work with elements
as members of the tablePane columns property, a list collection of %ZEN.Auxiliary.column objects.
Each in the becomes a member of the columns collection in tablePane, associated
with its ordinal position: 1, 2, 3, etc.
8.5 Table Style
offers the following attributes to control the general style of the table.
Using Zen 83

Zen Tables
Attribute
caption
extraColumnWidth
fixedHeaders
bodyHeight
nowrap
showRowNumbers
showValueInTooltip
Description
Text specifying the caption to display for this table.
Although you enter ordinary text for this attribute, it has the
underlying data type %ZEN.Datatype.caption. This makes it easy to
localize its text into other languages. See Zen Localization.
The HTML width to allow for extra columns, such as when multiple
rows are selected or row numbers are displayed in the tablePane.
The default width for an extra column is 30.
If true, the header of the table will stay in position when the body
of the table is scrolled. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
If fixedHeaders is true, bodyHeight provides an HTML length value
that specifies the height of the body section of the table. The
default bodyHeight is "20.0em".
If true, table cells disallow word wrapping. If false, they allow it.
The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
If true, display a row number column on the left-side of the
tablePane. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
If true, the tooltip (HTML title attribute) displayed for cells within
the table consists of the current value of the cell. The default is
false.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
84 Using Zen

Conditional Style for Rows or Cells
Attribute
showZebra
Description
If true, use zebra striping (alternating dark and light rows) to display
the tablePane. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
8.6 Conditional Style for Rows or Cells
A may contain one or more elements. Each is a simple expression,
based on the values of a given row, that controls the style of the row or of an individual cell within
the row. For example:
In the above example, every row in which the value of the Name column starts with “A” will be displayed
with a plum background.
Typically, the conditional style mechanism is used to highlight rows or cells containing special values
(such as out-of-range or error cases). Adding conditions does increase the amount of processing needed
to display a table, so use them sparingly.
The element supports the following attributes.
Attribute
cellStyle
Description
CSS style to be applied to cells within the target column, for rows in which
this condition evaluates true. For example:
"color: red;"
colName
Required. The name of the column that provides the data value to be
evaluated by the . colName can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
Using Zen 85

Zen Tables
Attribute
predicate
rowStyle
Description
The logical operator used to evaluate the condition. predicate may be one
of the following comparison operators: "", "GT", "EQ", "LT", "NEQ",
"GTEQ", "LTEQ", "EXTEQ", "STARTSWITH", or "CONTAINS". The default
predicate is "EQ". For details about each operator, see the next table.
CSS style to apply to rows in which this condition evaluates to true. For
example:
"font-weight: bold;"
targetCol
value
The name of the column that cellStyle applies to. If not specified, colName
is used.
targetCol can be a literal string, or it can contain a Zen #()# expression.
See Zen Runtime Expressions.
The literal value to be compared against the value in the column identified
in colName. If enclosed within {} (for example, "{Title}") value is treated
as the name of another column, and the value in that column is used.
value can be a literal string, or it can contain a Zen #()# expression. See
Zen Runtime Expressions.
When a table is displayed, all elements within the are evaluated individually
for each row in the table. If a evaluates true, then the rowStyle or cellStyle for the condition
is applied to the row or cell, respectively.
The predicate attribute may have the following values.
predicate Values
Predicate
CONTAINS
EQ
EXTEQ
GT
Description
True if the value in the column identified by colName contains (as a
substring) the value specified by value.
True if the value in the column identified by colName is equal to the
value specified by value.
True if the filename in the column identified by colName has the file
extension specified by value.
True if the value in the column identified by colName is greater than
the value specified by value.
86 Using Zen

Snapshot Mode
Predicate
GTEQ
LT
LTEQ
NEQ
STARTSWITH
Description
True if the value in the column identified by colName is greater than
or equal to the value specified by value.
True if the value in the column identified by colName is less than the
value specified by value.
True if the value in the column identified by colName is less than or
equal to the value specified by value.
True if the value in the column identified by colName is not equal to
the value specified by value.
True if the value in the column identified by colName starts with the
value specified by value.
When you work with %ZEN.Component.tablePane programmatically, you work with
elements as members of the tablePane conditions property, a list collection of %ZEN.Auxiliary.condition
objects. Each in the becomes a member of the conditions collection in
tablePane, associated with its ordinal position: 1, 2, 3, etc.
8.7 Snapshot Mode
A can operate in snapshot mode. In this mode, Zen runs the table query once and copies
these results to a temporary location on the server. Subsequent screen refresh operations display data
from this temporary location, rather than resubmitting the query. Zen automatically manages the creation
and lifecycle of the temporary snapshot data. Snapshot mode is particularly useful for working with
multipage tables, or with tables that the user can sort.
The element supports the following attributes for snapshot mode.
Using Zen 87

Zen Tables
Attribute
useSnapshot
pageSize
Description
When true, this is in snapshot mode. This means that
whenever data is fetched, it is copied into a server-side temporary
location. Paging and sorting operations use this snapshot data and do
not re-execute the query. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
For snapshot tables, this attribute specifies that you wish to display the
data as multiple pages, and what the page size should be. 0, the default,
means show all data on first page. This can only be set to a non-zero
value when the table is in snapshot mode. Compare maxRows, which
is the total number of rows to fetch in the query.
Any of the query mechanisms described in the previous topics can be used with snapshot or direct
(non-snapshot) mode. The following example specifies an SQL query to be used in snapshot mode:
The following %ZEN.Component.tablePane properties are not available as XML attributes in the
definition, but they can be useful for working with snapshot tables once the page has been
created.
Attribute
clearSnapshot
currPage
Description
A runtime flag that the client can set to true to force re-execution of
the table query when Zen would otherwise use the stored snapshot.
The default is false.
For snapshot tables with multiple pages of data, this is the (1–based)
index number of the currently displayed page of data.
You can also programmatically adjust the values for useSnapshot and pageSize that were originally
set by in XData Contents.
8.7.1 Fetching Data From the Server
The %ZEN.Component.tablePane class offers a getRowData method for tables in snapshot mode only.
getRowData fetches the data values for a given row (0-based) from the server-side snapshot data.
88 Using Zen

This data is packaged into a JavaScript object whose properties correspond to the names of the columns
in the snapshot table; type conversion is handled appropriately. For non-snapshot tables or out-of-range
row numbers, getRowData returns null.
8.7.2 Navigating Snapshot Tables
Snapshot Mode
Several different options permit users to navigate multipage tables. The and
components provide a basic navigation interface. is particularly
useful for managing multipage tables. For details, see Navigation Buttons.
If you wish to undertake additional programming, the %ZEN.Component.tablePane class provides a
client-side JavaScript API that an application can use to implement the desired paging interface. These
methods work only when the tablePane is in snapshot mode. They include:
Method
getPageCount()
getProperty('currPage')
getProperty('pageSize')
getProperty('rowCount')
Description
Calculates and returns the current number of
pages within the table.
Returns the page number (1–based) of the
current page displayed by the table.
Returns the current page size.
Returns the total number of rows within the
table.
Note that rowCount is a string, and not numeric,
as its value might be "" or "100+". Any
number of rows greater than 100 is represented
as "100+". When testing rowCount
from JavaScript, if you want to convert to a
numeric value use parseInt for base 10:
rowCount = parseInt(rowCount,10);
setProperty('currPage',pageno)
setProperty('pageSize',rows)
Changes the current page displayed by the
table to pageno.
Changes the current page size used by the
table to rows.
Using Zen 89

Zen Tables
8.8 Column Filters
A Zen table can create a “filter” to place above the header for any column. A filter is a simple box
with an input field where a user can enter one or more search criteria. When the user submits these
changes, the query associated with the is re-executed using the new criteria. Zen updates
the table and nothing else on the page changes.
Filtering works only if the is using an automatically generated SQL statement or an
OnCreateResultSet callback, and the callback generates the appropriate WHERE logic to implement
the data filtering. When your table uses a generated SQL query, your page class can gather what the
user enters; format it appropriately into the %ZEN.Component.tablePane properties groupByClause,
orderByClause, and whereClause; then re-execute the table query.
Important:
If you do not provide a colName value with the element that specifies the
filter, Zen does not create the filter.
The element offers the following attributes for filters.
Attribute
filterEnum
Description
If filterType is "enum", filterEnum defines the set of enumerated values
used by the filter as a comma-delimited list. For example:
"red,green,blue"
The enumerated values will be displayed within a combo box. The
names supplied in the filterEnum list will appear as selections in the
combo box unless filterEnumDisplay is defined.
filterEnumDisplay
filterLabel
If filterType is "enum", and if filterEnumDisplay provides a commadelimited
list of values, the combo box displays these values in place
of the corresponding filterEnum values.
The filterEnumDisplay attribute has its ZENLOCALIZE datatype
parameter set to 1 (true). This means it is easy to localize its text into
other languages. See Zen Localization.
If specified, this is a label to display for the filter control. If there is a
multipart filter control (such as a filterType of "range"), then
filterLabel is assumed to contain a comma-delimited list of labels.
90 Using Zen

Column Filters
Attribute
filterOp
filterQuery
filterTitle
filterType
filterValue
Description
If this column has a filter, filterOp is the name of the SQL operator
that should be used in conjunction with the filter. Supported values
are: "", "%STARTSWITH", "=", ">=", "", "

Zen Tables
The following sample generates an SQL statement that displays the Name and Department
of employees:
This example uses the filterType attribute to specify that the Name column should display
a column filter (“text” indicates that this filter displays a box in which the user may type text). If the
user enters a value in the box (such as “A”) and presses Enter, the table will be updated to only show
rows where the Name column starts with “A”. (If the does not specify a filterOp value, the
default matching operation is %STARTSWITH.)
For the Department column the example displays a more sophisticated filter: a combo box showing 3
possible values. To do this, it sets the filterType to “enum” and sets filterEnum to a commadelimited
list of possible values. It also specifies that an exact match is required, by setting the filterOp
value to "=".
A has filters active and enabled by default. You do not need to supply any
attributes to enable filtering. However, should you want to override the default settings,
offers the following attributes that control filtering for the table as a whole, not just for individual
columns.
Attribute
autoExecute
filtersDisabled
Description
If true, this attribute causes the table query to be executed whenever
a filter value is changed. autoExecute is "true" by default. When false,
a page must explicitly cause the to run its query by
calling its executeQuery method.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
If true, disable column filters (if any). When true, column filters are
still displayed, but they are inactive. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
92 Using Zen

Column Links
Attribute
headerLayout
Description
Controls how to display the table header when column filters are used.
Possible values are:
• "filtersOnTop" — Display column filters above column headers.
This is the default.
• "headersOnTop" — Display column headers above column filters.
showFilters
If true, display column filters (if any) above the column headers. If
false, do not display filters. The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
8.9 Column Links
Columns within a Zen table can display links, such as a link that takes the user to another page to edit
the details of the object displayed within the current row. This link can either be displayed within a
column that contains a data value (in this case, the data value is displayed as a link), or as an extra
column in the table that contains the link.
The element offers the following attributes for links.
Attribute
link
Description
If specified, this column is displayed as a link using the value of the link
property as a URI. If you want to invoke a client-side JavaScript method
in the link, start the URI with javascript: as in:
link="javascript:zenPage.myMethod();"
linkCaption
If this column has a link defined and does not display a data value, the
linkCaption specifies the text to use as the caption for the link.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Using Zen 93

Zen Tables
Attribute
linkConfirm
Description
If specified and this column has a link defined, the linkConfirm text is
displayed as a confirmation message before the link is executed.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
For example:
This example does the following:
1. The sql value specifies that this table will display information about the top 100 items
in the MyApp.Inventory table ordered by price.
2. The needs the value of the “ID” column (as part of the links) but there is no need to
display this value. Therefore, the hidden value is true.
3. The needs the “Item” column to contain a link to a page that displays information
about a specific item. Therefore, the link value defines this link. The linkTitle
value defines a tooltip message that will be displayed when the user moves the mouse over this
link.
4. The defines an extra column (with no data displayed within it) that contains an “Add
to cart” link. This link invokes a client-side addToCart method when the user clicks on it. Specifying
a value for the linkConfirm value indicates that the user will have a chance to
confirm this choice before the link is executed.
The two links used within this example make use of the Zen expression syntax to include the value of
row-specific data within the link. See Zen Runtime Expressions. The following expression refers to
the ID column within the current row of the table: #(%query.ID)#
94 Using Zen

User Interactions
8.10 User Interactions
Zen tables provide built-in mechanisms to support basic user interactions such as navigating pages,
sorting columns, and selecting rows in a table.
8.10.1 Navigation Buttons
The component automatically displays a set of buttons for moving through the pages
of a . The has identical syntax, but displays extra buttons to help
users navigate large, multipage tables.
To use either component, place it anywhere on the same page as a and set its tablePaneId
attribute value to match the id value from the . For example:
8.10.2 Navigation Keys
The can specify event handling for user key clicks as follows.
Property
onkeypress
Description
If useKeys is true, this client-side JavaScript expression runs
whenever the user presses a key (Up, Down, Page Up, Page Down,
Home, End) while focus is in the table.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the
JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions.
See Zen Runtime Expressions.
Using Zen 95

Zen Tables
Property
useKeys
Description
If true, this tablePane captures user keystrokes (Up, Down, Page
Up, Page Down, Home, End) and uses them for simple table navigation.
The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
8.10.3 Sorting Tables
The user can click on a column header and cause this action to sort the table according to the data in
that column: First click, ascending order; second click, descending order; and so on. You can set an
initial value for sortOrder when you add the to the page, but generally it takes its values
at runtime, due to user interactions.
Property
sortOrder
Description
When the user clicks on a column header, Zen re-executes the table query
(unless the table is in snapshot mode) and sorts the table based on the
values in that column and the order specified by the sortOrder value.
sortOrder toggles between its possible values "asc" (sort in ascending
order) and "desc" (sort in descending order) as the user repeats clicks in
that column header.
sortOrder does not affect the query itself (it does not interact with the query
ORDER BY setting). sortOrder simply controls the order in which the table
displays the resultset returned by the query.
The sortOrder value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
8.10.4 Selecting Rows and Columns
The user can select rows or columns within a Zen table by clicking on them. Zen indicates the current
row visually and notifies the application of the event by triggering the event handler provided by the
onselectrow attribute.
%ZEN.Component.tablePane supports a number of properties for row and column selection. Many of
these properties can be set as attributes, but some of them can only take their values at
runtime in response to user actions.
96 Using Zen

User Interactions
Property
currColumn
multiSelect
ondblclick
Description
The colName of the column most recently selected by the user.
You may allow user actions to provide a value for this property, or
you can set it. The currColumn value can be a literal string, or it
can contain a Zen #()# expression. See Zen Runtime Expressions.
If true, the user can select multiple rows within the table. Zen
displays an extra column, containing check boxes, to indicate which
rows are selected. The default is false. multiSelect and rowSelect
can be true or false independently of each other.
Client-side JavaScript expression that runs whenever the user
double-clicks on a row within this table. Generally this expression
invokes a client-side JavaScript method defined in the page class.
This method becomes the “ondblclick event handler” for the
.
When providing a value for an event handler attribute such as
ondblclick, use double quotes to enclose the value and single quotes
(if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
onheaderClick
onselectrow
onmultiselect
rowSelect
selectedIndex
Client-side JavaScript expression that runs whenever the user clicks
on a column header within this table. Zen stores the name of this
column in the currColumn property.
If rowSelect is true, this is the client-side JavaScript expression that
runs whenever the user selects a new row within this table. This
will only happen if showRowSelector is true.
If multiSelect is true, this is the client-side JavaScript expression
that runs whenever the user changes the set of multiply-selected
rows within this table.
If true, the user can select a row within the table (one row at a time).
The default is true. multiSelect and rowSelect can be true or false
independently of each other.
The (0–based) index number of the currently selected row. This
value is relevant only if the showRowSelector property is true. For
snapshot tables, this is row number within the current page.
Using Zen 97

Zen Tables
Property
selectedRows
showRowSelector
value
Description
Read-only. For tables in which multiSelect is true, this string
indicates which rows are currently selected.The string is in the form
"1,,,1,,,1" with "1" indicating a selected row.
If true, and if row(s) are selected, the table displays an extra column
that indicates the selected row(s). The default is true.
Read-only. This is the logical value used to determine which is the
currently selected row. value works with valueColumn. The value
may be empty ("").
Do not access this value directly; use getProperty('value')
instead.
valueColumn
A can have a logical value defined. Each time the
table is refreshed, in each row Zen tests this logical value against
the actual value that appears in the valueColumn in that row. Zen
selects any row(s) that contain value in valueColumn. This implies
the following:
• You can preset the value of a and the row(s) that
match will be selected when the table is first displayed.
• The current selection is preserved when you sort the rows in a
table.
8.11 Table Refresh
When you refresh a table, only the table refreshes. It is not necessary for the entire Zen page to refresh
itself in order to refresh a table.
Typically, Zen refreshes the visible contents of the table automatically as needed. When you work
with tables programmatically, you can also explicitly refresh table contents. The techniques are as
follows:
• Set the refreshRequired property of the %ZEN.Component.tablePane to true (1) from a server-side
method. This forces the tablePane to re-execute its query.
• Call the executeQuery method of the %ZEN.Component.tablePane. This causes the data query
to be re-executed and updates the visible contents of the table to reflect the current values of
tablePane properties.
98 Using Zen

Table Touchups
8.12 Table Touchups
Any time you set an attribute value for in XData Contents, the corresponding property
in the tablePane object automatically acquires this value. This might be just enough programming for
your purposes. Nevetheless, %ZEN.Component.tablePane offers many more opportunities for programmatic
interaction on the client or server sides, for example:
• Touching up values set in XData Contents, just prior to display, by setting tablePane properties
in the %OnAfterCreatePage callback of the page class.
• Examining read-only properties of %ZEN.Component.tablePane such as lastUpdate and rowCount
to determine the current state of the table. Note that rowCount is a string, and not numeric, as its
value might be "" or "100+". Any number of rows greater than 100 is represented as "100+".
• Resetting values of certain tablePane properties and then refreshing the table.
Using Zen 99

9
Zen and SVG
Scalable Vector Graphics (SVG) is a language that allows you to describe two-dimensional vector
graphics in XML format. The SVG language specification is available on the Web site
www.w3.org/TR/SVG/.
Zen uses SVG to display high-performance, data-driven charts and meters. You can use the built-in
SVG components to define eye-catching corporate dashboards that update their statistics in real time.
You can also define your own SVG components. An SVG component is any component that inherits
from %ZEN.SVGComponent.svgComponent. These components render dynamic SVG images that
change their appearance in response to data values.
Note:
If you want to display a static SVG file on the Zen page, use . If you want to use a
static SVG file as the image for a button control, use . The conventions described
in the following topics apply to dynamic SVG components only.
This chapter describes how to place SVG components on the Zen page. Topics include:
• Layout
• Style
• Meters
• Charts
• The radial navigator component
• Drawing your own SVG
Using Zen 101

Zen and SVG
9.1 SVG Component Layout
The following components allow you to place SVG components on a Zen page:
•
•
•
9.1.1
is a Zen component that creates a rectangular frame on the Zen page, into which you can
place SVG components. Only SVG components may appear inside this frame. Any dynamic SVG
component, such as a meter or chart, requires an to contain it.
inherits from %ZEN.Component.component. This gives the usual component
style attributes: height, width, label, etc. See Zen Style. This also allows to be placed
within a (or contained within an or ) just like any other Zen component.
See Zen Layout.
The following figure shows a mix of Zen components and SVG components on a page. This is similar
to the output provided by the sample class ZENDemo.Dashboard in the SAMPLES namespace.
102 Using Zen

SVG Component Layout
The following XData Contents block contains the components that produced the above figure. These
are a mix of:
• Zen components (,,, , , )
• SVG components (, , , , ,
)
Using Zen 103

Zen and SVG
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
This is an example of a Zen Dashboard:
}
An element may contain as many nested and elements as are
required to achieve the desired layout. has the following attributes.
104 Using Zen

SVG Component Layout
Attribute
Zen component
attributes
backgroundStyle
Description
has the same general-purpose attributes as any Zen
component. The previous chapter, Zen Style, describes them.
SVG CSS style definition (Styles within SVG are CSS compliant, but
there is a different set of styles available.) Specifies the background
style for the frame.This style must include a fill value, or mouse events
within this frame will not work correctly. The default backgroundStyle
is:
"fill: white;"
disabled
dragCanvas
editMode
If true, this frame and its children are disabled. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
If true, the user can use the pointing device (mouse) to drag the canvas
of this frame. This updates he values of the offsetX and offsetY
attributes and moves the shapes on the canvas. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Edit mode for this frame. Possible values are:
• "none" — The user cannot edit the contents of this frame. This is
the default.
• "select" — The user can click on an SVG component to select it.
• "drag" — The user can click on an SVG component, hold down
the mouse button, and drag the SVG component to a new position.
frameStyle
CSS style definition that applies to this frame. For example, to produce
the recessed, beveled border shown in the illustration above, you
would use:
frameStyle="border-style: inset;"
gridX
If snapToGrid is true, gridX defines the HTML width of each cell in the
sizing grid. The default is 25.
Using Zen 105

Zen and SVG
Attribute
gridY
layout
offsetX
offsetY
ondragCanvas
Description
If snapToGrid is true, gridY defines the HTML height of each cell in
the sizing grid. The default is 25.
Specifies how the SVG components within this frame should be laid
out. Possible values are "horizontal" and "vertical".
If layout is set to "none" or the empty value "", components may be
placed using specific coordinates x and y. See the x and y attributes
in the topic SVG Component Style.
Offset, along the x-axis, of the coordinates of this frame from its upper,
left-hand corner. The default is 0.
Offset, along the y-axis, of the coordinates of this frame from its upper,
left-hand corner. The default is 0.
Client-side JavaScript expression that runs each time the user drags
the background canvas using a pointing device. Generally this
expression invokes a client-side JavaScript method defined in the
page class. A boolean variable, done, is passed to this event handler
to indicate if the operation is complete.
As with all event handler expressions including onmouseWheel,
onmoveItem, etc:
• When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the
JavaScript expression. For example:
• The JavaScript expression may contain Zen #()# expressions.
See Zen Runtime Expressions.
onmouseWheel
onmoveItem
Client-side JavaScript expression that runs whenever the user moves
the mouse wheel over the background rectangle of this frame. Currently
only available in FireFox.
Client-side JavaScript expression that runs whenever this frame is in
drag mode and the user moves one or more selected items. Refer to
the selectedItems property for the list of items. A boolean variable,
done, is passed to this event handler to indicate if the operation is
complete.
106 Using Zen

SVG Component Layout
Attribute
onresizeItem
onselectItem
onzoom
snapToGrid
svgAutoSize
svgHeight
Description
Client-side JavaScript expression that runs whenever this frame is in
drag mode and the user resizes one or more selected items. Refer to
the selectedItems property for the list of items. A boolean variable,
done, is passed to this event handler to indicate if the operation is
complete.
Client-side JavaScript expression that runs whenever the user changes
the number of selected items in this frame (by selecting or unselecting
an item). A variable, item, is passed to this event handler and refers
to the item most recently selected or unselected.
Client-side JavaScript expression that runs whenever the user changes
the zoom level for this frame.
If true, all mouse operations (sizing and dragging) are constrained to
occur on the grid defined by gridX and gridY. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Controls the size of the SVG drawing canvas within the frame. If
dragCanvas is true, the svgAutoSize property is ignored. Otherwise,
if svgAutoSize is true, Zen calculates (and updates) the canvas size
automatically based on the frame contents, with the minimum canvas
size being svgWidth by svgHeight. If svgAutoSize is false, the canvas
size is determined by the values of svgWidth and svgHeight.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Controls the size of the SVG drawing canvas within the frame.
svgHeight gives the canvas height (using any valid SVG measurement
units). If not specified, the default svgHeight is 100% of the height of
the . If height is also not specified, the default height (and
svgHeight) is 100.
Using Zen 107

Zen and SVG
Attribute
svgPage
Description
(Optional) Identifies a specialized CSP page that serves SVG content,
defining styles and colors for SVG components in the frame. If provided,
the svgPage value must be the name of a class that extends
%ZEN.SVGComponent.svgPage. Otherwise, the frame uses the base
class %ZEN.SVGComponent.svgPage by default.
When you provide a value for the svgPage attribute, you can also
include elements within the . Zen passes
the value strings from these elements to the svgPage
class as URI parameters. For example:
The value supplied for a can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
svgWidth
zoom
zoomLevels
Controls the size of the SVG drawing canvas within the frame.
svgWidth gives the canvas width (using any valid SVG measurement
units). If not specified, the default svgWidth is 100% of the width of
the . If width is also not specified, the default width (and
svgWidth) is 300.
Decimal value, at least 1.0 (the decimal portion of the number may
be omitted). This value indicates the zoom factor for the frame. 100
means no zoom; this is the default. Values larger than 100 increase
image size, while smaller values decrease it.
Comma-separated list of suggested zoom values. The default is:
"10,25,50,75,100,125,150,175,200,300,400,500"
zoomWithWheel
If true, this frame automatically zooms in and out in response to mouse
wheel events. The default is false. Currently only available in FireFox.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Important:
It is not possible for to contain any component that inherits from
%ZEN.Component.component, such as , , , ,
, , , or any of the other Zen components discussed in this
book. can contain SVG components only.
108 Using Zen

SVG Component Layout
9.1.2
is a special container designed to contain and lay out SVG components within .
is not a Zen component (%ZEN.Component.component), nor is it a Zen group component
(%ZEN.Component.group). is an Zen SVG component
(%ZEN.SVGComponent.svgComponent) with the ability to contain other Zen SVG components.
has the following attributes.
Attribute
SVG
component
attributes
disabled
layout
Description
has the same general-purpose attributes as any SVG
component.
If true, this group and its children are disabled (hidden).The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
Specifies how the SVG components within this group should be laid out.
Possible values are "horizontal" and "vertical".
If layout is set to "none" or the empty value "", components may be placed
using specific coordinates x and y. See the x and y attributes in the topic
SVG Component Style.
9.1.3
The element is useful within containers. Use with a width value
to inject additional space in a horizontal , or height for additional space within a vertical
. supports all of the SVG component attributes.
9.1.4
The Zen element draws a simple rectangle. This is not the same as the element defined
by the SVG language specification. Zen is a built-in Zen SVG component that you can place
within an or .
The Zen element takes up space within an or , but in a different way
than . The conceptual difference between and is that may
have visible style attributes, such as a fill color.
Using Zen 109

Zen and SVG
Attribute
SVG
component
attributes
rx
style
Description
has the same general-purpose attributes as any SVG component.
Radius of curve for the corners (using any valid SVG measurement units).
SVG CSS style definition. (Styles within SVG are CSS compliant, but there
is a different set of styles available.)
9.2 SVG Component Attributes
All SVG components have the following style attributes. These are entirely distinct from the attributes
supported by ordinary Zen components.
SVG Component Attributes
Attribute
height
hidden
onclick
Description
Height of this component (using any valid SVG measurement
units). The exact effect of setting this value depends on the
component. In the case of built-in SVG components, the effect is
usually straightforward. A height value larger than the height of
the containing will cause the SVG component to
appear cropped by the frame.
If true, this component is disabled (hidden). The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
Client-side JavaScript expression that runs each time the user
clicks the mouse on this shape. Generally this expression invokes
a client-side JavaScript method defined in the page class.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the
JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
110 Using Zen

SVG Component Attributes
Attribute
name
id
preserveAspectRatio
viewBoxHeight
viewBoxWidth
width
x
y
Description
Specifies a name for the component.
Name that can be used to select the SVG component so that its
attributes can be updated. For example, displays that use meters
might periodically update the value that the meter represents.
By default, Zen preserves the aspect ratio (height relative to width)
for any SVG component when you change its size. If you set
preserveAspectRatio to "none", Zen does not preserve the aspect
ratio and allows your height and width changes to operate
independently of each other.
Height of the view box for this component (using any valid SVG
measurement units). If a viewBoxHeight attribute is provided, its
value is used as the height of the view box. Otherwise, the height
value for the component is used.
Width of the view box for this component (using any valid SVG
measurement units). If a viewBoxWidth attribute is provided, its
value is used as the width of the view box. Otherwise, the width
value for the component is used.
Width of this component (using any valid SVG measurement units).
The exact effect of setting this value depends on the component.
In the case of built-in SVG components, the effect is usually
straightforward. A width value larger than the width of the containing
will cause the SVG component to appear cropped
by the frame.
x position of this component (using any valid SVG measurement
units). The actual position of the component may depend on the
layout of its enclosing . If the has vertical
or horizontal layout, this x coordinate is ignored. However, if
layout="" this x coordinate takes effect. x is a positive value
relative to an origin of (0,0) at the top left corner of the .
y position of this component.
Using Zen 111

Zen and SVG
9.3 Meters
A meter is an SVG component that displays a graphical representation of a single numeric value. Each
meter is a class derived from %ZEN.SVGComponent.meter that generates the SVG required to display
itself.
Zen provides several built-in meters. To place one of them on the Zen page, provide the corresponding
meter element within an or :
•
•
•
•
•
•
• To create your own style of meter, see Custom Components
This topic describes how to supply a meter with a value, lists the attributes that all meters share in
common, then describes the unique attributes for each type of meter listed above.
9.3.1 Providing Data for Meters
Your code can dynamically update the value displayed by a meter in one of two ways:
• From a JavaScript method in the page class, set the meter’s value attribute using the meter class
methods getComponentById and setValue as follows:
this.getComponentById("myMeterID").setValue(myNewValue);
Where myMeterID matches the id attribute value for the meter, and myNewValue is a variable that
contains a single, numeric value.
• Associate the meter with a data controller, as described in the chapter Model View Controller.
For example, if your XData Contents block contains an reference that looks like
this:
And if the referenced modelClass myPackage.MyModel contains a property called Automobiles,
then your XData Contents block can also contain a meter definition that looks like this:
112 Using Zen

Meters
This technique works when the meter’s controllerId value matches the id value,
and the meter’s dataBinding value matches the name of a property defined in the
modelClass.
9.3.2 Meter Attributes
All meters have the following attributes, which define their style and behavior.
Meter Component Attributes
Attribute
SVG
component
attributes
animate
controllerId
dataBinding
label
Description
All meters have the same general-purpose attributes as any SVG
component.
Some of the built-in Zen meters provide animation. For example, if the
meter uses a needle to indicate a value, animation causes the needle
to “swing” from the previous value to the new value. If a meter supported
animation, this attribute controls whether animation is on (true)
or off (false). The default is "true".
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Identifies the data controller that provides the data for this meter. The
controllerId value must match the id value provided for that
component. See Model View Controller.
If this meter is associated with a data controller, this attribute identifies
the specific property within the modelClass that
provides the value for this control. See Model View Controller.
A text label for the meter.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Using Zen 113

Zen and SVG
Attribute
labelStyle
onnotifyView
Description
SVG CSS style definition. (Styles within SVG are CSS compliant, but
there is a different set of styles available.) When Zen lays out this
meter, it applies this style to the label text.
This attribute applies if the meter is associated with a data controller.
The onnotifyView value is a client-side JavaScript expression that is
executed each time the data controller connected to this meter raises
an event. Generally this expression invokes a client-side JavaScript
method defined in the page class. This method becomes the
“onnotifyView event handler” for the meter. See Model View Controller.
When providing a value for this attribute, use double quotes to enclose
the value and single quotes (if needed) within the JavaScript expression.
For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
rangeLower
rangeUpper
scaleFactor
thresholdLower
thresholdUpper
Integer or decimal value that defines the low end of the range for this
meter. The default is 0.
Integer or decimal value that defines the high end of the range for this
meter. The default is 100.
Integer or decimal factor used to scale the values provided to this
meter. Zen scales the incoming values before comparing them with
rangeLower, rangeUpper, and so on. The default is 1 (no scaling).
Integer or decimal value that defines a threshold for meter behavior.
The meter will do something when the meter value falls below this
value. Typically, the thresholdLower value is greater than rangeLower
and serves as a warning that the meter value is approaching
rangeLower. The default is 0.
Integer or decimal value that defines a threshold for meter behavior.
The meter will do something when the meter value rises above this
value. Typically, the thresholdUpper value is less than rangeUpper
and serves as a warning that the meter value is approaching
rangeUpper. The default is 90.
114 Using Zen

Meters
Attribute
value
Description
The current integer or decimal value of the meter (actually stored as
a string). Although you can set this value while placing the meter on
the page, generally you do not do this. Instead, you use
getComponentById and setValue, or associate the meter with a
%ZEN.Auxiliary.dataController, as described in the paragraph prior to this
table.
9.3.3
The fuel gauge is a narrow, vertical gauge with a needle that moves from left to right to indicate a
value within a specific range. The gauge distributes marks or “ticks” proportionally across its range.
The meter attributes rangeLower and rangeUpper define the range, with the rangeLower value at left
and the rangeUpper value at right.
The fuel gauge displays its current value in a text box at the center of the gauge.
You may specify warning lights to appear at the upper left or right of the gauge, above the ticks. These
lights change color as the needle approaches them. The light at right changes color when the meter
value rises to or above thresholdUpper. The light at left changes color when the meter value falls to
or below thresholdLower.
There is always a thresholdLower warning light with a default setting of 0. You must specify a
thresholdUpper value if you want a warning light to appear at the top of the range as well.
Using Zen 115

Zen and SVG
Attribute
Meter attributes
highLampColor
Description
has the same general-purpose attributes as any meter.
String containing a CSS color value. This is the color that the displays when its value exceeds thresholdUpper. The default
is a pre-defined Zen color that produces a “glowing” effect through
shading:
url(#glow-red)
Several glow colors are defined in the class
%ZEN.SVGComponent.svgPage. always references this
class, or some subclass of it, through its svgPage attribute, so these
colors are always available to any SVG component in the frame.
logo
lowLampColor
Text label for the face of the meter (similar to "Zen" in the illustration
above).
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
String containing a CSS color value. This is the color that the displays when its value exceeds thresholdUpper. The default
is a pre-defined Zen color:
url(#glow-red)
9.3.4
The indicator lamp is a rectangular bar that changes its fill pattern depending on the meter value.
Essentially there are three possible states: above thresholdUpper, below thresholdLower, or between
the two values.
If the meter has a label attribute, this text appears in the middle of the indicator lamp with the style
defined by labelStyle.
116 Using Zen

Meters
Attribute
Meter
attributes
highStyle
Description
has the same general-purpose attributes as any meter,
plus the attributes described in this table.
SVG CSS style definition. Specifies the fill style for the
when its value exceeds thresholdUpper. The highStyle must include a fill
value, or mouse events within the shape will not work correctly.The default
highStyle uses a pre-defined Zen color that produces a “glowing” effect
through shading:
"fill: url(#glow-green);"
Several glow colors are defined in the class %ZEN.SVGComponent.svgPage.
always references this class, or some subclass of it, through
its svgPage attribute, so these colors are always available to any SVG
component in the frame.
lowStyle
SVG CSS style definition. Specifies the fill style for the
when its value falls below thresholdLower. The lowStyle must include a
fill value, or mouse events within the shape will not work correctly. The
default lowStyle uses a pre-defined Zen color:
"fill: url(#glow-red);"
normalStyle
SVG CSS style definition. Specifies the fill style for the
when its value is between thresholdLower and thresholdUpper. The
normalStyle must include a fill value, or mouse events within the shape
will not work correctly. The default normalStyle uses a pre-defined Zen
color:
"fill: url(#glow-blue);"
9.3.5
Using Zen 117

Zen and SVG
The light bar provides a stack of lamps arranged in a vertical bar. The light bar is similar to the traffic
light, but its larger number of lamps provide a sense of movement from one end of the scale to the
other.
The light bar is intended to appear “off” when the value is low, and fully lit when the value is high.
The color of the bar shades from green (at the bottom of the scale) to yellow and red (at the top of the
scale), implying that you should stop and address a problem when the value is high.
Sometimes a low number indicates a condition that requires attention. If this is the case you can reverse
the sense of a light bar by inverting the values for rangeLower and rangeUpper. Then the fully lit lamp
indicates low values, and the “off” lamp indicates high values.
Warning lights appear at the top or bottom left of the light bar. The top light changes color when the
meter value rises to or above thresholdUpper. The bottom light changes color when the meter value
falls to or below thresholdLower. You can specify what color you want to use for these lights. You
cannot change the colors for the light bar itself (green, yellow, red).
Note:
When you reverse rangeLower and rangeUpper, do not at the same time reverse
thresholdUpper and thresholdLower.
Attribute
Meter attributes
highLampColor
Description
has the same general-purpose attributes as any meter, plus
the attributes described in this table.
String containing a CSS color value.This is the color that the
displays when its value exceeds thresholdUpper. The default is a predefined
Zen color that produces a “glowing” effect through shading:
url(#glow-red)
Several glow colors are defined in the class
%ZEN.SVGComponent.svgPage. always references this
class, or some subclass of it, through its svgPage attribute, so these
colors are always available to any SVG component in the frame.
lowLampColor
String containing a CSS color value.This is the color that the
displays when its value falls below thresholdLower. The default is a
pre-defined Zen color: url(#glow-red)
118 Using Zen

Meters
9.3.6
The smiley is the familiar yellow circle with two eyes and a smile. The mouth line changes depending
on the meter value. The mouth forms a smile when the meter value is near rangeUpper. The mouth is
a horizontal line at the midpoint between rangeLower and rangeUpper. The mouth forms a frown
when the meter value is near rangeLower. This is useful when a large number indicates a positive
condition, and a small number indicates a negative condition.
You can reverse the sense of a smiley by inverting the values for rangeLower and rangeUpper. Then
the smile occurs at low values, and the frown at high values.
has no unique attributes. It has the usual meter attributes. It ignores any threshold values.
9.3.7
The speedometer is a circular gauge with a needle that moves from lower left, all the way around to
lower right, to indicate a value within a specific range. The gauge distributes marks or “ticks” proportionally
across its range. The meter attributes rangeLower and rangeUpper define the range, with the
rangeLower value at left and the rangeUpper value at right.
By default, the speedometer displays its current value in a text box at the center of the gauge. However,
you can specify that this text box actually contains a different value that you control separately. Use
the independentOdometer and odometerValue attributes for this.
You may specify warning lights to appear at the lower left or lower right of the gauge. These lights
change color as the needle approaches them. The light at right changes color when the meter value
Using Zen 119

Zen and SVG
rises to or above thresholdUpper. The light at left changes color when the meter value falls to or below
thresholdLower.
Attribute
Meter attributes
highLampColor
Description
has the same general-purpose attributes as
any meter, plus the attributes described in this table.
String containing a CSS color value. This is the color that the
displays when its value exceeds
thresholdUpper. The default is a pre-defined Zen color that
produces a “glowing” effect through shading:
url(#glow-red)
Several glow colors are defined in the class
%ZEN.SVGComponent.svgPage. always references
this class, or some subclass of it, through its svgPage attribute,
so these colors are always available to any SVG component in
the frame.
independentOdometer
logo
lowLampColor
odometerValue
If true, this meter can display an additional value independent
of its needle value, in a text box at the center of the gauge. If
false, the value in the text box is the same as the needle value.
The default is false.
This attribute has the underlying data type
%ZEN.Datatype.boolean. It has the value "true" or "false" in XData
Contents, 1 or 0 in server-side code, true or false in client-side
code. See Datatype Classes.
Text label for the face of the meter (similar to "Zen" in the illustration
above).
Although you enter ordinary text for this attribute, it has the
underlying data type %ZEN.Datatype.caption. This makes it easy
to localize its text into other languages. See Zen Localization.
String containing a CSS color value. This is the color that the
displays when its value falls below
thresholdLower. The default is a pre-defined Zen color:
url(#glow-red)
If independentOdometer is true, this is the value to display in
the text box at the center of the gauge.
120 Using Zen

Charts
9.3.8
The traffic light consists of three circular lamps in a vertical column. From top to bottom, the lamps
are red, yellow, and green.
When the meter value is at or below thresholdLower, the bottom lamp shows green. At values above
thresholdLower but below thresholdUpper, the center lamp shows yellow. At values at or above
thresholdUpper, the top lamp shows red. This is useful when a large number indicates a condition that
requires attention.
Sometimes a low number indicates a condition that requires attention. If this is the case you can reverse
the sense of a traffic light by inverting the values for rangeLower and rangeUpper. Then the red lamp
indicates low values, and the green lamp indicates high values.
has no unique attributes. It has the usual meter attributes. looks best
when width is half of height. You cannot change the colors for the traffic light (green, yellow, red).
9.4 Charts
Charts, or graphs, are SVG components that represent a series of data points. Zen provides several
built-in chart types, including line charts, bar charts, and pie charts. As SVG components, charts have
the layout and style characteristics described in this chapter. However, charts also have many unique
attributes. For a complete explanation, see the next chapter, Zen Charts.
Using Zen 121

Zen and SVG
9.5
The radial navigator is a specialized SVG component that displays the relationship between a set of
data items as a dynamic, radial diagram. There is a central circular hub surrounded by a set of evenly
spaced nodes. As you click on a node at the outer rim of the diagram, it becomes the hub node and the
nodes to which it connects are shown circling it.
You define the nodes in the data set by providing elements inside
the element. For example:
122 Using Zen

Attribute
SVG component
attributes
backgroundStyle
hubStyle
mainLabel
mainLabelStyle
nodeStyle
onselectNode
Description
has the same general-purpose attributes as any
SVG component.
SVG CSS style definition for the background panel. (Styles within
SVG are CSS compliant, but there is a different set of styles
available.)
SVG CSS style definition. Specifies the style for the central hub.This
style must include a fill value, or mouse events within this shape will
not work correctly.
Label text for the central hub.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its
text into other languages. See Zen Localization.
SVG CSS style definition. Specifies the style for the mainLabel text.
SVG CSS style definition. Specifies the style for the radial nodes.
This style must include a fill value, or mouse events within this shape
will not work correctly.
Client-side JavaScript expression that runs whenever the user clicks
the mouse on a node shape. Generally this expression invokes a
client-side JavaScript method defined in the page class.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the JavaScript
expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
selectedIndex
When the onselectNode event is invoked, the selectedIndex contains
the index (0-based) of the currently selected node. If the user clicks
on the central hub node, selectedIndex is -1. When selectedIndex
is –2, this means no node is selected.
Using Zen 123

Zen and SVG
Attribute
title
titleStyle
Description
Title text for the radial navigator.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its
text into other languages. See Zen Localization.
SVG CSS style definition. Specifies the style for the title text.
The element is the XML projection of the %ZEN.Auxiliary.radialNode class.
has the following attributes.
Attribute
caption
onclick
Description
Text specifying the caption to display for this radial node.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Client-side JavaScript expression that runs whenever the user clicks the
mouse on the node shape. When providing a value for this attribute, use
double quotes to enclose the value and single quotes (if needed) within
the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
style
value
SVG CSS style definition for the node. The style must include a fill value,
or mouse events within the node shape will not work correctly.
(Optional) Value associated with this node. The value may be a decimal
or integer number, but it is represented as a string.
When you work with %ZEN.SVGComponent.radialNavigator programmatically, you work with
elements as members of the radialNavigator nodes property, a list collection of
%ZEN.Auxiliary.radialNode objects. Each in the becomes a member
of the nodes collection in radialNavigator, associated with its ordinal position: 1, 2, 3, etc.
124 Using Zen

9.6
is an empty SVG component whose contents are filled dynamically by invoking a
runtime callback method that provides SVG content. has the following attributes.
Attribute
SVG
component
attributes
onrender
Description
has the same general-purpose attributes as any SVG
component.
Client-side JavaScript expression. Generally this invokes a client-side
JavaScript method defined in the page class. This method provides the
statements that render the SVG component on the page.
When providing a value for this attribute, use double quotes to enclose
the value and single quotes (if needed) within the JavaScript expression.
For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
The following is an example of an element:
In the above example, the JavaScript expression invokes the page class doOwnerDraw method with
the object as its argument. The expression represents the page with the built-in variable
zenPage, and the object with the built-in variable zenThis. Elsewhere in the page
class, the doOwnerDraw method could look like this:
Using Zen 125

Zen and SVG
Method doOwnerDraw(svg) [ Language = javascript ]
{
// clear contents of ownerDraw component
}
svg.unrender();
// create a line; add it to the svg component
for (var n = 0; n < 30; n++) {
var line = svg.document.createElementNS(SVGNS,'line');
line.setAttribute('x1',200);
line.setAttribute('y1',100);
line.setAttribute('x2',Math.random() * 400);
line.setAttribute('y2',Math.random() * 200);
line.setAttribute('style','stroke: blue; stroke-width: 2;');
svg.svgGroup.appendChild(line);
}
The SAMPLES namespace offers examples in the page classes ZENDemo.SVGBrowser
and ZENTest.SVGOwnerDrawTest.
You can also create custom SVG components. See Custom Components.
126 Using Zen

10
Zen Charts
This chapter explains how to place a chart on a Zen page. Charts represent series of data items by
graphing them, usually across a grid defined by two axes. The following figure shows a line chart.
Zen offers several built-in chart types: line charts, bar charts, pie charts, etc. Every chart is an SVG
component as described in the previous chapter, Zen and SVG. This means that every chart is derived
from the class %ZEN.SVGComponent.svgComponent. Charts follow the layout and style conventions
for SVG components, but add specific behaviors of their own.
Using Zen 127

Zen Charts
The base chart class %ZEN.SVGComponent.chart defines the data, grid (axes and scales), styles, and
legend used by charts. All charts are plotted onto a virtual coordinate space that measures 100 units
by 100 units. The actual dimensions of this space are determined by the chart height and width values.
Within this virtual space, there is a smaller plot area in which the chart appears. Margins fill the space
around the plot area. Generally you use these margins as space in which to display the labels and legend
for the chart.
The following diagram gives some indication of how chart attributes affect the layout of a chart. The
attributes shown in the diagram include some from the SVG component class
%ZEN.SVGComponent.svgComponent (width, height) and some from the base chart class
%ZEN.SVGComponent.chart (marginTop, bandUpper, legendX). If this were a line chart, there would
also be attributes specific to line charts (chartFilled, chartPivot).
Layout Conventions for Zen Charts
The number and variety of chart attributes can seem overwhelming at first. That is why this chapter
begins by introducing the various types of chart, so that you can look at some visual examples and
think about the items you want to display on the Zen page, before reading the exact details of how to
display them. Chapter topics appear in this order:
128 Using Zen

Types of Chart
• Types of Chart
• Providing Data for Charts
• Chart Attributes
• Chart Axes
10.1 Types of Chart
This topic describes and illustrates several types of chart that you can place on the Zen page. Each
description includes the unique attributes that define that type of chart. For attributes that all charts
share in common, see the topic Chart Attributes.
10.1.1 Line Charts
A displays one or more data series as a set of lines across a grid. The beginning of this
chapter displays a simple line chart. has the following attributes.
Using Zen 129

Zen Charts
Attribute
Chart
attributes
chartFilled
chartPivot
chartStacked
Description
has the same general-purpose attributes as any chart, plus
the attributes described in this table.
If true, the area under each line is filled (as in an area chart). If false, it
is not filled (as in a line chart).
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
If true, pivot the chart (display categories vertically and values horizontally).
If false, display the chart in typical fashion (categories on the
horizontal axis and values on the vertical axis).
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
chartStacked comes into play if there are multiple data series. If true,
the lines are stacked atop one another (values are additive). If false,
the lines are superimposed (the values are independent). When
chartStacked is true, negative values are ignored.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
130 Using Zen

Types of Chart
10.1.2 Bar Charts
A displays one or more data series as a set of vertical or horizontal bars. has
the following attributes.
Using Zen 131

Zen Charts
Attribute
Chart
attributes
chartPivot
chartStacked
Description
has the same general-purpose attributes as any chart, plus
the attributes described in this table.
The chart attribute plotToEdge is always treated as false for .
The baseValue is used to plot the bottom of the bars; see Chart
Axes.
If true, pivot the chart (display categories vertically and values horizontally).
If false, display the chart in typical fashion (categories on the
horizontal axis and values on the vertical axis).
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
chartStacked comes into play if there are multiple data series. If true,
the bars at each position along the category axis are stacked atop one
another (values are additive). If "false" the bars appear side by side (the
values are independent). When chartStacked is true, negative values
are ignored.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
132 Using Zen

Types of Chart
10.1.3 Difference Charts
A is a specialized type of line chart that highlights the difference between two series:
1. The first, reference data series shows ideal or projected values
2. The second data series shows actual values
The shades the area between the two series using the color of the actual data series. To
further distinguish between the series, the chart draws a line representing the reference series across
the shaded area of the chart. This line uses the reference series color; it can take additional styling
from the refLineStyle attribute.
Using Zen 133

Zen Charts
Attribute
Chart
attributes
refLineStyle
Description
has the same general-purpose attributes as any chart, plus
the attributes described in this table.
SVG CSS style definition for the reference line. By default, this line uses
the color assigned to the reference (first) data series, but typically it also
assigns some patterning using refLineStyle. The default is:
stroke-dasharray: 1,1;
The figure above shows:
stroke-dasharray: 3,3; stroke-width: 2px;
10.1.4 High/Low Charts
134 Using Zen

A can be used to show stock market high-low-close values, or to trace a measured value
along with its high and low ranges to indicate possible error margins. The chart displays a set of bars
as established by three data series:
1. A series of high values sets the top (right) limit of each bar.
2. A series of low values sets the bottom (left) limit of each bar.
3. (Optional) The “closing” values. The chart places a marker on each bar at these values.
Types of Chart
Each low value is assumed to be smaller than its corresponding high value. Each closing value is
assumed to between its corresponding high and low values. The chart uses its first seriesColor value
to plot all bars and marker. It ignores the colors provided for the other series.
Attribute
Chart
attributes
chartPivot
Description
has the same general-purpose attributes as any chart,
plus the attributes described in this table.
The chart attribute plotToEdge is always treated as false for
.
If true, display bars horizontally, as shown in the example above. If false,
display the chart with vertical bars.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
Using Zen 135

Zen Charts
10.1.5 Scatter Diagrams
An plots two or more data series as (x,y) points. This type of chart is sometimes called a
scatter diagram; it is intended to show the raw data distribution for the series. The represents
its data series as follows:
1. The first data series provides the x values
2. The second data series provides correlated y values
3. Any additional data series are plotted as y values correlated to the x values provided by the first
series.
The result is that an always displays one less plot than its number of data series.
has no unique attributes. has the same chart attributes as any chart, except that
markersVisible and plotToEdge are always set to true. Generally you need to manipulate some of the
other chart attributes to produce the desired results. For example:
136 Using Zen

• The seriesCount value must always be one more than the number of plots you want to display.
This leaves room for the first, x-value series.
• The first data series is not plotted, so the applies series settings beginning with the
second series, not the first. For example:
- The seriesColor list applies to the second, third, and successive series.
- The seriesNames list applies to the second, third, and successive series.
- The markerShapes list applies to the second, third, and successive series.
• A scatter diagram does not appear “scattered” unless you hide the lines between the markers. To
do this, set the plotStyle for an as follows:
plotStyle="stroke-width: 0;"
Types of Chart
10.1.6 Pie Charts
Using Zen 137

Zen Charts
A displays a circle with radial slices representing one series of data values. The chart
adjusts the size of each slice proportionally so that the full set of slices forms a complete circle. The
does not support axes, or grids in the plot area, as for line charts or bar charts.
Attribute
Chart attributes
pieScale
plotBy
showPercentage
Description
has the same general-purpose attributes as any chart,
plus the attributes described in this table.
Decimal value that specifies the scaling factor for the size of the pie
within the chart. The default scaling value is 1.0. A value larger than
1.0 makes the pie bigger relative to the plot area; a value smaller than
1.0 makes the pie smaller.
Specifies how the pie chart will plot its data. Possible values are
"items", "series", or "both". The default is "items". The following topics
describe all the details.
If true, percentage values (rounded to nearest integer) are displayed
as part of the label for each slice. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
The plotBy attribute controls how Zen generates a pie chart from the data provided. You
may actually provide multiple series to the . The chart processes all the data series to create
one series, and then displays that series as slices in the chart. plotBy options are as follows.
• "items"
• "series"
• "both"
10.1.6.1 Pie Charts by Item
When the value of plotBy is "items", a plots one slice for every item within the data series.
If you provide multiple data series to an "items" pie chart, each slice of the pie represents the total of
a particular item, summed across all of the data series in the chart.
The following conceptual figure shows how five data series, each containing eight items, would generate
an eight-slice pie chart. Each slice represents the sum of the five values for that item in each
series.
138 Using Zen

Types of Chart
How Zen Plots Pie Charts by Item
When the value of plotBy is "items", labels for the slices are treated as labels. This means
you cannot specify them directly using a chart attribute such as seriesNames. Labels are provided by
a %ZEN.Auxiliary.dataController, if present, or you can provide an onGetLabelY event handler to get
the label values.
10.1.6.2 Pie Charts by Series
When the value of plotBy is "series", multiple series are in use. The plots one slice for
every data series, so the number of slices in the pie chart is seriesCount. Each slice represents the sum
of all the items within one of the series. The seriesNames attribute provides the labels for the slices,
and for the legend. The chart at the beginning of this topic has plotBy set to "series".
The following conceptual figure shows how five data series, each containing eight items, would generate
a five-slice pie chart. Each slice represents the sum of the eight items in that series.
Using Zen 139

Zen Charts
How Zen Plots Pie Charts by Series
10.1.6.3 Pie Charts by Both Items and Series
When the value of plotBy is "both", multiple series are in use. The plots one slice for every
item in every data series, so there are seriesCount times seriesSize slices. The base color for each slice
is the associated series color. Alternating slices use dark and normal shades of this color. The chart
legend displays series names; the seriesNames attribute provides these labels. The slices display item
names; the labels are provided by an onGetLabelY event handler, or a data controller.
The following pie chart example compares three series (Products, Services, and Training), each of
which has data items in four categories (America, Asia, Europe, and Africa). The chart has twelve
slices.
140 Using Zen

Providing Data for Charts
Zen Pie Chart from Both Items and Series
10.2 Providing Data for Charts
The data for a chart consists of one or more data series. Each data series that you use for a chart is a
simple array of numeric values. You can provide the data for a chart in one of two ways:
• Invoke a JavaScript method in the page class, by setting the chart’s ongetData attribute.
• Associate the chart with a data controller, by setting the chart’s controllerId attribute.
Using Zen 141

Zen Charts
This topic describes both techniques in detail. First it describes how to limit the data returned by either
technique to the desired number and size of series.
10.2.1 Limiting the Data Set
The following attributes from the base class %ZEN.SVGComponent.chart tell the chart how many series
to use, and how many of the items in each data series to use, when constructing the chart. All types of
chart support these attributes.
Attribute
seriesCount
seriesSize
Description
Positive integer specifying the number of series in the chart. Even if your
data source actually provides a larger number of series, you can trim the
number of displayed series by setting seriesCount to a smaller number.
If the chart does not supply a seriesCount, Zen infers the number of
series from the data, as shown in the following figure.
Positive integer specifying the number of items within each data series
to display on this chart. If "", then seriesSize is computed automatically
based on the chart’s data source. Even if the data source actually
provides a larger number of items, you can trim the number of displayed
items by setting seriesSize to a smaller number. If the chart does not
supply a seriesSize, Zen infers the size of the series from the data, as
shown in the following figure.
142 Using Zen

Providing Data for Charts
Data Series Count and Size
10.2.2 Using a JavaScript Method
All charts support the ongetData attribute. The value of this attribute is a client-side JavaScript
expression that Zen invokes whenever:
• The chart is initially displayed
• The chart’s updateChart method is invoked
For example:
ongetData="return zenPage.getChartData(series);"
Generally the ongetData expression invokes a client-side JavaScript method defined in the page class.
This method becomes the “ongetData event handler” for the chart. In the above example, this method
is called getChartData. The ongetData event handler must accept a single argument, series, and must
assume that this argument contains the 0-based ordinal number of the data series to be plotted. The
method may consist of a switch statement based on the value of this input argument. It must return a
simple array of numeric values for the specified data series.
Using Zen 143

Zen Charts
The following is a sample ongetData event handler that provides random values as a test. You can see
this event handler in the SAMPLES namespace in the template page class ZENTest.SVGChartTest. It
provides the data for charts drawn by page classes that extend the ZENTest.SVGChartTest template,
such as SVGLineChartTest and SVGBarChartTest:
Method getChartData(series) [ Language = javascript ]
{
var chart = zenPage.getComponentById('chart');
var data = new Array(chart.seriesSize);
var value = 50;
}
for (var i = 0; i < chart.seriesSize; i++) {
if (Math.random() > 0.9) {
value += (Math.random() * 50) - 35;
}
else {
value += (Math.random() * 20) - 9;
}
data[i] = value;
}
return data;
10.2.3 Using a Data Controller
All charts support the following attributes, which associate the chart with a view on a data controller,
as described in the chapter Model View Controller.
Attribute
controllerId
onnotifyView
Description
Identifies the data controller that provides the data for this chart. The
controllerId value must match the id value provided for that
.
This attribute applies if the chart is associated with a data controller. The
onnotifyView value is a client-side JavaScript expression that is executed
each time the data controller connected to this chart raises an event.
Generally this expression invokes a client-side JavaScript method defined
in the page class.This method becomes the “onnotifyView event handler”
for the chart.
When providing a value for this attribute, use double quotes to enclose
the value and single quotes (if needed) within the JavaScript expression.
For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
144 Using Zen

If your XData Contents block contains a reference that looks like this:
Then your XData Contents block may also contain a chart definition that looks like this:
Chart Attributes
The chart’s controllerId value must match the id value. The chart takes its seriesSize
from the number of properties in the modelClass.
10.3 Chart Attributes
The base class %ZEN.SVGComponent.chart offers a large number of attributes that you can apply to
a Zen chart to control details such as:
• Layout and style — The relative size and characteristics of the background
• Plot area — The part of the chart that displays the data
• Markers — Shapes that highlight the exact data points on a continuous plot
• Legends — A key to the meaning of each plot on the chart
• Titles — Text that labels the chart, and the items on the chart
• User events — How the chart should respond to user actions, such as mouse clicks
• Coordinate axes — Characteristics of the two axes that define most charts
10.3.1 Layout and Style
The following attributes from the base class %ZEN.SVGComponent.chart determine the background
style and the position of the plot area within the chart. When setting values for these attributes, keep
in mind that the chart occupies a virtual coordinate space that measures 100 units by 100 units.
Using Zen 145

Zen Charts
Chart Layout and Style Attributes
Attribute
SVG
component
attributes
backgroundStyle
marginBottom
marginLeft
marginRight
marginTop
Description
A chart has the same general-purpose attributes as any SVG
component. These attributes include the height and width shown in
the above diagram.
SVG CSS style definition. Specifies the style for the background panel.
This is the area outside the plot area but inside the chart component’s
height and width.
Margin to allow from the bottom edge of the background to the bottom
edge of the plot area. X-axis labels or the chart legend usually appear
in this space. Provide an integer value. The default is 10 units.
Margin to allow from the left edge of the background to the left edge
of the plot area. Y-axis labels or the chart legend usually appear in
this space. Provide an integer value. The default is 10 units.
Margin to allow from the right edge of the background to the right edge
of the plot area. Provide an integer value. The default is 2 units.
Margin to allow from the top edge of the background to the top edge
of the plot area. The table title usually appears in this space. Provide
an integer value. The default is 6 units.
10.3.2 Plot Area
The following attributes from the base class %ZEN.SVGComponent.chart determine display conventions
for graphs within the plot area and for the coordinate axes that border the plot area. Also see the next
major topic, Chart Axes.
Attribute
bandLower
bandLowerStyle
bandUpper
bandUpperStyle
Description
Decimal value. If defined, the chart displays a colored band on the
plot area covering the range lower than this value. bandLowerStyle
defines the style of this band.
SVG CSS style definition for the band defined by bandLower.
Decimal value. If defined, the chart displays a colored band on the
plot area covering the range higher than this value. bandUpperStyle
defines the style of this band.
SVG CSS style definition for the band defined by bandUpper.
146 Using Zen

Chart Attributes
Attribute
gridStyle
labelStyle
labelsVisible
ongetLabelX
Description
SVG CSS style definition. Default style applied to all grid line elements
within the plot area for this chart. If defined, gridStyle overrides any
styles define in the CSS style definition for the page, but gridStyle is
in turn overridden by any styles defined by a specific axis element in
the chart.
SVG CSS style definition. Default style applied to all label elements
for this chart. If defined, labelStyle overrides any styles define in the
CSS style definition for the page, but labelStyle is in turn overridden
by any styles defined by a specific axis element in the chart.
If true, display axis labels for this chart (or slice labels for a pie chart).
If false, hide labels. The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Client-side JavaScript expression. If the chart provides an ongetLabelX
value, then the ongetLabelX expression is executed to provide the
text for labels on the x-axis.
Generally the ongetLabelX expression invokes a client-side JavaScript
method defined in the page class. This method becomes the
“ongetLabelX event handler” for the chart. It must accept an argument,
value, that contains the 0-based ordinal number of the data point
whose text label is to be returned. It may consist of a switch statement
based on the value of the input argument. It must return a text string.
For example:
ongetLabelX="return zenPage.getXLabels(value);"
When providing a value for an event handler attribute such as
ongetLabelX, use double quotes to enclose the value and single
quotes (if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
ongetLabelY
Client-side JavaScript expression, as for ongetLabelX.
For pie charts, ongetLabelY is the attribute to use to set slice labels.
Using Zen 147

Zen Charts
Attribute
onrenderPlotArea
plotAreaStyle
plotStyle
plotToEdge
Description
Client-side JavaScript expression. If the chart provides an
onrenderPlotArea value, then the onrenderPlotArea expression is
called by the chart just after it displays its underlying plot area (and
bands) but before it display grid lines and data.
SVG CSS style definition for the plot area panel for this chart.
Default SVG CSS style definition applied to the SVG elements that
are used to plot data for this chart. These elements include the line
in a line chart, or the bar in a bar chart.
Specifies how values should be plotted along a category axis:
• True— plot the first and last values on the edges of the plot area
(as in a line chart)
• False— plot values in the centers of each unit (as in a bar chart)
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
seriesColors
Comma-delimited list of CSS color values to use for data series. The
chart applies these colors to each data series in ordinal order (series
0 gets the first color, series 1 the second color, and so on). If you omit
seriesColors, the default color list is:
"blue,red,green,yellow,orange,plum,purple"
seriesNames
Comma-delimited list of names to use for data series. The chart
applies these names to each data series in ordinal order (series 0
gets the first name, series 1 the second name, and so on). These
names can appear as labels for the series in the legend chart.
The seriesNames attribute has its ZENLOCALIZE datatype parameter
set to 1 (true). This means it is easy to localize its text into other languages.
See Zen Localization.The entire list of seriesNames is treated
as one localized string.
10.3.3 Markers
Markers are shapes that are placed at each data point along the chart. If the chart has multiple series,
each series in the chart can use a different shape for its marker. Marker attributes apply only to types
148 Using Zen

Chart Attributes
of chart that support markers (that is, line charts). The base class %ZEN.SVGComponent.chart offers
the following marker attributes.
Attribute
markerScale
markerShapes
Description
Decimal value that specifies the scaling for markers. A value of 1.0 (or
"") displays markers with the default size. Use a larger value for larger
markers, smaller for smaller markers.
Comma-separated list of shapes to use for each series. It can be convenient
to use a different shape for each series in the chart. This adds
further distinction besides the color of each plot in the chart.The list can
contain any of the following keywords in any order or combination:
• "circle" — a circle
• "down" — a triangle with point down
• "square" — a square
• "up" — a triangle with point up
The default value for markerShapes is "circle,up,down,square"
markerStyle
markersVisible
SVG CSS style definition. Style applied to all marker elements for this
chart. The default is to outline the shape in the same color as the series
plot, and fill the shape with white.
If true, and this chart supports markers, markers will be displayed for
the data points within the chart. If false, no markers are displayed, even
if they are defined. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
10.3.4 Legends
The following attributes from the base class %ZEN.SVGComponent.chart determine the style of the
chart legend and whether or not it should display.
Attribute
legendHeight
Description
If this chart has a legend, this is the height of the legend box (within
the chart coordinate space). If not specified, the chart uses a default
height based on the number of data series.
Using Zen 149

Zen Charts
Attribute
legendLabelStyle
legendStyle
legendVisible
legendWidth
legendX
legendY
Description
SVG CSS style definition for label text within the legend box.
SVG CSS style definition for the background of the legend box.
If true, display a legend for this chart. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
If this chart has a legend, this is the width of the legend box (within
the chart coordinate space). If not specified, the chart assigns a default
width of 15 units.
If this chart has a legend, this is the x-position of the legend box (within
the chart coordinate space). If not specified, the default is 0 (left).
If this chart has a legend, this is the y-position of the legend box (within
the chart coordinate space). If not specified, the default is 0 (top).
10.3.5 Titles
The following attributes from the base class %ZEN.SVGComponent.chart determine the style and
contents of the chart title.
Attribute
title
titleStyle
titleX
titleY
Description
Title text for the chart. Generally you position a chart title outside the plot
area but inside the chart background. See titleX and titleY.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
SVG CSS style definition. Specifies the style for the title text.
If this chart has a title, this is the x-position of the center of the title text
(within the chart coordinate space). If titleX is not specified, the default is
50 (centered between 0 at left and 100 at right in the virtual space).
If this chart has a title, this is the y-position of the bottom line for the title text
(within the chart coordinate space). Descenders (for letters such as 'p' and
'q') fall below this line. If titleY is not specified, the default is 5 (just below
the top of the chart, within the default marginTop value of 6).
150 Using Zen

Chart Attributes
10.3.6 User Selections
The following attributes control user interactions with the chart.
Attribute
onelementClick
Description
Client-side JavaScript expression that runs whenever the user clicks
on a chart element (such as a marker in a line chart, or bar in a bar
chart).
Generally the onelementClick expression invokes a client-side
JavaScript method defined in the page class. This method becomes
the “onelementClick event handler” for the chart. It must accept an
argument, chart, that represents this chart object. It then calls a
method on this object to determine the identity of the currentlyselected
data point (getSelectedItem) or data series
(getSelectedSeries). Either method returns the 0–based ordinal
number of the item that was selected, or -1 if nothing is currently
selected. For example:
onelementClick="zenPage.chartElementClick(chart);"
If no onelementClick expression is provided, Zen uses its own handler
to provide values for selectedItem and selectedSeries.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the JavaScript
expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
selectedItem
selectedItemStyle
selectedSeries
0–based ordinal number of the currently selected chart element (such
as a marker in a line chart, or bar in a bar chart). This value is -1 if
nothing is currently selected.
SVG CSS style definition for the currently selected item in the chart.
0–based ordinal number of the currently selected series in the chart,
or -1 if no series is currently selected.
Using Zen 151

Zen Charts
10.4 Chart Axes
Axes are essential for determining how chart data will be displayed. The range of axis values (minValue
to maxValue) can be specified using or elements, or Zen can determine these values
automatically based on the range of data values. With the exception of pie charts, all Zen charts are
plotted using two axes as follows:
• is the category axis; it names the categories in which data is being displayed.
• is the value axis; it displays the value of the data in each category.
In the following example, a element contains and definitions.
The following attributes from the class %ZEN.Auxiliary.axis are available as attributes of either
or within a chart definition. All of these attributes are optional; Zen provides reasonable
defaults for each of them based on the data supplied to the chart.
Chart Axis Attributes
Attribute
baseValue
labelAngle
labelStyle
labelUnits
Description
For charts with filled regions (bar charts), baseValue is a decimal value
that specifies where the base of the filled region should be plotted. If
missing or blank (""), the base is the bottom of the plot area.
Decimal value that specifies the number of degrees by which labels
for this axis should be rotated. The default is 0 (the label text is
horizontal).
SVG CSS style definition for the text labels along this axis.
Decimal value that specifies the amount of space between labels along
this axis. If labelUnits is missing or blank (""), Zen automatically
calculates a value based on the data series.
152 Using Zen

Chart Axes
Attribute
majorGridLines
majorGridStyle
majorUnits
maxValue
minValue
minorGridLines
minorGridStyle
minorUnits
title
Description
If true, grid lines are displayed for each major unit on this axis. If false,
major grid lines are not displayed. The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
SVG CSS style definition for the major grid lines along this axis.
Decimal value that specifies the amount of space between major grid
lines along this axis. If majorUnits is missing or blank (""), Zen
automatically calculates a value based on the data series.
Decimal value that specifies the maximum data value along this axis.
If maxValue is missing or blank (""), Zen automatically calculates a
value based on the data series.
Decimal value that specifies the minimum value along this axis. If
minValue is missing or blank (""), Zen automatically calculates a value
based on the data series.
If true, grid lines are displayed for each minor unit on this axis. If false,
minor grid lines are not displayed. The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
SVG CSS style definition for the minor grid lines along this axis.
Decimal value that specifies the amount of space between minor grid
lines along this axis. If minorUnits is missing or blank (""), Zen
automatically calculates a value based on the data series.
Title text for the axis.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
When you work with %ZEN.SVGComponent.chart subclasses programmatically, you work with axes
as the xAxis and yAxis properties of the chart object. Each of these properties is a %ZEN.Auxiliary.axis
object with properties corresponding to the attributes listed above.
Using Zen 153

11
Zen Forms
Forms permit the user to enter data. A Zen control is a component that displays application data and
allows the user to edit this data. A Zen form is a specialized group component designed to contain
control components. Zen forms have the same style and layout attributes as any Zen group. Also,
because they are groups, forms may contain any other type of Zen component.
Like all Zen components, a Zen form must be the child of a Zen page object. This means that if you
want to provide a form for a Zen application, you must create a Zen page class that includes a form
component inside the container. Two components are available:
• — A Zen group that contains a specific list of control components. These controls may
or may not take their values from a data controller, but their layout is entirely determined by the
definition in XData Contents.
• — An extension of that dynamically injects control components into a group
(or groups) on the Zen page. The list of controls may be determined by the properties of an associated
data controller, or by a callback method that generates a list of controls. Layout is automatic,
determined by code internal to the .
11.1 Forms and Controls
The Zen library includes a number of controls for use in forms. Many of these controls are wrappers
for the standard HTML controls, while others offer additional functionality. The following figure displays
a form that contains a number of controls, including text fields and radio buttons. This is the
sample form generated by the class ZENDemo.FormDemo in the SAMPLES namespace.
Using Zen 155

Zen Forms
The following figure lists the form and control components that Zen provides. Most of the classes
shown in the figure are controls. All of the classes shown in the diagram are in the package
%ZEN.Component, for example %ZEN.Component.form and %ZEN.Component.control. The diagram
shows the inheritance relationships for these classes, and highlights the base classes most frequently
discussed in this book.
156 Using Zen

Forms and Controls
Class Inheritance Among Form and Control Components
For details about individual controls, see the next chapter, Zen Controls.
Using Zen 157

Zen Forms
11.2 User Interactions
The basic interaction between a Zen application user and a Zen form is as follows:
1. A user interacts with controls on the form
2. Zen may validate the data as it is entered
3. A user action indicates that it is time to submit the form
4. Zen may validate the data prior to attempting the submit
5. Zen interacts with the user to handle any errors it finds
6. When all is well, Zen submits data from the form
7. Any of the following might happen next:
• Data from the form may be written to the server
• The same Zen page may redisplay
• A different Zen page may display
• The same Zen page may display, but with components added or changed
11.3 Defining a Form
The Zen components and each support the following attributes for defining the
characteristics of a form.
Form Component Attributes
Attribute
Zen group
attributes
autoValidate
Description
A form has the same style and layout attributes as any Zen group.
The chapter Zen Layout describes them.
If true (the default), automatically invoke this form’s validate method
whenever this form is submitted.
This attribute has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
158 Using Zen

Defining a Form
Attribute
controllerId
enctype
invalidMessage
Description
If this form is associated with a data controller, the controllerId
attribute identifies the controller that provides the data for this form.
The controllerId value must match the id value provided for that
. See Model View Controller.
(Optional) Specifies a HTML enctype for the form, such as
"multipart/form-data"
Message text that the form validate method displays in an alert box
when the contents of this form are invalid. The default is:
This form contains invalid values.
Please correct the following field(s) and try again.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize
its text into other languages. See Zen Localization.
key
nextPage
onchange
(Optional) Identifier used by the OnLoadForm method to load data
for this form. If this form is connected to a dataController, this value
is ignored. The key can be a literal string, or it can contain a Zen
#()# expression. See Zen Runtime Expressions.
URI of the page to display after this form is successfully submitted.
This URI may be overwritten by a specific button on the
form.
Client-side JavaScript expression that Zen invokes when the value
of a control on this form is changed by the user or when the modified
flags are cleared by a call to the form’s clearModified method.
Generally this expression invokes a client-side JavaScript method.
This method becomes the “onchange handler” for the form.
When fired for a control, the onchange expression can use an
argument called control to reference the modified control.
When providing a value for an event handler attribute such as
onchange, use double quotes to enclose the value and single quotes
(if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
Using Zen 159

Zen Forms
Attribute
ondefault
oninvalid
OnLoadForm
onnotifyView
Description
Client-side JavaScript expression that Zen invokes when the user
performs an action that triggers the default action for a form.
Typically this is when the user presses the Enter key within a control
within the form.
Client-side JavaScript expression that Zen invokes when this form’s
validate method determines that the contents of this form are invalid.
This provides the application with a chance to display a custom
message.
(Optional) Name of a server-side method to call to get values for
this form when it is first displayed. The OnLoadForm value must be
the name of a server-only method in the page class that contains
this form component.
This attribute applies if the form is associated with a data controller.
The onnotifyView value is a client-side JavaScript expression that
is executed each time the data controller connected to this form
raises an event. Generally this expression invokes a client-side
JavaScript method defined in the page class.This method becomes
the “onnotifyView event handler” for the form. See Model View
Controller.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the JavaScript
expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
onreset
OnSubmitForm
Client-side JavaScript expression that Zen invokes when this form
is about to be reset. Generally this expression invokes a client-side
JavaScript method.
(Optional) Name of a server-side method to call when this form is
submitted. The OnSubmitForm value must be the name of a
server-only method in the page class that contains this form
component. If no OnSubmitForm value is specified, then the page’s
%OnSubmit method is called instead.
160 Using Zen

Providing Values for a Form
Attribute
onsubmit
onvalidate
readOnlyMessage
Description
Client-side JavaScript expression that Zen invokes when this form
is about to be submitted. Generally this expression invokes a
client-side JavaScript method with a Boolean return value. Invoking
this method gives Zen a chance to perform client-side validation of
values within the form. If the method returns false, the pending
submit operation will not occur. Note that unlike the HTML onsubmit
event, the onsubmit callback is always called whenever the form is
submitted.
Client-side JavaScript expression that Zen invokes when this form’s
validate method is called. Generally this expression invokes a
client-side JavaScript method that performs validation.
Message text that the form validate method displays in an alert box
when the user makes an attempt to save a form bound to a readonly
data model. The default readOnlyMessage text is:
This data is read only.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize
its text into other languages. See Zen Localization.
11.4 Providing Values for a Form
A form can initially display with blank fields, or you can provide data for some of the fields. Providing
data for a field that the user sees means setting the value property for the associated Zen control component,
before you ask Zen to display the form. There are several ways to do this:
• Set the value attribute while adding each control to XData Contents.
• Set the onLoadForm attribute while adding the form to XData Contents.
• Set value properties from the page’s %OnAfterCreatePage method.
Do ..%SetValueById("Doctor",$G(^formTest("Doctor")))
• On the client side, call the setValue method for each control.
Presumably, once the user begins editing the form, any initial values may change.
Using Zen 161

Zen Forms
11.5 Detecting Modifications to the Form
A Zen form component tracks whether or not changes have occurred in any control on the form.
%ZEN.Component.form and %ZEN.Component.control each offers a client-side method called isModified
that tests this programmatically.
A control’s isModified method returns true if the current logical value of the control (the value property)
is different from its original logical value (the originalValue property). With each successive submit
operation, the originalValue for each control acquires its previous value, so that this answer is always
current with respect to the current state of the form.
When you call a form’s isModified method, it invokes isModified for each control on the form, and
if any control returns true, isModified returns true for the form.
Note: The control returns an accurate isModified status when it contains fewer than 50
characters. When the value contains 50 characters or more, the control does not
compute an isModified status.
11.6 Validating a Form
Each Zen form has a validate method whose purpose is to validate the values of controls on the form.
If the form’s autoValidate property is true, validate is called automatically each time the form is submitted.
Otherwise, validate may be called explicitly by the application. validate does the following:
1. Calls a form-specific onvalidate event handler, if defined. If this event returns false, Zen declares
the form invalid and no further testing occurs.
2. Resets the invalid property of all the form’s controls to false, then tests each control by calling the
control’s validationHandler method. This method, in turn, does the following:
• If the control’s readOnly or disabled properties are true, return true.
• If the control’s required property is true and the control does not have a value (its value is ""),
return false.
• If the control defines an onvalidate event, execute it and returns its value. Otherwise, call the
control’s isValid method. isValid can be overridden by subclasses that wish to provide builtin
validation (such as the dateText control).
3. As the validate method tests each control, the form builds a local array of invalid controls.
4. After the validate method is finished testing the controls, it returns true if the form is valid.
162 Using Zen

5. If the form contains one or more controls with invalid values, it is invalid. validate performs one
of the following additional steps to handle this case:
• If the form defines an oninvalid event handler:
Execute the handler. This provides the form with a chance to handle the error conditions. The
value returned by the oninvalid event is then returned by the form’s validate method. The
oninvalid handler has an argument named invalidList that receives a JavaScript array containing
the list of invalid controls. For example:
Where the formInvalid method looks like this:
Method formInvalid(form,list) [ Language = javascript ]
{
return false;
}
• When the form has no oninvalid event handler:
Errors and Invalid Values
validate sets the invalid property to true for each invalid control (which changes their style
to zenInvalid); gives focus to the first invalid control; and displays an error message within
an alert box. The message displayed in the alert box is built from a combination of the form’s
invalidMessage property along with the value returned from each invalid control’s
getInvalidReason method.
11.7 Errors and Invalid Values
Should an error occur while a form is being submitted, or should the form fail validation, Zen redisplays
the page containing the form. The user has the opportunity to re-enter any incorrect values and submit
the page again. All of this is extremely easy to set up when adding the or component
to the Zen page.
The SAMPLES namespace class ZENTest.FormTest allows you to experience error handling with Zen
forms as follows:
1. Start your browser.
2. Enter this URI:
http://localhost:57772/csp/samples/ZENTest.FormTest.cls
Where 57772 is the Web server port number that you have assigned to Caché.
3. Ensure that the Name field is empty.
4. Uncheck the Status box.
Using Zen 163

Zen Forms
5. Click Submit.
6. The form’s validate method detects the invalid fields and highlights them with pink.
7. The following alert message displays in the browser.
To generate this message, the form has assembled the following snippets of text. Zen offers default
values for these items, so there is no need for you to do anything for the default message to appear.
However, if you wish you can customize them to any extent:
• The message begins with the form’s invalidMessage text.
• For each control that has its required attribute set to true, but contains no entry, the message
lists the control’s label followed by the control’s requiredMessage text.
• For each control that contains an invalid value, the message lists the control’s label followed
by the control’s invalidMessage text.
8. Click OK to dismiss the alert message box.
9. The invalid controls remain highlighted until the user edits them and resubmits the form.
11.8 Processing a Form Submit
The request to submit the contents of a form can be triggered in one of two ways:
• The user clicks a button placed within the form
• The application calls the submit method of the form object in response to a user event:
%form.submit
When a form is submitted, the values of the controls in the form are sent to the server and the
%OnSubmit callback method of the page containing the form is called. Note that the %OnSubmit
callback method is that of the page that contains the form, not of the form itself or of any component
on the form.
%OnSubmit receives an instance of a special %ZEN.Submit object that contains all the submitted
values (there is no page object available during submit processing). Zen automatically handles the full
164 Using Zen

details of the submit operation, including invoking server callbacks and error processing. All forms
are submitted using the HTTP POST submission method.
If you are interested in details of how Zen executes a submit operation, the following table lists the
internal events in sequence, organized by user viewpoint, browser-based execution, and server-side
execution. Most of the communication details are handled by the CSP technology underlying Zen. For
background information, see the chapter Zen Client and Server.
Form Submit Sequence
Processing a Form Submit
User Viewpoint
In the Browser
On the Server
1
User clicks a button
to invoke form
submit
2
Post control values to the
server via the HTTP POST
mechanism
3
4
5
6
7
8
Deserialize data from the
client
Reconstruct DOM based on
new control values
Run the server-side code for
the page
Update server-side DOM
Generate new HTML page
Send new HTML page as
response to HTTP POST
9
10
Render the HTML received
in HTTP POST response
Update client-side DOM to
reflect changes made on
the server
11
User sees new page
Using Zen 165

Zen Forms
11.9 User Login Forms
An application login page presents a special case of a Zen form.
See the chapter Zen Application Security, topic Controlling Access to Applications.
11.10 Dynamic Forms
A is a specialized type of form that dynamically injects control components into a group
(or groups) on the Zen page. Layout is determined automatically by code internal to the .
The list of controls may be determined by the properties of an associated data controller, or by a callback
method that generates a list of controls.
has the attributes listed in the following table.
Attribute
Form component
attributes
controllerId
defaultGroupId
OnGetPropertyInfo
Description
A has the same general-purpose attributes as any Zen
form. These attributes include the controllerId and onnotifyView
attributes needed to work with a data controller.
If this form is associated with a data controller, the controllerId
attribute identifies the component that provides
the data for this form.The controllerId value must match the id value
for the .
For full details about creating a that uses a data controller,
see the Model View Controller chapter.
(Optional) The id of a group in which to place the controls generated
by this . This provides a way to control layout.
Somewhere inside the , you must specify a group
component (such as or ) with an id that matches
the defaultGroupId. If no defaultGroupId is provided, controls are
added directly to the without being contained in a
group.
(Optional) Name of a server-side method to call to get a list of the
controls to provide on this form. OnGetPropertyInfo provides an
alternative to using a data controller to generate the
The OnGetPropertyInfo value must be the name of a server-only
method in the page class that contains this .
166 Using Zen

Dynamic Forms
Attribute
onnotifyView
Description
This attribute applies if the form is associated with a data controller.
The onnotifyView value is a client-side JavaScript expression that
is executed each time the data controller connected to this form
raises an event. Generally this expression invokes a client-side
JavaScript method defined in the page class.This method becomes
the “onnotifyView event handler” for the form.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the JavaScript
expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
For full details about creating a that uses a data controller,
see the Model View Controller chapter.
Using Zen 167

12
Zen Controls
Zen controls are the user input elements that you place on a Zen form. All controls are Zen components,
but Zen controls also have unique characteristics derived from their parent class
%ZEN.Component.control.
Most importantly, each control has a value associated with it. value is a property that contains the
current logical value of the control. Each control has the ability to display this value or keep it internally.
Zen validates and submits all the control values for a form together, as a unit, according to the rules
described in the previous chapter, Zen Forms.
This chapter:
• Describes characteristics shared by all Zen controls.
• Identifies variations in layout, style, and behavior for different categories of control:
- Buttons — , ,
- Text — , , ,
- Choices — , , , ,
- Lists — , , , ,
- Calendars — ,
- Hidden —
- Spreadsheet —
Using Zen 169

Zen Controls
12.1 Control Attributes
All Zen controls have the following attributes in common.
Control Component Attributes
Attribute
Zen component
attributes
clientType
Description
A control has the same general-purpose attributes as any Zen
component. The chapter Zen Style describes them. The name
attribute for a control has special significance: this name (and not the
id) is associated with the control’s value when the form is submitted.
Indicates the client-side (JavaScript) data type to expect for this
control’s value. By default, a controls treats its value as a string with
no client-side normalization. However, a control can set a value for
clientType to indicate that it has a non-string value on the client side.
Possible values are:
• "string" — The client-side value is a string.
• "boolean" — The client-side value is true or false.
• "integer" — The client-side value is either an integer or '' to
indicate an invalid integer.
• "float" — The client-side value is either a float or '' to indicate
an invalid float.
controlClass
controlStyle
dataBinding
disabled
Name of a CSS style class. When Zen lays out this control, it assigns
this value to the primary HTML element displayed for this control.
String containing a CSS style definition. Zen applies this style to the
primary HTML element displayed for this control.
If this control is associated with a data controller, this attribute
identifies the specific property within the modelClass
that provides the value for this control. See Model View Controller.
If true, this control is disabled; its appearance is unchanged, but it
does not respond to user actions. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
170 Using Zen

Control Attributes
Attribute
invalid
invalidMessage
Description
Set to true when the value of this control is known to be invalid. Zen
form validation logic does this so that Zen can display this control in
a way that indicates its value is invalid. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Message text to provide when invalid is true. The default is:
out-of-range or invalid value.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption.This makes it easy to localize its text
into other languages. See Zen Localization.
—
The next several attributes (names beginning with “on...”) identify
event handlers for user actions relating to a control. In each case,
the value of the attribute is a client-side JavaScript expression that
Zen invokes when the related event occurs. Generally this expression
invokes a client-side JavaScript method defined in the page class.
This method becomes known as the “handler” for that specific event.
When providing a value for an event handler attribute, use double
quotes to enclose the value and single quotes (if needed) within the
JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
onblur
onchange
onclick
ondblclick
onfocus
Fired when the control loses focus.
Fired when the value of the control changes. Note that controls fire
this event indirectly; the actual onchange event is sent to a built-in
handler that notifies the form that owns this control of the modification.
Fired when the mouse is clicked on the control.
Fired when the mouse is double-clicked on the control.
Fired when the control is given focus.
Using Zen 171

Zen Controls
Attribute
onkeydown
onkeypress
onkeyup
onmousedown
onmouseout
onmouseover
onmouseup
onsubmit
onvalidate
—
originalValue
readOnly
Description
Fired when the user presses down on a key while this control has
focus. There is a corresponding onkeyup for when the user releases
the key.
Fired after the user has pressed a key (that is, the user has pushed
down and then released the key) while this control has focus.
Fired when a key is released while this control has focus.
Fired when a mouse button is released while within the area of the
control.
Fired when the mouse pointer leaves the area of the control.
Fired when the mouse pointer enters the area of the control.
Fired when a mouse button is pressed while within the area of the
control.
Fired when the form this control belongs to is submitted. This gives
controls a chance to supply or modify the value they submit.
Fired when this control’s value is validated by its parent form.
(End of the list of attributes that identify event handlers.)
Original value for this control before any user modification. It is used
to detect which controls have been modified. This is a special value
in that it is automatically initialized when a form is displayed.
On the client side, do not access this property directly; instead use
the getProperty and setProperty client-side methods. Note that
setting the originalValue property on the client (via setProperty) will
reset it to the current value of this control.
If true, this control is read-only. The user cannot change the value of
this control, but the control still submits its value when the form that
contains it is submitted. The default readOnly value is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
172 Using Zen

Control Methods
Attribute
required
requiredMessage
Description
If true, this control is required. That is, a user must supply a value for
this control or the default form validation logic will fail.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Message text that the form validate method displays in an alert box
when this control is required and does not have a value. The default
requiredMessage text is:
required.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption.This makes it easy to localize its text
into other languages. See Zen Localization.
value
Default value displayed within this control. This is a special value in
that it is automatically initialized when a form is displayed. The value
can be a literal string, or it can contain a Zen #()# expression. See
Zen Runtime Expressions.
On the client side, do not access this property directly; instead use
the getValue and setValue client-side methods.
12.2 Control Methods
Each control has internal methods, which you can study in more detail by viewing the online class
documentation for %ZEN.Component.control and its subclasses.
The most important of these methods are those used to manipulate the value of the control. You can
get and set the value property using the client-side getProperty and setProperty methods; getProperty
and setProperty are available for you to work programmatically with any of the properties listed in
the previous topic, not just value. Calling the setProperty method ensures that all actions relating to
setting the property are also carries out, such as rendering the content within the control on the page.
However, Zen controls also define the convenient client-side methods getValue and setValue, which
work only on the value property and save the need to specify which property you wish to change.
Using Zen 173

Zen Controls
12.3 Buttons
Zen offers the following button-style controls:
• — The user clicks a button that can trigger further actions
• — The user clicks an image that can trigger further actions
• — The user clicks a button that submits a form
12.3.1
The component is a simple wrapper for the HTML element.
A Zen looks like this:
has the following attributes:
Attribute
Control
component
attributes
caption
Description
has the same general-purpose attributes as any Zen control.
These attributes include the onclick attribute, which determines what
happens when a user clicks the button. If you want the form to be submitted
when the user clicks this button, use the control instead of
.
Text displayed on this button. The above example uses:
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text into
other languages. See Zen Localization.
The caption value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
12.3.2
The control displays a static image. can be used simply to display an image, or it
can serve as a button if you specify an onclick event for it.
174 Using Zen

Buttons
Attribute
Control
component
attributes
srcDisabled
streamId
src
Description
has the same general-purpose attributes as any Zen control.
However, has no associated value.
(Optional) URI of the image to display when the src image is disabled.
(Optional) Stream id of a binary stream object on the server that provides
the data for this image. The streamId value overrides src if present.
This attribute has ZENENCRYPT set to 1 (true) to specify that the streamId
value will be encrypted (using the current session key) when it is sent to
the client. If this value is returned to the server, it will be automatically
decrypted. This makes it possible to place sensitive data on the client for
future processing on the server without letting a user view this data.
Identifies the pathname and filename of the image. The path is relative to
the Caché installation directory. Typically this path identifies the images
subdirectory for your Zen application, for example:
12.3.3
is a special type of button that submits a form. has the following attributes.
Attribute
Control
component
attributes
caption
action
Description
has the same general-purpose attributes as any Zen control.
These attributes include the onclick attribute, which determines what
happens when a user clicks the button.
Text displayed on this button.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
(Optional) String giving the action code associated with this
button. This value is passed along to the server-side %OnSubmit method
of the page that contains the . If not provided, the default string
is "submit".
Using Zen 175

Zen Controls
Attribute
nextPage
Description
(Optional) URI of the page to display after this form is successfully
submitted. If a button defines a nextPage value, it overrides the
nextPage value for the form that contains the .
12.4 Text
Zen offers the following text-style controls:
• — Displays a text label
• — The user inputs text
• — The user inputs multiple lines of text
• — The user inputs a text password
12.4.1
The control passively displays a static text value. Zen submits the along with other
controls on the . has the same attributes as any Zen control.
12.4.2
The Zen control is a wrapper around the HTML element. Zen
displays a text input box like this:
has the following attributes.
Attribute
Control
component
attributes
maxlength
size
Description
has the same general-purpose attributes as any Zen control.These
include the value, a string of text.
Maximum number of characters that the user may enter within this text
control.
Integer indicating the HTML width of the input area for this text control.
The default size is 20.
176 Using Zen

Text
12.4.3
The Zen control is a wrapper around the HTML element. Zen
displays a multi-line text input box, like this:
has the following attributes.
Attribute
Control
component
attributes
cols
rows
Description
has the same general-purpose attributes as any Zen control.
These include the value, a string of text that may or may not
include line break characters, depending on what the user types.
Keep in mind that many browsers do not cope well with long lines of
unbroken text (greater than 4K characters with no white space).
Number of columns in the control. The default is 19.
Number of rows in the control. The default is 2.
12.4.4
The Zen control is a wrapper around the HTML element.
Zen displays a text input box for passwords. Any text that the user enters into the
control is echoed as a dot instead of being displayed on the screen. For example:
has the following attributes.
Attribute
Control
component
attributes
maxlength
size
Description
has the same general-purpose attributes as any Zen control.
These include the value, a string of text.
Maximum number of characters that the user may enter within this control.
Integer indicating the HTML width of the input area for this control. The
default size is 20.
Using Zen 177

Zen Controls
12.5 Simple Choices
Zen offers the following simple choice controls:
• — The user checks or unchecks a box
• — The user browses to choose a file
• — The user selects one color from a palette
• — The user clicks one in a simple row of radio buttons
• — Radio buttons might be placed anywhere on the page
The difference between and is that is simpler to lay out. Use
for a concise list of choices. Use when you want a more complex page
layout that provides intervening information or images in between the radio button choices, or when
you want to place radio buttons in a vertical group.
12.5.1
The Zen control is a wrapper around the HTML element.
The Zen control displays a caption next to the check box and detects user mouse clicks
on the caption text as well as on the box. Unlike an HTML check box, the Zen control
always submits a value. Zen looks like this:
has the following attributes.
178 Using Zen

Simple Choices
Attribute
Control
component
attributes
caption
Description
has the same general-purpose attributes as any Zen control.
has a clientType of "boolean" which means its value is
expressed as "true" or "false" in XData Contents, 1 or 0 in server-side
code, and true or false in client-side code. True means the
is currently checked; false means it is unchecked.
Text displayed to the right of the check box. The above example uses:
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text into
other languages. See Zen Localization.
The caption value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
captionClass
Name of a CSS style class to apply to the caption text. The default is:
checkboxCaption
12.5.2
The component is a simple wrapper for the HTML element.
A Zen control looks like this. A user can enter a full pathname in the text field or click
the Browse button to search for the file:
has the following attributes:
Attribute
Control
component
attributes
maxlength
size
Description
has the same general-purpose attributes as any Zen control.
These include the value, a string that is the full pathname of
a file.
Maximum number of characters that the user may enter within this control.
Integer indicating the HTML width of the input area for this control. The
default size is 20.
Using Zen 179

Zen Controls
12.5.3
The component displays a row of color choices. The user can click on a color to select
it. offers a simple alternative to the complex palette in . A Zen
looks like this:
has the following attributes.
Attribute
Control
component
attributes
colorList
Description
has the same general-purpose attributes as any Zen control.
These include the value, a string that identifies the most
recently selected CSS color value.
Comma-separated list of CSS color values to display within the control,
from left to right. The default colorList value is as shown in the example
above:
",black,gray,darkblue,darkred,darkgreen,blue,red,green,yellow,orange,plum,purple,white"
12.5.4
The control displays a concise row of radio buttons to show a set of choices. A Zen
looks like this:
12.5.4.1 Logical and Display Values
The simplest way to define a is to provide a valueList for the user to choose from. You can
also add a corresponding displayList for the user to see. These attributes are as follows.
180 Using Zen

Simple Choices
Attribute
displayList
valueList
Description
(Optional) A comma-separated list of choices to display for this .
displayList applies only if a valueList is defined. Display values may differ
from the actual logical values.
The displayList attribute has its ZENLOCALIZE datatype parameter set to
1 (true). This means it is easy to localize the text into other languages, but
you must ensure that any translated displayList string remains a commaseparated
list. See Zen Localization.
Comma-separated list of logical values for the . One of these
logical values becomes the value when the user clicks on the
corresponding button.
You could produce the above sample with the following statement in XData Contents:
12.5.4.2 Query Attributes
A can indicate a data source for its buttons via an SQL query. offers a number
of attributes for this purpose. When you use this technique, the columns returned by the query determine
what is displayed in the as follows:
• If the %ResultSet has one column, the contents of this column are used as both the logical and
display values within the radioSet.
• If the %ResultSet has two (or more) columns, the contents of the first column supply the logical
value and the contents of the second column supply the display values.
provides the following attributes to support using a query.
Using Zen 181

Zen Controls
Attribute
maxRows
queryClass
queryName
sql
Description
(Optional) If a query is used to provide data, this is the maximum number
of items that will be displayed. The default is 500.
(Optional) The name of the class containing the query. You must also
provide a value for queryName.
(Optional) The name of the class query that will provide the %ResultSet for
this . You must also provide a value for queryClass.
(Optional) Server-side SQL query to get contents of the .
This attribute has the underlying data type %ZEN.Datatype.sql. This means
it cannot be accessed from the client. Its value is encrypted (using the
current session key) when it is sent to the client. If this value is returned to
the server, it is automatically decrypted. This makes it possible to place
sensitive data on the client for future processing on the server, without letting
a user view this data.
For additional details, plus examples, see the Zen Tables chapter as follows:
• How to use query attributes with :
- Data Sources (maxRows)
- Specifying an SQL Query (sql)
- Referencing a Class Query (queryClass, queryName)
• How to provide elements within :
- Query Parameters
12.5.4.3 General Attributes
has the following general-purpose attributes.
182 Using Zen

Simple Choices
Attribute
Control
component
attributes
captionClass
emptyCaption
Description
has the same general-purpose attributes as any Zen control.
These include the value, which is the logical value of the
currently selected button in the set.
(Optional) Name of the CSS style class to apply to captions for radio
buttons within this . The default is the built-in CSS style class
radioSetCaption.
The default caption to use for any buttons within this that
have no display value. If you do not specify an emptyCaption, the default
caption is:
None
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
titleList
Comma-separated list of tooltip text strings for each radio button in the
.
The titleList attribute has its ZENLOCALIZE datatype parameter set to
1 (true). This means it is easy to localize its text into other languages.
See Zen Localization.
12.5.5
The Zen control is a wrapper around the HTML element
with some enhanced capabilities. The Zen control has the following attributes.
Using Zen 183

Zen Controls
Attribute
Control
component
attributes
Description
has the same general-purpose attributes as any Zen control.
These include:
• name (not id) establishes the association between radio buttons.You
create a set of associated radio buttons by adding
elements to XData Contents and assigning the same name value to
each that in the set.
• At runtime, value always contains the optionValue of the button in the
set that is currently selected. As soon as the user selects one of the
buttons in the set, Zen resets the value of every button in this set to
the optionValue of the selected button. This makes it very easy for
you to determine which button in the set is currently selected, by
programmatically checking the value property of any button in the set.
caption
captionClass
optionValue
The caption text for this . Each button in the set needs a
caption so that the user can distinguish between the choices.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text into
other languages. See Zen Localization.
The caption value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
(Optional) Name of the CSS style class to apply to the captions for this
. The default is the built-in CSS style class
radioButtonCaption.
Defines a logical value to associate with this . The
optionValue for each radio button in the set must be unique.
The optionValue can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
12.6 Lists
Zen offers the following list controls:
• — You display a list box by using the Zen wrapper for HTML
• — You define a Zen list box with fixed options for the user to choose
184 Using Zen

Lists
• — Zen generates a list box for you, based on a runtime query
• — You define a Zen combo box with fixed options for the user to choose
• — Zen generates a combo box for you, based on a runtime query
A list box offers a simple list of options, but a combo box has two parts:
• A text control that displays the current value of the control
• A dropdown list that displays a set of options for the user to select
A combo box dropdown list may appear when activated by the user, for example when the user clicks
the button beside the control. There are a number of ways to reveal the dropdown list. The user can
click on an image or button, or the list can simply appear when the cursor has hovered over the control
for some length of time. You can specify these details when you place a list control on a Zen form, or
simply use the default characteristics that Zen provides.
12.6.1
The Zen control is a wrapper around the HTML element. Zen produces a
list from which the user can select an item.
12.6.1.1 Logical and Display Values
The simplest way to define a list is to provide a valueList for the user to choose from. You
can also add a corresponding displayList for the user to see. These attributes are as follows.
Using Zen 185

Zen Controls
Attribute
displayList
showEmpty
valueList
Description
(Optional) A comma-separated list of values to display for this list.
displayList applies only if a valueList is defined. Display values may differ
from the actual logical values.
The displayList attribute has its ZENLOCALIZE datatype parameter set to
1 (true). This means it is easy to localize the text into other languages, but
you must ensure that any translated displayList string remains a commaseparated
list. See Zen Localization.
When true, provides an extra blank row (value "") at the top of its
dropdown box. Typically, this is the desired behavior, so the default
showEmpty value is true.
showEmpty has the underlying data type %ZEN.Datatype.boolean. It has the
value "true" or "false" in XData Contents, 1 or 0 in server-side code, true or
false in client-side code. See Datatype Classes.
Comma-separated list of logical values for the list.
12.6.1.2 Query Attributes
A Zen control can indicate a data source for its list via an SQL query. Zen offers a
number of attributes for this purpose. When you use this technique, the columns returned by the SQL
query determine what is displayed within the list as follows:
• If the %ResultSet has one column, the contents of this column are used as both the logical and
display values within the dropdown.
• If the %ResultSet has two (or more) columns, the contents of the first column supply the logical
value and the contents of the second column supply the display values.
Zen provides the following attributes to support using a query.
186 Using Zen

Lists
Attribute
maxRows
queryClass
queryName
sql
Description
(Optional) If a query is used to provide data, this is the maximum number
of items that will be displayed. The default is 500.
(Optional) The name of the class containing the query. You must also
provide a value for queryName.
(Optional) The name of the class query that will provide the %ResultSet for
this list. You must also provide a value for queryClass.
(Optional) Server-side SQL query to get contents of the list.
This attribute has the underlying data type %ZEN.Datatype.sql. This means
it cannot be accessed from the client. Its value is encrypted (using the
current session key) when it is sent to the client. If this value is returned to
the server, it is automatically decrypted. This makes it possible to place
sensitive data on the client for future processing on the server, without letting
a user view this data.
For additional details, plus examples, see the Zen Tables chapter as follows:
• How to use query attributes with :
- Data Sources (maxRows)
- Specifying an SQL Query (sql)
- Referencing a Class Query (queryClass, queryName)
• How to provide elements within :
- Query Parameters
12.6.1.3 General Attributes
Zen has the following general-purpose attributes.
Attribute
Control
component
attributes
size
Description
has the same general-purpose attributes as any Zen control.These
include the value, a string indicating the user’s current choice from
the list.
Number of rows to display in the list.
Using Zen 187

Zen Controls
12.6.2
The Zen control displays a list box, whose options may be individually formatted.
The Zen control is not a wrapper around HTML . The Zen is implemented
using HTML primitives. This allows the to provide functionality not available with HTML
, including:
• Greater control over the contents of the list
• Solutions to problems with Internet Explorer interoperating with CSS
12.6.2.1 Options
The simplest way to define a Zen list box is to provide a set of elements inside a
component. The following statements produce the sample list box shown above:
The element is the XML projection of the %ZEN.Auxiliary.option class and supports the
attributes described in the following table.
188 Using Zen

Lists
Attribute
style
text
value
Description
(Optional) CSS style to apply to this option.
Display value. This is the text that the user sees in the list box.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
Logical value. This is the value that Zen submits for this control when it
submits the form. You must always provide both text and value for each
option in the list.
When you work with %ZEN.Component.listBox programmatically, you work with elements
as members of the options property, a list collection. Each in the becomes a
member of the options collection, associated with an ordinal position: 1, 2, 3, etc.
12.6.2.2 General Attributes
and have the following attributes in common.
List Box Component Attributes
Attribute
Control
component
attributes
listHeight
listWidth
selectedIndex
text
Description
A list box has the same general-purpose attributes as any Zen control.
These include the list box value, a string of text that represents the
currently selected logical value of the control.
CSS length value. If defined, listHeight overrides the default height of
the list box window, which is 250px.
CSS length value. If defined, listWidth overrides the default width of
the list box window, which is 250px.
0-based index of the currently selected option in the list box.The default
selectedIndex is –1 (nothing is selected).
The display text that corresponds to the currently selected item. Do not
access the text value directly; use getProperty('text') instead.
12.6.3
A is a specialized type of that presents the user with a list of options obtained
at runtime via an SQL query. Unlike , does not allow you to specify
elements or to set styles for individual options in the list. This is because uses a query
Using Zen 189

Zen Controls
to obtain a dynamic list of options. There are no statically defined options in a , so there
are no elements.
A with an item selected looks like this:
12.6.3.1 Query Attributes
The provides its list by creating, executing, and fetching from a %ResultSet object on
the server. You can specify how to create this %ResultSet object using the attributes that the
inherits from its parent class %ZEN.Auxiliary.QuerySource.
The columns returned by the SQL query determine what is displayed within the list,
as follows:
• If the %ResultSet has one column, the contents of this column are used as both the logical and
display values within the dropdown.
• If the %ResultSet has two (or more) columns, the contents of the first column supply the logical
value and the contents of the second column supply the display values.
The following topics in the chapter Zen Tables describe how to use QuerySource attributes:
• How to indicate a data source for a :
- Data Sources (maxRows)
- Specifying an SQL Query (sql)
- Generating an SQL Query ( groupByClause, orderByClause, tableName, whereClause)
190 Using Zen

Lists
- Referencing a Class Query (queryClass, queryName)
- Using a Callback Method (onCreateResultSet, onExecuteResultSet)
• How to provide elements within :
- Query Parameters
12.6.3.2 Display and Logical Values
has an sqlLookup attribute that works in the same way as for . See the
discussion of logical and display values later in this chapter.
12.6.3.3 General Attributes
has the following general-purpose attributes.
Attribute
List box
attributes
Data source
attributes
OnDrawItem
itemCount
sqlLookup
Description
has the same general-purpose attributes as the
component. cannot contain any
elements.
has the same attributes as for specifying
a data source and query parameters.
(Optional) Name of a server-side callback method that is called for
each item in the list before it is displayed. This callback receives the
logical and display values for the current item. It returns the HTML
that is to be displayed within the cell for the given item. OnDrawItem
must be the name of a server-only method in the page class that
contains this list box.
(Read-only) Number of options within the list. This is calculated when
the query for this component is run.
An optional SQL statement that is used under particular conditions.
See the discussion of logical and display values later
in this chapter.
12.6.4
The Zen provides a text field with a dropdown list below it:
Using Zen 191

Zen Controls
The Zen control is not a wrapper around HTML . The Zen is
implemented using HTML primitives. This allows the to provide functionality not
available with HTML , including:
• The ability to edit values in the text box
• Greater control over the contents of the list
• Solutions to problems with Internet Explorer interoperating with CSS
12.6.4.1 Logical and Display Values
The simplest way to define a is to provide a valueList for the user to choose from. You
can also add a corresponding displayList for the user to see. These attributes are as follows.
Attribute
displayList
valueList
Description
A comma-separated list of values to display for the list in this combo box.
displayList applies only if a valueList is defined. Display values may differ
from the actual logical values.
The displayList attribute has its ZENLOCALIZE datatype parameter set to
1 (true). This means it is easy to localize the text into other languages, but
you must ensure that any translated displayList string remains a commaseparated
list. See Zen Localization.
valueList overrides any elements provided within the
(see the discussion following this table).The valueList is a comma-separated
list of logical values for the dropdown list in this . If you provide
a valueList, you must also provide a displayList.
12.6.4.2 Options
Alternatively, you can define a by providing a set of elements inside a
component. is more flexible than a valueList and displayList because it allows you
to apply a CSS style to each of the list entries individually. For example:
192 Using Zen

Lists
The element is the XML projection of the %ZEN.Auxiliary.option class and supports the
attributes described in the following table.
Attribute
style
text
value
Description
(Optional) CSS style to apply to this option.
Display value. This is the text that the user sees in the combo box.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
Logical value. This is the value that Zen submits for this control when it
submits the form. You must always provide both text and value for each
option in the combo box.
When you work with %ZEN.Component.combobox programmatically, you work with elements
as members of the options property, a list collection. Each in the becomes a
member of the options collection, associated with an ordinal position: 1, 2, 3, etc.
12.6.4.3 General Attributes
and have the following attributes in common.
Combo Box Component Attributes
Attribute
Control
component
attributes
buttonCaption
buttonImage
buttonImageDown
Description
A combo box has the same general-purpose attributes as any Zen
control. These include the combo box value, a string of text that
represents the currently selected logical value of the control.
Caption used for the button when the comboType is "button".
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its
text into other languages. See Zen Localization.
URI of the image to display for the combo button in its normal state.
URI of image to display for the combo button in its down (pressed)
state.
Using Zen 193

Zen Controls
Attribute
buttonTitle
comboType
Description
Popup title used for the dropdown button when comboType is "button"
or "image".
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its
text into other languages. See Zen Localization.
How the dropdown box is activated for the combobox:
• "image" indicates that a user-clickable image should be displayed
next to the combo box text box. This is the default.
• "button" indicates that a button should be displayed next to the
combo box text box.
• "timer" indicates that the dropdown should appear shortly after
the user enters a value within the combo box text box.
delay
dropdownHeight
dropdownWidth
editable
maxlength
scrollIntoView
When comboType is "timer", delay specifies how many milliseconds
to wait after user finishes typing before showing the dropdown. The
default is 250 milliseconds.
CSS length value. If defined, dropdownHeight overrides the default
height of the dropdown window, which is 250px.
CSS length value. If defined, dropdownHeight overrides the default
width of the dropdown window, which is 250px.
If true, a user can directly edit the value within the input box as if it
were a text field. The default is false.
editable has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Maximum number of characters that the user may enter within this
control.
If true, Zen uses the JavaScript scrollIntoView function to try and
make visible the currently selected item within the dropdown.
scrollIntoView has the underlying data type %ZEN.Datatype.boolean.
It has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
194 Using Zen

Lists
Attribute
selectedIndex
size
unrestricted
Description
0-based index of the currently selected option in the dropdown list.
The default selectedIndex is –1 (nothing is selected).
HTML width of the text input area for this control. The default size is
20.
If true, and if editable is also true, values entered by the user may
be used as the value of the control. If false, the value is restricted to
one of the choices within the dropdown list. The default is false.
unrestricted has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
%ZEN.Component.combobox is a subclass of the %ZEN.Component.text control. This means you can
use the various methods defined by the text control to manipulate the text box portion of a
or .
12.6.5
A is a specialized type of that presents the user with a list of options
obtained at runtime via an SQL query. Unlike , does not allow you to
specify elements or to set styles for individual options in the list. This is because
uses a query to obtain a dynamic list of options. There are no statically defined options in a , so there are no elements.
A with text entered for a search looks like this:
Using Zen 195

Zen Controls
12.6.5.1 Query Attributes
The provides its list by creating, executing, and fetching from a %ResultSet object on
the server. You can specify how to create this %ResultSet object using the attributes that the inherits from its parent class %ZEN.Auxiliary.QuerySource.
The columns returned by the SQL query determine what is displayed within the list, as
follows:
• If the %ResultSet has one column, the contents of this column are used as both the logical and
display values within the dropdown list.
• If the %ResultSet has two (or more) columns, the contents of the first column supply the logical
value and the contents of the second column supply the display values. You can change which
columns are used to provide the logical and display values using the valueColumn and
choiceColumn attributes.
• If the %ResultSet has more than two columns, you can use the displayColumns and columnHeaders
attributes to specify that the dropdown should display multiple columns.
The following topics in the chapter Zen Tables describe how to use QuerySource attributes:
• How to indicate a data source for a :
- Data Sources (maxRows)
- Specifying an SQL Query (sql)
- Generating an SQL Query ( groupByClause, orderByClause, tableName, whereClause)
- Referencing a Class Query (queryClass, queryName)
- Using a Callback Method (onCreateResultSet, onExecuteResultSet)
• How to provide elements within :
- Query Parameters
12.6.5.2 Query Parameters
The query used to provide the contents of the dropdown list may contain one or more
runtime parameters, such as:
WHERE Name %STARTSWITH
Values for query parameters can be provided in one of the following ways:
• The can define a list, as described in the Zen Tables topic Query
Parameters. It is possible to modify the values of these parameters programmatically from the
196 Using Zen

client; if so, be sure to call the %ZEN.Component.dataCombo method clearCache so that the
dropdown query is re-executed with the new values.
Lists
• If searchKeyLen is set to a non-zero value, and editable is true, then the first searchKeyLen
number of characters in the current contents of the combo input box are used as the value for the
first query parameter. In this case, the first member of the parameters list is ignored. Any additional
query parameters are provided from the parameters list, with one exception: if any parameter value
is equal to "", then the current search key value (that is, the value used for the first parameter)
will also be used for this query parameter.
12.6.5.3 Logical and Display Values
Any list box or combo box has two current values:
• Logical value — its actual stored value as returned by the getValue method
• Display value — the value that the user views and selects in the dropdown list
The Zen controls , , and provide a fixed list of logical and display
values. When an application sets the value of one of these controls, it is simple for the control to
identify which display value is associated with the new logical value.
and acquire their values dynamically, so additional steps are needed to
achieve the same result. When an application sets the local value of a control, internally
the tries to find the display value that best matches this logical value. This works differently
on the server and client:
• On the server, executes the SQL statement defined by its sqlLookup attribute
• On the client, the first looks for a match for a given logical value within its dropdown
cache. If it does not find a match, it calls a server method to execute the sqlLookup query.
For example, suppose you want to define a to show a set of Customer names; the display
value will be Name while the logical value will be the ID of the Customer. To do this you define a
with two SQL statements, as follows:
This definition has the following effects:
1. The query defined by sql is called whenever the dropdown list is displayed. It provides a set of
logical (ID) and display (Name) values. The parameter gets its value from the contents of the
text field at the time when the dropdown appears; the value of searchKeyLen
Using Zen 197

Zen Controls
indicates that up to the first 10 characters will be used. The remembers the results
of the last query in a local cache.
2. The query defined by sqlLookup is used to find a specific display value for a specific logical value.
When this query is executed, the logical value of the control is provided as a query input parameter
(a within the SQL statement). This query must return a single row containing a display value.
3. The sqlLookup query is also executed when the application tries to set the logical value of this
at runtime, and the answer is not in the cache from item 1.
The sqlLookup attribute has the underlying data type %ZEN.Datatype.sql. This means it cannot be
accessed from the client. Its value is encrypted (using the current session key) when it is sent to the
client. If this value is returned to the server, it is automatically decrypted. This makes it possible to
place sensitive data on the client for future processing on the server, without letting a user view this
data.
12.6.5.4 General Attributes
has the following general-purpose attributes.
Attribute
Combo box
attributes
Data source
attributes
auxColumn
choiceColumn
Description
has the same general-purpose attributes as the
component. There can be no statically defined options,
so does not support the displayList and valueList
attributes. A also cannot contain any elements.
has the same attributes as for specifying
a data source and query parameters.
If there are multiple data columns displayed in the dropdown list,
auxColumn is the 1-based column number of the column that will
provide an additional auxiliary value for this control. auxColumn
provides a way to supply an additional value that is not the display or
logical value. If the auxColumn value is not a valid column number,
no auxiliary data is provided. The default auxColumn value is 0.
If there are multiple data columns displayed within the dropdown list,
choiceColumn is the 1-based column number of the column that will
provide the display value for this control. The default choiceColumn
value is 2. If the supplied choiceColumn value is greater than the
number of columns in the query, the second column is used.
198 Using Zen

Lists
Attribute
columnHeaders
displayColumns
loadingMessage
Description
If defined, columnHeaders is a comma-separated list of column
headers to display in the dropdown list.
The columnHeaders attribute has its ZENLOCALIZE datatype
parameter set to 1 (true). This means it is easy to localize its text into
other languages. See Zen Localization.
(Optional) If there are multiple data columns in the %ResultSet for the
, displayColumns can provide a comma-separated list
of 1–based column numbers. This list identifies which columns out of
the %ResultSet should be displayed.
This message is temporarily displayed while a server-side query is
running to populate the list. The default is:
$$$Text("Loading...","%ZEN");
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
multiColumn
searchKeyLen
showEmpty
If true, and if the result set contains more than 2 columns, display
multiple columns in the dropdown box. The default is true.
This attribute has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
If non-zero, searchKeyLen is the maximum number of search
characters for Zen to take from the combo input box and pass as a
parameter to the SQL query that provides the contents of the dropdown
list. If zero, the contents of the input box are not used as a query
parameter. The default is 0.
When true, the outputs an extra blank row (value "") at
the top of its dropdown box. Typically, this is the desired behavior, so
the default showEmpty value is true. Regardless of the showEmpty
value, this blank row does not display when the has its
control component attribute required set to true.
showEmpty has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side
code, true or false in client-side code. See Datatype Classes.
Using Zen 199

Zen Controls
Attribute
sqlLookup
valueColumn
Description
An optional SQL statement that is used under particular conditions.
See Logical and Display Values, above.
(Optional) If there are multiple data columns in the %ResultSet for the
, valueColumn identifies the 1-based column number
of the column that will provide the logical value for this control. The
default valueColumn is 1. If the supplied valueColumn value is greater
than the number of columns in the query, the first column is used.
12.6.5.5 Display Sequence
If you are interested in details of how Zen displays the , the following table lists the
internal events in sequence, organized by user viewpoint, browser-based execution, and server-side
execution. Most of the communication details are handled by the CSP technology underlying Zen. For
background information, see the chapter Zen Client and Server.
200 Using Zen

Lists
Display Sequence
User Viewpoint
In the Browser
On the Server
1
Select the dropdown
2
3
Dropdown is activated
Send hyperevent to the
server to execute SQL
4
5
Receive hyperevent to
execute SQL
Send hyperevent response
(consisting of JavaScript code)
to populate the dropdown unit
6
Server fills the dropdown
list
7
8
List fills with items
User selects an item
9
10
11
Dropdown item is selected
Call client-side select event
handler
Send hyperevent to the
server to start a
ZenMethod
12
13
14
Receive hyperevent to start
ZenMethod
Update server-side DOM
Send hyperevent response
(consisting of JavaScript code)
to synchronize client DOM
with server DOM
15
Update client-side DOM to
reflect changes made on
the server during the
ZenMethod
Using Zen 201

Zen Controls
16
User Viewpoint
In the Browser
Update visual presentation
of DOM-bound
components to match new
client-side DOM
On the Server
17
Form fields get filled
in based on the
selection
12.7 Calendars
Zen offers the following date selection controls:
• — The user selects dates from a popup calendar
• — The user can enter text or select a date
12.7.1
The component displays a navigable calendar, one month at a time. The user can view and
select dates from this calendar. A initially displays with the current date highlighted in
bold (7 in the example below) and the currently selected date in bold with a yellow background color
(14 in the example below). A Zen looks like this:
has the following attributes.
202 Using Zen

Calendars
Attribute
Control
component
attributes
dayList
Description
has the same general-purpose attributes as any Zen control.
These attributes include the value, a string in the format
YYYY-MM-DD (it has the datatype %Timestamp on the server).
Comma-separated list of day abbreviations to show at the top of the
calendar. The default value is:
$$$Text("S,M,T,W,T,F,S");
The dayList attribute has its ZENLOCALIZE datatype parameter set to
1 (true). This means it is easy to localize its text into other languages
and permits use of the $$$Text macro as shown in the default dayList
value. See Zen Localization.
endYear
firstDayOfWeek
fixedMonth
gapWidth
maxDate
Four-digit end year number for the year selector in the calendar. If not
defined, the default is the year portion of maxDate, if defined. Otherwise,
the default endYear is 30 years from now.
Number (Sunday=0, Saturday=6) that specifies which day of the week
is displayed as the starting day of the week. The default is 0 (Sunday).
If true, this calendar displays a single month and provides no way for
the user to change month and year. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
HTML length value giving the size of the gap between the month and
year indicators at the top of the calendar. Setting this provides a way
to adjust the width of the calendar.The above example uses the default
of 40px.
(Optional) String in the format YYYY-MM-DD (datatype %Timestamp on
the server). If specified, this is the latest date that the will
accept as its value. The maxDate value does not affect which years
are displayed by the calendar unless endYear is omitted.
The value supplied for maxDate can be a literal string, or it can contain
a Zen #()# expression. See Zen Runtime Expressions.
Using Zen 203

Zen Controls
Attribute
minDate
month
monthList
Description
(Optional) String in the format YYYY-MM-DD (datatype %Timestamp on
the server). If specified, this is the earliest date that the will
accept as its value. The minDate value does not affect which years are
displayed by the calendar unless startYear is omitted.
The value supplied for minDate can be a literal string, or it can contain
a Zen #()# expression. See Zen Runtime Expressions.
Number (January=1, December=12) that specifies which month of the
year is currently displayed by the calendar. This is not the same as the
current value, which includes a day and year, which can
include time, and whose month may be different.
Comma-separated list of month names to display in the list of months
that the user can choose from the calendar. The default value is:
$$$Text("January,February,March,April,May,June,July,August,September,October,November,December");
monthList has its ZENLOCALIZE datatype parameter set to 1 (true).
This means it is easy to localize its text into other languages and permits
use of the $$$Text macro as shown in the default monthList value. See
Zen Localization.
showTime
startYear
If true, this component displays a text entry field below the main calendar.
In the example above, showTime is true. The default is false.
The user can enter a time of day in the showTime field using the 24–hour
time format HH:MM:SS. When the form is submitted, the
value accepts both date and time values in the following ODBC/JDBC
timestamp format: YYYY-MM-DD HH:MM:SS
showTime has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
Four-digit start year number for the year selector in the calendar. If not
defined, the default is the year portion of minDate, if defined. Otherwise,
the default startYear is 10 years ago.
204 Using Zen

Calendars
Attribute
timeCaption
Description
Caption text for the showTime field. The default value is shown in the
example above:
$$$Text("Time:");
timeCaption has its ZENLOCALIZE datatype parameter set to 1 (true).
This means it is easy to localize its text into other languages and permits
use of the $$$Text macro as shown in the default timeCaption value.
See Zen Localization.
year
Four-digit number that specifies which year is currently displayed by
the calendar. This is not the same as the current value,
which includes a day and month, which can include time, and whose
year may be different.
12.7.2
The control is essentially a combo box. It displays a text box as well as a button that, when
pressed, displays a popup calendar. When the user enters a value into the text area of this control, Zen
either converts this value into the closest matching date value, or it displays an invalid date message.
Note:
always normalizes the date format to YYYY-MM-DD. There is no alternate
format for this built-in control.
A Zen component looks like this:
has the following attributes.
Using Zen 205

Zen Controls
Attribute
Control component
attributes
invalidDateMessage
Description
has the same general-purpose attributes as any Zen
control. These attributes include the value, a string in
the format YYYY-MM-DD (it has the datatype %Timestamp on the
server).
Message displayed by control when the date entered by the user
fails validation. The default is:
$$$Text("Invalid Date","%ZEN");
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption.This makes it easy to localize
its text into other languages. See Zen Localization.
maxDate
minDate
showTime
(Optional) String in the format YYYY-MM-DD (datatype %Timestamp
on the server). If specified, this is the latest date that the
will accept as its value. The maxDate value does not affect which
years are displayed by the calendar unless endYear is omitted.
The value supplied for maxDate can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
(Optional) String in the format YYYY-MM-DD (datatype %Timestamp
on the server). If specified, this is the earliest date that the
will accept as its value. The minDate value does not affect
which years are displayed by the calendar unless startYear is
omitted.
The value supplied for minDate can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
If true, this component displays a text entry field below the main
calendar. In the example above, showTime is true. The default is
false.
The user can enter a time of day in the showTime field using the
24–hour time format HH:MM:SS. When the form is submitted, the
value accepts both date and time values in the following
ODBC/JDBC timestamp format: YYYY-MM-DD HH:MM:SS
showTime has the underlying data type %ZEN.Datatype.boolean. It
has the value "true" or "false" in XData Contents, 1 or 0 in serverside
code, true or false in client-side code. See Datatype Classes.
206 Using Zen

Hidden Items
Attribute
size
Description
HTML width of the text input area for this control. The default is 15.
Note:
When you set the value property of a dateText control programmatically, this bypasses the
date matching function that Zen provides when the user sets the date by typing text in the
input field.
12.8 Hidden Items
The Zen control is a wrapper around the HTML element. The
control is present in the form, and has a value associated with it, but is never visible to the
user. The value can be changed programmatically on the client or server side. When the form is submitted,
the values of any controls are submitted along with all the others.
has the same general-purpose attributes as any Zen control. It has no additional attributes.
12.9 Spreadsheet
The control displays a two-dimensional, editable grid, similar to a spreadsheet. When the
user clicks in a cell, an edit control appears in the cell and the user can edit the cell contents. The user
presses Enter to save changes. A with a newly-edited cell looks like this:
You can create a in one of the following ways:
• Specify a data set, rows, and columns as described below
• Associate the with a Model View Controller
Using Zen 207

Zen Controls
12.9.1 Data Set
The data displayed within the is supplied by a %ZEN.Auxiliary.dataSet object. dataSet is
a special data container object that is used to define one-, two-, or three-dimensional data in a form
that can be easily transported between the server and client.
When a object is first created, it automatically creates a two–dimensional dataSet object
with the number of rows (dimension 1) and columns (dimension 2) specified by the number of
and entries within the definition in XData Contents. The following
example specifies four rows and four columns for the initial dataSet object:
An application can change the size and contents of the initial dataSet object by defining a server-side
callback method. You can specify the name of this callback method using the
OnCreateDataSet attribute, as in the example above. The OnCreateDataSet value must be the name
of a server-side callback method defined within the page class that contains the control.
In the above example, this method name is CreateDS. The OnCreateDataSet callback method is called
once, when the object is first created on the server and before the is first
displayed.
The signature of the OnCreateDataSet callback method must look like this:
Method CreateDS(
pGrid As %ZEN.Component.dynaGrid,
pDataSet As %ZEN.Auxiliary.dataSet) As %Status
Where:
• pGrid is the dynaGrid object that is invoking the callback.
• pDataSet is the dataSet object associated with the dynaGrid object.
• The method returns a %Status value indicating success or failure.
Typically a OnCreateDataSet callback method looks like this:
208 Using Zen

Spreadsheet
Method CreateDS(
pGrid As %ZEN.Component.dynaGrid,
pDataSet As %ZEN.Auxiliary.dataSet) As %Status
{
// make sure dataSet is cleared out
Do pDataSet.%Clear()
// fill in contents of dataSet
// This is a 2-D data structure
// row labels (dimension 1)
Do pDataSet.%SetLabel("Boston",1,1)
Do pDataSet.%SetLabel("New York",2,1)
Do pDataSet.%SetLabel("Chicago",3,1)
Do pDataSet.%SetLabel("Miami",4,1)
// column labels (dimension 2)
Do pDataSet.%SetLabel("Cars",1,2)
Do pDataSet.%SetLabel("Trucks",2,2)
Do pDataSet.%SetLabel("Trains",3,2)
Do pDataSet.%SetLabel("Planes",4,2)
// get size of dataSet
Set rows = pDataSet.%GetDimSize(1)
Set cols = pDataSet.%GetDimSize(2)
// fill in initial data values
For r=1:1:rows {
For c=1:1:cols {
Set value = 0
Do pDataSet.%SetValue(value,r,c)
}
}
}
Quit $$$OK
The above example defines a two–dimensional dataSet object with four rows and four columns. It
supplies labels for the rows and columns and then loops over the cells to provide initial values for the
cells.
If the OnCreateDataSet callback changes the dataSet object to contain three dimensions, this gives
the the ability to move among “pages” of data. Each page is displayed as a two-dimensional
grid that represents the currently visible “page.” The following figure illustrates this data model.
Note:
The next several topics provide details regarding the label attributes shown in the figure. See
, , and Dynamic Grid Attributes.
Using Zen 209

Zen Controls
Data Model for the Dynamic Grid Control
If there are pages in the , the gridLabel cell provides navigation information as follows.
Click on the > symbol for the next page. The number indicates
which page you are currently viewing:
12.9.2 Methods
Since the dataSet object is designed to work on either the server or the client, it provides local APIs
for both environments. The following table lists the server-side (ObjectScript) methods. For further
details, and to see the list of client-side (JavaScript) methods, see the class documentation for
%ZEN.Auxiliary.dataSet.
210 Using Zen

Spreadsheet
Note:
When you work with %ZEN.Component.dynaGrid programmatically, on the server side you
can access the dataSet object via the dataSet property of the dynaGrid object. On the client,
you cannot access the dataSet directly; you must the dynaGrid object’s getDataSet method
to get the dataSet object.
Server Method
%Clear
%GetArray
%GetDimensions
%GetDimSize
%GetLabel
Description
Clear the contents of the dataSet (set every cell to "") without
changing its size or number of dimensions.
Gets the contents of the dataSet as a multidimensional array,
subscripted by the 1–based dimensional addresses of the cells
(row, column, page). This array is passed to %GetArray by
reference.
Returns the number of dimensions within the dataSet.
Receives a 1–based number identifying a dimension (row, column,
page) and returns the number of cells in that dimension.
Receives two numbers:
• 1–based number identifying a cell position within a dimension
• 1–based number identifying the dimension (row, column, page)
%GetLabel returns the value of the label at the specified position.
%GetValue
%SetArray
Receives up to three 1–based numbers identifying a specific cell
in the grid (row, column, page). Gets the value of the cell at that
position.
Receives up to four arguments:
• A multidimensional array, passed by reference, and subscripted
by the 1–based dimensional addresses of the cells (row, column,
page).The local array must have the same dimensionality
as the dataSet and must have the correct number and type of
subscripts.
• Up to three 1–based numbers identifying the number of cells
in each dimension of the grid (row, column, page).
%SetArray copies the contents of the array into the dataSet.
%SetDimensions
Sets the number of dimensions within the dataSet to 1, 2, or 3.
Using Zen 211

Zen Controls
Server Method
%SetLabel
Description
Receives three arguments:
• String that specifies a label.
• 1–based number identifying a cell position within a dimension
• 1–based number identifying the dimension (row, column, page)
%SetLabel copies the string to the label at the specified position.
%SetValue
Receives up to four arguments:
• String that specifies a value.
• Up to three 1–based numbers identifying a specific cell in the
grid (row, column, page).
%SetValue sets the value of the cell at the indicated position.
%SetValue also updates the dimension size, if needed.
12.9.3
A with dimensions greater than zero must contain one or more and
elements to define the initial dimensions of the grid. defines dimension 1 of a one-
, two-, or three-dimensional .
The element is the XML projection of the %ZEN.Auxiliary.gridRow class.
supports the attributes described in the following table.
Attribute
height
hidden
label
Description
HTML height value to apply to this row, such as 0.3in or 3%.
If true, this row is not displayed. The default is false.
hidden has the underlying data type %ZEN.Datatype.boolean. It has the value
"true" or "false" in XData Contents, 1 or 0 in server-side code, true or false
in client-side code. See Datatype Classes.
Default text label for the row.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
212 Using Zen

Spreadsheet
Attribute
readOnly
rowName
style
Description
If true, cells in this row are read-only; the user cannot edit them.The default
is false.
readOnly has the underlying data type %ZEN.Datatype.boolean. It has the
value "true" or "false" in XData Contents, 1 or 0 in server-side code, true
or false in client-side code. See Datatype Classes.
Logical name of the row.
CSS style to apply to cells in this row, for example:
color: red;
If there is a column style and a row style active for a given cell, the row
style is applied before the column style.This means the column style might
override the row style.
title
Help text displayed when mouse hovers over this row. If there is a row title
and a column title active for a given cell, the column title overrides the row
title.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
When you work with %ZEN.Component.dynaGrid programmatically, you work with elements
as members of the dynaGrid property called rows. This is a list collection of %ZEN.Auxiliary.gridRow
objects. Each provided in the original definition in XData Contents becomes
a member of the rows collection, associated with its ordinal position in the : 1, 2, 3, etc.
12.9.4
A with dimensions greater than zero must contain one or more and
elements to define the initial dimensions of the grid. defines dimension 2 of a
two- or three-dimensional .
The element is the XML projection of the %ZEN.Auxiliary.gridColumn class.
supports the attributes described in the following table.
Using Zen 213

Zen Controls
Attribute
columnName
hidden
label
readOnly
style
Description
Logical name of the column.
If true, this column is not displayed. The default is false.
hidden has the underlying data type %ZEN.Datatype.boolean. It has the
value "true" or "false" in XData Contents, 1 or 0 in server-side code, true
or false in client-side code. See Datatype Classes.
Default text label for the column.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
If true, cells in this column are read-only; the user cannot edit them.The
default is false.
readOnly has the underlying data type %ZEN.Datatype.boolean. It has the
value "true" or "false" in XData Contents, 1 or 0 in server-side code, true
or false in client-side code. See Datatype Classes.
CSS style to apply to cells in this column, for example:
color: red;
If there is a row style and a column style active for a given cell, the row
style is applied before the column style. This means the column style
might override the row style.
title
width
Help text displayed when mouse hovers over this column. If there is a
row title and a column title active for a given cell, the column title overrides
the row title.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
HTML width value to apply to this column, such as 0.3in or 3%.
When you work with %ZEN.Component.dynaGrid programmatically, you work with
elements as members of the dynaGrid property called columns. This is a list collection of
%ZEN.Auxiliary.gridColumn objects. Each provided in the original definition
in XData Contents becomes a member of the columns collection, associated with its ordinal position
in the : 1, 2, 3, etc.
214 Using Zen

Spreadsheet
12.9.5 Attributes
When you place a element within an XData Contents block, you can assign it the following
attributes. When working with the programmatically, these attributes are available as
properties of the dynaGrid object.
Attribute
Control component
attributes
controllerId
currColumn
currPage
currRow
gridLabel
Description
has the same general-purpose attributes as any Zen
control. However, unlike most other controls it does not have a
single value.
If this is associated with a data controller, the
controllerId attribute identifies the controller that provides the data
for this .The controllerId value must match the id value
provided for that . See Model View Controller.
The 1–based column number of the currently selected cell in the
grid. The default (until the user makes selections) is 1.
The 1–based page number of the data currently displayed in the
grid. If the data set associated with this grid contains
three–dimensional data, currPage indicates which page (along
the third dimension) is currently displayed. The default is 1.
The 1–based row number of the currently selected cell in the grid.
The default (until the user makes selections) is 1.
Caption to display in the upper-left corner cell.
Although you enter ordinary text for this attribute, it has the
underlying data type %ZEN.Datatype.caption. This makes it easy to
localize its text into other languages. See Zen Localization.
Using Zen 215

Zen Controls
Attribute
onchangecell
Description
(Optional) Client-side JavaScript expression that is executed
whenever the user changes the contents of a cell. Generally this
expression invokes a client-side JavaScript method defined in the
page class. This method becomes the “onchangecell event handler”
for the .
If you omit the onchangecell attribute, the default behavior is to
assign the user-entered value to the cell.
When providing a value for an event handler attribute such as
onchangecell, use double quotes to enclose the value and single
quotes (if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions.
See Zen Runtime Expressions.
onclickcolumn
onclickrow
OnCreateDataSet
ondrawcell
oneditcell
(Optional) Client-side JavaScript expression that is executed
whenever the user clicks on a column header cell (at the top of a
column).
(Optional) Client-side JavaScript expression that is executed
whenever the user clicks on a row header cell (at the left of a row).
As described in the topic Data Set, the
OnCreateDataSet value is the name of a server-side callback
method that provides the data set associated with this .
(Optional) Client-side JavaScript expression that is executed when
the is about to draw a cell. If this event handler returns
a value, this value is used as DHTML to render the cell contents.
This convention provides a way to display custom cell formatting
within a .
(Optional) Client-side JavaScript expression that is executed when
the is ready to accept user input in one of its cells. If
the oneditcell event handler returns a value, this value is used as
DHTML to render the editor used for the cell. oneditcell provides
a way to display a custom cell editor within a . The
default behavior is to place an HTML input control over that region
of the grid to permit the user to enter data. There is no need to
override this default, but you may.
216 Using Zen

Spreadsheet
Attribute
onnotifyView
Description
This attribute applies if the is associated with a data
controller. The onnotifyView value is a client-side JavaScript
expression that is executed each time the data controller connected
to this raises an event. Generally this
expression invokes a client-side JavaScript method defined in the
page class.This method becomes the “onnotifyView event handler”
for the . See Model View Controller.
When providing a value for this attribute, use double quotes to
enclose the value and single quotes (if needed) within the
JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions.
See Zen Runtime Expressions.
rowLabelWidth
showColumnLabels
showRowLabels
HTML width value, such as 3 or 0.3in or 3%. rowLabelWidth
applies to the column of row labels. The default width is 100.
If true, column labels are displayed in a row along the top of the
grid. The default is true.
showColumnLabels has the underlying data type
%ZEN.Datatype.boolean. It has the value "true" or "false" in XData
Contents, 1 or 0 in server-side code, true or false in client-side
code. See Datatype Classes.
If true, row labels are displayed in a column along the left side of
the grid. The default is true.
showRowLabels has the underlying data type
%ZEN.Datatype.boolean. It has the value "true" or "false" in XData
Contents, 1 or 0 in server-side code, true or false in client-side
code. See Datatype Classes.
Using Zen 217

13
Model View Controller
To simplify the flow of data from a data source to a Zen page, Zen provides a set of classes that let
you define a data model (the model) and connect it to a set of Zen components (the view) via an
intermediate object (the controller). The name for this mechanism is Model View Controller, or
MVC. The following are some typical uses of MVC:
• Create a form that displays a set of properties, loaded from a persistent object within the database.
The form automatically displays controls appropriate to the data type of each property.
• Display a chart based on values within a form. The chart automatically updates its display whenever
the user submits any changes to the form.
• Display meters representing values calculated on the server. When the page is refreshed, these
meters automatically update themselves with current values from the server.
13.1 Architecture
The following figure shows the three parts of the MVC architecture — model, view, and controller
— and indicates where these objects execute their code. The controller and its associated views are
Zen components, placed on the Zen page. The controller component is hidden from view, but view
components are user-visible. The view components display data values, which they obtain by
requesting them from the controller. The controller resides on the client, but has the ability to execute
code on the server. The model resides entirely on the server. It draws its data values from a source on
the server and can respond to requests for data from the controller.
Using Zen 219

Model View Controller
Model View Controller Architecture
13.1.1 Data Model
A data model is any subclass of %ZEN.DataModel.DataModel. A data model can:
1. Retrieve data values from one or more sources, such as:
• A persistent Caché object
• An external database (ODBC or JDBC) via the Caché SQL Gateway
• A Caché global
• An Ensemble business service
2. Place these values into its own properties.
3. Make these properties available to be consumed by a data controller.
There are two variations on a data model class. Typically you will choose one of these as your parent
class when you create a new data model. The variations are closely related, but serve different purposes.
The available data model subclasses are %ZEN.DataModel.ObjectDataModel and
%ZEN.DataModel.Adaptor, as shown in the following figure.
220 Using Zen

Architecture
Data Model Classes
13.1.1.1 %ZEN.DataModel.ObjectDataModel
A subclass of %ZEN.DataModel.ObjectDataModel is called an object data model. It defines one or
more properties that a data controller component can consume. Each of these properties is correlated
with a value from the data source class. Not every value in the data source needs to be exposed in the
model. This convention allows you to expose in the data model only those values that you wish to.
An example of this might be a patient record, which contains confidential information that not every
application should expose. Keep in mind that when you use this option, the developer of the object
data model class is responsible for implementing methods to load values from a source into data model
properties, store values back to a source, and validate values. This is in contrast to the adaptor data
model, where Zen takes care of these details. However, this is not such a difficult procedure, as the
next major topic, Building a Form, will explain.
Using Zen 221

Model View Controller
For examples, use Studio to view the classes ZENMVC.FormDataModel and ZENMVC.FormDataModel2
in the SAMPLES namespace.
13.1.1.2 %ZEN.DataModel.Adaptor
There are many times where it is convenient to use a persistent object as a data model object. To make
this easy to accomplish, Zen provides the %ZEN.DataModel.Adaptor interface. Adding this an additional
superclass to a persistent class will make it possible to use the persistent class as a data model. This
data model makes available to a data controller any and all properties that it contains. This option is
useful when you want to expose every property in an existing class.
An example of this might be a class that you are using in an inventory or parts control application,
wherein each product might be described by a class with a large number of properties. If you want to
place all of these properties onto a form automatically without writing another class, you can simply
cause the product class to extend %ZEN.DataModel.Adaptor. Following that, Zen simply generates the
form for you, as later topics will explain.
The drawback of this choice is that your data and form are very closely linked. If you want some
flexibility, you should subclass the object data model class and implement the internal interface. This
is the classic trade-off of convenience versus flexibility.
For examples, use Studio to view the classes ZENMVC.Address and ZENMVC.Person in the SAMPLES
namespace.
13.1.2 Data Controller
A data controller is any subclass of %ZEN.Auxiliary.dataController. Through class inheritance, every
data controller is also a Zen component, as the following figure shows. This convention permits you
to place a data controller on a Zen page.
222 Using Zen

Architecture
Data Controller and Data View Classes
A data controller manages the communication between a data model and a data view. The
component appears in the page description along with other components, but it is not visible
on the output page. Its role is as an intermediary between a data model and one or more data views.
13.1.2.1 Data Controller Attributes
When you place a within a Zen , you can assign it the following attributes.
Attribute
Zen component
attributes
defaultSeries
modelClass
Description
A has the same general-purpose attributes as any
Zen component. The chapter Zen Style describes them. The id
attribute is required for . name and condition may
also apply. A is not visible, so visual style attributes
do not apply.
Optional. If a data model has multiple data series, defaultSeries is
a 1-based number that specifies which series should be used to
provide values to data views that can only display values from one
data series (such as a form). The default is 1.
Package and class name of the data model class that provides data
for this . Changing the modelClass value causes
the controller to abandon the previous model and load data from the
new model.
The modelClass value can be a literal string, or it can contain a Zen
#()# expression. See Zen Runtime Expressions.
Using Zen 223

Model View Controller
Attribute
modelId
oncreate
Description
String that identifies a specific instance of a data model object. The
form and possible values of the modelId string are determined by
the developer of the data model class. Changing the modelId value
causes the controller to load a new record, and to update its associated
views.
The modelId value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
Client-side JavaScript expression that runs each time the
createNewObject method is called. Generally this expression
invokes a client-side JavaScript method. This method becomes the
“oncreate event handler” for the .
When providing a value for an event handler attribute such as
oncreate, use double quotes to enclose the value and single quotes
(if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
ondelete
onerror
onnotifyController
onsave
Client-side JavaScript expression that runs each time the deleteId
method is called. The parameter id is passed to the event handler
and contains the modelId of the deleted object.
Client-side JavaScript expression that runs each time the data controller
attempts to open an instance of a data model object and
encounters an error.
When you work with a %ZEN.Auxiliary.dataController programmatically,
you can obtain the most recent error message reported by the data
model object associated with this data controller, by examining the
modelError property of the dataController object. This property is not
available as an XML attribute when adding the to
the Zen page.
Client-side JavaScript expression that runs each time a data view
connected to this data controller raises an event.
Client-side JavaScript expression that runs each time the save
method is called. The parameter id is passed to the event handler
and contains the current modelId.
224 Using Zen

Architecture
Attribute
autoRefresh
Description
Setting autoRefresh to a non-zero value turns on automatic refresh
mode for this data controller. In this mode, the data controller reloads
its data from the server at the periodic interval specified by
autoRefresh (in milliseconds). autoRefresh is provided as a
convenience for data controller used to drive meters or charts; it is
of limited use for forms. Setting autoRefresh to 0 disables automatic
refresh mode.
13.1.2.2 Data Controller Changes
The following data controller attributes can be changed to affects what is seen on screen:
• modelClass — Cause the data controller to look at a different data model
• modelId — Cause the data controller to look at a different data record within the same model
• defaultSeries — Cause the data controller to look at a different data series within the same data
record and model
The SAMPLES namespace class ZENMVC.MVCForm allows you to experience changes in these data
controller attributes. Try entering the following URI in the browser:
http://localhost:57772/csp/samples/ZENMVC.MVCForm.cls
Where 57772 is the Web server port number that you have assigned to Caché. To change the model
ID, click the Previous and Next buttons. to change the model class, click the Change Model button.
You can use Studio to view the class code.
13.1.3 Data View
A data view is any Zen component that implements the %ZEN.Component.dataView interface. As
shown in the previous figure, this includes:
•
• All forms
• All charts
• All meters
A data view component connects to its associated data controller at runtime, and uses it to get and set
values from the associated data model. A data view points to its data controller; more than one data
view can point to the same data controller.
Using Zen 225

Model View Controller
13.1.3.1 Data View Attributes
Data view components support the usual Zen component attributes, plus any specialized attributes that
are typical of the specific type of component. Additionally, all data view components support the following
attributes, which relate specifically to the component’s role as a data view.
Attribute
controllerId
dataBinding
Description
Identifies the data controller for this data view (). The controllerId value
must match the id value provided for that component.
Identifies the data model property that is bound to this component. This
property provides the value that the component displays:
• If the dataBinding value is a simple property name, this is assumed
to be a property within the data model class identified by the modelClass attribute.
• Alternatively, dataBinding can provide a full package, class, and
property name.
dataBinding is suitable only for components that display a single value
(meters or controls). Each meter on a Zen page must supply a controllerId
and a dataBinding. Controls do not support the data view interface, so
cannot supply a controllerId, but if the form that contains the controls
has an associated data controller, each control within the form can
supply a dataBinding attribute that identifies which property it displays.
onnotifyView
Client-side JavaScript expression that is executed each time the data
controller associated with this data view raises an event. Generally this
expression invokes a client-side JavaScript method defined in the page
class. This method becomes the “onnotifyView event handler” for the
data view component.
When providing a value for this attribute, use double quotes to enclose
the value and single quotes (if needed) within the JavaScript expression.
For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
226 Using Zen

Architecture
13.1.3.2 The Controller Object
When you work with a data view component programmatically, you can obtain a reference to the
associated %ZEN.Auxiliary.dataController object via the following properties of the
%ZEN.Component.dataView interface:
• controller — Use in JavaScript code that runs on the client side
• %controller — Use in ObjectScript or Basic code that runs on the server side
13.1.3.3 Multiple Data Views
Whenever a user modifies a value within one of the controls that is bound to a data controller, the data
controller is notified. It is common for data views to share a controller; for example, different types
of chart on the same page could share the same data controller to display different visualizations of
the same data, as in the following figure. If there are multiple data view components connected to the
same data controller, they are all notified of any change to a bound control.
For examples of shared data controllers, use Studio to view the classes ZENMVC.MVCChart and
ZENMVC.MVCMeters. The class ZENMVC.MVCMeters uses the same data controller to provide values
for a and several meters. The class ZENMVC.MVCChart provides a and three
charts that all use the same data controller. Try entering the following URIs in the browser:
http://localhost:57772/csp/samples/ZENMVC.MVCChart.cls
http://localhost:57772/csp/samples/ZENMVC.MVCMeters.cls
Where 57772 is the Web server port number that you have assigned to Caché.
When you change a value in one of these pages by editing it in the and pressing Enter,
this change affects the corresponding value in all the charts (or meters) on the same page, because all
of them share the same data controller. In the following figure, the user has just modified the Trucks
field in the for ZENMVC.MVCChart.
Using Zen 227

Model View Controller
13.2 Constructing a Model
This topic provides the first in a series of exercises that show how to use the Model View Controller
to create a form. The topics are:
• Constructing a Model
• Binding a to an Object Data Model
• Adding Behavior to the
• with an Object Data Model
• with an Adaptor Data Model
If you have a new Caché installation, before you begin these exercises you must first generate data
records for the SAMPLES namespace. You only need to do this once per Caché installation. Enter the
following URI in the browser:
http://localhost:57772/csp/samples/ZENDemo.Home.cls
Where 57772 is the Web server port number that you have assigned to Caché.
13.2.1 Step 1:Type of Model
There are two basic choices when generating a form using the Model View Controller:
• %ZEN.DataModel.ObjectDataModel or %ZEN.DataModel.Adaptor
An object data model takes more work to code. An object data model gives you explicit control
over which properties end up in the model, so it makes more sense for cases when you want to
shield certain properties from display or when you want to display charts, which require very fine
data control. The choice of adaptor data model is simple and convenient, but it imposes a burden
on the original persistent object, in that you must change its class code to allow it to become an
adaptor data model.
• or
A is a good choice for the key forms that are critical to the success of your application.
A requires more work to encode, but provides as fine a level of control as you need to
perfect the results. A provides automatic results and automatically updates its layout
if you change the underlying data model. This is useful to generate forms for large volumes of
detailed information such as system administration, inventory, or maintenance requests.
For this exercise we choose an object data model and a .
228 Using Zen

Constructing a Model
13.2.2 Step 2: Object Data Model
Suppose a persistent object called Patient contains a patient record. This object may have hundreds of
properties. Suppose you want to create a simple page that only displays demographic information, in
this case the patient’s name and city of residence. This is a clear case for using
%ZEN.DataModel.ObjectDataModel.
First, define an object data model class called PatientModel that knows how to load and store properties
from the Patient object:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4.
Choose File > New or Ctrl-N or the
5. Click the General tab.
6. Click the Caché Class Definition icon.
icon.
7. Click OK.
8. For Package Name enter:
MyApp
9. In the Class Name field, type:
PatientModel
10. Click Next.
11. Choose Extends
12. Click Next and enter (or browse to) this class name:
%ZEN.DataModel.ObjectDataModel
13. Click Finish.
Studio creates and displays a skeletal object data model class:
Class MyApp.PatientModel Extends %ZEN.DataModel.ObjectDataModel
{
}
14. Add properties and methods to complete the class as shown in the following code example. This
example defines two properties for the data model (Name and City). It also overrides several of
the server-side methods in the %ZEN.DataModel.ObjectDataModel interface. For documentation
of these methods, refer to the topic Object Data Model Callback Methods, later in this chapter.
Using Zen 229

Model View Controller
Class MyApp.PatientModel Extends %ZEN.DataModel.ObjectDataModel
{
Property Name As %String;
Property City As %String;
/// Load an instance of a new (unsaved) source object for this DataModel.
Method %OnNewSource(Output pSC As %Status = {$$$OK}) As %RegisteredObject
{
Quit ##class(ZENDemo.Data.Patient).%New()
}
/// Load an instance of the source object for this DataModel.
Method %OnSaveSource(pSource As ZENDemo.Data.Patient) As %Status
{
Set tSC=pSource.%Save()
If $$$ISOK(tSC) Set ..%id=pSource.%Id()
Quit tSC
}
/// Load an instance of the source object for this DataModel.
Method %OnOpenSource(pID As %String, pConcurrency As %Integer = -1,
Output pSC As %Status = {$$$OK}) As %RegisteredObject
{
Quit ##class(ZENDemo.Data.Patient).%OpenId(pID,pConcurrency,.pSC)
}
/// Delete instance of associated source object.
ClassMethod %OnDeleteSource(pID As %String) As %Status
{
Quit ##class(ZENDemo.Data.Patient).%DeleteId(pID)
}
}
/// Do the actual work of loading values from the source object.
Method %OnLoadModel(pSource As ZENDemo.Data.Patient) As %Status
{
Set ..Name = pSource.Name
}
Set ..City = pSource.Home.City
Quit $$$OK
/// Do the actual work of storing values into the source object.
Method %OnStoreModel(pSource As ZENDemo.Data.Patient) As %Status
{
Set pSource.Name = ..Name
Set pSource.Home.City = ..City
Quit $$$OK
}
15.
Choose Build > Compile or Ctrl-F7 or the
icon.
13.3 Binding a to an Object Data Model
This exercise creates a data controller based on the object data model from the previous exercise. It
then binds a form to this data controller.
230 Using Zen

Binding a to an Object Data Model
13.3.1 Step 1: Data Controller
If you do not already have a simple Zen application and page class available from previous exercises,
create them now using instructions from the Zen Tutorial chapter:
• Creating a Zen Application — Create the class MyApp.MyNewApp.
• Creating a Zen Page — Create the class MyApp.MyNewPage. You only need to complete the steps
in the first section, Step 1: New Page Wizard.
Now place a data controller component on the Zen page by adding a element in the
MyApp.MyNewPage class XData Contents block, inside the container, as follows:
Where:
• id is the unique identifier of the data controller on the Zen page. A data view (such as a form) will
specify its data controller using this id.
• modelClass is package and class name of the data model class. The previous exercise created the
class MyApp.PatientModel which is an object data model that represents objects of the
ZENDemo.Data.Patient class.
• modelId is a number that identifies the record to initially load from the data source. In this case,
it is the identifier of a specific ZENDemo.Data.Patient object.
Note:
The component is not visible on the page.
13.3.2 Step 2: Data View
Now create a form and connect it to the data controller, as follows:
1. Place a component inside the container.
Bind the form to the data controller from the previous topic by setting the controllerId
to match the id value. For example:
The id attribute does not affect the binding but becomes useful in a future step, when we will save
the form.
2. Within the add two controls.
Using Zen 231

Model View Controller
Bind each control to a property of the data model by providing a dataBinding attribute that
identifies a property within the modelClass of the . Also provide a label for each
control. For example:
The label attribute does not have any purpose relative to the Model View Controller, but it is
necessary if we want our controls to have a meaningful labels on the Zen page.
13.3.3 Step 3: Initial Results
View your initial results as follows:
1. Open your Zen page class in Studio.
2.
3.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the
icon.
icon.
The data controller component creates a MyApp.PatientModel object on the server, and asks it to
load data from data source record number 1 (identified by the modelId attribute)
into its own properties. The data controller places these data values into the appropriate controls
within the form. The dataBinding attribute for each control identifies which property provides the
value for that control, Name or City.
The following figure shows our form with the current values from record 1.
13.3.4 Step 4: Saving the Form
Suppose you want the user to be able to edit the values in this form, and to save changes. To save the
values in a form associated with a data controller, your application must call the form’s save method.
Typically you would enable this as follows:
1. Add a client-side method to the page class as follows:
232 Using Zen

Method save() [ Language = javascript ]
{
var form = zenPage.getComponentById('MyForm');
Binding a to an Object Data Model
}
form.save();
Now you can see why it was important to define an id for our . The method
getComponentById needs this id to get a reference for the form so that we can call its save
method.
2. Add to your page a that calls this method to save the form.
The entire definition now looks something like this:
3. Try editing the data and clicking Save.
Each time the user clicks the Save button, the form save method calls back to the server and saves the
data by calling the appropriate methods of the data model class. During this process, the form ask the
data controller to assist with data validation of the various properties. The source of this validation
logic is the data model class.
The data controller also has a save method we can use. There is a difference between saving the form
and saving the controller. Calling the save method of the form triggers the form validation logic, after
which the form instructs the controller to save data by calling the appropriate methods of the data
model class. Saving the controller skips form validation.
You can try out basic form validation in step 3 of this example as follows: If you empty the Patient
Name field entirely and click Save, a validation error occurs. This is because the Patient property is
marked as Required in the ZENDemo.Data.Patient class that serves as our data source. However, if
you change the Patient Name or Patient City to any non-empty value, the form saves correctly. It will
be easier to prove this to yourself once you have extended the form to allow you to easily view more
than one data record. Then you can switch back and forth between records to see that they in fact
contain your changes.
Note:
For further validation examples, try using and viewing the Zen page class ZENMVC.MVCForm
in the SAMPLES namespace. Try entering the following URI in the browser:
http://localhost:57772/csp/samples/ZENMVC.MVCForm.cls
Where 57772 is the Web server port number that you have assigned to Caché. Edit values
in one of the forms shown on the page, and click a Submit button. You can use Studio to
view the class code.
Using Zen 233

Model View Controller
Rather than wait for server-side validation, we can add client-side validation to the data model class
by defining a property-specific IsValidJS method. This is a JavaScript class method that uses the
naming convention propertyIsValidJS and returns an error message if the value of the given property
is invalid or '' (an empty string) if the value is OK. This method can be defined within the data model
class, or you can define a datatype class that defines a propertyIsValidJS method.
Adding the following method to the MyApp.PatientModel class causes the data controller to automatically
apply this validation to the City property on the client each time its save method is called:
ClassMethod CityIsValidJS(value) [Language = javascript]
{
return ('Boston' == value) 'Invalid City Name' : '';
}
13.4 Adding Behavior to the
The %ZEN.Auxiliary.dataController class offers several useful methods. Suppose you want to enhance
your page from the previous exercise so that it can open new records, create new records, delete existent
records, or reset the current record to a particular model ID. This topic explain how to accomplish
these tasks using dataController methods such as getModelId and setModelId.
13.4.1 Step 1: Opening a New Record
When you ask the browser to display the page you have been building during these exercises, it always
displays the same data record. This is because you have configured the modelId property of your
element with the value of 1. You can see what happens if you change this property
to other values, such as 2, 3, or 4, up to 1000.
However, you must remember that these values represent real ID values of existing instances of the
ZENDemo.Data.Patient class. These instances exist because all of the classes in ZENDemo.Data are
populated automatically when you first run the Zen Demo as described in the first chapter, Introducing
Zen.
Suppose you want to give the user the option of choosing which record to view. There are several
options, including:
• Add a text field that allows the user to enter an ID
• Add a combo box that allows the user to choose the record by one of its properties, such as a
patient name
• Add a table that allows the user to click on a patient name and see the details on a form below
It does not matter which option you choose for user input. The key task is for your page to be able to
tell the data controller to load the record. You can accomplish this as follows:
234 Using Zen

Adding Behavior to the
1. Open your Zen page class in Studio.
2. Add a new text field to the :
3. Add a corresponding client-side method:
Method loadRecord(id) [ Language = javascript ]
{
var controller = zenPage.getComponentById('patientData');
}
controller.setModelId(id);
The onblur event calls a client-side method loadRecord that first gets a pointer to the data controller
using its id value "patientData", then uses whatever the user has entered in the field as a
modelId to load the desired record from the data model. To actually load the record, loadRecord
uses the data controller method setModelId.
Also observe that this example binds the ID field to the %id property of the data model, so that
this field will always show you the ID of the current record. This is not necessary for setModelId
to work, but it will be very useful in the next topic.
4.
5.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the icon.
The following figure shows the form.
icon.
6. Try the onblur functionality as follows:
• Enter 2 (or any other number) in the ID field.
Using Zen 235

Model View Controller
• Press the Tab key to move out of the ID field.
• The alternate record should display.
7. In Binding a to an Object Data Model, Step 4: Saving the Form, you added Save functionality
without the ability to easily test it. Try it now, as follows:
• Note the number of the current record.
• Make a significant change to the Name or City field.
• Click Save.
• Enter a different number in the ID field.
• Press the Tab key to move out of the ID field.
• The alternate record should display.
• Enter the number for the record that you saved in the ID field.
• Press the Tab key to move out of the ID field.
• Your saved changes should be visible on the form.
13.4.2 Step 2: Creating and Deleting Records
Creating and deleting records are also simple tasks. Modify your page to add the necessary buttons
and client side code as follows.
1. Open your Zen page class in Studio.
2. After the and before the closing , replace the single Save button with the following
:
These statements add the buttons to an so that they will appear on the screen in a row.
Each button defines its onclick method as a different client-side method.
3. Add the corresponding new client-side methods to the page class:
Method newRecord() [ Language = javascript ]
{
var controller = zenPage.getComponentById('patientData');
}
controller.createNewObject();
And:
236 Using Zen

Method updateRecord() [ Language = javascript ]
{
var controller = zenPage.getComponentById('patientData');
Adding Behavior to the
}
controller.update();
And:
Method deleteRecord() [ Language = javascript ]
{
var controller = zenPage.getComponentById('patientData');
controller.deleteId(controller.getModelId());
controller.createNewObject();
}
Each of these methods uses a different dataController method to achieve its purposes.
4.
5.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the icon.
The following figure shows the form.
icon.
13.4.2.1 New
Suppose the user clicks New. Calling createNewObject immediately creates a new empty model. In
the browser, every time the user clicks New the form is emptied. After that, if the user completes the
empty form and clicks Save, this invokes the form’s save method. This (eventually) leads to a call to
the data model’s %OnSaveSource method on the server.
In Binding a to an Object Data Model, Step 4: Saving the Form, you added Save functionality
by causing the %OnSaveSource method to set the %id property of the model to the ID of the saved
object, as follows:
Using Zen 237

Model View Controller
Method %OnSaveSource(pSource As ZENDemo.Data.Patient) As %Status
{
Set tSC=pSource.%Save()
If $$$ISOK(tSC) Set ..%id=pSource.%Id()
Quit tSC
}
As a result, every time the user clicks New, enters values, then clicks Save, the form shows the newlyassigned
ID to the user (thanks to the dataBinding on that field). Of course, this only works if the data
entered in the form passes validation. Name is a required field, so if no Name is entered, the record is
not saved.
13.4.2.2 Delete
Suppose the user clicks Delete. The data controller’s deleteId method expects to recieve the ID for
the record to be deleted. Therefore, when the user clicks Delete, the page uses the data controller’s
getModelId method to determine the ID of the record the user is currently viewing. It passes this ID
on to deleteId. This (eventually) leads to a call to the data model’s %OnDeleteSource method on the
server. The source object is deleted, and since there will be no source object anymore, the page calls
the data controller’s createNewObject method to empty the form and prepare it for new input.
Important:
If, while using this exercise, you delete a record with a specific ID, this object no
longer exists. You cannot view or create a record with this ID again.
13.4.2.3 Update
Before clicking Update, the user must enter an ID number (between 1 and 1000) in the ID field. The
page updates the form fields with data from that record. This fails only if you have previously deleted
a record with that ID.
13.5 with an Object Data Model
This topic explains how to use with a data controller. In this case the data model is an
object data model.
13.5.1 Step 1: is Easy
You may create your first very easily as follows:
1. Create a new Zen page class. Use the steps in Creating a Zen Page, Step 1: New Page Wizard.
Call your new class anything you like, but keep it in the MyApp package. Be careful not to overwrite
your previous work.
2. In XData Contents, place a and inside :
238 Using Zen

with an Object Data Model
3.
4.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the
icon.
icon.
The form displays two fields that contain the current Name and City values for the record whose
modelId you entered in the statement. Perhaps you have changed these values,
or deleted this record, during previous exercises. Whatever data is now available for that modelId
displays.
The label for each control is determined by the corresponding property name in MyApp.PatientModel.
These labels are different from the text you assigned to the caption attribute when you used
and components to lay out the form. In all other respects, this display is identical to the
display you first saw in Building a Form, Step 3: Initial Results. Later steps show how to set specific
labels for the controls in a .
13.5.2 Step 2: Converting to
Now you are ready to recreate the example from previous exercises as a . To do
this, you will need to rewrite your MyApp.MyNewPage XData Contents block so that it looks like this:
Using Zen 239

Model View Controller
That is:
1. In Studio, return to your existing sample page, MyApp.MyNewPage.
2. Remove or comment out this , which specifies each control individually:
3. Add this , which relies on the data controller to supply it with any control definitions
that can be generated based on properties in the data model:
Where:
• controllerId identifies the data controller.
• defaultGroupId identifies the group, on the form, that will contain the controls generated by
that data controller.
• defaultGroupId is optional; but if it appears in the then somewhere inside the
, you must specify a group with an id that matches the defaultGroupId, in this
case a .
240 Using Zen

with an Object Data Model
• If you want controls to appear on the form that do not depend on the data controller, such as
the control whose value is based on the %id variable, you must place them explicitly, as
shown.
4.
5.
Choose Build > Compile or Ctrl-F7 or the
Choose View > Web Page or the icon.
The following displays:
icon.
6. You may assign specific labels to the generated controls on the as follows:
• In Studio, open the object data model class, MyApp.PatientModel.
• Edit the properties to add the ZENLABEL parameter to each of them:
Property Name As %String(ZENLABEL = "Patient Name");
And:
Property City As %String(ZENLABEL = "Patient City");
•
Choose Build > Compile or Ctrl-F7 or the
icon to compile the data model.
7. Refresh your Zen page MyApp.MyNewPage in the browser.
Your and now produce identical results.
13.5.3 Step 3: Automatic Control Selection
When you use instead of , it is no longer necessary to add data view components
(controls) to the form, item by item, as in the first example of building a form. This information is now
extracted automatically from the data model. determines which type of control to assign
to each property in the model based on its data type.
Using Zen 241

Model View Controller
The following exercise demonstrates this by adapting your existing page class to use a different data
model. When you complete the exercise and display the page, a new form will appear whose controls
are clearly different from those we previously used:
1. Return to Studio in the SAMPLES namespace.
2. Choose Tools > Copy Class.
3. The Class Copy dialog displays. Enter:
• Copy Class — MyApp.PatientModel
• To — MyApp.EmployeeModel
• Check the Replace Instances of Class Name box.
• Click OK.
The new class definition for MyApp.EmployeeModel displays in Studio.
4. Edit MyApp.EmployeeModel so that it has the following three properties only:
Property Name As %String;
Property Salary As %Numeric;
Property Active As %Boolean;
5. Edit the methods inside MyApp.EmployeeModel to work with the new properties:
Method %OnLoadModel(pSource As ZENDemo.Data.Employee) As %Status
{
Set ..Name = pSource.Name
}
Set ..Salary = pSource.Salary
Set ..Active = pSource.Active
Quit $$$OK
And:
Method %OnStoreModel(pSource As ZENDemo.Data.Employee) As %Status
{
Set pSource.Name = ..Name
}
Set pSource.Salary = ..Salary
Set pSource.Active = ..Active
Quit $$$OK
6.
Choose Build > Compile or Ctrl-F7 or the
icon.
7. Choose Tools > Copy Class.
8. The Class Copy dialog displays. Enter:
• Copy Class — MyApp.MyNewPage
• To — MyApp.MyOtherPage
• Check the Replace Instances of Class Name box.
242 Using Zen

with an Object Data Model
• Click OK.
The new class definition for MyApp.MyOtherPage displays in Studio.
9. Take a shortcut by leaving the id as "patientData".
You may ignore this shortcut by globally replacing "patientData" with a more meaningful id, for
example "employeeData". However, make sure you change all the instances of this id string in
the class, or you will encounter errors at runtime.
10. Change the modelClass to "MyApp.EmployeeModel".
11.
12.
Choose Build > Compile or Ctrl-F7 or the icon.
Choose View > Web Page or the icon.
The following figure shows the resulting form, with the values for record 5.
has chosen controls for this form as follows:
• for the Name, which is a %String
• for the Salary, which is %Numeric
• for the Active status, which is a %Boolean
Using Zen 243

Model View Controller
Property Type
Boolean
Date
Date
Enumerated
Enumerated
Numeric
Object reference
Stream
Stream
String
String
Public properties
Private properties
Controls Based on Property Types
Details
—
In YYYY-MM-DD format
In other formats
Using a VALUELIST with 4 or fewer values
Using a VALUELIST with more than 4 values
—
generates an SQL query
Character
Binary
With MAXLEN over 250
With MAXLEN between 1 and 250
All types not listed above
Any properties marked private
Control
Not displayed
If you do not like the choices that makes, you can switch to and bind each control
to a property individually, using the dataBinding attribute.
13.6 with an Adaptor Data Model
This topic explains how to use with a data controller when the data model is an adaptor
data model. This approach is particularly convenient when you have an existing class with a large
number of properties that you need to display on a form. In that case it would be extremely time-consuming
to add these properties one by one to a subclass of %ZEN.DataModel.ObjectDataModel, as
demonstrated in the previous topics. can save coding time, especially when you use it in
combination with a subclass of %ZEN.DataModel.Adaptor. All you need to do then is to create a Zen
page class whose contains a and a . Your subclass of
%ZEN.DataModel.Adaptor becomes the model, the view, and the controller, all in one. All of its properties
become controls on the resulting . Zen generates the appropriate control type for
property automatically.
244 Using Zen

with an Adaptor Data Model
13.6.1 Step 1: Generating the Form
The basic outline for using with an adaptor data model is as follows:
Note:
This example is based on the Zen classes ZENMVC.MVCDynaForm, ZENMVC.Person, and
ZENMVC.Address in the SAMPLES namespace.
1. Edit a persistent class so that it also extends %ZEN.DataModel.Adaptor, for example:
Class ZENMVC.Person Extends (%Persistent, %ZEN.DataModel.Adaptor)
{
Property Name As %String [ Required ];
}
Property SSN As %String;
Property Salary As %Numeric;
Property Active As %Boolean;
Property Home As Address;
Property Business As Address;
The Person class includes properties defined by another class, Address, which must also extend
%ZEN.DataModel.Adaptor but which need not be persistent, for example:
Class ZENMVC.Address Extends (%SerialObject, %ZEN.DataModel.Adaptor)
{
Property City As %String(MAXLEN = 50);
Property State As %String(MAXLEN = 2);
Property Zip As %String(MAXLEN = 15);
}
2. Compile both data model classes.
3. Create a new Zen page class.
4. In XData Contents, place a and inside :
5. Compile the Zen page class.
6.
Choose View > Web Page or the
icon.
generates the appropriate controls and displays the form, for example:
Using Zen 245

Model View Controller
13.6.2 Step 2: Property Parameters
Once you have the basics in place, you may refine the form by assigning data model parameters to the
properties in the persistent class that you are using as an adaptor data model. For example:
1. Open the data model class Person from the previous exercise.
2. Add data model parameters to the properties as shown below:
Class ZENMVC.Person Extends (%Persistent, %ZEN.DataModel.Adaptor)
{
Property Name As %String (ZENLABEL = "Employee Name") [ Required ];
Property SSN As %String (ZENREADONLY = 1);
Property Salary As %Numeric (ZENHIDDEN = 1);
Property Active As %Boolean (ZENLABEL = "Is this person working");
Property Home As Address;
Property Business As Address;
}
3. Compile the Zen page class.
4.
Choose View > Web Page or the
icon.
generates the appropriate controls and displays the form, for example:
246 Using Zen

with an Adaptor Data Model
The data model parameters have the following effects:
• ZENHIDDEN hides the control associated with that property.
• ZENLABEL replaces the default label (the property name) with a custom string.
• ZENREADONLY displays the control but prevents the user from editing its contents.
Note:
A full list of parameters is available at the end of this chapter, in the topic Data Model Classes,
subtopic Data Model Property Parameters.
13.6.3 Step 3: Adding Behavior to the
Adding behavior to a is quite similar to the steps outlined in the earlier topic, Adding
Behavior to the :
1. Open the Zen page class from the previous exercise.
2. Add a control to display the current model ID value, and buttons to permit Update, New,
and Save operations, as follows:
Using Zen 247

Model View Controller
3. Add the corresponding new client-side methods to the page class:
Method loadRecord(id) [ Language = javascript ]
{
var controller = zenPage.getComponentById('source');
}
controller.setModelId(id);
And:
Method showRecord() [ Language = javascript ]
{
var controller = zenPage.getComponentById('source');
}
controller.update();
And:
Method newRecord() [ Language = javascript ]
{
var text = zenPage.getComponentById('idText');
text.setValue("");
var controller = zenPage.getComponentById('source');
controller.createNewObject();
}
And:
Method save() [ Language = javascript ]
{
var form = zenPage.getComponentById('MyForm');
}
form.save();
4. Compile the Zen page class.
5.
Choose View > Web Page or the icon.
6. Click the New button.
7. Enter data in the fields (except ID) and click Save.
8. Click the New button again, just to clear the fields.
248 Using Zen

with an Adaptor Data Model
9. Enter the number 1 in the ID field and click Update. The corresponding record displays. For
example:
Since you have provided no special format for model ID values in the Person class, the default
prevails. This means each new record you add gets a sequential number starting at 1. You may
add more records by repeating steps 6 and 7. The numbers increment automatically.
If you try to view a record by entering an ID number that does not exist, the displays
with all of its fields disabled. You may click New to redisplay an active form in which to enter
data for a new record.
13.6.4 Step 4: Virtual Properties
If you want to interject changes in a data model before using it, you can override the
%OnGetPropertyInfo method in the data model class. This is the way to add virtual properties that
you want to use in the model, but that do not exist in the class that you began with. You can use
%OnGetPropertyInfo with either type of data model, but it makes the most sense for an adaptor data
model because in that case you are using an existing class as a data model.
Using Zen 249

Model View Controller
This exercise adds a %OnGetPropertyInfo method to the adaptor data model class Person from the
previous exercises.
1. Open the Person class in Studio.
2. Choose Class > Override.
3. Select %OnGetPropertyInfo and click OK.
Studio adds a skeleton %OnGetPropertyInfo method to the class.
4. Edit the method as follows:
These statements add a and a to any generated by the model.
ClassMethod %OnGetPropertyInfo(pIndex As %Integer,
ByRef pInfo As %String,
pExtended As %Boolean = 0) As %Status
{
#; Increment past the 3 embedded properties from the last Address object.
#; This is not necessary when the last property in the Person object
#; is a simple data type such as %String or %Boolean or %Numeric.
Set pIndex = pIndex + 3
#; add a field at the end of the form
Set pInfo("Extra") = pIndex
Set pInfo("Extra","%type") = "checkbox"
Set pInfo("Extra","caption") = "Extra!"
Set pInfo("Extra","label") = "This is an extra checkbox."
Set pIndex = pIndex + 1
#; add another field at the end of the form
Set pInfo("Comments") = pIndex
Set pInfo("Comments","%type") = "textarea"
Set pInfo("Comments","caption") = "Please enter additional comments:"
Set pIndex = pIndex + 1
}
Quit $$$OK
5. Recompile the Person class.
6. There is no need to recompile the Address class or the Zen page class.
7. View the Zen page that contains the associated , it generates the appropriate controls
and displays the form, for example:
250 Using Zen

Data Model Classes
13.7 Data Model Classes
The basic behavior of data models comes from the base class %ZEN.DataModel.DataModel. This class
defines the basic data model interface which is, in turn, implemented by subclasses. A data model
class can be one of the following types:
• The data model class serves as a wrapper for an independent data source. The data model object
provides the interface and the source object (or objects) provide the actual data. In this case the
data model class must implement the additional callback methods related to the data source object.
Our form examples followed this convention by subclassing %ZEN.DataModel.ObjectDataModel
and overriding several server-side callback methods.
• The data model class is also the data source object. The data model object provides both the data
and the interface. In this case, there is no need to override the callback methods related to the data
source object. All you need to do is to make your data source class implement the
Using Zen 251

Model View Controller
%ZEN.DataModel.Adaptor interface. Then you can use the resulting class directly as the modelClass
for the component in your page class.
13.7.1 Data Model Class Properties
The %ZEN.DataModel.DataModel class provides the following properties:
• String that identifies the currently active instance of the data model object, also known as the
model ID. This value can be initially set by providing a modelId attribute in the
definition. The exact form and possible values of the model ID are up to the developer of a specific
data model class. The property names are:
- id — Use in JavaScript code that runs on the client side
- %id — Use in ObjectScript or Basic code that runs on the server side
For examples, see the exercises in Adding Behavior to the .
• Array of strings that provide display names for the data series in the model. Each string labels one
data series. The array is subscripted by series number (1–based). The property names are:
- seriesNames — Use in JavaScript code that runs on the client side
- %seriesNames — Use in ObjectScript or Basic code that runs on the server side
• Number of data series contained within the data model. The property names are:
- seriesCount — Use in JavaScript code that runs on the client side
- %seriesCount — Use in ObjectScript or Basic code that runs on the server side
For details about series, see Data Model Series, later in this topic.
13.7.2 Data Model Class Parameters
Data model classes provide class parameters that determine the type of data model. The following
table lists them.
252 Using Zen

Data Model Classes
Data Model Class Parameters
Property Parameter
READONLYMODEL
DYNAMICPROPERTIES
Description
1 (true) or 0 (false). If true, indicates that this is a read-only
model. It can be used to display data but not to generate
editable forms. The default is 0 (false).
1 (true) or 0 (false). If true, indicates that this model supports
virtual properties as described in the exercise
with an Adaptor Data Model, Step 4: Virtual Properties, and
in the later topic Virtual Properties. The default is:
• 1 (true) for %ZEN.DataModel.ObjectDataModel
• 0 (false) for %ZEN.DataModel.Adaptor
13.7.3 Data Model Property Parameters
The %ZEN.DataModel.DataModel class provides property parameters that you can apply to the data
model properties that you wish to use as controls on a form. These parameters let you provide more
specific control over the properties of the data model class. The utility class
%ZEN.DataModel.objectModelParameters defines these parameters; the following table lists them.
Note:
For examples, use Studio to view the classes ZENMVC.FormDataModel and
ZENMVC.FormDataModel2 in the SAMPLES namespace. Also see the exercises in
with an Adaptor Data Model.
Data Model Property Parameters
Property Parameter
ZENATTRS
Description
List of additional attributes to apply to the control used for this
property. This string should have the following form:
"attribute:value|attribute:value"
ZENCONTROL
ZENDISPLAYCOLUMN
Type of control used to display this property within a form; If
not defined, Zen chooses the control type based on the data
type of the property.
If defined, this is the name of the column used to provide a
display value for SQL statements automatically generated for
this property.
Using Zen 253

Model View Controller
Property Parameter
ZENGROUP
ZENHIDDEN
ZENLABEL
ZENREADONLY
ZENSIZE
ZENSQL
ZENSQLLOOKUP
ZENTAB
ZENTITLE
Description
The id of a group component that the control used for this
property should be added to. This provides a way to control
layout. If not defined, the control is added directly to the form.
1 (true) or 0 (false). If true, indicates that this is a hidden field.
When the value of this field is sent to the client, it is not
displayed. The default is 0 (false).
Label used for this property within a form.
1 (true) or 0 (false). If true, this is a read-only field and cannot
be edited by the user. The default for is 0 (false).
If specified, this overrides the default size of the control used
to display the property within a form.
If defined, this is an SQL statement used to find possible values
for this property.This parameter corresponds to the sql property
of the various data-driven Zen components. For details, see
the chapter Zen Tables, topic Specifying an SQL Query.
If defined, this is an SQL statement used to find the appropriate
display value for a given logical value. This parameter
corresponds to the sqlLookup property of the various data-driven
Zen components. For details, see the chapter Zen Controls,
topic Lists, subtopic Logical and Display Values.
A positive integer. If specified, this will override the (1–based)
default tab order of the control used to display the property
within a form. All controls with ZENTAB specified are placed
before controls that do not define it.
Optional popup title string displayed for this property within a
form.
13.7.4 Object Data Model Callback Methods
When you create an object data model, you subclass %ZEN.DataModel.ObjectDataModel and provide
implementations for its server-side callback methods. The following table describes these methods in
detail. You first encountered several of these methods in the exercise topic Constructing a Model, Step
2: Object Data Model; the Example column indicates these.
254 Using Zen

Data Model Classes
Object Data Model Callback Methods
Method
%OnDeleteModel
%OnDeleteSource
%OnGetPropertyInfo
%OnInvokeAction
%OnLoadModel
%OnNewSource
%OnOpenSource
%OnSaveSource
%OnStoreModel
Example
—
Yes
—
—
Yes
Yes
Yes
Yes
Yes
This Callback Method is Invoked When...
The data model is deleted. This method is
implemented by the subclasses of the data model
class, if they exist.
The data model is deleted. If implemented, it is
responsible for deleting the object that has the given
id and returning the status code resulting from that
operation.
The %GetPropertyInfo method invokes it. See the
discussion following this table.
A user-defined, named action is invoked on this
model object. See the discussion following this table.
This method is implemented by the subclasses of
the data model class, if they exist.
Zen does the actual work of loading values from the
data source into the data model object.The only data
to load is the data that is actually seen by the user.
This is the place to perform any aggregation or other
operations on the data before storing it.
A data model needs a new instance. If implemented,
it opens a new (unsaved) instance of the data source
object used by the data model, and return its
reference.
A data model is opened. If implemented, it opens an
instance of the data source object used by the data
model, and returns its reference
The data model is saved. If implemented, it is
responsible for saving changes to the data source.
It saves the given source object and return the status
code resulting from that operation. Before returning
the status code, it sets the data model’s %id property
to the identifier for the source object.
Zen does the actual work of copying values from the
data model to the data source. This method loads
data from the model (probably changed by the user
through a form) back into the source object.
Using Zen 255

Model View Controller
Method
%OnSubmit
Example
—
This Callback Method is Invoked When...
A form connected to this data model is submitted.
The contents of this data model will be filled in from
the submitted values before this callback is invoked.
Implementing this callback is optional.
13.7.5 Virtual Properties
When a data controller needs to find information about the properties within a data model, it calls the
data model’s %GetPropertyInfo method. This returns a multidimensional array containing details
about the properties of the data model. The code that assembles this information is automatically
generated based on the properties, property types, and property parameters of the data model class.
A data model class can modify the property information returned by %GetPropertyInfo by overriding
the %OnGetPropertyInfo callback method. %GetPropertyInfo invokes the %OnGetPropertyInfo
immediately before it returns the property information. %OnGetPropertyInfo receives, by reference,
the multidimensional array containing the property information. %OnGetPropertyInfo can modify
the contents of this array as it sees fit. Properties can be added, removed, or have their attributes
changed. Attributes that you add using this method are called virtual properties.
Note:
For examples, see the exercises in with an Adaptor Data Model, Step 4: Virtual
Properties.
The %OnGetPropertyInfo signature looks like this:
ClassMethod %OnGetPropertyInfo(pIndex As %Integer,
ByRef pInfo As %String,
pExtended As %Boolean = 0,
pModelId As %String = "",
pContainer As %String = "") As %Status
Where:
• pIndex is the index number that should be used to add the next property to the list.
• pInfo is a multidimensional array containing information about the properties of this data model.
• If pExtended is true, then complete information about the properties should be returned; if false,
then only property names need be returned (applications can simply ignore this).
• pModelId is the id value of the current Data Model instance. This is provided for cases where the
contents of a dynamic form may vary by instance of the Data Model object.
• If this is an embedded property, pContainer is the name of the property that contains it.
256 Using Zen

Within the %OnGetPropertyInfo method, the property information array pInfo is subscripted by
property name. The top node for each property contains an integer index number used to determine
the ordinal position of a property within a dynamically generated form:
If you want %OnGetPropertyInfo to add a new property to a data model, simply add the appropriate
nodes to the property information array. The new property will be treated as a “virtual” property. That
is, you can set and get its value by name even though there is no property formally defined with this
name. When adding a new property in %OnGetPropertyInfo, set the top level node to the current
index number and then increment the index by 1:
pInfo("Property") = pIndex
Set pIndex = pIndex + 1
The property information array has a number of subnodes that can be defined to provide values for
other property attributes. Built-in attributes start with % and include:
• pInfo("Property","%type") = "control"
The %type subnode identifies the name of the Zen control that should be used for properties of
this type when using a dynamic form. Note that this name is the class name of a component. If
no package name is provided, it is assumed that this is a component in the %ZEN.Component
package. Use a full class name if you wish to specify a component from a different package.
• pInfo("Property","%group") = "groupId"
The %group subnode indicates the id of a group component contained by a dynamic form. If
%group is specified and there is a group with this id, then the control for this property will be
created within this group. This provides a way to control the layout of controls within a dynamic
form.
Attributes that do not start with a % specify values that should be applied to a property of the control
with the same name. For example, the following statement causes a dynamic form to set the label
property of the control used for the MyProp property to "My Label".
Set pInfo("MyProp","label") = "This is an extra field!"
Data Model Classes
Data models and data controllers each support the %OnGetPropertyInfo method. At runtime, the
order in which Zen adds controls to the generated form is as follows:
1. Creates an initial list of controls based on the data model properties and their parameters.
2. Modifies this list of controls by calling the data model’s %OnGetPropertyInfo method, if present.
3. Further modifies this list of controls by calling the data controller’s %OnGetPropertyInfo method,
if present.
Using Zen 257

Model View Controller
13.7.6 Controller Actions
The %OnInvokeAction callback lets you define “actions” that can be invoked on the data model via
the data controller. The client can invoke an action by calling the dataController’s invokeAction
method as follows:
controller.invokeAction('MyAction',data);
This, in turn, invokes the server-side %OnInvokeAction callback of the data model, passing the name
of the action and the data value. The interpretation of the action name and data is up to the application
developer.
13.7.7 Data Model Series
The basic data model object consists of a series of name-value pairs.
Data Model with Name-Value Pairs
The name-value pairs in the data model comprise all of the properties in the data model class, minus
those properties marked ZENHIDDEN, plus any properties added by %OnGetPropertyInfo, minus
any properties deleted by %OnGetPropertyInfo. By default, the number of series is 1, but it could
be larger. If there are multiple series in the model, conceptually it becomes a matrix.
258 Using Zen

Data Model Classes
Data Model with Data Series
You can add multiple series to the model if you write your own %OnLoadModel method, as in the
SAMPLES class ZENMVC.ChartDataModel2, shown below. This example creates three series for the
model and assigns values to data model properties in each of the series.
Class ZENMVC.ChartDataModel2 Extends %ZEN.DataModel.ObjectDataModel
{
Property Cars As %Integer;
Property Trucks As %Integer;
Property Trains As %Integer;
Property Airplanes As %Integer;
Property Ships As %Integer;
Method %OnLoadModel(pSource As %RegisteredObject) As %Status
{
Set scale = 100
}
#; This model has multiple data series. We set up the data series here.
Set ..%seriesCount = 3
Set ..%seriesNames(1) = "USA"
Set ..%seriesNames(2) = "Europe"
Set ..%seriesNames(3) = "Asia"
#; Now we provide data for each property within each series.
#; We use the %data array so that we can address multiple series.
For n = 1:1:..%seriesCount {
Set ..%data(n,"Cars") = $RANDOM(100) * scale
Set ..%data(n,"Trucks") = $RANDOM(100) * scale
Set ..%data(n,"Trains") = $RANDOM(100) * scale
Set ..%data(n,"Airplanes") = $RANDOM(100) * scale
Set ..%data(n,"Ships") = $RANDOM(100) * scale
}
Quit $$$OK
}
When your data model has multiple series, if you bind the data model to a chart, the chart automatically
picks up the various series, although you need to be careful with a pie chart. Series work similarly for
Using Zen 259

Model View Controller
a grid. A form can only display one series at a time, so you need to rely on the data controller attribute
defaultSeries to determine which series is currently in view.
13.7.8 Custom Data Model Classes
%ZEN.DataModel.ObjectDataModel or %ZEN.DataModel.Adaptor are sufficient for most needs. However,
sometimes a developer might want to create a special category of data model, for example to represent
a global. In that case the developer must subclass %ZEN.DataModel.DataModel and implement the
details of this subclass.
The following table lists methods that applications can call in order to work with a data model object.
The behavior of these methods is up to the specific %ZEN.DataModel.DataModel subclass that implements
them.
Custom Data Model Class Methods
Method
%DeleteModel
%OpenModel
%SaveModel
Description
Delete an instance of a data model object given an identifier value.
This takes the given identifier value and uses it to delete an instance
of a source object (if applicable). (If the data model object serves as
both interface and data source, then the data model object itself is
deleted).
Open an instance of a data model object given an identifier value.
This takes the given identifier value and uses it to find an instance
of a source object (if applicable) and then copies the appropriate
values of the source object into the properties of the data model
object. (If the data model object serves as both interface and data
source, then this copying is not carried out).
Save an instance of a data model object. This copies the properties
of the data model object back to the appropriate source object (if
applicable) and then asks the source object to save itself. (If the data
model object serves as both interface and data source, then the data
model itself is saved.).
260 Using Zen

14
Navigation Components
The Zen Layout chapter, Groups topic introduced Zen group components as the key to laying out the
Zen page. That chapter described the simple group components , , , ,
and .
This chapter describes a more complex set of group and menu components. A developer can use these
components to support navigation through Zen applications:
• Links — Link to other Zen pages, or other application content, via a URI.
• Menus — Present and manage a structured set of choices, usually links.
• Tabs — Define tabbed menus and tabbed forms.
• — Display a group that expands or contracts when the user clicks on an icon.
The following table organizes Zen navigation components into two categories: containers (at left) and
contained (at right). This chapter describes each component in the order listed in the table.
Using Zen 261

Navigation Components
Container
(Any)
Purpose
Provide a link to another page
or to a popup message.
Navigation bar for the top of
the page.
Menu container. The default
layout is vertical but you can
use the layout attribute to
change to horizontal layout.
Alternatively, you may use
or .
Horizontally oriented menu
Vertically oriented menu
Traditional set of tabs from
which the user can choose
one to be displayed on top of
the set.
A tabbed menu that displays
a button for each tab. Clicking
on a button makes the tab
contents display beneath the
button. Each tab consists of
menu items.
A tab is a group that may
contain any combination of
components.
Expanding and contracting
group which may contain any
combination of components.
Components It Typically Contains
for each link.
for each link in the
navigation sequence.
for each option.
for the space
between options.
for each option.
Inside a , each
contains and
components.
For a simple navigation tree, you can
provide components within
.
The following figure lists the components described in this chapter. All of the classes shown in the
diagram are in the package %ZEN.Component, for example %ZEN.Component.tab. The diagram shows
the inheritance relationships for these classes. It also highlights which of these components can contain
other components, by showing which components inherit from %ZEN.Component.group.
262 Using Zen

Links
Zen Navigation Components
14.1 Links
The following Zen components provide links to content that is available via a URI:
•
•
14.1.1
The component outputs a simple link (an HTML anchor element) to the Zen page. The default
formatting for this type of link is to use color and underline it. has the following attributes.
Attribute
Zen
component
attributes
Description
has the same general-purpose attributes as any Zen component.
The chapter Zen Style describes them.
Using Zen 263

Navigation Components
Attribute
caption
disabled
href
Description
Text for this link in the Zen page display.
The caption value can be a literal string, or it can contain a Zen #()#
expression. See Zen Runtime Expressions.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
If true, this link is disabled. The default is false. A newly disabled link is
redisplayed, without an anchor tag, to ensure that it is truly disabled from
the user’s point of view.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
URI of the content to display when the user clicks the caption text. If you
want to invoke a client-side JavaScript method in the href, start the URI
with javascript: as in:
href="javascript:zenPage.myMethod();"
The href value can be a literal string, or it can contain a Zen #()# expression.
See Zen Runtime Expressions.
onclick
(Optional) Client-side JavaScript expression that Zen invokes when the
user clicks on the link. Generally this expression invokes a client-side
JavaScript method.This method becomes the “onclick handler” for the link.
If onclick is specified, href is ignored. If onclick is not specified, the link
displays the content specified by href.
When providing a value for an event handler attribute such as onclick, use
double quotes to enclose the value and single quotes (if needed) within
the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
style
CSS style to apply to cells in this link, for example:
color: red;
264 Using Zen

Links
Attribute
title
Description
Help message to display when the user hovers the cursor over the link,
without clicking.
The title value can be a literal string, or it can contain a Zen #()# expression.
See Zen Runtime Expressions.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
One way to use is to place it within an component to present a tree-style menu of
links.
14.1.2
A looks like the following example, based on the class ZENTest.FormTest in the SAM-
PLES namespace:
The corresponding definition follows. As this example shows, entries
within the display their caption values on the Zen page in sequential order, from left to
right. The text for each caption is enclosed in square brackets. Captions are further separated by a right
angle bracket to indicate the navigation sequence. The next topic provides additional details about
attributes.
has the following attributes.
Using Zen 265

Navigation Components
Attribute
Zen component
attributes
OnGetQuickLinks
Description
has the same general-purpose attributes as any Zen
component. The chapter Zen Style describes them.
(Optional) Name of a server-side method that returns an array of
“quick links.” If provided, these links are displayed in a dropdown
list at the edge of the locator bar. The array is of the form:
pLink("caption")=url
The OnGetQuickLinks value must be the name of a server-only
method in the page class that contains this form component.
14.1.3
can appear only inside the container. Each defines one
link within the navigation chain expressed in the . is the XML projection
of the auxiliary class %ZEN.Auxiliary.locatorLink. has the following attributes.
Attribute
id
name
caption
href
Description
This value can be used to select a CSS style definition for the .
Component name. Typically, this is not used for .
Text for this link in the .
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
URI of the content to display when the user clicks the caption text. If you
want to invoke a client-side JavaScript method in the href, start the URI with
javascript: as in:
link="javascript:zenPage.myMethod();"
title
Help message to display when the user hovers the cursor over the link,
without clicking.
Although you enter ordinary text for this attribute, it has the underlying data
type %ZEN.Datatype.caption. This makes it easy to localize its text into other
languages. See Zen Localization.
266 Using Zen

Menus
14.2 Menus
Menu components permit you to create classic navigation menus, with lists of choices from which the
user can select an item by clicking on it. With each choice of a menu item, an event may occur
depending on how the menu and menu item have been defined:
• A submenu might display
• A message might pop up
• A different page might display
• The contents of the current page might change
• Something else might happen, depending on how you have programmed the menu to respond
when the user selects each
A vertical menu, expanded to three levels, looks like the following example, based on the class
ZENTest.MenuTest in the SAMPLES namespace. Any options that produce submenus use the » right
angle quote to indicate this, as shown for “Submenu” and “Sub Submenu”.
The definition that produced this illustration is shown below:
Using Zen 267

Navigation Components
The next several topics explain details of the menu components in this example. For now, simply note:
• In many cases, the example uses JavaScript alerts in place of URI links for demonstration purposes.
link values can take this form, or they can redirect the browser to other pages in the Zen application,
as the example shows:
• A can contain a . If so, the contained becomes a submenu and its caption
is listed in sequence along with any components at the same level. The above
example provides three levels of .
• The example provides a on the first- and third-level menus. Note how the
component generates the divider bar between “Submenu” and “Test Suite” and
between “Sub Submenu” and “Help Desk” in the output.
14.2.1
Each item on a is defined using . has the following attributes. Since
either of them may display their caption or image as a choice within a menu cell, and
share all of these attributes in common. has additional attributes; the next topic
describes them.
Menu Cell Attributes
Attribute
Zen
component
attributes
Description
and have the same general-purpose attributes
as any Zen component. The chapter Zen Style describes them.
268 Using Zen

Menus
Attribute
caption
disabled
help
image
Description
Text for this menu item when it appears as a choice within its containing
.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
If true, this menu item is disabled. The default is false.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
The help attribute supplies help text for this menu item.
Generally what you want in place of help is the title attribute. title supplies
tooltip text that displays whenever the user hovers the mouse over this
item. All Zen components, including and , support
the title attribute.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Identifies the pathname and filename of an image to display for this
menu item. If both image and caption are provided, they appear side
by side, teh image at left and the text at right.
The image path is relative to the Caché installation directory. Typically
this path identifies the images subdirectory for your Zen application, for
example:
imageHeight
imageWidth
link
If an image is provided, imageHeight is its height in pixels. The default
is 16.
If an image is provided, imageWidth is its width in pixels. The default is
16.
URI of the content to display when the user clicks the menu item. If you
want to invoke a client-side JavaScript method in the link, start the URI
with javascript: as in:
link="javascript:zenPage.myMethod();"
Using Zen 269

Navigation Components
Attribute
linkResource
onclick
Description
Name of a Caché resource. The user must have privileges to access
this resource or this menu item becomes disabled. If you are not familiar
with Caché resources, see the Caché Security Administration Guide
chapter Assets and Resources.
(Optional) Client-side JavaScript expression that Zen invokes when the
user clicks on the menu item. Generally this expression invokes a clientside
JavaScript method. This method becomes the “onclick handler” for
the menu item.
If onclick is specified, link is ignored. If onclick is not specified, the menu
item displays the content specified by link.
When providing a value for an event handler attribute such as onclick,
use double quotes to enclose the value and single quotes (if needed)
within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
14.2.2 , , and
All Zen groups that do not have a predefined layout setting have a vertical layout by default. This is
true for the component. However, it can be useful to explicitly state the desired layout of the
menu group. You can do this by:
• Setting a value for the layout attribute (as in the example above)
• Choosing one of the following in place of :
- — a horizontally oriented list of choices
- — a vertically oriented list of choices
, , and have the following attributes.
Attribute
Zen group
attributes
Description
A menu has the same style and layout attributes as any Zen group. The
chapter Zen Layout describes them. The layout attribute does not apply
to or because these components have layout set to
"horizontal" and "vertical" respectively.
270 Using Zen

Tabs
Attribute
Zen menu
cell attributes
onactivate
Description
A menu may display its caption or image as a choice within a menu cell.
For this reason, , , and share a number of
attributes in common with . See the previous topic.
If this menu is a submenu, onactivate is the client-side JavaScript
expression that Zen invokes just before the submenu is made visible.
Generally this expression invokes a client-side JavaScript method. This
method becomes the “onactivate handler” for the menu.
When providing a value for an event handler attribute such as onactivate,
use double quotes to enclose the value and single quotes (if needed)
within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
onshowHelp
Client-side JavaScript expression that Zen invokes when the user moves
the mouse over this menu item. Generally this expression invokes a
client-side JavaScript method.
14.2.3
A bar helps to visually group the options on a . has the
same general-purpose attributes as any Zen component. The chapter Zen Style describes them.
has no additional attributes.
14.3 Tabs
The following Zen components support tabbed menus and forms for Zen applications:
•
•
•
Using Zen 271

Navigation Components
14.3.1
A displays a set of components. It can only display one at a time. The user
can choose one of these tabs to be displayed on top of the set. A looks like the following
example, based on the class ZENTest.TabTest in the SAMPLES namespace.
In the above example, the user has clicked the tab labelled “First Page.” In the following example, the
user has clicked the tab labelled “Second Page” and has clicked the down-arrow to select a “Home
City” option from the control.
272 Using Zen

Tabs
The definition that produces these illustrations is shown below:
Using Zen 273

Navigation Components
This is the first tab!
This is the second tab!
This is the third tab!
has the following attributes. Since either or may display
components, both and share these attributes in common. has additional attributes that distinguish it from ; the next topic describes them.
274 Using Zen

Tabs
Tab Group Attributes
Attribute
Zen group
attributes
currTab
onhideTab
Description
and have the same style and layout
attributes as any Zen group. The chapter Zen Layout describes them.
1–based sequential number of the tab currently displayed. The default
is 1.
(Optional) Client-side JavaScript expression that Zen invokes when a
previously displayed tab becomes hidden. Generally this expression
invokes a client-side JavaScript method. This method becomes the
“onhideTab handler” for the menu item.
When providing a value for an event handler attribute such as onhideTab,
use double quotes to enclose the value and single quotes (if needed)
within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
onshowTab
remember
showTabBar
Client-side JavaScript expression that Zen invokes when a previously
hidden tab becomes the displayed tab. Generally this expression invokes
a client-side JavaScript method.
If true, remember the most recently displayed tab number in a session
cookie and return to this tab when redisplayed. The default is false.
remember has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
If true, display a set of tab buttons along the top of this group.The default
is false.
remember has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
14.3.2
A presents a stack of buttons, one for each tab. Clicking on a button shifts the other
buttons down so that they display below the contents of the currently selected tab.
Using Zen 275

Navigation Components
The following example is based on the class ZENTest.LookoutMenuTest in the SAMPLES namespace.
In the illustration, the user has clicked the “Animal” button to reveal the contents of that tab. This
selection moved the remaining buttons to the bottom of the lookout menu. The cursor is now on the
“Vegetables” menu item. If the user clicks this item, the contents of its link will be activated as defined
in the corresponding .
A contains a set of components, which in turn contain and
components. These tabs are groups that can contain any component, but when they
are present inside a they contain the components that would normally define a .
The definition that produced the above illustration follows:
276 Using Zen

Tabs
has the following attributes.
Attribute
Zen tab
group
attributes
expandable
Description
shares a number of attributes in common with .
See the previous topic. also has the attributes listed in this
table.
If true, this group is expandable. The default is false.
When expandable is true, an expansion bar displays along the top of the
as shown in the illustration above. The user clicks on this
bar to toggle the expanded state of the . When the menu
is contracted, only the expansion bar is visible. The user clicks the bar
again to expand the .
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
Using Zen 277

Navigation Components
Attribute
expanded
oncontract
Description
If true, this group is expanded (children visible). If false, it
is contracted (children not visible). The default is true.
expanded has the underlying data type %ZEN.Datatype.boolean. It has the
value "true" or "false" in XData Contents, 1 or 0 in server-side code, true
or false in client-side code. See Datatype Classes.
Client-side JavaScript expression that Zen invokes just before contracting
(hiding) the children of this group. Generally this expression
invokes a client-side JavaScript method. This method becomes the
“oncontract handler” for the .
When providing a value for an event handler attribute such as oncontract,
use double quotes to enclose the value and single quotes (if needed) within
the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
onexpand
Client-side JavaScript expression that Zen invokes just before expanding
(displaying) the children of this group.
14.3.3
A is a specialized group that defines a tab within a or . has
the following attributes.
278 Using Zen

Expanding Group
Attribute
Zen group
attributes
caption
tabResource
Description
has the same style and layout attributes as any Zen group. The
chapter Zen Layout describes them.
Text for this tab when it appears as a choice within its containing or .
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Name of a Caché resource.The user must have privileges to access this
resource or this tab becomes disabled. If you are not familiar with Caché
resources, see the Caché Security Administration Guide chapter Assets
and Resources.
14.4 Expanding Group
The is a group with the ability to show or hide its children. A clickable graphic beside the
label expands (displays) or contracts (hides) the contents of the group. A fully contracted
group looks like the following example.
The user expands the group by clicking on the plus sign beside its label. The contents of the
then display below its label. As a Zen group, an may contain any type of Zen
component. In particular, each level of the may contain additional, nested
groups that can be expanded or contracted independently of the containing group.
In the following example, the user has just clicked on the plus sign to expand the group. The cursor is
now poised to contract the by clicking the minus sign
beside the label. This example
Using Zen 279

Navigation Components
contains three nested groups. The innermost uses a horizontal layout, and
contains components instead of components as in the other levels.
The definition that produced this example follows:
280 Using Zen

Expanding Group
This definition references a number of methods defined in the page class. For example, the secondlevel
references the server-side callback method DrawContent to produce additional formatted
text, in this case a list of honors awarded to the author of the books listed. DrawContent looks
like this:
Method DrawContent(ByRef expando As %ZEN.Component.expando) As %Status
{
&html
Quit $$$OK
}
The component has the following attributes.
Using Zen 281

Navigation Components
Attribute
Zen group
attributes
caption
Description
has the same style and layout attributes as any Zen group.
The chapter Zen Layout describes them.The default layout
is vertical.
Text to display as the title of this group. This text displays
even when the is contracted.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
childIndent
expanded
HTML length value giving the amount to indent the children in the
expanded list of items. The above example uses 35px. The default is
to use no indentation, aligning the children with the caption.
If true, this group is expanded (children visible). If false, it
is contracted (children not visible). The default is true.
expanded has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
imageContracted
(Optional) URI of the image to display when the group is
contracted. The user clicks on this image to expand the group. The
default for imageContracted is the plus sign
whose URI is:
/csp/broker/images/contracted.gif
You may specify an alternate image. The path that you provide for
imageContracted must be relative to the Caché installation directory.
imageExpanded
(Optional) URI of the image to display when the group is
expanded. The user clicks on this image to contract the group. The
default for imageExpanded is the minus sign
whose URI is:
/csp/broker/images/expanded.gif
You may specify an alternate image. The path that you provide for
imageExpanded must be relative to the Caché installation directory.
282 Using Zen

Expanding Group
Attribute
oncontract
Description
Client-side JavaScript expression that Zen invokes just before contracting
(hiding) the children of this group. Generally this
expression invokes a client-side JavaScript method. This method
becomes the “oncontract handler” for the .
When providing a value for an event handler attribute such as
oncontract, use double quotes to enclose the value and single quotes
(if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
OnDrawContent
onexpand
remember
Optional. Name of a server-side callback method that provides
additional HTML content for this component. If defined, this callback
is invoked on the server when the component is drawn. It
provides HTML content by using &html or the WRITE command.
OnDrawContent must be the name of a server-only method in the page
class that contains this view component; this method must return a
%Status type.
Client-side JavaScript expression that Zen invokes just before
expanding (displaying) the children of this group.
If true, remember the most recent expanded state in a session cookie
and return to this state when redisplayed. The default is false.
remember has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
can be particularly useful in navigation when combined with .
Using Zen 283

15
Popup Windows and Dialogs
This chapter describes Zen components that “pop up” to display their contents over the main application
page. The tradeoff for the flexibility provided by these components is that you must provide more
programming in the page class to make them effective. This chapter describes the following components:
• Modal Groups — Make HTML content visible in response to a user event.
• Popup Windows — Pop up a new window that displays a Zen page or any other content.
• Dialogs — Pop up a dialog that prompts the user and accepts user input.
15.1 Modal Groups
A modal group is a specialized group component that normally does not display its contents. When
the modal group is made visible, only its contents receive user events. Any event that occurs outside
of the modal group (such as a mouse click) automatically hides the modal group. Zen uses this modal
mechanism when it creates dropdown menus and dropdown combobox controls. You can also use this
mechanism for popup items.
You can define the contents of a modal group either by placing a component within
the page class or by creating an instance of the %ZEN.Component.modalGroup class programmatically.
There are three options:
• Static — Place a component in the page class XData Contents block. Its contents
remain hidden until a client-side method on the page calls the modalGroup show method.
• Dynamic — Have the page call its createComponent method to create a modalGroup component
dynamically. Add components to the group. Display it by calling the modalGroup show method.
Using Zen 285

Popup Windows and Dialogs
• Built-in — Have the page call the modalGroup show method to display one of the built-in modal
groups: "msgBox" or "calendar"
To close the current modal group, the page must invoke its endModal method. Generally endModal
is triggered by an event handler for one of the buttons in the modal group (OK, Cancel, or similar). It
is an error to call endModal if there is no modal group currently displayed.
While a modal group has the editing focus, keyboard controls are disabled. For example, it is not
possible to use Tab to move from field to field within the modal group. This prevents the user from
(inadvertently) pressing Tab to navigate through all the fields and then back to the page, while the
modal group has focus. The modal group keeps the focus until the user either clicks away from it or
clicks the button that has been set up to close the modal group.
Note:
For Internet Explorer (IE) only: When displaying a modal group, Zen hides the contents of
any elements (that is, SVG content). This is because IE ignores z-index setting for
elements.
15.1.1 Static Modal Groups
In static mode, the modal group is defined within a page class XData Contents block using XML
statements. The contents of the group are hidden until the modal group component’s show method is
called; then they are displayed in a popup window.
The following steps set this up in the page class:
1. Supply a definition within the in XData Contents. For example:
2. Provide a client-side method to display the modal group. For example:
Method modalGroupStatic() [ Language = javascript ]
{
var group = this.getComponentById('mgStatic');
}
group.show();
This method:
• Finds the on the by calling getComponentById with the id value
• Calls the client-side show method. No arguments are needed because the
definition provides all the necessary information to show.
286 Using Zen

3. Somewhere within the you must give the user a mechanism to invoke the
modalGroupStatic method to display the modal group. The following example provides a button:
4. For testing purposes, you may provide the with a field in which to echo the data from the
popup:
No data entered yet.
The page XData Contents block now looks like this.
No data entered yet.
5. You must give the user a mechanism to close the popup. Additionally, if your popup invited the
user to enter values, you will want to retrieve and use these values. The following client-side
method in the page class does this:
Method mgBtnClick() [ Language = javascript ]
{
// get value from text field
var ctrl = zenPage.getComponentById('mgText');
}
// write user value into HTML component
var html = zenPage.getComponentById('mgHtml');
html.setProperty('content','User entered: ' + ctrl.getValue());
// hide the modal group
zenPage.endModal();
This method:
• Executes when the user clicks OK in the popup. This works because step 1 identified this
method as the onclick event handler for the in the .
• Finds the control from the by calling getComponentById with the
id value
• Gets the value entered into the control by calling getValue
Modal Groups
• Finds the component on the by calling getComponentById with the
id value
Using Zen 287

Popup Windows and Dialogs
• Sets the content property of the component by calling setProperty. The new
content concatenates a literal string with the newly-acquired value.
• Calls the page’s endModal method to close the popup.
The user may interact with this sample page as follows:
1. The user initially sees:
2. Clicking the button on this page invokes the modalGroupStatic method. This causes a window
to pop up in front of the main page. The contents of the popup are the contents of the . The popup title is the groupTitle text.
In the illustration below, the user has typed a value in the control within the popup:
3. Clicking the OK button in this popup invokes the mgBtnClick method. This closes the popup
and changes the contents of the component on the to echo the user input, as follows:
The above example is similar to one available in the class ZENDemo.MethodTest in the SAMPLES
namespace. You can try this sample from the Zen Demo main page by choosing Home, Overview,
Methods, then Modal Group: Static.
15.1.2 Dynamic Modal Groups
In dynamic mode, the page creates a modal group component programmatically, by calling the clientside
JavaScript methods createComponent, addChild, and setProperty. The sequence culminates
in a call to the modalGroup show method with the appropriate arguments.
The following steps set this up in the page class:
1. Provide a client-side method to display the modal group. For example:
288 Using Zen

Modal Groups
Method modalGroupDynamic() [ Language = javascript ]
{
// create a modal group
var group = this.createComponent('modalGroup');
}
// add components dynamically
var col = this.createComponent('colorPicker');
group.addChild(col);
col.setProperty('id','myCol');
var radio = this.createComponent('radioSet');
group.addChild(radio);
radio.setProperty('id','myRadio');
radio.setProperty('valueList','elm,maple,oak');
var btn = this.createComponent('button');
group.addChild(btn);
btn.setProperty('caption','Save');
btn.setProperty('onclick','zenPage.btnClick();');
// Show the group in "dynamic" mode.
group.show('Dynamic Popup','dynamic',null,null,null,'236');
This method:
• Calls the page’s createComponent method to add a modalGroup component
• Adds a colorPicker to the group
- Calls the page’s createComponent method to create a colorPicker control
- Calls the modal group’s addChild method to add the colorPicker to the group
- Calls the color picker’s setProperty method to give the colorPicker an id value
• Adds a radioSet to the group in the same way
• Adds a button to the group in the same way
• Calls the button’s setProperty method to set its onclick value to the name of a client-side
method that will execute when the user clicks this button
• Calls the modal group’s show method with these arguments:
- A title for the popup window
- The keyword 'dynamic'
- The keyword null in argument positions three, four, and five
- An optional width value of '236'
For argument details see The show Method topic, below.
2. Somewhere within the you must give the user a mechanism to invoke the
modalGroupDynamic method to display the modal group. The following example provides a
button:
Using Zen 289

Popup Windows and Dialogs
3. For testing purposes, you may provide the with a field in which to echo the data from the
popup:
No data entered yet.
The page XData Contents block now looks like this.
No data entered yet.
4. You must give the user a mechanism to close the popup. Additionally, if your popup invited the
user to enter values, you will want to retrieve and use these values. The following client-side
method in the page class does this:
Method btnClick() [ Language = javascript ]
{
// get values from controls
var col = zenPage.getComponentById('myCol');
var radio = zenPage.getComponentById('myRadio');
}
// write user values into HTML component
var html = zenPage.getComponentById('mgHtml');
html.setProperty('content','User entered: ' +
col.getValue() + ' ' + radio.getValue());
// hide the modal group
zenPage.endModal();
This method:
• Executes when the user clicks Save in the popup. This works because step 1 identified this
method as the onclick event handler for the Save button in the modal group.
• Gets the color picker’s value as follows:
- Finds the color picker control by calling getComponentById with the color picker id
value
- Gets the value entered into the color picker control by calling its getValue method
• Gets the radio set’s value in the same way
• Finds the component on the by calling getComponentById with the
id value
• Sets the content property of the component by calling setProperty. The new
content concatenates a literal string with the newly-acquired color picker and radio set values.
290 Using Zen

Modal Groups
• Calls the page’s endModal method to close the popup.
The user may interact with this sample page as follows:
1. The user initially sees:
2. Clicking the button on this page invokes the modalGroupDynamic method. This causes a window
to pop up in front of the main page. The contents of the popup are the child components that
modalGroupDynamic added. The popup title is the first argument that modalGroupDynamic
passed to the show method.
In the illustration below, the user has clicked on a color and a radio button:
3. Clicking the Save button in this popup invokes the btnClick method. This closes the popup and
changes the contents of the component on the as follows:
15.1.3 Built-in Modal Groups
In built-in mode, Zen dynamically creates and displays one of its built-in modal groups. This option
is much simpler than the steps for a dynamic modal group. There are two options for built-in modal
groups:
• "calendar" — Display the built-in calendar box.
• "msgBox" — Display the built-in message box.
15.1.3.1 Calendar
The following steps add a calendar popup to a Zen page class:
1. Provide a client-side method to display the modal group.
Using Zen 291

Popup Windows and Dialogs
Method modalGroupCalendar() [ Language = javascript ]
{
var group = zenPage.createComponent('modalGroup');
group.setProperty('onaction','zenPage.calendarAction(group);');
group.show('Select a date:','calendar','2005-12-12');
}
This method:
• Calls the page’s createComponent method to add a modalGroup component
• Calls the modal group’s setProperty method to set its onaction value to the name of a clientside
method that will execute when the user performs any action on this popup, such as
selecting a date value from the calendar. This method accepts an argument, group, that represents
the modalGroup instance.
• Calls the modal group’s show method with three arguments:
- A title for the popup window
- The keyword 'calendar'
- An optional pre-selected date for the calendar to display when it pops up
2. Somewhere within the you must give the user a mechanism to invoke the method that
displays the modal group. The following example provides a button:
3. Finally, you must retrieve and use the date value acquired by the calendar control, and then close
the popup. The following client-side method in the page class does this:
Method calendarAction(group) [ Language = javascript ]
{
alert("You selected: " + group.getValue());
}
// write user value into HTML component
var html = zenPage.getComponentById('mgHtml');
html.setProperty('content','User entered: ' + group.getValue());
This method:
• Executes when the user clicks on a specific date value in the popup. This works because step
1 identified this method as the onaction event handler for the modal group.
• Calls the modal group’s getValue method to retrieve the date value entered into the calendar.
• Issues a JavaScript alert message that confirms the value.
• Finds the component on the by calling getComponentById with the
id value
292 Using Zen

Modal Groups
• Sets the content property of the component by calling setProperty. The new
content concatenates a literal string with the newly-acquired date value.
• Does not call the page’s endModal method. The built-in calendar modal group closes automatically
when the user chooses a date.
The user may interact with this sample page as follows:
1. The user initially sees:
2. Clicking the button on this page invokes the modalGroupCalendar method. This causes a window
to pop up in front of the main page. The popup title is the first argument that modalGroupCalendar
passed to the show method. The currently selected date is the one specified by the third show
argument.
3. Selecting a different month, year, and date from the preselected value automatically invokes the
calendarAction method. This closes the popup and displays a browser alert message that echoes
the new date value:
4. Dismissing the alert makes it easy to see that the contents of the component on the
have now changed as follows:
Using Zen 293

Popup Windows and Dialogs
The above example is similar to one available in the class ZENDemo.MethodTest in the SAMPLES
namespace. You can try this sample from the Zen Demo main page by choosing Home, Overview,
Methods, and Modal Group: Calendar.
15.1.3.2 Message Box
The following steps add a message box popup to a Zen page class:
1. Provide a client-side method to display the modal group.
Method modalGroupMsg() [ Language = javascript ]
{
var group = this.createComponent('modalGroup');
group.show('My New Message','msgBox',
'Thismessagecontains HTML!');
}
This method:
• Calls the page’s createComponent method to add a modalGroup component
• Calls the modal group’s show method with three arguments:
- A title for the popup window
- The keyword 'msgBox'
- HTML-formatted message content for the popup message
2. Somewhere within the you must give the user a mechanism to invoke the method that
displays the modal group. The following example provide a button:
3. When the user clicks this button, the popup displays:
Clicking OK on the popup dismisses it.
294 Using Zen

The above example is similar to one available in the class ZENDemo.MethodTest in the SAMPLES
namespace. You can try this sample from the Zen Demo main page by choosing Home, Overview,
Methods, and Modal Group: MsgBox.
15.1.4 The show Method
show is a client-side JavaScript method that displays a modal group. It has no return value, and up to
eight optional arguments. Previous topics have discussed some of these arguments. A complete list
follows:
• title — Title for the popup window. For static modal groups, this overrides the groupTitle value
in the definition.
• type — One of the following keywords:
- "calendar" — Display the built-in calendar box.
- "dynamic" — Display a dynamically created modal group.
- "msgBox" — Display the built-in message box.
- "static" — Display a statically defined .
If no type argument is supplied, the default is "static" if a definition exists
within the . Otherwise the default is "dynamic".
• value — Value to display when a built-in modal group is used. When the type is:
- "calendar" — value is a date in YYYY-MM-DD format. When the window pops up, the
calendar displays this month and year with value as a pre-selected date.
- "msgBox" — value is the HTML-formatted message content for the popup message.
• top — Vertical coordinate at which the top left corner of the window will pop up (0 is the top)
• left — Horizontal coordinate at which the top left corner of the window will pop up (0 is far left)
• wid — Width of the popup window
• hgt — Height of the popup window
Modal Groups
• parms — Object containing a set of additional characteristics passed on to the modalGroup as a
set of name-value pairs. Typically this offers a way to pass additional parameters to the popup
calendar.
Using Zen 295

Popup Windows and Dialogs
15.1.5 Attributes
The component is the XML projection of the %ZEN.Component.modalGroup class.
The following table lists the attributes that are available when defining a
within a page class XData Contents definition.
296 Using Zen

Modal Groups
Attribute
Zen group
attributes
groupTitle
okCaption
onaction
Description
has the same style and layout attributes as any Zen
group. The chapter Zen Layout describes them.
Title to display at the top of the modal group. For static modal groups,
you can set the groupTitle value in the definition. Otherwise,
this value is set dynamically by the first argument of the show
method.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Caption displayed in OK button for a message box. The default is "OK".
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Client-side JavaScript expression that runs whenever the user takes
action on a built-in modal group popup ("msgBox" or "calendar").
Generally this expression invokes a client-side JavaScript method
defined in the page class. This method becomes the “onaction event
handler” for the .
When providing a value for an event handler attribute such as onaction,
use double quotes to enclose the value and single quotes (if needed)
within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
onhideGroup
onshowGroup
seed
Client-side JavaScript expression that runs when the modal group is
hidden.
Client-side JavaScript expression that runs when the modal group is
made visible.
Allows you to pass some arbitrary value to the onaction event handler.
%ZEN.Component.modalGroup also has a value property is used to hold a value for the modal group.
value is set by the show method; applications should not set this. However, it is sometimes useful to
retrieve this value, for example when working with the built-in calendar modal group.
Using Zen 297

Popup Windows and Dialogs
15.2 Popup Windows
A popup window is a new browser window that pops up over the currently active window in response
to a user event. The popup window becomes the active window as soon as it is displayed, and remains
dominant until the user closes it.
To display a popup window from a Zen page, do the following:
1. Open the Zen page class in Studio.
2. Add a client-side method that calls the function zenLaunchPopupWindow, for example:
Method showPopupWindow() [ Language = javascript ]
{
zenLaunchPopupWindow(
zenLink('MyApp.MyDialog.cls'),
'A True Dialogue',
'status,scrollbars,resizable,width=400,height=300');
}
zenLaunchPopupWindow has the following arguments:
• A string that identifies the content you wish to display, either:
- The name of a Zen page class, including its package name and .cls extension
- The URI of the desired content
The zenLink function makes sure that any additional URI parameters, such as session tracking
values, are included in the link. You may use zenLink with the class name or with any URI.
In the following example, the client-side method uses JavaScript string concatenation to
construct a URI from several disparate elements before making the call to
zenLaunchPopupWindow. The example also uses the escape function to correctly format
any variable values used in the string:
Method editCSSValue(context) [ Language = javascript ]
{
var ctrl = this.getComponentById('value');
var value = ctrl.getValue();
var url = zenLink('%ZEN.Dialog.cssDeclarationEditor.clscontext='
+ escape(context) + '&declaration=' + escape(value)
);
zenLaunchPopupWindow(url,
'CSSDeclarationEditor',
'resizable,width=500,height=700'
);
}
• A string that identifies the popup window
• A comma-separated list of window attributes expected by the JavaScript function
window_open.
298 Using Zen

Dialogs
3. Provide a component on the page that invokes this method, for example:
4. Override the onPopupAction method to retrieve and use the value returned by the popup. Use
the exact method signature shown below. Within the method, you may use the value in any way
you wish, for example:
Method onPopupAction(popupName, action, value) [ Language = javascript ]
{
var html = zenPage.getComponentById('mgHtml');
html.setProperty('content','User entered: ' + value);
}
5. Clicking the button on the page displays the popup window.
zenLaunchPopupWindow supports a fourth parameter, an array of values intended to be used as URI
parameters. You can use it to supply parameters for the URI so that you do not have to worry about
correctly concatenating them to the string provided in the first parameter. The convention for this array
is as follows:
var parms = new Object();
parms.Aaa = 10;
parms.Bbb = 20;
Now when you call zenLaunchPopupWindow with parms as its fourth parameter, the function uses
Aaa and Bbb as parameters within the URI that you provided in the first parameter, and gives these
parameters the values that you assigned to the corresponding members of the parms array.
zenLaunchPopupWindow takes care of all the details of correctly escaping these parameters in the
URI string.
Important:
When Internet Explorer is the browser, do not use a submit operation to save values
from any popup window. Use a save operation instead.
15.3 Dialogs
Zen includes some built-in classes designed to work as popup dialog windows. A Zen dialog window
can contain any of the usual Zen components. All dialog windows are subclasses of
%ZEN.Dialog.standardDialog, which is a Zen page class. This base class provides classic dialog buttons
such as OK, Apply, and Cancel, as well as conventions for retrieving the values entered into the dialog
if the user clicks OK.
This topic describes the conventions for working with Zen dialog windows:
• Displaying the built-in file select window
Using Zen 299

Popup Windows and Dialogs
• Displaying the built-in color select window
• Creating a new dialog window based on %ZEN.Dialog.standardDialog
• Creating a new dialog window template, as an alternative to %ZEN.Dialog.standardDialog
15.3.1 File Selection Dialog Window
The %ZEN.Dialog.fileSelect window displays and lets the user choose from a list of directories and
files on the server system. The resulting value is a full path and filename. To display the fileSelect
dialog as a popup window, use the steps in the previous topic, but in step 2, provide a client-side
method similar to the following:
Method showPopupFile() [ Language = javascript ]
{
var pathname = '\Temp';
var showdir = '0';
zenLaunchPopupWindow(
'%ZEN.Dialog.fileSelect.clsDir=' + escape(pathname) +
'&showdirectoryonly=' + showdir,
'FileSelectWindow',
'status,scrollbars,resizable,width=660,height=700');
}
The method calls the client-side function zenLaunchPopupWindow with these arguments:
• URI string beginning with the filename of the %ZEN.Dialog.fileSelect class. The filename is all
that is needed, but in this case, the URI continues with various parameters, including:
- Pathname for the file search window. This is either a full pathname or a path relative to the
Caché system management directory (\mgr under the Caché installation directory). If omitted,
the default is the Caché system management directory.
- A showdirectoryonly value of 0 so that files will be visible in the display. You can omit
this, as 0 is the default. Set showdirectoryonly to 1 if you want to show directories only.
• Identifier for the popup window
• Comma-separated list of popup window characteristics
15.3.2 Color Selection Dialog Window
The %ZEN.Dialog.colorSelect window lets the user choose from a set of colored cells. The resulting
value is an HTML color value, such as #F3FDDA. To display the fileSelect dialog as a popup window,
use the steps in the previous topic, but in step 2, provide a client-side method similar to the following:
300 Using Zen

Dialogs
Method showPopupColor() [ Language = javascript ]
{
zenLaunchPopupWindow(
'%ZEN.Dialog.colorSelect.cls',
'ColorPicker',
'status,scrollbars,resizable,width=500,height=700');}
This method calls the client-side function zenLaunchPopupWindow with arguments as follows:
• Filename of the %ZEN.Dialog.colorSelect class
• Identifier for the popup window
• Comma-separated list of popup window characteristics
15.3.3 Creating a Dialog Window
To create a new type of Zen dialog window based on %ZEN.Dialog.standardDialog:
1. Subclass %ZEN.Dialog.standardDialog.
2. Add a new XData block with:
• The name dialogBody
• A as the container
• An id value for the component that you identify as the source of user input
For example:
XData dialogBody
{
}
3. Override the server-side callback method %OnGetTitle, for example:
Method %OnGetTitle() As %String
{
Quit $$$TextHTML("This is My Dialog")
}
4. Override the server-side callback method %OnGetSubtitle, for example:
Method %OnGetSubtitle() As %String
{
Quit $$$TextHTML("by John Smith")
}
5. Override the client-side JavaScript method getDialogValue so that it returns a value, for example:
Using Zen 301

Popup Windows and Dialogs
Method getDialogValue() [ Language = javascript ]
{
return this.getComponentById('yourReply').getValue()
}
6. To give the dialog an Apply button (in addition to the automatic OK and Cancel buttons) override
the APPLYBUTTON parameter and set it to 1:
Parameter APPLYBUTTON = 1;
7. To enable the $$$Text localization macros, give the DOMAIN parameter a meaningful value:
Parameter DOMAIN = "MyDomain";
8. When displayed, this dialog appears as follows:
15.3.4 Creating a Dialog Window Template
Suppose you want to apply your own styling to the dialogs, rather than using the same layout and
graphics as in the Zen standard dialog. The most straightforward way to accomplish this is to create
a new dialog window template class and use it as an alternative to %ZEN.Dialog.standardDialog in the
above instructions. The steps are:
1. Subclass %ZEN.Dialog.standardDialog.
2. In your subclass, apply the style differences you require.
3. When creating new dialogs, extend the new subclass instead of extending
%ZEN.Dialog.standardDialog
4. When you need a file selector class:
302 Using Zen

Dialogs
• Copy the class %ZEN.Dialog.fileSelect
• Edit the copy so that it extends your new dialog window template class instead of extending
%ZEN.Dialog.standardDialog
5. When you need a color selector class:
• Copy the class %ZEN.Dialog.colorSelect
• Edit the copy so that it extends your new dialog window template class instead of extending
%ZEN.Dialog.standardDialog
Using Zen 303

16
Other Zen Components
This chapter describes components that fit into none of the previously defined categories: layout, tables,
meters, charts, forms, controls, menus, or popups. These are the “other” components, in approximate
order of complexity:
• — A snippet of arbitrary HTML content
• — A static image or other content within a frame
• — A non-visible component that fires an event after a time interval
• — A group component that helps visually organize a form
• — A large, detailed palette from which the user can select colors
• — Repeat the same layout for each entry returned by a runtime query.
• — Draw an expandable tree of links based on a global or callback method.
• — Display a view box based on data provided by a callback method.
If you have examined the full roster of components, including those listed above, and still do not see
the functionality you need, consider adding a custom component to the Zen library. The Custom
Components chapter provides full instructions.
16.1 HTML Content
The Zen component provides a way to place arbitrary HTML content within a Zen page. The
HTML content is displayed within the Zen page exactly as specified. This content is drawn within an
enclosing HTML in the same manner as any other Zen component.
There are several ways to define the content displayed by the element:
Using Zen 305

Other Zen Components
• Literally specify the content within the component:
This is some HTML.
The content must be well-formed. That is, any HTML elements within the content must have
matching closing elements, and any attribute values must be quoted correctly. The tag
is not allowed.
The content may not reference other Zen components. However, it may contain Zen #()# expressions.
See Zen Runtime Expressions.
• Define a server-side OnDrawContent callback method that writes HTML content. If you define
such a method, and reference it from the element, this method is called whenever the
component is displayed.
The method itself would look something like this:
Method GetHTMLContent(pSeed As %String) As %Status
{
&html
Quit $$$OK
}
• If you work with the component programmatically, you will see that it has a content
property, a string of HTML statements. An initial value of the content can be set by placing the
desired HTML tags in between the and elements in XData Contents, or by referencing
an OnDrawContent callback.
Client code can change the value of the content property by resetting it from JavaScript. For
example:
// get html content
var html = zenPage.getComponentById('myContent');
html.setProperty('content','some new content');
The component has the attributes listed in the following table.
306 Using Zen

Framed Content
Attribute
Zen component
attributes
OnDrawContent
seed
Description
has the same general-purpose attributes as any Zen
component.
Optional.The name of a server-side callback method that provides
HTML content for this component, either by using &html or by
using the WRITE command.
The OnDrawContent value must be the name of a server-only
method defined in the page class whose XData Contents references
this component, and it must return the %Status data type.
Optional. Allows you to pass some arbitrary value to the
OnDrawContent callback.
16.2 Framed Content
The Zen component is a wrapper for the HTML element. It may display images
or other content within a frame. Zen has the following attributes.
Attribute
Zen
component
attributes
longdesc
frameAlign
frameBorder
scrolling
Description
has the same general-purpose attributes as any Zen component.
URI that provides the link to the long (text) description of the frame.
The align value for the HTML : "left", "right", or "center".
The frameborder value for the HTML . If true, the frame has a
border; if false it does not have a border.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has
the value "true" or "false" in XData Contents, 1 or 0 in server-side code,
true or false in client-side code. See Datatype Classes.
The scrolling value for the HTML : "auto", "yes", or "no".
Using Zen 307

Other Zen Components
Attribute
src
Description
Identifies the pathname and filename of the frame content. The path is
relative to the Caché installation directory, for example:
If you wish to change the contents of the frame from the client, you can
do so programmatically by resetting the value of the src property of the
iframe object.
If you wish to place an image on a button control, so that you can define an onclick event or other
types of event for it, use the control component. See the Zen Controls chapter.
16.3 Page Timer
The component has no visual representation. It raises a client-side event after a specified time
period. You may place a on the Zen page within XData Contents as follows:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
has the following attributes.
308 Using Zen

Field Sets
Attribute
ontimeout
Description
Client-side JavaScript expression that runs whenever the timer runs out.
Generally the ontimeout expression invokes a client-side JavaScript
method defined in the page class. This method becomes the “ontimeout
event handler” for the timer. It must accept an argument, timer, that represents
this timer object.The element can use the built-in variable
zenThis to pass the timer object to the method.
When providing a value for this attribute, use double quotes to enclose
the value and single quotes (if needed) within the JavaScript expression.
For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
timeout
Number of milliseconds in the timer. Zen automatically starts the timer
when the page is first loaded. When the timeout time has elapsed, Zen
fires the ontimeout expression.
The example above sets a timeout value of 10,000 milliseconds. This
provides an timeout value of 10 seconds.
The client-side ontimeout method might look something like the following. A only fires its
ontimeout event once, so your JavaScript method must restart the timer (by calling its startTimer
method) before exiting. The following example does this:
Method timeout(timer) [ Language = javascript ]
{
// ...do something
}
// restart the timer
timer.startTimer();
16.4 Field Sets
A is a group component that draws an outer box around the children and displays a title
within this box. This creates a visual panel that can help to organize a page. The following example
from the SAMPLES namespace class ZENApp.HelpDesk defines a panel called “Details” that contains
a form with several different controls.
Using Zen 309

Other Zen Components
The that produces the above example looks like this:
A group may contain a , as above, or a may contain a . A
provides a visual grouping only; it is not a Zen form, because it does not provide any form
behavior such as validation or submit. has the following attributes:
310 Using Zen

Color Selector
Attribute
Zen group
attributes
legend
title
Description
A has the same style and layout attributes as any Zen group.
The chapter Zen Layout describes them.
Text specifying the caption to display for this . The legend
can be a literal string, or it can contain a Zen #()# expression. See Zen
Runtime Expressions.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
Text specifying a popup message to display for this . The title
can be a literal string, or it can contain a Zen #()# expression. See Zen
Runtime Expressions.
Although you enter ordinary text for this attribute, it has the underlying
data type %ZEN.Datatype.caption. This makes it easy to localize its text
into other languages. See Zen Localization.
16.5 Color Selector
The component lets the user view and select colors or enter RGB values in a large color
palette. The palette is a grid that can be visualized as one possible slice from a three-dimensional cube
of available colors. The captures a slice from the cube by accepting the user’s choice of
one of three faces (red, green, or blue) and slicing through the cube, parallel to that face, at some saturation
level (brighter or dimmer) to produce a grid of colors.
From the user’s viewpoint, the has these features:
• The user selects a color by clicking a square in the palette.
• The user can cycle through different faces and slices of the color cube by clicking on the red,
green, or blue color bars at left, bottom, and right. The segmented bar at left allows the user to
select a slice that uses a brighter or dimmer range of color combinations.
• The bar at top right displays the currently selected color and its corresponding HTML hexadecimal
value. The user can copy (but not edit) the text value from this color bar.
• At top left, the user can change the text entry fields R, G, and B to any number in the range 0–255,
then click on the color bar at top right to apply these changes and see the result. The text fields R,
G, and B also respond to user selections from the palette.
Using Zen 311

Other Zen Components
A with a color selected looks like this:
has the following attributes. For a simpler color selection component, see .
Attribute
Zen
component
attributes
currCol
currRow
currSlice
face
Description
has the same general-purpose attributes as any Zen component.
The chapter Zen Style describes them.
is not a full-blown control component, but it does allow the
user to select a value, and it can be used within Zen forms. Any control
attribute not listed in this table is not available for .
0–based column number of the currently selected cell in the color palette.
The default is 0. The range is from 0 to 15.
0–based row number of the currently selected cell in the color palette. The
default is 0. The range is from 0 to 15.
0–based slice number of the currently selected slice of the 3–dimensional
color cube. The default is 0. The range is from 0 to 15.
Face number of the currently selected face of the 3–dimensional color cube:
1, 2, or 3. The default is 1.
312 Using Zen

Repeating Group
Attribute
onchange
Description
Client-side JavaScript expression that Zen invokes when the value of the
component changes. Generally this expression invokes a
client-side JavaScript method. This becomes the “onchange handler” for
the component.
When providing a value for an event handler attribute such as onchange,
use double quotes to enclose the value and single quotes (if needed) within
the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See Zen
Runtime Expressions.
ondblclick
value
Client-side JavaScript expression that Zen invokes when the user
double-clicks on the component.
String that identifies the most recently selected HTML hexadecimal value.
The default is:
#FFFFFF
16.6 Repeating Group
A is a specialized group component that defines the layout for a single group entry,
then outputs multiple entries with this layout. The number of entries, and the data contained in each
entry, is determined by a runtime query.
has the following attributes.
Using Zen 313

Other Zen Components
Attribute
Zen group
attributes
Data source
attributes
Description
has the same style and layout attributes as any
Zen group.The chapter Zen Layout describes them.The default layout
for a is vertical.
has the same attributes as for specifying
a data source. For details and examples, see the Zen Tables
chapter as follows:
• How to use query attributes with :
- Data Sources (maxRows)
- Specifying an SQL Query (sql)
- Referencing a Class Query (queryClass, queryName)
• How to provide elements within :
- Query Parameters
The typical layout strategy for a repeating group is for the element to enclose a
horizontal group that contains the individual entry. Since the default layout for a
is vertical, the result of this arrangement is that each entry is laid out horizontally, while the set of
entries is laid out from top to bottom.
The following excerpt from an XData Contents block provides an example of this layout strategy for
. This is similar to the XData Contents block in the class ZENTest.RepeatingGroupTest
in the SAMPLES namespace. Note the that defines the individual entry. This
contains a and an component.
314 Using Zen

Repeating Group
#(%query.Title)#
The following figure illustrates sample output from this excerpt. To produce this output, the user
entered the key C, requested 10 rows, and then clicked Search. This caused Zen to display the repeating
group using the first 10 entries that start with the letter C. The user then clicked an employee name in
the group to display the alert window, which contains data retrieved from the server during the query.
Using Zen 315

Other Zen Components
16.7 Dynamic Tree
The component displays a set of user-defined items as an expandable tree. In many ways
is similar to . However, instead of specifying components, acquires
its contents dynamically, using a global or callback.
16.7.1 Defining a Tree Using a Global
The simplest way to define a is to use a Caché global (multidimensional array). The following
definition references the ^myTree global by providing the dataGlobal attribute:
This definition causes the contents of the ^myTree global to be displayed on the page as nodes within
an expandable tree.
16.7.1.1 Node Labels
Suppose you define ^myTree using the following statements at the Terminal command line:
Set ^myTree("Root","Item 1") = "ZENMVC.MVCForm.cls"
Set ^myTree("Root","Item 2") = "http://www.intersystems.com"
Set ^myTree("Root","Item 2","SubItem") = "ZENDemo.Home.cls"
Each global node now has one or more subscripts, such as "Root" or "Item 2". Zen uses these
subscripts as labels for the nodes in the . Our ^myTree global can now generate a that looks like the following illustration. This is fully expanded, with the user
holding the cursor over the node label "SubItem" at the lowest level.
Important:
When you use a global to define a , the resulting nodes always appear in
alphabetical order (by label) because that is the way globals are organized in the
database.
16.7.1.2 Node Values
When the user clicks on a node label such as:
316 Using Zen

Dynamic Tree
"SubItem"
The corresponding node value is triggered. If the values are set as described in the previous topic, then
this value is:
"ZENDemo.Home.cls"
Each node value is a string. Typically the node values are URI values. For example:
• The name of a Zen page class:
"ZENMVC.MVCForm.cls"
• A Web site:
"http://www.intersystems.com"
• Or the URI of some other content.
If you want a link to invoke JavaScript, you can start the URI with the string javascript: as in the
following examples:
• You can invoke a client-side JavaScript method in the page class:
"javascript: zenPage.myMethod();"
• Or simply execute a JavaScript expression:
"javascript: alert('You clicked me!');"
When providing a JavaScript expression, use double quotes to enclose the value and single quotes
(if needed) inside the expression, as shown above.
16.7.2 Defining a Tree Using a Callback
can get its list of nodes by invoking a server-side callback method, defined in the page
class. The method name is specified using the OnGetNodeInfo attribute. For example:
This example defines a tree whose nodes are provided by the server-side callback method GetNodeInfo.
When the user clicks on an item, the treeClick method is called. For a similar example, see the class
ZENTest.DynaTreeTest in the SAMPLES namespace.
Using Zen 317

Other Zen Components
16.7.2.1 Callback Parameters
A can contain zero or more elements. Each specifies an input
parameter for the callback method that generates the . and both
support this convention.
Note:
For examples, see ZENTest.DynaViewTest in the SAMPLES namespace.
The element has the following attributes.
Attribute
paramName
value
Description
The paramName must be unique within the . It becomes a
subscript in the array of parameters passed to the callback method.
The value supplied for a can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
16.7.2.2 Callback Method
The OnGetNodeInfo attribute must identify a server-side callback method in the page class that contains
the component. This callback is called repeatedly to get information about each node
displayed within the tree. Zen handles this repetition as follows:
• A tree contains a set of top-level nodes at level 1. A node may contain child nodes; each child is
considered to have a level number one greater than its parent: 2, 3, 4, etc.
• Starting with level 1, Zen calls the OnGetNodeInfo callback repeatedly until it returns false, indicating
that there are no more nodes at the current level.
• If a node reports that it has child nodes, Zen calls the OnGetNodeInfo callback repeatedly (with
the appropriate value for pLevel) to get information on each child node until false is returned for
that child level.
The OnGetNodeInfo callback method must have a signature that looks like this:
Method GetNodeInfo(Output tSC As %Status,
ByRef pParams As %String,
pLevel As %Integer,
ByRef pHandle As %String,
pNodeInfo As %ZEN.Auxiliary.NodeInfo) As %Boolean
Where:
• The method returns a %Boolean value indicating whether or not there is a node at the level indicated
by pLevel.
• tSC is a status code, returned by reference, that indicates success.
318 Using Zen

• pParms represents any elements defined by the . pParms is an array.
Each member of this array uses its paramName as a subscript and its value as a value.
• pLevel is the current level of the tree.
Dynamic Tree
• pHandle is user-definable value that is passed, unchanged, to each call to the callback. The callback
can use this store any state information it needs while providing the view information.
• pNodeInfo is a pre-instantiated %ZEN.Auxiliary.NodeInfo object and is used to specify how the tree
node should be displayed. A %ZEN.Auxiliary.NodeInfo object has the following properties.
Property
expanded
hasChildren
link
Description
If true, this node (if it has children) is initially displayed as expanded. If
false, it is initially displayed as contracted. The default is true.
expanded has the underlying data type %ZEN.Datatype.boolean. It has the
value 1 or 0 in server-side code, true or false in client-side code. See
Datatype Classes.
If true, this node has one or more child nodes. If this is the case, thenthe
next call to the OnGetNodeInfo callback will be to fetch information about
these child nodes. The default is true.
hasChildren has the underlying data type %ZEN.Datatype.boolean. It has the
value 1 or 0 in server-side code, true or false in client-side code. See
Datatype Classes.
If non-empty, link defines a link that will be used if the user clicks on this
node. This can be a URI such as the name of a page to display, or a
JavaScript expression. If you want to invoke a client-side JavaScript
method in the link, start the URI with javascript: as in:
link="javascript:zenPage.myMethod();"
When providing a JavaScript expression, use double quotes to enclose
the value and single quotes (if needed) inside the expression.
text
value
A string containing a value to display for this node within the tree.
A string containing a logical value to associate with this node within the
tree.
Using Zen 319

Other Zen Components
16.7.3 Attributes
The component is the XML projection of the %ZEN.Component.dynaTree class. This
topic has already described the dataGlobal and OnGetNodeInfo attributes in detail. The following
table lists all the attributes.
Attribute
Zen group
attributes
childIndent
dataGlobal
Description
has the same style and layout attributes as any Zen
group. The chapter Zen Layout describes them.
HTML length value giving the amount by which each level within the
dynaTree should be indented. The default is to use no indentation.
Name of a Caché global (multidimensional array) that can provide
the contents of the . This string must include the ^ prefix
that is characteristic of Caché global names, for example:
dataGlobal="^myTree"
Using dataGlobal excludes OnGetNodeInfo. See Defining a Tree
Using a Global.
imageContracted
(Optional) URI of the image to display when the is contracted.
The user clicks on this image to expand the group. The
default for imageContracted is the plus sign
whose URI is:
/csp/broker/images/contracted.gif
You may specify an alternate image. The path that you provide for
imageContracted must be relative to the Caché installation directory.
imageExpanded
(Optional) URI of the image to display when the is
expanded. The user clicks on this image to contract the group. The
default for imageExpanded is the minus sign
whose URI is:
/csp/broker/images/expanded.gif
You may specify an alternate image. The path that you provide for
imageExpanded must be relative to the Caché installation directory.
320 Using Zen

Dynamic Tree
Attribute
onchange
Description
Client-side JavaScript expression that Zen invokes when the current
value of the changes. Generally this expression invokes
a client-side JavaScript method.This method becomes the “onchange
handler” for the .
When providing a value for an event handler attribute such as
onchange, use double quotes to enclose the value and single quotes
(if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions. See
Zen Runtime Expressions.
onclick
ondblclick
OnGetNodeInfo
selectedIndex
Client-side JavaScript expression that Zen invokes when the user
clicks on a node within the .
Client-side JavaScript expression that Zen invokes when the user
double-clicks on a node within the .
Name of a server-side callback method that reports information about
each node within the tree. Using OnGetNodeInfo excludes
dataGlobal. See Defining a Tree Using a Callback.
0-based index of the currently selected node in the .The
default selectedIndex is –1 (nothing is selected).
When you work with %ZEN.Component.dynaTree programmatically, you must also know about the
following properties of the dynaTree class:
• Each element provided in the original definition in XData Contents
becomes a member of the dynaTree parameters property, a list collection of
%ZEN.Auxiliary.parameter object. Each acquires an ordinal position in the parameters
collection: 1, 2, 3, etc.
• The read-only text property holds the text (display) value of the currently selected node within
the tree. This is the node label that displays in the .
• The read-only value property holds the logical (actual) value of the currently selected node within
the tree. This is the string that is activated when the user clicks the corresponding label in the
.
Using Zen 321

Other Zen Components
16.8 Dynamic View
The component displays a set of user-defined items within a view box, similar to the
way a file dialog box might display a set of files or directories. items can displayed in
one of two modes:
• "list" — All items are displayed compactly in a grid. Only the first column of data is displayed.
• "details" — Each item is displayed as one row within a table. Each row may present several
columns of data.
A in “details” mode looks like the following example, based on the class
ZENTest.DynaViewTest in the SAMPLES namespace.
16.8.1 Defining a View Using a Callback
gets its list of items by invoking a server-side callback method, defined in the page class.
The method name is specified using the OnGetViewContents attribute. For example:
This example defines a view box whose items are provided by the server-side callback method
GetViewContents. When the user clicks on an item, the viewChange method is called. For a similar
example, see the class ZENTest.DynaViewTest in the SAMPLES namespace.
16.8.1.1 Callback Parameters
A can contain zero or more elements. Each specifies an input
parameter for the callback method that generates the . and both
support this convention.
322 Using Zen

Dynamic View
Note:
For examples, see ZENTest.DynaViewTest in the SAMPLES namespace.
The element has the following attributes.
Attribute
paramName
value
Description
The paramName must be unique within the . It becomes a
subscript in the array of parameters passed to the callback method.
The value supplied for a can be a literal string, or it can
contain a Zen #()# expression. See Zen Runtime Expressions.
16.8.1.2 Callback Method
The OnGetViewContents attribute must identify a server-side callback method in the page class that
contains the component. The callback method must have a signature that looks like this:
Method GetViewContents(
ByRef pParms As %String,
Output pContents As %String,
Output pHeaders As %String) As %Status
Where:
• The method returns a %Status value indicating success or failure.
• pParms represents any elements defined by the . pParms is an array.
Each member of this array uses its paramName as a subscript and its value as a value.
• pContents is a multidimensional array that describes the set of items that will be displayed within
the view box. The array is subscripted by item number (starting with 1). Each array element contains
a $List structure containing the following information:
Set pContents(n) =
$ListBuild(textValue,logicalValue,icon,col2,col3,...))
Where:
- textValue is the value displayed for the item
- logicalValue is a logical value associated with the item
- icon is the URI of the image to be displayed with the item (if any)
- Subsequent values define the values displayed in any additional columns when the dynaView
is in “details” mode
• pHeaders is a multidimensional array that provides a set of column headers, subscripted by column
number. When the dynaView is in “details” mode, this is used to define how many columns of
data to display and what the column headers are. For example:
Using Zen 323

Other Zen Components
// define 3 column headers
Set pHeaders(1) = "Name"
Set pHeaders(2) = "Size"
Set pHeaders(3) = "Date"
16.8.2 Attributes
The component is the XML projection of the %ZEN.Component.dynaView class. This
topic has already described the OnGetViewContents attribute in detail. The following table lists all the
attributes.
Property
onchange
Description
Client-side JavaScript expression that Zen invokes when the
current value of the changes. Generally this
expression invokes a client-side JavaScript method. This method
becomes the “onchange handler” for the .
When providing a value for an event handler attribute such as
onchange, use double quotes to enclose the value and single
quotes (if needed) within the JavaScript expression. For example:
The JavaScript expression may contain Zen #()# expressions.
See Zen Runtime Expressions.
onclick
ondblclick
OnGetViewContents
rows
selectedIndex
viewType
Client-side JavaScript expression that Zen invokes when the user
clicks on a node within the .
Client-side JavaScript expression that Zen invokes when the user
double-clicks on a node within the .
Name of a server-side callback method that provides the contents
of the . See Defining a View Using a Callback.
Number of rows to display when the is in list mode.
0-based index of the currently selected node in the .
The default selectedIndex is –1 (nothing is selected).
Specifies how the contents of the should be displayed.
Possible values are:
• "list" — all items are displayed compactly in rows and columns
• "details" — each item is displayed as one row within a table
324 Using Zen

Dynamic View
When you work with %ZEN.Component.dynaView programmatically, you must also know about the
following properties of the dynaView class:
• Each element provided in the original definition in XData Contents
becomes a member of the dynaView parameters property, a list collection of
%ZEN.Auxiliary.parameter object. Each acquires an ordinal position in the parameters
collection: 1, 2, 3, etc.
• The read-only text property holds the text (display) value of the currently selected node within
the tree. This is the node label that displays in the .
• The read-only value property holds the logical (actual) value of the currently selected node within
the tree. This is the string that is activated when the user clicks the corresponding label in the
.
Using Zen 325

17
Custom Components
One of the most powerful features of the Zen framework is that it lets you easily develop new, reusable
components that automatically work with other Zen components.
The first chapter in this book, Introducing Zen, asserts that the Zen application development framework
is extensible. The claim is certainly true. However, Zen anticipates many of the features that you might
consider adding yourself. It is worthwhile to examine all of the available Zen components before
beginning a custom development effort. Possibly, you will discover the features you want in a Zen
component that already exists.
Following the introductory chapters Zen Component Concepts, Zen Layout, and Zen Style, this book
presents the details of existing Zen components by category: tables, meters, charts, forms, controls,
menus, popups, and other. After examining all of these chapters, you might find that you still wish to
create custom components. If so, continue with this chapter to view the options and instructions for
doing so.
In general, the most common way to extend Zen is to create a custom component. Custom components
fit into the existing Zen framework with minimal effort. They provide the style and behavior that you
need while still obeying the Zen layout conventions and leveraging the Zen client/server framework.
The following table describes options for creating custom components.
Using Zen 327

Custom Components
Options for Extending Zen
Task
Build a composite
component
Modify component
style
Create a custom
component
Create a custom
meter
Description
A composite arranges a group of existing, built-in Zen
components in a particular way.You can place this arrangement
on the page as if it were a single component.
You can make simple changes to the style of a built-in Zen
component by subclassing it and overriding its XData Style block.
The chapter Zen Style, topic Overriding Built-in Styles explains
how to do this.
You can extend the roster of Zen components by writing a new
component class. When you use Zen conventions to do this, the
resulting class is automatically projected as XML for use in any
Zen page XData Contents block.
You can add a new type of meter to Zen by subclassing the base
meter class and adding the method calls required to render the
new meter’s SVG contents.
17.1 Building Composite Components
A composite component assembles a group of built-in Zen components and lets you refer to the group
from XData Contents as if it were a single component. Zen places the children of the composite within
the page’s object model as if XData Contents referenced them explicitly. This shorthand is convenient,
and it also prevents errors when you want to repeat identical component arrangements on different
pages.
The following table is your checklist for building a composite component class. Not every item in the
checklist is necessary for every composite. This checklist lists every possible item, and notes those
that are optional. See the example of a composite component class that follows the table.
Extending Zen with Composite Components
Task
Subclass
Description
Extend %ZEN.Component.composite to create a new class. The example
creates a composite component class called myComposite in the MyApp
package. Any class that extends %ZEN.Component.composite is a group,
with all of the group layout and style attributes listed in the Zen Layout
chapter.
328 Using Zen

Building Composite Components
Task
Parameters
Properties
Methods
XData
Contents
XML
Element
Description
Provide class parameters and appropriate values. The NAMESPACE
parameter is required to assign a namespace to the composite.You must
reference this namespace when you place the composite component on
a Zen page.
(Optional) Provide properties, if needed. The example does not require
any new properties for the subclass.
(Optional) Provide supporting methods as needed for component behavior.
The example provides an event handler method that is activated when
the user clicks one of the buttons in the composite.
Within the composite component class, define an XData Contents block
that uses as its top-level element. The example provides
two elements within .
To add a composite element to a page, place its corresponding XML
element in the page class XData Contents block.There is a specific syntax
for this; see the example following this table.
The following is a sample composite component class that provides two buttons:
Class MyApp.myComposite Extends %ZEN.Component.composite
{
}
/// Define xml namespace for this component
Parameter NAMESPACE = "http://www.intersystems.com/myApp";
/// Contents of this composite component:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
Method okBtn() [Language = JavaScript]
{
alert('ok');
}
The correct way to reference this composite component from an XData Contents block is as follows:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
Using Zen 329

Custom Components
Where:
• The element references the namespace defined for the composite component, and defines
an alias for it, by providing the following attribute within the opening element:
xmlns:myApp="http://www.intersystems.com/myApp"
This statement defines an alias myApp for the namespace that was defined in the composite
component class
Parameter NAMESPACE = "http://www.intersystems.com/myApp";
• The element references the myComposite component. This reference
has the form:
where alias is the namespace alias defined in the element (myApp in this case) and
component is the name of the custom component class (myComposite in this case).
17.1.1 The composite Property
When you work with composite components programmatically, every component within a composite
has a property called composite that points to the containing composite object. This makes it easy to
define actions for a composite that refer to methods of the composite class. You can see this in the
first element from the example above:
The onclick attribute value for this definition uses zenThis.composite to represent the containing
composite object. This convention allows the to call the okBtn method that is defined
within the composite class.
17.1.2 Composites and Panes
To review panes and how their contents are defined, see the chapter Zen Layout.
When a component is placed within a composite element, the contents of the pane can be
defined within the composite class (or subclass of the composite). At runtime, the composite first looks
for a pane with a given name within the current page; if it does not find it there, it looks within the
composite class.
330 Using Zen

17.2 Overriding Component Style
Overriding Component Style
If you have subclassed a built-in Zen component to modify styles already in use by a parent component,
then the instructions in the chapter Zen Style, topic Overriding Built-in Styles, are sufficient. These
are:
1. Determine the relevant CSS style name
2. Subclass the built-in Zen component
3. Use the Zen Style Wizard to edit XData Style.
If you want to define an entirely new CSS style (with a new name) and apply that style to a component,
then there are additional steps to perform. You must not only define the CSS style, but also reference
it from the class code that renders the custom component as HTML. At this point, you are truly creating
a custom component. The next topic covers the necessary steps in detail.
17.3 Creating Custom Components
Each Zen component is implemented as a class and is completely self-contained. The component class
specifies its own behavior (server and client methods) and appearance (SVG or HTML, DHTML, and
stylesheets) in one logic unit: the class. Each component class has an XML projection. This projection
consists of:
• An XML element with the same name as the class (, , , etc.)
• XML attributes, which are properties of that class (width, height, etc.)
To build a Zen page you place a selection of the available XML elements and attributes in a wellformed
XML document in the Zen page class. The container for this document is called XData Contents.
At compile time, Zen generates the code required to display the page in the browser with the layout,
style, and behavior that you have chosen for its components. At runtime, Zen handles all of the display
details and correctly executes any snippets of JavaScript, HTML, or CSS that are embedded or referenced
in the component or page classes.
Zen components provide all of these features automatically because they inherit them from their base
classes. This is something you can do yourself. To create a custom component, simply choose the
appropriate base class and extend it. Your new class automatically gets the following features:
• An XML projection to use in the page class XData Contents
• Any properties, methods, parameters, or other characteristics of its parent(s)
Using Zen 331

Custom Components
• Appropriate handling of any client-side material in the class:
- JavaScript
- CSS style definitions
- HTML
- SVG
• Properties can be exposed as settings, to be observed and modified using the client-side getProperty
and setProperty methods.
The following table is your checklist for creating a custom component class. The following topics
describe each item in detail.
Extending Zen with Custom Components
Task
Package
XML Namespace
Subclass
Parameters
XData Style
Properties
Methods
%DrawHTML
XML Element
Description
Use one class package for all your custom components.
Use one XML namespace for all your custom components.
Choose a base class from a short list of candidates.
Provide class parameters, such as NAMESPACE.
(Optional) Within the component class, provide an XData Style block
that defines CSS styles.
(Optional) Provide properties, if needed. The various properties of
a component can be exposed as settings, and can be observed and
modified using the client-side getProperty and setProperty
methods.
(Optional) Provide supporting methods as needed for component
behavior.
Within the component class, ensure that the %DrawHTML method
references any new CSS styles. Visual components must draw the
HTML (or SVG) needed to create their client-side visual
representation.
To add a custom component to a page, place its corresponding XML
element in the page class XData Contents block. There is a specific
syntax for this; see the Examples topic below.
332 Using Zen

Creating Custom Components
17.3.1 Package and Namespace
The best practice is to use a common XML namespace for all your custom components (and only for
custom components). Also, place all your component classes in their own package. There are two main
reasons for these conventions:
• Custom components need their own XML namespace to avoid conflict with other components.
• The Zen framework automatically generates JavaScript and CSS stylesheet include files for your
custom components. These files are generated on a per-class-package basis, so it is much easier
to organize this if your custom components are contained within their own package.
Whatever namespace you choose, it must specified by the NAMESPACE parameter within each custom
component class that you create. For example:
Parameter NAMESPACE = "http://www.mycompany.com/mycomponents";
17.3.2 Base Class
Choose a base class for the new component. There are five significant options to choose from. The
following table and figure summarize the choices.
Custom Component Base Classes
Base Class
%ZEN.Component.component
%ZEN.Component.control
%ZEN.SVGComponent.svgComponent
%ZEN.SVGComponent.meter
Purpose
Visual, HTML based
component.
HTML based component
can be placed within a
form for the user to enter
a value.
Visual, SVG based
component.
Dynamically updated SVG
graphic that displays a
value.
Inherited Attributes
Zen components
Zen components,
Zen controls
SVG components
SVG components,
meter components
%ZEN.Component.object
Non-visual component. Typically this is a helper
object that is used by visual components and
requires a client-side object representation.
Using Zen 333

Custom Components
Base Classes for Custom Components
17.3.3 Zen Component Wizard
Use the Caché Studio New Zen Component Wizard to create a new Zen component class. You can
start the wizard using the Studio File New command, selecting the Custom tab, and clicking the New
Zen Component icon.
17.4 Custom Style
To define a new CSS style for a custom component, you can place an XData Style block in the subclass.
Within this block place a tag and a closing tag. Within
the element, place whatever CSS style definitions you like.
The built-in class %ZEN.Component.group includes the following XData Style block:
334 Using Zen

Custom Style
XData Style
{
/* @doc="Table used by groups." */
table.group {
padding: 0px;
}
/* @doc="Cell within table used by groups." */
table.group td {
padding: 0px;
}
/* @doc="Header within table used by groups." */
table.group th {
padding: 0px;
}
}
Note the /* @doc="text" */ syntax in the above example. When you provide a comment for an
XData Style entry using this syntax, the Zen Style Wizard automatically includes a description of your
style in its list of available styles. To display this list while editing a Zen class in Studio, press CTRL-
T to display the list of Zen templates. Select the Zen Style Wizard; a list of all defined styles appears.
This list is organized alphabetically by component name.
While viewing the list of styles in the Zen Style Wizard, you can select the radio button next to the
name of the styles you want to edit and click OK. Templates for these styles appear in your XData
Style block.
Important:
If you are overriding existing styles in a subclass of one of the built-in Zen components,
the Zen Style Wizard offers the most convenient way to select the styles you want to
override.
The XData Style example above is a definition of styles for a built-in Zen component,
%ZEN.Component.group. Suppose you wish to create a custom component with entirely new styles.
In that case you will want to create styles named appropriately for your component. A component
called MyComponent might include an XData Style block like the one shown below. Zen automatically
includes this style definition in any page that uses in its XData Contents block:
XData Style
{
/* @doc="Main style definition for MyComponent." */
.MyComponent {
color: blue;
background: yellow;
white-space: nowrap;
}
}
Simply defining a XData Style block is not sufficient: the component class must actually use the newly
defined CSS styles within the HTML that it generates. To accomplish this, you must provide a reference
to the style in the %DrawHTML method that renders HTML for the custom component class. The
Using Zen 335

Custom Components
following sample %DrawHTML method references the MyComponent style defined in the XData
Style example above:
Method %DrawHTML()
{
&html
}
This sample %DrawHTML method uses a syntax that you see commonly throughout this book: &html
followed by HTML statements enclosed in angle brackets . This is the ObjectScript syntax for
embedded HTML statements. See the definition of the & symbol in the Caché ObjectScript Reference.
By convention, any CSS style names you provide in an XData Style block should use a name that is
related to the name of the component, as in the example above. This helps to avoid conflicts (which
cannot be detected in advance due to the nature of CSS) and makes it easier for users to determine
how to override styles. A component should never redefine a style defined by another component, or
define an element-wide style selector (such as “input” or “table”), as this will cause interference with
other components.
Important:
The chapter Zen Style, topic Cascade of Styles describes order of precedence rules
for CSS styles defined in component, page, and application classes. Custom components
are subject to these rules.
17.4.1 XData SVGStyle
XData Style does not apply to Zen SVG components. Zen SVG components use XData SVGStyle.
To define styles for a custom Zen SVG component class, you can provide an XData SVGStyle block
and add CSS statements between the tag and the closing
tag. For example:
XData SVGStyle
{
.customSVGComponent {
fill: url(#myGrad);
stroke: black;
stroke-width: 2px;
}
}
17.4.2 XData SVGDef
The XData SVGStyle example above is from the class ZENTest.customSVGComponent in the SAMPLES
namespace. It refers to a color myGrad as the fill color for the customSVGComponent shape.
myGrad is defined in the same class, but in a separate block called XData SVGDef. This block defines
myGrad as a shaded gradient from blue to red:
336 Using Zen

Custom Properties
XData SVGDef
{
}
17.4.3 Zen Color Definitions
The built-in class %ZEN.SVGComponent.svgPage provides an XData SVGDef block with several
useful color definitions:
• The glow-silver color produces a metallic look for instrumentation items such as the
meter.
• Meters such as the traffic light use glow-red, glow-yellow, and glow-green for indicator lamps.
• Lamp colors glow-blue, glow-purple, glow-orange, and glow-teal are also available.
always references this class, or some subclass of it, through its svgPage attribute, so these
colors are always available to any SVG component.
17.5 Custom Properties
Since a component is a class, it may define properties in addition to those it inherits. The definition of
these properties influence how they work on the server, how they can be used within the component’s
corresponding JavaScript class definition, and how they can be specified within an XML representation
of the page.
17.5.1 Naming Conventions
The chapter Zen Tutorial, topic Zen Naming Conventions, describes the case-sensitive naming conventions
for properties in Zen classes. Briefly:
• Client-only properties: myProperty
• Server-only properties (the % is essential): %MyProperty
• Properties that invoke an event handler via Javascript: onmousedown
• Properties that identify a server-side callback method: OnCreateDataSet
• Other properties: myProperty
Using Zen 337

Custom Components
17.5.2 XML Projection
All Zen components are derived from the %XML.Adaptor class and use its mechanisms for defining
their XML behavior. If you would like more detail about this, see the book Using XML with Caché,
chapter Controlling the Caché Object-XML Projection.
All simple properties of Zen components should have an XMLPROJECTION value of "attribute". If
you do not want to make a property visible via XML, set its XMLPROJECTION parameter to "none"
as in the following example:
Property beeswax As %ZEN.Datatype.string(XMLPROJECTION="none");
Datatypes from the %ZEN.Datatype package use a default XMLPROJECTION value of "attribute" so
that they will be projected as XML attributes. Zen datatypes offer many conveniences when you are
defining properties in a custom component class. See the topic Datatype Classes below.
17.5.3 setProperty Method
If you add a property to a custom component class, you must override the setProperty method in the
subclass to implement cases for each property that you have added to the class. You can default to the
superclass method for properties of the superclass. There are several examples of this practice in the
topics below.
Near the end of each example of a custom component class is a setProperty method that implements
cases for properties defined in that class. See the Odometer Meter Example and the Clock Meter
Example.
17.5.4 Datatype Parameters
All Zen classes inherit (from %ZEN.componentParameters) the following set of property parameters,
which you can apply to any property you add to a Zen class. The property does not need to have a Zen
datatype to use these parameters:
• ZENENCRYPT
• ZENEXPRESSION
• ZENLOCALIZE
• ZENSETTING
17.5.4.1 ZENENCRYPT
Set ZENENCRYPT to 1 (true) to specify that a property’s value will be encrypted (using the current
session key) when it is sent to the client. If this value is returned to the server, it will be automatically
338 Using Zen

decrypted. This makes it possible to place sensitive data on the client for future processing on the
server without letting a user view this data.
The ZENENCRYPT parameter applies only to code that Zen generates from the XML description
within XData Contents in the page class. If you bypass XData Contents and work with Zen pages
programmatically, then you are responsible for handling the equivalent encryption tasks.
17.5.4.2 ZENEXPRESSION
Set ZENEXPRESSION to 1 (true) to indicate that the property can interpret a Zen #()# expression to
get its value at runtime. For details, see Zen Runtime Expressions.
17.5.4.3 ZENLOCALIZE
Any Zen property that has its ZENLOCALIZE parameter set to 1 (true) automatically generates a
Message Dictionary entry that can be used to translate the value of the property into another language.
This is described in detail in the chapter Zen Localization.
It is a good practice to localize any string-valued properties that contain messages that you want to
display to communicate with the Zen application user. It is convenient to give a property the Zen
datatype %ZEN.Datatype.caption, which always has ZENLOCALIZE set to 1 (true) but you can set
ZENLOCALIZE directly if you want to.
The ZENLOCALIZE parameter:
Custom Properties
• Applies only if the class that uses it also defines a localization domain by providing a value for
the DOMAIN class parameter.
• Applies only to code that Zen generates from the XML description within XData Contents in the
page class. If you bypass XData Contents and work with Zen pages programmatically, then you
are responsible for handling the equivalent localization tasks (including calls to $$$Text). See
Zen Localization.
17.5.4.4 ZENSETTING
Set ZENSETTING to 1 (true) to specify that the property should be considered as a “setting” within
the client class definition. This means that:
• The property becomes visible to Zen utilities such as the Control Test page
• You can observe and modify its value using the client-side getProperty and setProperty methods
Every datatype class in the %ZEN.Datatype package already sets ZENSETTING to 1. When you use
the %ZEN.Datatype classes, you must set ZENSETTING to 0 for any properties that you do not want
to be treated as settings.
Using Zen 339

Custom Components
17.5.5 Datatype Classes
For convenience, Zen provides a set of datatype classes that you can use when defining properties in
Zen classes. The datatype classes are in the %ZEN.Datatype package. The following table lists them.
When you define new Zen classes, you are free to use any datatype classes you wish. Using the
%ZEN.Datatype classes makes it easier to understand the purpose of a property in the context of a Web
application. Also, in many cases datatype classes automatically enable features that you would otherwise
have to encode yourself, including easy localization, event handler conventions, and language-independence
for Boolean values and list arrays.
Fundamentally, all Zen datatypes classes are strings. All of the datatypes listed in the following table
share the same base class, %ZEN.Datatype.datatype, whose value is defined as type %Library.String.
As you can see from the entries in the table, each of these strings is interpreted by its subclass in a
uniquely useful way.
Datatype Classes
Class
align
boolean
caption
classMember
className
color
cssClass
Description
HTML horizontal alignment value. Possible values for this are “left”, “right”,
and “center”. For vertical alignment values, see valign.
Boolean value: It can have the text value "true" or "false" in XData
Contents. When accessed programmatically from ObjectScript or Basic
code running on the server, it can have the value 1 or 0. When accessed
programmatically from JavaScript code running on the client, it can have
the value true or false.
String that is automatically added to the set of localized text resources
when this property is initialized by an XData Contents block provided that
the page has defined a localization DOMAIN and its ZENLOCALIZE
parameter is set to 1. See Zen Localization.
Name of a server-side class member (such as a property name or method
name). This class defines a datatype parameter, MEMBERNAME, that
indicates the type of class member. When using this datatype to define
a property, you must also provide a value for its MEMBERNAME
parameter. Possible values for MEMBERNAME are “PROPERTY”,
“METHOD”, “QUERY”, “INDEX”, or “XDATA”.
Name of a server-side class.
CSS color value.
Name of a CSS style class.
340 Using Zen

Custom Properties
Class
csv
delegator
eventHandler
Description
Comma-separated list of values such as “John,Paul,George,Ringo”
Name of a server-side method within the current page class that is used
as a callback method. For example, the Zen component has an
OnDrawContent attribute that specifies the name of a server-side callback
method that provides HTML content by using &html or by using the WRITE
command. If defined, this callback is invoked on the server whenever this
component is drawn. In the underlying class %ZEN.Component.html,
OnDrawContent is defined to be of type delegator.
JavaScript expression to be executed on the client in response to a clientside
event. As an event handler, this JavaScript expression is expected
to invoke a client-side method that is the “handler” for this event.
For example, the Zen component has an onclick attribute that
specifies what should happen when a user clicks on the control. In the
underlying class %ZEN.Component.button, onclick is defined to be of type
eventHandler.
You must use the eventHandler type if you wish to use the %GetEventHandlers
helper method to access the event handler from %DrawHTML.
The next topic explains the details.
expression
float
glvn
html
id
integer
length
list
name
Server-side ObjectScript expression.
Floating point numeric value.
Name of a Caché global (multidimensional array) such as “^myGlobal”.
String of text that is marked up using HTML.
The id value for a component. It must not be used for any other purpose.
Integer value.
HTML length value. For example: “5” or “5%”.
On the server a list represents a set of items as a piece-delimited string.
On the client the list is converted to a JavaScript array. This datatype has
a DELIMITER parameter, the value of which is used to delimit the server
representation of the list. The default DELIMITER value is $C(5).
The name value for a component. It must not be used for any other
purpose.
Using Zen 341

Custom Components
Class
resource
script
sql
string
style
svgStyle
uri
valign
value
Description
Name of a Caché resource. If you are not familiar with Caché resources,
see the Caché Security Administration Guide chapter Assets and
Resources.
Client-side JavaScript expression.
SQL statement. By default, properties of this type are encrypted when
sent to the client (the ZENENCRYPT parameter is set to 1).
String with a default MAXLEN of 250. You can reset the MAXLEN value.
CSS style statement. For example: "color:red; background:
yellow;"
SVG CSS style definition. Styles within SVG are CSS compliant, but there
is a different set of styles available, so this datatype designates them.
URI value. For example: “http://www.intersystems.com/zen”
HTML vertical alignment value. Possible values are “top”, “bottom”, and
“middle”. For horizontal alignment values, see align.
A value to be used as the value of an HTML control.
17.6 Custom Methods
Since a component is a class, it may define methods in addition to those it inherits. The definitions of
these methods influence where and how they can be used. These rules are exactly the same for methods
in Zen component classes as they are for methods within a Zen page.
The chapter Zen Application Programming, topic Zen Page Methods, describes these rules. The following
table summarizes them.
342 Using Zen

Custom Methods
Component Class Method Conventions
Callable
From
Runs On
Code
Language
Keyword
Naming
Convention
Client
Client
JavaScript
Language =
JavaScript
myMethod
Client
Server (but can
send back code
that runs on the
client)
ObjectScript or
Basic
ZenMethod
MyMethod
Server
Server
ObjectScript or
Basic
—
%MyMethod
The most important method in your custom component class is the required server-side method
%DrawHTML. The following topics describe how to work with this method.
17.6.1 %DrawHTML
The %DrawHTML method is responsible for providing the HTML used to draw a Zen component.
This method is called when the page containing the component is first served. It may subsequently be
called if the page needs to dynamically refresh the contents of the component, such as when the query
for a is re-executed.
The basic operation of the %DrawHTML method is very simple: Any output that this method produces
is served up as HTML within the browser. You can output from %DrawHTML using the WRITE
command, as follows:
Method %DrawHTML()
{
Write "This is some HTML!",!
}
As an alternative to WRITE, you can use the ObjectScript syntax for embedded HTML statements.
This syntax uses &html followed by HTML statements enclosed in angle brackets as in the following
example:
Method %DrawHTML()
{
&html
}
Any output from %DrawHTML is enveloped by the component’s enclosing element, as supplied
by the Zen framework.
What makes this convention powerful is that %DrawHTML is an instance method of the component
class: it can execute logic and has access to the component’s properties and methods, as well as the
Using Zen 343

Custom Components
underlying Caché database. It supports Caché ObjectScript expression, CSP #()# syntax, and Zen #()#
expression syntax. The following simple example uses a number of these features:
Method %DrawHTML()
{
#; draw items as specified by myCount
For i=1:1:..myCount {
&html
}
}
17.6.2 Helper Methods for %DrawHTML
The Zen framework defines three server-side helper methods for use in the %DrawHTML method
for custom components: %MakeId, %Attr, and %GetEventHandlers. The class code for
shows one way to use these methods effectively in %DrawHTML:
344 Using Zen

Custom Methods
Class %ZEN.Component.button Extends control
{
Parameter DEFAULTCONTROLCLASS = "button";
/// Caption displayed for this button.
/// This is a localized value.
Property caption As %ZEN.Datatype.caption;
/// defines style sheet used by this component
XData Style
{
/* @doc="Style for button (input)." */
.button {
}
}
Method %DrawHTML()
{
Set disabled = $S(..disabled:"disabled",1:"")
Set tIgnore("onchange") = ""
&html<
>
}
/// This method fills in reasonable default values for
/// this control. Used by tools (such as Control Tester) to
/// dynamically create controls.
Method %SetDefaultValues()
{
Set ..caption = "Button"
}
/// Set the value of a named property.
Method setProperty(property, value, value2) [ Language = javascript ]
{
switch(property) {
}
}
case 'caption':
this.caption = value;
var el = this.findElement('control');
if (el) {
el.value = this.caption;
}
break;
case 'value':
// do not set control value; just internal value
this.value = value;
break;
default:
// dispatch
return this.invokeSuper('setProperty',arguments);
}
return true;
Important:
This example is close, but not identical, to the built-in class %ZEN.Component.button.
The following topics discuss how each of the %DrawHTML helper methods is used:
Using Zen 345

Custom Components
• %MakeId — Generate the id value for the HTML element that displays the component on the
page. Use a consistent naming scheme so that the client-side method findElement can find the
HTML element on the page.
• %Attr — Assign a value to an attribute of the HTML element that displays the component on the
page. This method may be called repeatedly to assign values to all the HTML attributes required
to render the component.
• %GetEventHandlers — Retrieve all of the event handling information from the component definition,
so that the HTML representation of the component can correctly match each user event
with the code that should execute.
17.6.3 Identifying HTML Elements
The %MakeId server-side method ensures uniqueness for the id of every HTML element on the output
page. The example in the previous topic calls %MakeId from embedded HTML to set the id for the
HTML element as follows:
id="#(..%MakeId("control"))#"
%MakeId concatenates the string provided by the caller with the underscore character “_” followed
by the unique sequential number that Zen assigns to every component it places on the page. It then
gives this identifier to Zen to use as the value for the id attribute in the enclosing for the element.
Additionally, if the component is part of a repeating group, Zen adds a further underscore character
“_” followed by the tuple number.
Thus, if you view the source of any generated Zen page you will see enclosing elements with
generated id values like spacer_23 in the following example:
The following more complex excerpt shows how Zen provides unique HTML id values for each element
in a repeating group of radio buttons. This excerpt is part of the page that results when Zen renders
the class ZENDemo.FormDemo from the SAMPLES namespace:
346 Using Zen

Marital Status:
Single&nbsp;
Married&nbsp;
Divorced&nbsp;
Widowed&nbsp;
Other&nbsp;
The client-side equivalent for %MakeId is a JavaScript method called makeId. The custom meter
component examples use makeId. See the Odometer Meter Example and the Clock Meter Example.
17.6.4 Finding HTML Elements
Custom Methods
When you are writing client-side code and need to access a specific HTML element on the page, you
can use the findElement method. Its argument is the value that you assigned to the id attribute when
placing the component on the page. findElement combines this string with the sequential identifier
for the element on the output page to generate the appropriate HTML id for the element on the output
page. It uses this information to obtain a pointer to the component object within the page object model
for the rendered page, then returns that pointer so that you can use properties and methods of the
component object.
Ordinary Zen components inherit findElement from %ZEN.Component.object. For SVG components
you must use findSVGElement from %ZEN.SVGComponent.svgComponent. The custom meter
component examples use findSVGElement.
findElement and findSVGElement work correctly only if you have assigned HTML id values using
%MakeId (on the server) or makeId (on the client).
Using Zen 347

Custom Components
17.6.5 Setting HTML Attribute Values
The %Attr server-side method assigns a value to an attribute of the HTML element that displays the
component on the page. This method may be called repeatedly to assign values to all the HTML
attributes required to render the component. The following sample %DrawHTML method uses %Attr
in rendering the component:
Method %DrawHTML()
{
Set disabled = $S(..disabled:"disabled",1:"")
Set tIgnore("onchange") = ""
&html
}
Suppose the value of the controlStyle attribute is currently myActionStyle. As the
%DrawHTML method outputs HTML, an expression in this format:
#(..%Attr("style",..controlStyle))#
Generates the following output:
style="myActionStyle"
17.6.6 Attaching Event Handlers to HTML Elements
The %GetEventHandlers server-side method gets all the event handler attributes for a given component
and uses them to write out any event handler attributes for the HTML that displays that component in
the output page.
Important:
%GetEventHandlers can only find event handler attributes whose underlying property
has been defined using the datatype class %ZEN.Datatype.eventHandler.
The chapter Zen Controls, topic Control Attributes lists the event handler attributes that you can
specify for a control component on a Zen form. The types of events covered by this list include mouse
movements, mouse clicks, or key clicks. Other types of Zen component have event handlers, but controls
offer the single largest pool for comparison.
Preceding chapters have explained that to set up an event handler for a built-in Zen component you
must specify a JavaScript expression as the value of the corresponding event handler attribute. Generally
this JavaScript expression invokes a client-side method that serves as the “handler” for this event. Of
course, if you set up the component this way you must also write the client-side method that is being
invoked.
348 Using Zen

For custom components, you must take additional steps to connect each user event with its appropriate
handler. This connection takes place in the %DrawHTML method for the custom component. Consider
the %DrawHTML method for the component:
Method %DrawHTML()
{
#; handle onclick directly
Set tIgnore("onclick")=""
Set tIgnore("onchange")=""
#; select image to display
Set tSrc = ..src
If (..streamId '= "") {
Set tSrc = ##class(%CSP.Page).Link(
"%25CSP.StreamServer.clsSTREAMOID="_$ZCVT(..streamId,"O","URL"))
}
Custom Methods
#; disabled logic
Set tSrc = $Case(..disabled,0:tSrc,:$S(..srcDisabled="":tSrc,1:..srcDisabled))
}
&html
In the above example, some interesting things take place with regard to event handlers. The following
line tells %GetEventHandlers to ignore any value provided for the onchange event handler, even if
it discovers that there is such a value:
Set tIgnore("onchange") = ""
You must provide one such line for each event handler that you want to handle directly in
%DrawHTML, as shown for onclick and onchange in the example above. Then, at the end of
%DrawHTML, pass the variable tIgnore to %GetEventHandlers by reference, as shown in the
example:
#(..%GetEventHandlers(.tIgnore))#
The %DrawHTML example above asks %GetEventHandlers to ignore onclick and onchange, but
for different reasons in each case: ignores onchange because it does not accept user input.
ignores onclick because it is designed to handle all onclick events in the same way, without
permitting the Zen programmer to specify a different behavior in the page class. Therefore, it provides
code in %DrawHTML to handle this event directly. Any event handlers that are not expressly ignored
by %DrawHTML in this way are written out to the page exactly as defined by the Zen programmer.
Now consider this expression from the example above:
#($S(..onclick="":"",1:"class=""imageLink"""))#
This expression uses the ObjectScript $SELECT function to return the first true expression it
encounters in a list of expressions. Looking at the expressions provided: If the component’s
Using Zen 349

Custom Components
onclick attribute value is an empty string, this statement writes an empty string. Otherwise, this statement
formats the HTML element on the output page by writing out the following string:
class="imageLink"
The following expression directs the client-side HTML page to invoke the component’s imageClick
method in response to any user mouse clicks on the corresponding HTML element.
onclick="zenPage.getComponent(#(..index)#).imageClick();"
The imageClick method is a client-side JavaScript method in the component class. It uses
the JavaScript helper method zenInvokeCallbackMethod to invoke onclick callback method for this
component. The imageClick method looks like this:
Method imageClick() [ Language = javascript ]
{
if (!this.disabled) {
// invoke callback, if present
zenInvokeCallbackMethod(this.onclick,this,'onclick');
}
}
Where the zenInvokeCallbackMethod arguments are as follows:
• this.onclick — The component’s onclick attribute value (a JavaScript expression that invokes
a client-side JavaScript method)
• this — A pointer to the component object
• 'onclick' — The HTML name for the event (must be quoted)
This completes the connection between the HTML element, the event, and its handler. You must provide
similar conventions for any event that you intend your custom component to support.
17.6.7 HTML for Dynamic Components
%DrawHTML works differently for components that change in response to runtime information or
that are generated using SVG.
The is an example of a component that writes no static HTML at all. Its %DrawHTML
method simply sets the values of properties such as the currently selected month and date, in preparation
for the more complex JavaScript method renderContents that is invoked whenever the page needs
to redraw the calendar. renderContents and its helper methods generate an array of dynamic HTML
statements based on the user’s current selections of calendar month and date. For details, examine the
class code for %ZEN.Component.calendar.
350 Using Zen

Examples of Custom Components
17.7 Examples of Custom Components
The following is an example of a custom component that defines a title bar. This example is from the
ZENDemo package in the SAMPLES namespace:
Class ZENDemo.Component.demoTitle Extends %ZEN.Component.component
{
/// XML namespace for this component.
Parameter NAMESPACE = "http://www.intersystems.com/zendemo";
/// Domain used for localization.
Parameter DOMAIN = "ZENDemo";
/// Title displayed within this pane.
Property title As %ZEN.Datatype.caption;
/// Category displayed within this pane (above the title).
Property category As %ZEN.Datatype.caption
[ InitialExpression = {$$$Text("ZEN Demonstration")} ];
/// defines style sheet used by this component
XData Style
{
.demoTitle {
color: black;
background: #c5d6d6;
width: 100%;
padding: 0px;
border-bottom: 1px solid darkblue;
font-size: 1.4em;
font-family: verdana;
text-align: center;
}
}
/// Draw the HTML contents of this component.
Method %DrawHTML()
{
Set tCategory = ..category
}
}
&html
The purpose of defining a custom component for a title bar is to provide a consistent look for every
page in a Web application. Page classes in the ZENDemo package provide countless examples of the
Using Zen 351

Custom Components
correct way to reference a custom component. An XData Contents block that provides a correct reference
looks like this:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
Where:
• The element references the namespace defined for the custom component, and defines an
alias for it, by providing the following attribute within the opening element:
xmlns:demo="http://www.intersystems.com/zendemo"
This statement defines an alias demo for the full namespace name.
• The element references the demoTitle custom component. This reference has
the form:
where alias is the namespace alias defined in the element (demo in this case) and component
is the name of the custom component class (demoTitle in this case).
There are further examples of custom components, and references to these components, in the SAMPLES
namespace. You can examine these classes in Studio. The examples of custom component classes
include:
• ZENDemo.Component.demoMenu, a subclass of %ZEN.Component.composite
• ZENDemo.Component.sidebar, a subclass of %ZEN.Component.component
• ZENDemo.Component.bullet, a subclass of %ZEN.Component.object
• ZENTest.customComponent, a subclass of %ZEN.Component.control
• ZENTest.customSVGComponent, a subclass of %ZEN.SVGComponent.svgComponent
352 Using Zen

Creating Custom Meters
17.8 Creating Custom Meters
The following table is your checklist for building a custom meter component. Also see the odometer
and clock examples that follow the table.
Extending Zen with Custom Meters
Task
Subclass
renderMeter
Parameters
Properties
XData SVGStyle
XData SVGDef
setProperty
Methods
renderLabel
XML Element
Description
Extend %ZEN.SVGComponent.meter to create a new class.
Any subclass of %ZEN.SVGComponent.meter must override this
method to render the SVG contents of the meter. The odometer
and clock examples show how to make SVG calls from the meter
class.
(Optional) Provide class parameters and appropriate values. The
odometer example overrides the DEFAULTHEIGHT and
DEFAULTVIEWBOXHEIGHT parameters from the base meter
class.
(Optional) Provide properties, if needed. The odometer sets a
maximum number of digits for its display. The clock overrides the
value property from the base meter class with an ObjectScript
expression that is evaluated each time the meter is displayed. For
the clock, this expression calculates the current time.
(Optional) Provide any CSS style definitions for the meter.
(Optional) Provide any SVG definitions for the meter.
(Optional) You may override this method to provide unique ways
to set certain properties of the meter. The clock example does this
for the value property, then defers to the superclass for setting all
other properties.
(Optional) Provide supporting methods as needed for component
behavior.
(Optional) Any subclass of %ZEN.SVGComponent.meter may override
this method to set the x and y positions of the meter label.
To add the component to a page, place it within that page’s XData
Contents block as an XML element. Examples of this convention
follow this table.
Using Zen 353

Custom Components
17.8.1 Custom Meters in XData Contents
The following sample XData Contents block refers to two custom meter elements, a clock called
and an odometer called :
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
17.8.2 Odometer Meter Example
The class code to display the meter would look like the following example:
354 Using Zen

Creating Custom Meters
Class MyTest.svgOdoDisplay Extends %ZEN.SVGComponent.meter
{
/// Default height of this component.
Parameter DEFAULTHEIGHT As INTEGER = 40;
/// Default viewBoxHeight of this component.
/// This is set to 25 to provide a fixed coordinate system for meters.
Parameter DEFAULTVIEWBOXHEIGHT As INTEGER = 40;
/// maximum digits to display
Property maxDigits As %ZEN.Datatype.length [ InitialExpression = 5 ];
/// Render the inner SVG contents of this component.
/// This is implemented by subclasses.
Method renderMeter() [ Language = javascript ]
{
var digits=this.maxDigits
var width=digits*5+8
// body
var body=this.document.createElementNS(SVGNS,'rect');
body.setAttribute('class','speedometer-body');
body.setAttribute('fill','url(#speedometer-bodyGrad)');
body.setAttribute('x',5);
body.setAttribute('y',3);
body.setAttribute('width',90);
body.setAttribute('height',14);
body.setAttribute('rx',2);
body.setAttribute('filter','url(#dropShadow)');
}
this.svgGroup.appendChild(body);
var box=this.document.createElementNS(SVGNS,'rect');
box.setAttribute('class','speedometer-levelTextBox');
box.setAttribute('fill','url(#speedometer-bodyGrad2)');
box.setAttribute('x',48-(width/2));
box.setAttribute('y',5);
box.setAttribute('width',width+3);
box.setAttribute('height',10);
box.setAttribute('rx',1);
this.svgGroup.appendChild(box);
var off=51+(width/2)
var lvlText = this.document.createElementNS(SVGNS,'text');
lvlText.setAttribute('id',this.makeId('levelText'));
lvlText.setAttribute('class','speedometer-levelText');
lvlText.setAttribute('x',off);
lvlText.setAttribute('y',13);
lvlText.setAttribute('text-anchor','end');
var textNode = this.document.createTextNode(this.value);
lvlText.appendChild(textNode);
this.svgGroup.appendChild(lvlText);
// label
this.renderLabel('50%',32);
Method setProperty(property, value) [ Language = javascript ]
{
switch(property) {
case 'value':
var text = this.findSVGElement('levelText');
var lvl = value
this.odometerValue = value;
if (!(isNaN(value))) {
lvl = value * this.scaleFactor;
Using Zen 355

Custom Components
}
}
// update odometer text
text.setAttribute("class",
(lvl>=0) "speedometer-levelText" : "speedometer-levelTextNeg");
}
this.setTextNode("levelText",lvl);
break;
default:
return this.invokeSuper('setProperty',arguments);
}
return true;
17.8.3 Clock Meter Example
The class code to display the meter would look like the following example:
356 Using Zen

Creating Custom Meters
Class MyTest.svgWatch Extends %ZEN.SVGComponent.meter
{
/// Speed adjustment default = 1
Property speed As %ZEN.Datatype.integer [ InitialExpression = 1 ];
/// Steps the second hand runs default=1 :== 1/10 sec
Property steps As %ZEN.Datatype.integer [ InitialExpression = 1 ];
/// Text for logo displayed in center
Property logo As %ZEN.Datatype.caption [ InitialExpression = "Zen" ];
/// Current value of the meter.
/// Start time in seconds since midnight [0...84000]
Property value As %ZEN.Datatype.string [ InitialExpression = {$p($h,",",2)} ];
/// fixed offset to local time in seconds e.g. -3600 => 1 hour less
Property timeshift As %ZEN.Datatype.integer [ InitialExpression = 0 ];
Method renderMeter() [ Language = javascript ]
{
var now = new Date();
this._starttime=now.getTime();
this._startvalue=this.value;
var value=this.value*1+this.timeshift*1;
var h=value/3600*30+90;
var m=(value%3600)/60*6+90 ;
var s=(value%60)*6+90 ;
//
var body=this.document.createElementNS(SVGNS,'g');
body.setAttribute('class','Watch-shadow');
body.setAttribute('fill','none');
body.setAttribute('stroke','none');
body.setAttribute('stroke-width','2px');
body.setAttribute('filter','url(#dropShadow)');
this.svgGroup.appendChild(body);
//
var path1d='M 20,45 a30,30 0 1,1 0,0.001'
//
var q1=this.document.createElementNS(SVGNS,'g');
q1.setAttribute('id',this.makeId('quarter'));
q1.setAttribute('fill','yellow');
q1.setAttribute('stroke','yellow');
body.setAttribute('stroke-width',2);
body.appendChild(q1);
for (a=0;a

Custom Components
hr.setAttribute('fill','lightgrey');
hr.setAttribute('stroke','grey');
hr.setAttribute('stroke-width',1);
hr.setAttribute('transform','rotate('+h+',50,45)');
body.appendChild(hr);
//
var c=this.document.createElementNS(SVGNS,'path');
c.setAttribute('d','M 25,45 l 27,-3 5,3 -5,3 z');
hr.appendChild(c);
//
hr=this.document.createElementNS(SVGNS,'g');
hr.setAttribute('id',this.makeId('min'));
hr.setAttribute('fill','lightgrey');
hr.setAttribute('stroke','grey');
hr.setAttribute('stroke-width',2);
hr.setAttribute('transform','rotate('+m+',50,45)');
body.appendChild(hr);
//
c=this.document.createElementNS(SVGNS,'path');
c.setAttribute('d','M 22,45 l 40,0');
hr.appendChild(c);
//
c=this.document.createElementNS(SVGNS,'path');
c.setAttribute('d','M 20,45 l 7,-1.5 0,3 z');
c.setAttribute('stroke-width',1);
hr.appendChild(c);
//
var c=this.document.createElementNS(SVGNS,'circle');
c.setAttribute('cx',50);
c.setAttribute('cy',45);
c.setAttribute('r',3);
c.setAttribute('fill','red');
c.setAttribute('stroke-width',1);
c.setAttribute('stroke','grey');
body.appendChild(c);
//
hr=this.document.createElementNS(SVGNS,'g');
hr.setAttribute('id',this.makeId('sec'));
hr.setAttribute('fill','lightgrey');
hr.setAttribute('stroke','red');
hr.setAttribute('stroke-width',1);
hr.setAttribute('transform','rotate('+s+',50,45)');
body.appendChild(hr);
//
c=this.document.createElementNS(SVGNS,'path');
//c.setAttribute('d','M 0,-12.5 l 0,50');
c.setAttribute('d','M 50,45 l 7.5,0 -50,0');
hr.appendChild(c);
//
var c=this.document.createElementNS(SVGNS,'circle');
c.setAttribute('cx',50);
c.setAttribute('cy',45);
c.setAttribute('r',1);
c.setAttribute('fill','black');
c.setAttribute('stroke-width',1);
c.setAttribute('stroke','black');
body.appendChild(c);
// logo
var logo = this.document.createElementNS(SVGNS,'text');
logo.setAttribute('id',this.makeId('logo'));
logo.setAttribute('class','speedometer-logoText');
logo.setAttribute('x',50);
logo.setAttribute('y',35);
logo.setAttribute('text-anchor','middle');
358 Using Zen

Creating Custom Meters
var textNode = this.document.createTextNode(this.logo);
logo.appendChild(textNode);
this.svgGroup.appendChild(logo);
// label
this.renderLabel('50%','97.5%');
this.updateHandles();
}
/// Internal method: update position of needle
Method updateHandles() [ Language = javascript ]
{
if (this.animate)
}
{
}
delete this._timerId;
var now = new Date();
var time=now.getTime();
var delta=(time-this._starttime)/1000; //only seconds
//if (delta >= (1/60)) // 0.1° change
//{
var value=this._startvalue*1+delta;
this.setProperty('value',value);
//}
this._timerId = window.setTimeout('zenPage.getComponent(' + this.index
+ ').updateHandles()',this.steps*100);
Method setProperty(property, value) [ Language = javascript ]
{
switch(property) {
case 'value':
this.value=value;
value+=this.timeshift*1;
// calculate actual rotation
var h = (value/120)+90;
var m = (value%3600)/10+90;
var s = (value%60)*6+90;
this.findSVGElement('hour').setAttribute('transform','rotate('+h+',50,45)');
this.findSVGElement('min').setAttribute('transform','rotate('+m+',50,45)');
this.findSVGElement('sec').setAttribute('transform','rotate('+s+',50,45)');
;break
}
}
case 'logo':
this.logo = value;
this.setTextNode('logo',this.logo);
break;
default:
return this.invokeSuper('setProperty',arguments);
}
return true;
Using Zen 359

18
Zen Application Programming
A Zen application specifies the full set of activities that can result when a Zen client and server interact.
These activities may consist of displaying Web pages, issuing queries to a database, writing data to
disk, and more. When you create a Zen application, you create a suite of Zen classes that specify these
activities. The language you use for these classes is Caché ObjectScript — with embedded snippets
of XML, HTML, SVG, and JavaScript as needed.
For an introduction to Zen application programming, see these chapters:
• Introducing Zen
• Zen Tutorial
• Zen Client and Server
• Zen Application Concepts
This chapter provides reference details that build upon the foundation provided by these chapters.
18.1 Zen Classes as CSP Classes
The base application class %ZEN.application and the base page class %ZEN.Component.page each
inherit from %CSP.page. This means that every Zen application class and every Zen page class is also
an instantiable Caché Server Page. All the CSP page class properties, methods, parameters, and variables
(such as %session) are available to Zen application and page classes.
The introductory chapter Zen Client and Server explains the relationship between Zen and CSP. This
chapter provides reference details for the Zen side of this relationship. The book Using Caché Server
Pages (CSP) provides details for CSP.
Using Zen 361

Zen Application Programming
18.2 Zen Application Classes
Every Zen application has an application class. This is a class derived from %ZEN.application that
provides high-level housekeeping and acts as the single root for all of the pages in the application. The
application does not keep an inventory of its pages. The association between the application and its
pages occurs because every Zen page class identifies the application that it belongs to.
The following table lists the elements of a Zen application class.
Application Class Elements
Element
APPLICATIONNAME
CSSINCLUDES
HOMEPAGE
JSINCLUDES
USERPACKAGES
USERSVGPACKAGES
Role
Class
parameter
Class
parameter
Class
parameter
Class
parameter
Class
parameter
Class
parameter
Purpose
Defines a text string that you can use in titles or
labels.
Comma-separated list of cascading style sheet
(CSS) files to include for every page in the
application. See Zen Style.
URI of a default Home Page for the application.
This makes it possible for the application class to
be specified as a starting point for the application,
even though it does not itself display a page.
When the application class receives an HTTP
request, it redirects the request to the URI specified
by the HOMEPAGE class parameter.
Comma-separated list of JavaScript include files
to include for every page in the application.
Comma-separated list of user-defined class
packages whose HTML class and style definitions
are in pre-generated include files. These include
files will be available to every page within the
application.
Comma-separated list of user-defined class
packages whose SVG class and style definitions
are in pre-generated include files. These include
files will be available to every page within the
application.
362 Using Zen

Zen Page Classes
Element
XData Style
Role
Embedded
XML
document
Purpose
Any CSS style definitions that appear within this
XData block are placed on every page within the
application. See Zen Style.
When programming, be aware that the application class can contain server-side methods written in
Caché Basic or ObjectScript only. It cannot contain any client-side methods marked with the JavaScript
keyword, or client/server methods marked with the ZenMethod keywords. The application class can
execute methods on the server only.
18.3 Zen Page Classes
Pages within a Zen application are derived from the class %ZEN.Component.page. A page class defines
and serves the contents of a Zen page in a browser. For an introduction to Zen pages, see these chapters:
• Zen Tutorial
• Zen Client and Server
• Zen Application Concepts
For details about placing components on a Zen page, see:
• Zen Component Concepts
• Zen Layout
• Zen Style
This topic provides reference details to support these chapters.
18.3.1 Zen Page Parameters
There are a number of class parameters that a page class can use to control the behavior of the page.
The following table lists the most useful of them. Others are described in the online class documentation.
Using Zen 363

Zen Application Programming
Page Class Parameters
Parameter
APPLICATION
AUTOLOGOUT
CSSINCLUDES
DOMAIN
JSINCLUDES
PAGENAME
PAGETITLE
RESOURCE
USERPACKAGES
USERSVGPACKAGES
Description
Package and class name of the associated application.
If 1 (true) attempt to refresh this page when its session has
expired. If 0 (false) do not. The default is 1.
Comma-separated list of cascading style sheet (CSS) include
files. See Zen Style.
Used for Zen Localization. The default is "" (an empty string
indicating no domain).
Comma-separated list of JavaScript include files for the page.
Defines a text string that you can use in titles or labels. If not
specified, the Zen page class name is used.
Default value for the component’s title attribute.
Name of a system Resource for which the current user must
hold USE privileges in order to view this page or to invoke any
of its server-side methods from the client.
See the Caché Security Administration Guide, chapter Assets
and Resources, topic Application Resources and Their Privileges.
Comma-separated list of user-defined class packages whose
HTML class and style definitions are in pre-generated include
files.
Comma-separated list of user-defined class packages whose
SVG class and style definitions are in pre-generated include
files.
18.3.2 Zen Special Variables
Zen offers several special variables to represent instantiated objects of various types within the Zen
application. These variables offer a convenient way to reference the methods and properties of these
objects from within Zen page or Zen component class code.
364 Using Zen

Zen Page Classes
Special Variables on the Server Side
Server Side
Variable
Refers To
Use in
These
Classes
Use in Zen
Runtime
Expressions
%application
Application object
Page
No
%composite
Current composite object (if any)
Page,
Component
Yes
%page
Current page object
Page,
Component
Yes
%query
Current ResultSet object (if any)
Page,
Component
Yes
%session
Current CSP session object
Page,
Component
Yes
%this
Current object (page or component)
Page,
Component
Yes
%url
An object whose properties are URI
parameters of the current page
Page,
Component
Yes
%zenContext
String that indicates what the server
code is currently doing
Page
No
Note that the %url special variable will only contain values when a page is first served; If you refer
to %url in subsequent methods calls or component refreshes, its properties will have no value. If you
need to refer to a value passed in via a URI parameter, define a property of your page class, link it to
a URI parameter using the ZENURL parameter, and then refer to this value via the %page object. See
Zen Page URI Parameters, later in this chapter.
18.3.2.1 %application
The server-side %application variable is available in every Zen page class. It is intended for use
in methods that run while the page object is being created. It refers to the instance, on the server, of
the application class that is associated with this page. This allows the page to invoke server-side
methods defined in the application class.
For example, the following method is defined in the application class ZENDemo.Application in the
SAMPLES namespace:
Using Zen 365

Zen Application Programming
ClassMethod GetQuickLinks(Output pLinks) As %Status
{
Set pLinks("Home") = "ZENDemo.Home.cls"
Set pLinks("Expense Calculator") = "ZENDemo.ExpenseCalculator.cls"
Set pLinks("MVC Master Detail") = "ZENMVC.MVCMasterDetail.cls"
Set pLinks("MVC Chart") = "ZENMVC.MVCChart.cls"
Set pLinks("MVC Meters") = "ZENMVC.MVCMeters.cls"
Set pLinks("MVC Form") = "ZENMVC.MVCForm.cls"
Set pLinks("Test Suite") = "ZENTest.HomePage.cls"
Set pLinks("Controls") = "ZENDemo.ControlTest.cls"
Set pLinks("Methods") = "ZENDemo.MethodTest.cls"
Quit $$$OK
}
Page classes that are associated with this application can then invoke this method as follows:
Class ZENDemo.ExpenseCalculator Extends %ZEN.Component.page
{
/// Application this page belongs to.
Parameter APPLICATION = "ZENDemo.Application";
}
// ...Intervening lines removed...
/// Return an array of quick links to be displayed by the locator bar.
ClassMethod GetQuickLinks(Output pLinks) As %Status
{
// dispatch to our application class
Quit %application.GetQuickLinks(.pLinks)
}
There is no client-side equivalent for %application.
18.3.2.2 %page and zenPage
Zen offers special variables to represent the Zen page object on the client and server sides:
• In ObjectScript or Basic code that runs on the server side, the page object is %page:
Set btn = %page.%GetComponentById("NewBtn1")
• In Zen runtime expressions, the page object is %page:
text id="rows" label="Rows:" value="#(%page.Rows)#" size="5"/>
• In JavaScript methods that run on the client side, the page object is zenPage:
var chart = zenPage.getComponentById('chart');
• In JavaScript expressions that are values of XML attributes, the page object is zenPage:
18.3.2.3 %this, this, and zenThis
Zen offers special variables to represent a Zen object (component or page) on the client and server
sides:
366 Using Zen

Zen Page Classes
• In ObjectScript or Basic code that runs on the server side, the object itself is %this:
Set %this.Name = pSource.Name
• In Zen runtime expressions, the object itself is %this:
Item #(%this.tuple)#: #(%query.Title)#
• In JavaScript methods that run on the client side, the object itself is this:
var out = this.getComponentById('events');
• In JavaScript expressions that are values of XML attributes, the object itself is zenThis:
onchange="zenPage.changeLayout('svgFrame',zenThis.getValue());"
18.3.2.4 zenEvent
Suppose you have a JavaScript expression as the value of an XML event handler attribute, such as
onchange in the following example:
The zenEvent special variable refers to the current JavaScript Event object that describes the event.
zenEvent provides a browser-neutral way to get access to the current event (such as a mouse click).
In the example above, onchange references the notifyOnChange method. The client-side method
notifyOnChange can reference the zenEvent special variable inside its JavaScript code.
zenEvent only works inside client-side JavaScript methods that are referenced from XML event
handler attributes, as is the case for , onchange, and notifyOnChange above.
18.3.2.5 %zenContext
When any activity on the server is being initiated by Zen, the server-side special variable %zenContext
tells you which type of activity it is. %zenContext is a string. If %zenContext has the value:
• page, Zen is serving the page in response to an HTTP request
• submit, Zen is processing a submit request
• method, Zen is processing a hyperevent
Sometimes it is possible to have trouble with code being executed at compile time. To detect this,
check for:
Using Zen 367

Zen Application Programming
$G(%zenContent)==""
There is no client-side equivalent for %zenContext.
18.3.3 Zen Runtime Expressions
Rather than always providing static information in a Zen page description, sometimes it is useful for
the page running on the client to be able to invoke runtime expressions that execute on the server. For
example, perhaps the caption text for a button needs to be different depending on the identity of the
currently logged-in user, which can only be determined from the server at runtime. Various runtime
values can play a part in these decisions. For this reason, Zen provides a way for client-side application
code to contain expressions that are resolved only on the server, and only at runtime.
Important:
The syntax rules for Zen runtime expressions are extremely specific.
A runtime expression is enclosed within #()# and looks something like this:
Where myProperty has a specific value on the server at runtime.
Zen runtime expression syntax can be used, with restrictions, in the following contexts only:
• XML that is embedded within an XData block (certain XML elements and attributes only)
• A server-side Caché ObjectScript method or ZenMethod (but not a JavaScript method)
• JavaScript that is embedded within a &js block in a ZenMethod
• A JavaScript expression provided as the value of an XML attribute such as onclick
• HTML that is embedded within an &html block in a server-side method
The following items cannot appear within the #()# delimiters of a Zen runtime expression:
• Calls to macros, such as $$$Text
• JavaScript expressions
• ObjectScript expressions, unless the runtime expression appears inside a server-side ObjectScript
method or ZenMethod, as shown later in this topic
18.3.3.1 Runtime Expressions in XML
Zen runtime expressions can be used within a Zen class XData block, but only the values of specific
XML elements and attributes can contain Zen runtime expressions. One such example is the
caption attribute:
368 Using Zen

Of all the possible attributes, only caption, value, and hidden support Zen runtime expressions.
The value of onclick in the above example does contain a Zen runtime expression, but this is acceptable
because the value of onclick is a JavaScript expression, which may contain #()# syntax. Refer to the
restrictions listed in the topic above.
XML elements and attributes that support Zen runtime expressions are clearly identified throughout
this book; you may find them by searching for the #()# string in the book text.
Another way to tell that an XML attribute supports runtime expressions is to consult the Caché class
documentation to see if the corresponding property has the datatype parameter ZENEXPRESSION
set to 1 (true).
You cannot simply set a property to have ZENEXPRESSION=1 to cause the property to support runtime
expressions. Built-in Zen component classes provide ZENEXPRESSION=1 to indicate that the property
supports runtime expressions, not to enable it to do so.
On the other hand, when you create your own component subclasses as instructed in the Custom
Components chapter, Datatype Parameters topic, you can set ZENEXPRESSION=1 for properties in
those subclasses. It must be a property of a custom component class and not a property of one of the
built-in Zen component classes.
A significant number of XML attributes support Zen runtime expressions, but only one XML element
supports them. This is the component, which may contain literal text and #()# runtime
expressions. For example:
Item #(%this.tuple)#: #(%query.Title)#
18.3.3.2 Runtime Expressions and Special Variables
A runtime expression may use the server-side special variables listed in the topic Zen Special Variables,
above. Zen runtime expressions support the following server-side special variables only:
• %composite
• %page
• %query
• %session
• %this
• %url
Zen Page Classes
By limiting expressions to a pre-defined set of object property values, the page developer maintains
control over which server-side values the client can see. Otherwise it would be possible for a page to
execute code that the page developer did not intend, and thus present a security risk.
Using Zen 369

Zen Application Programming
18.3.3.3 Runtime Expressions in Server-Side Methods
The following is an example of a server-side method with an &html block, in which a runtime
expression invokes the ObjectScript function $ZCONVERT ($ZCVT) to help it to write out the elements
of a bulleted list:
Method %DrawHTML()
{
&html
Write $ZCVT(..text,"O","HTML")
}
#; bullets
Set tCount = ..bullets.Count()
If (tCount > 0) {
&html
For n = 1:1:tCount {
Set tBullet = ..bullets.GetAt(n)
&html
}
&html
}
}
&html
The following is an example of a ZenMethod with a &js block, in which a runtime expression
passes the server-side identifier pIndex to JavaScript code that needs to execute on the client. In a later
&js block, runtime expressions invoke the ObjectScript function $RANDOM ($R) to produce
drawing coordinates, and provide CSS style statements to configure a graphical object:
ClassMethod GetSVGContents(pIndex As %Integer) [ ZenMethod ]
{
#; get the svg component
&js
}
#; lines
For i=1:1:30 {
&js<
var line = svg.document.createElementNS(SVGNS,'circle');
//line.setAttribute('x1',200);
//line.setAttribute('y1',100);
line.setAttribute('r',5);
line.setAttribute('cx',#(10+$Random(380))#);
line.setAttribute('cy',#(10+$Random(180))#);
line.setAttribute('style',
'#("fill: yellow; stroke: black; stroke-width: 2;")#');
svg.svgGroup.appendChild(line);
>
}
Quit
The following is an example of a ZenMethod that uses a &js block, in which runtime expressions
call server-side methods of the server-side %page object to compose a JavaScript alert message:
370 Using Zen

Zen Page Classes
Method serverInstanceMethod() [ ZenMethod ]
{
#; The server returns the following JavaScript statements to
#; client for execution.
&js<
alert('Server instance method');
alert('page: #(%page)#');
alert('child 1: #(%page.children.GetAt(1))#');
alert('title by id: #(%page.%GetComponentById("title"))#');
alert('menu by id: #(%page.%GetComponentById("menu"))#');
>
}
Note:
The samples in this topic demonstrate how runtime expressions can be used in a server-side
method. In a client-side JavaScript method, you can achieve similar results without using
runtime expressions.
18.3.4 Zen Page Properties
Any property defined within a page class whose name does not start with % becomes a property of the
client-side page object. These client-side properties are initialized to the values they held on the server
side, immediately before the page’s %DrawHTML method was invoked.
You cannot set the value of any properties that you add to your page class by using the element
within the XData Contents block. Only properties defined by the parent class %ZEN.Component.page
are available in XData Contents.
You can provide initial values for page class properties in one of the following ways:
• Define an InitialExpression for the property, as in:
Property dayList As %ZEN.Datatype.caption
[ InitialExpression = "Sun,Mon,Tue,Wed,Thu,Fri,Sat" ];
• Set the property in the %OnCreatePage or %OnAfterCreatePage callback methods.
You can also set a page property’s value at runtime within any other method; these are just ways to
initialize them.
18.3.5 Zen Utility Methods
The %ZEN.Utils class includes a number of utility methods for performing various common functions.
Most of these classes are for internal use by the Zen library.
ZENTest.LogPage in the SAMPLES namespace is an example of a page class that uses some of these
utility methods to respond to the user’s selection of whether or not to enable logging for the application.
The page class provides:
• A definition for the event log display, plus the following :
Using Zen 371

Zen Application Programming
• This client-side method:
Method enabledChange(cb) [ Language = javascript ]
{
this.EnableLog(cb.getValue()==1 true : false);
}
this.refreshLog();
• And this Zen method:
ClassMethod EnableLog(flag As %Boolean = "") As %Boolean [ ZenMethod ]
{
If (flag = "") {
Set flag = ##class(%ZEN.Utils).%LoggingEnabled()
}
If (flag) {
Do ##class(%ZEN.Utils).%StartLog()
}
Else {
Do ##class(%ZEN.Utils).%StopLog()
}
Quit 1
}
The result is as follows:
Sample Log of Zen Events
To read more about %ZEN.Utils, start the Caché online documentation system and choose Class Reference
Documentation for the %SYS namespace.
18.3.6 Client-Side Functions and Variables
All page classes have the following JavaScript utility functions and variables available to them:
372 Using Zen

Zen Page Classes
Client-Side Functions and Variables
Function or Variable
zenLaunchPopupWindow
zenLink
zenSynchronousMode
Description
A function that launches the referenced HTML content as
a popup window. See the chapter Popup Windows and
Dialogs, topic Popup Windows.
A function that escapes any special characters found in a
string intended to be used as a URI. See the chapter Popup
Windows and Dialogs, topic Popup Windows.
A flag with the value true (all methods will be executed
synchronously regardless of whether or not they have return
values) or false (methods will be synchronous if they have
a return value, asynchronous otherwise). See Synchronous
and Asynchronous Methods, later in this chapter.
18.3.7 Zen Page URI Parameters
Sometimes it is useful to pass values to a page via URI parameters.
There is a datatype parameter, ZENURL, that can be applied to properties of page classes. The presence
of this parameter causes the page to generate code that will initialize the value of the datatype to the
value of a URI parameter.
For example, in a page class you can define a property:
Property employeeID As %ZEN.Datatype.string(ZENURL="ID");
When this page is requested, the value of the URI parameter, ID, will be assigned to the employeeID
property. For example, this URI:
MyApp.MyPage.clsID=48
Will cause the following code to run:
Set %page.employeeID = $GET(%request.Data("ID",1))
If the URI parameter assigned to a property does not pass the property’s validation test for any reason,
such as a value greater than the property’s MAXVAL, the page is not displayed and an error message
is displayed instead.
Using Zen 373

Zen Application Programming
18.3.8 Zen Page Event Handling
Many components define event handlers such as onclick, onchange, etc. See the description of any
Zen control component, such as , , or . Also see the description of zenEvent
in the topic Zen Special Variables, above.
While a page is being displayed, Zen traps all events until the page finished building. This is to prevent
the user from clicking on an element before the browser has finished building the zenPage object on
the client side.
18.4 Zen Properties on Client and Server
On the server side, you can get and set values of class properties directly, using normal dot syntax.
For example:
Method serverInstanceMethodCreate() [ ZenMethod ]
{
#; create
Set group = %page.%GetComponentById("group")
If '$IsObject(group) {
&js
Quit
}
Set count = group.children.Count()
}
Set cal = ##class(%ZEN.Component.calendar).%New()
Set cal.id = "NewCal"_count
Do group.%AddChild(cal)
Set btn = ##class(%ZEN.Component.button).%New()
Set btn.id = "NewBtn"_count
Set btn.caption = "New Button"
Do group.%AddChild(btn)
Set btn = ##class(%ZEN.Component.text).%New()
Set btn.label = "Hey"
Do group.%AddChild(btn)
On the client side, you cannot access any property values directly. You must use the get and set
methods provided in the component classes. For single-valued properties, use the getProperty and
setProperty methods. For example:
var index = table.getProperty('selectedIndex');
Or:
var svg = zenPage.getComponentById('svgFrame');
svg.setProperty('layout','');
svg.setProperty('editMode','drag');
374 Using Zen

Zen Methods
Important:
Do not confuse getProperty and setProperty with the getValue and setValue
methods, which get and set the value of a control component, and do not apply to any
other component property.
18.5 Zen Methods
The following table outlines the possibilities for different types of method in a Zen page class.
Page Class Method Conventions
Callable
From
Runs On
Class
Scope
Timing
Code
Language
Keyword
Naming
Convention
Client
Client
Instance
—
JavaScript
Language
=
JavaScript
myMethod
Client
Server
(Can send
back code
that runs on
the client)
Instance
Class
Async
Sync
Async
Sync
ObjectScript
or Basic
ZenMethod
MyMethod
Server
Server
Instance
Class
—
ObjectScript
or Basic
—
%MyMethod
Any method defined within a page class whose name does not start with % becomes a method of the
client-side page object. Any method whose name starts with % is server-only.
Any instance method defined as having [Language = javascript] automatically becomes a
client-side instance method of the client page object. When called, it executes within the browser.
Any method defined with its [ZenMethod] keyword set automatically becomes a client-side instance
method of the client page object. When the client-side method is called, the server-side version of the
method is executed. Any context needed to run the server method is automatically provided. An instance
method runs as an instance method on the server; the serialized state of its client object is shipped to
the server and instantiated. A class method runs as a class method on the server (but is called as an
instance method on the client).
Using Zen 375

Zen Application Programming
18.5.1 Synchronous and Asynchronous Methods
Server-side methods can be called synchronously or asynchronously. This happens very smoothly and
automatically as follows: If a server-side method has a return type, it is called synchronously, and its
return value is returned to the client. If the method has no return type, it is called asynchronously; the
client does not wait for the return value.
The CSP hyper-event logic handles all the details of this, so (unlike AJAX) you do not need to provide
any additional application logic to enable asynchronous calls. In this way, Zen takes the next step past
most AJAX frameworks.
The main advantages of asynchronous methods are:
• The browser can keep working while the server request is processed
• You can call a server method, modify the client (say by displaying a message), and the server
logic can update this message when it completes
Some of the Zen components take advantage of asynchronous methods. For example, the
control uses an asynchronous method to execute a server-side query. This allows the
to display a loading... message while the query is running. This message is replaced when the
response from the server arrives, so the user does not see the message if the query is quick.
Zen offers a client-side flag zenSynchronousMode that you can set to true to force all methods to
be executed synchronously, regardless of their return values. When false, methods are synchronous
if they have a return value, asynchronous otherwise. When you want to set this flag:
1. First, get and store the current value of zenSynchronousMode.
2. Then, set the flag as you wish.
3. When your processing is done, restore the previous value of zenSynchronousMode.
In addition to this convention, the client-side refreshContents method (available for every component)
offers a single optional argument whose value can be true or false. This flag specifies whether the
client should refresh the component synchronously (true) or asynchronously (false). If this argument
is omitted, the default is false.
18.5.2 Server-Side Callback Methods
Callback methods are user-written methods within a Caché class that are triggered, not by a method
call, but by specific system events. To distinguish callback methods, Caché developers give them
names of the following form:
%OnEvent
376 Using Zen

where the keyword Event identifies the Caché system event that triggers the callback. If an event
supports a callback method, the method controlling the event automatically executes the callback
method, if it exists within the class.
You must never execute callback methods by calling them explicitly. Instead, provide an implementation
of the method within your class so that Caché can invoke the method automatically when the time is
right. If you want your class to do nothing in response to an event, omit any implementation of the
corresponding callback method.
When an HTML page derived from %ZEN.Component.page is drawn, it invokes a number of callback
methods that are executed on the server before the page content is sent to the browser. The following
table lists these methods. A page class can override these methods to control the behavior of the page.
Page Class Server-side Callback Methods
Zen Methods
Callback Method
%OnBeforeCreatePage
%OnCreatePage
%OnAfterCreatePage
%OnDrawHTMLHead
%OnDrawHTMLBody
Description
This class method is called just before the server-side page
object is created.
This instance method is called just after the server-side page
object is created but before any of its child components are
created.
This instance method is called after the server-side page object
and all of its pre-defined child components are created. A
subclass can override this method to add, remove, or modify
items within the page object model, or to provide values for
controls.
This instance method is called when the HTML for the page is
being rendered just before the end of the HTML HEAD section
of the page. This provides a way to inject addition content into
the HEAD section of a page should this ever be necessary.
This instance method is called when the HTML for the page is
being rendered close to the start of the HTML BODY section
of the page (before any child components are rendered). This
provides a way to inject additional content into the BODY
section of a page should this ever be necessary.
For details about each method see the class documentation for %ZEN.Component.abstractPage. That
is, start the Caché online documentation system, choose Class Reference Documentation for the %SYS
namespace, and navigate to %ZEN.Component.abstractPage.
Using Zen 377

Zen Application Programming
18.5.3 Server-Only Methods
The %ZEN.Component.page class contains a number of server-side methods that can be useful when
working with the page object tree on the server or for processing form submits. The following table
lists these methods.
Page Class Server Methods
Method
%GetComponent
%GetComponentById
%GetComponentByName
%GetValueById
%GetValueByName
%SetErrorById
%SetErrorByName
%SetValueById
%SetValueByName
%SetValuesByName
Description
Find a component object given its system-assigned index
number.
Find a component object given its user-assigned id value.
Find a control object given its user-assigned control name.
Get the value of a control object given its user-assigned
control id value.
Get the value of a control object given its user-assigned
control name.
Set the value of a component error message given its
user-assigned id value.
Set the value of a component error message given its
user-assigned control name.
Set the value of a control object given its user-assigned
control id value.
Set the value of a control object given its user-assigned
control name.
Set the values of a set of control objects given an array of
values subscripted by user-assigned control name.
For details about each method see the class documentation for %ZEN.Component.abstractPage.
18.5.4 Type Conversion for Server-Side Methods
The mechanism for handling type conversions when invoking a server-side method works as follows:
• When calling a server-side method, any %ZEN.Datatype.boolean arguments are converted from
client-side true/false to server-side 1/0.
• If a server method has a %ZEN.Datatype.boolean return type, its return value are converted to a
client-side true/false value.
378 Using Zen

Zen Methods
• If a server method has a numeric return type, its return value are converted to a client-side numeric
value (unless it the method returns "").
• Methods that take object-valued arguments behave well if the argument is missing or null.
18.5.5 Background Tasks on the Server
There is a mechanism for starting a background job from a Zen page and tracking its progress within
the page. This can be useful for cases where a page needs to initiate a long-running task and wants to
provide some degree of feedback to the client while waiting for that task to complete.
A Zen page class has a backgroundTimerInterval property. This is the interval, in milliseconds, at which
timer events are fired to check on the status of background tasks started by this page. The default is
1000.
Two methods support background tasks; both are available in any class that inherits from
%ZEN.Component.page:
• %RunBackgroundMethod starts a background job to run a class method of this Zen page.
%RunBackgroundMethod returns a %Status value and may have one or more arguments:
- The first argument, a %String, is the name of the class method to run.
- Depending on the method signature, a variable number of arguments may follow; these are
the arguments of the method named in the first argument.
Zen monitors only one background task at a time. If %RunBackgroundMethod is called while
a previous background task is running, the new method becomes the current monitored task. The
previous task runs to completion, but the client is not notified about it.
• %SetBackgroundMethodStatus can be called from within a method that is running in the
background, to update its own status information. %SetBackgroundMethodStatus has no return
value and takes two arguments:
- A %String specifies the status message that will be seen by the client page. The string may
be empty.
- An optional %Float value indicates how much of the background task is complete (as a percentage
between 0 and 100). A client page can use this information to display progress to the
user.
18.5.6 Client-Side Page Callback Methods
The client-side page object zenPage inherits a number of callback methods. These are JavaScript
methods which, if defined, are called in response to specific events. The following table lists these
methods.
Using Zen 379

Zen Application Programming
Page Class Client-side Callback Methods
Callback Method
onloadHandler
onpopupAction
onresizeHandler
onunloadHandler
Description
This client-side page method, if defined, is called when the client
page is finished loading (i.e. it is called by the page’s HTML onload
event).
This client-side page method, if defined, is called when a popup
window, launched by this page, is completed.
This client-side page method, if defined, is called when the client
page is resized (it is called by the page’s HTML onresize event).
This client-side page method, if defined, is called when the client
page is about to unload (it is called by the page’s HTML onunload
event).
18.5.7 Client-Side Page Methods
The client-side page object zenPage inherits a number of JavaScript methods that can be useful in
client-side programming. The following table lists these methods.
Page Class Client-side Methods
Method
cancelPopup
createComponent
createComponentNS
endModal
getComponent
getComponentById
startModal
Description
(Popup windows only). Close the current popup window with no
further action.
Create a new component on the page (by component name).
Create a new component on the page (by component name and
namespace).
Hide the current modalGroup, if there is one.
Find a component on the page given its system-assigned index
number.
Find a component on the page given its user-assigned id value.
Make a modalGroup visible. Alternately, use the show method
of the modalGroup.
380 Using Zen

Zen Page Contents
18.5.8 Client-Side Component Methods
Every component on the page (including the page itself) inherits a number of useful JavaScript methods.
The following table lists these methods. Specific components also have specialized methods not listed
in the table.
Page Class Client-side Component Methods
Method
findElement
getEnclosingDiv
getHidden
getProperty
getSettings
getValue
invokeSuper
isOfType
refreshContents
setHidden
setProperty
setValue
Description
Find a named HTML element associated with a specific component.
Get the HTML div element used to enclose a specific component.
Return whether a component is hidden (or displayed).
Return a named property of a component.
Get the set of named properties that can be observed and modified
using getProperty and setProperty.
(Subclasses of control only). Get the value of a control. This is
equivalent to calling getProperty('value').
Invoke the super class implementation of the current component
method.
Tests if a component is a subclass of (is a type of) another component.
Make a request to the server to regenerate the HTML that defines a
component. For tablePane components, use executeQuery instead.
Sets whether a component is hidden (or displayed).
Sets the value of a named property for a component.
(Subclasses of control only). Set the value of a control.
18.6 Zen Page Contents
This topic explains how to specify the component object model for a Zen page using XML, programmatically,
or with a combination of both.
The visible contents of the page are defined by a set of Zen components that belong to the page. This
set of components is typically defined within an XML block named XData Contents. It is also possible
to define or modify this set of components by overriding the %OnAfterCreatePage callback method.
Using Zen 381

Zen Application Programming
18.6.1 Defining Page Contents Using XML
A Zen page class can provide an XData Contents block (an XML document embedded within the
class definition) that defines the set of components that will be used for the page. It is possible to define
the contents of a page programmatically, but in most cases an XML block is more convenient.
The following XData Contents block defines a simple page object containing a single button
component:
XData Contents [XMLNamespace="http://www.intersystems.com/zen"]
{
}
The XData Contents block is not processed at runtime. Instead, at compile time the class compiler
uses the XData Contents information to generate a method called %CreatePage. You can view
(but not modify) this method if you like by compiling a page class and then using the View Other
command in Studio to see the code generated for the page class. The %CreatePage method is called
at runtime to create the contents of the page component model.
Zen Layout and the chapters that follow it describe XData Contents in detail.
18.6.2 XML Namespaces
InterSystems recommends that you include an XML namespace declaration within an XData Contents
definition. You do this by providing the xmlns attribute with the element. For example:
As you add custom components, chances increase that there will be conflicts between components in
different namespaces. This is also true for other Zen elements such as and . Adding
the xmlns attribute to the prevents this.
18.6.3 Defining Page Contents Programmatically
If you need to programmatically modify the contents of a page before displaying it, add code to the
%OnAfterCreatePage callback method to do so. You can find a component on the page using the
%GetComponentById method, then set component properties directly. Then you must add the new
component to a group or page using %AddChild. For example:
382 Using Zen

Zen Page Contents
Method %OnAfterCreatePage() As %Status
{
Set tGroup = ##class(%ZEN.Component.group).%New()
Do %page.%AddChild(tGroup)
Set tBtn = ##class(%ZEN.Component.button).%New()
Set tBtn.caption = "Button 1"
Do tGroup.%AddChild(tBtn)
Set tBtn = ##class(%ZEN.Component.button).%New()
Set tBtn.caption = "Button 2"
Do tGroup.%AddChild(tBtn)
}
Quit $$$OK
Any text you add for captions or other labels is not magically localized as it is when you add a caption
attribute using XML. If you want localized captions, your %OnAfterCreatePage methods must call
the $$$Text localization macros. This is not shown in the example above.
If the component is not visible (such as ) you may add it to a page using %AddComponent
instead of %AddChild. For components that are visible, the methods %AddChildBefore and
%AddChildAfter are also available. These methods have a second parameter that identifies the
existing, sibling component.
If you need to add components to a page programmatically, based on user interactions, you can do this
as well. The SAMPLES namespace class ZENTest.DynamicComponentsTest provides useful examples
of doing this from the client or server sides in response to user input. Remember that you need to both
create the component and add it as a child of the page before the user can see it. A separate set of
methods exists for doing this on the server and on the client (see the lists in previous topics). As another
example of dynamically adding components to a page, see the Sample Development Project, below.
One of the best ways to get a sense of how pages are put together programmatically is to look at the
generated code for the %CreatePage method in any Zen page class that uses XData Contents to define
page contents. To do this:
1. Open the page class in Studio.
2.
Choose View > View Other or Ctrl-Shift-V or the
icon.
3. Select the file marked “1” and click Open.
4. Search for this string: %CreatePage
5. Scroll through the method to see how components are added to the page.
18.6.4 Zen Layout Handler
The actual work of laying out a group component’s children is handled by the %ZEN.LayoutManager
class. It is possible to implement layout strategies in addition to those normally provided. If you wish
to serve the page using your own, custom layout handler code, you can.
Using Zen 383

Zen Application Programming
Zen provides a simple, built-in layout strategy with the intention of making rapid application development
easier. Components start at top left of the page and work their way to the right and bottom. You
can achieve a lot, very quickly, by manipulating nests of vertical and horizontal groups.
There may be cases when your layout needs finer control. If so, ultimately it might suit your project
best to develop your own layout handler for use with Zen. For these cases, Zen provides an
onlayoutHandler callback method. This client-side method, if defined, is called when a page is first
displayed and whenever the size of the page is changed thereafter. This provides a way to define code
that will adjust the size and position of components whenever the size of the containing page is changed.
For example:
Method onlayoutHandler(load) [ Language = javascript ]
{
// adjust size of lookout menu
var menu = zenPage.getComponentById('lookout');
zenASSERT(menu,'Unable to find menu',arguments);
}
// find div for titleBox & mainMenu
var title = zenPage.getComponentById('titleBox');
var divTitle = title.getEnclosingDiv();
// find height of window
var winHeight = zenGetWindowHeight();
// adjust size of menu
var sz =
winHeight - (parseInt(divTitle.offsetHeight)) - 20;
menu.setSize(null,sz);
18.7 Sample Development Project
The chapter Zen Layout explains how to use template pages and panes to organize layout and style
for a Zen application. This topic traces an example that uses composites and dynamic page generation
to organize behavior for a Zen application. This example uses Zen to add new order entry module
pages to an existing Weblink application. Constraints are as follows:
• You need to be able to call the new pages from within your existing application.
• You do not have the luxury of rewriting the whole application, so you want to evolve into Zen
one module at a time.
• Your order entry page needs to have flexible content. That is, you need to be able to easily update
portions of the page depending on the context.
• Your order entry page is so big and complex, you want to only build what you need when the
page is first loaded and then fill in some empty segments on the fly.
• Ideally, you want to break up the page into segments that can be written simultaneously by different
developers.
384 Using Zen

Sample Development Project
The following example addresses these constraints. It purposely does not address layout or style but
focuses on behavior.
• The following class provides the main page. It defines a set of named groups. Each group is populated
with components from the server in response to user events. The main page also defines
an API (set of methods) that the various components can call to work with the page. For example,
there is a method that loads a new component into one of the groups on the page. Note the
parameter USERPACKAGES, the groups g1 and g2, and the method loadForm, which adds a
specific type of form to the page based on the parameters provided to it.
• The contents of each group is defined using a composite component. A composite is a custom
component that you build by grouping one or more built-in Zen components in a specific way.
For full details, see the chapter Custom Components, topic Building Composite Components.
Composites can be developed individually by different developers; this satisfies the project constraints.
In the sample code, there are four such composites: searchForm is the starting form that
drives the loading of other forms. formOne, formTwo, and formThree are sample forms.
Using Zen 385

Zen Application Programming
Class TestMe.MainPage Extends %ZEN.Component.page
{
/// Comma-separated list of User class packages whose HTML class
/// and style definitions are in pre-generated include files.
Parameter USERPACKAGES = "TestMe.Components";
/// Class name of application this page belongs to.
Parameter APPLICATION;
/// Displayed name of this page.
Parameter PAGENAME;
/// Domain used for localization.
Parameter DOMAIN;
/// This Style block contains page-specific CSS style definitions.
XData Style
{
/* style for title bar */
#title {
background: #C5D6D6;
color: black;
font-family: Verdana;
font-size: 1.5em;
font-weight: bold;
padding: 5px;
border-bottom: 1px solid black;
text-align: center;
}
}
/* container style for group g1 */
#g1 {
border: 1px solid black;
background: #DDEEFF;
}
/* container style for group g2 */
#g2 {
border: 1px solid black;
background: #FFEEDD;
}
/// This XML block defines the contents of this page.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
TestMe Test Page
}
/// Create a form (via a composite element) and place it into the group with
/// the id groupId. formClass is the name of the composite element
386 Using Zen

Sample Development Project
/// containing the form. formId is the id applied to the form.
Method loadForm(formClass, formId, groupId) [ Language = javascript ]
{
try {
// if there is already a form, get rid of it
var comp = zenPage.getComponentById(formId);
if (comp) {
zenPage.deleteComponent(comp);
}
}
}
var group = zenPage.getComponentById(groupId);
var form = zenPage.createComponentNS('TestMe',formClass);
form.setProperty('id',formId);
group.addChild(form);
group.refreshContents(true);
}
catch(ex) {
zenExceptionHandler(ex,arguments);
}
Some important things to notice about the TestMe.MainPage class:
• The parameter USERPACKAGES is set as follows:
Parameter USERPACKAGES = "TestMe.Components";
This tells the page to use the generated include files for the components in this package. This is
important as we are creating things on-the-fly and we want to ensure that the relevant JS object
are available.
• The XData Contents block for the page provides a reference to the XML namespace for the new
composite components:
xmlns:testme="TestMe"
• XData Contents places the searchForm component on the page as follows:
When the user presses one of the buttons on the searchForm, it invokes the loadForm method on
the Main page. This deletes the current form (by id) and loads a new form (it does not actually
have to be a form, that is just what we have used as an example).
Now take a look at the components for the example. As suggested in Building Composite Components,
all of these composite component classes are placed together in their own package, TestMe.Components.
The reason for this is that Zen will automatically generate JS and CSS header files for components in
a given package. By placing these components in a package you can exploit this feature by setting the
parameter USERPACKAGES to the package name, on the main page, as shown above:
Parameter USERPACKAGES = "TestMe.Components";
The composites also use their own XML namespace to avoid conflict with other components.
The composite component classes are as follows:
Using Zen 387

Zen Application Programming
• searchForm — the starting form that drives the loading of other forms:
Class TestMe.Components.searchForm Extends %ZEN.Component.composite
{
/// This is the XML namespace for this component.
Parameter NAMESPACE = "TestMe";
/// This Style block contains component-specific CSS style definitions.
XData Style
{
}
}
/// Contents of this composite component.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
}
/// User click on form 1 button.
Method btnForm1() [ Language = javascript ]
{
// Notify the page that the search button was pressed
// and that a new form should be loaded.
zenPage.loadForm('formOne','form1','g1');
}
/// User click on form 2 button.
Method btnForm2() [ Language = javascript ]
{
// replace contents of 'g1' with formTwo
zenPage.loadForm('formTwo','form1','g1');
}
/// User click on form 3 button.
Method btnForm3() [ Language = javascript ]
{
// replace contents of 'g2' with formTwo
zenPage.loadForm('formTwo','form2','g2');
}
/// User click on form 4 button.
Method btnForm4() [ Language = javascript ]
{
// replace contents of 'g2' with formThree
zenPage.loadForm('formThree','form2','g2');
}
Every component that is part of a composite can refer to its containing composite group via its
composite property. You can see this in the syntax used to invoke client-side methods defined in
the composite class, when the user clicks a button on this form:
onclick="zenPage.getComponent(#(..index)#).btnForm1();"
• formOne — a sample form:
388 Using Zen

Class TestMe.Components.formOne Extends %ZEN.Component.composite
{
/// This is the XML namespace for this component.
Parameter NAMESPACE = "TestMe";
Sample Development Project
/// This Style block contains component-specific CSS style definitions.
XData Style
{
}
/// Contents of this composite component.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
}
}
• formTwo — another sample form:
Class TestMe.Components.formTwo Extends %ZEN.Component.composite
{
/// This is the XML namespace for this component.
Parameter NAMESPACE = "TestMe";
/// This Style block contains component-specific CSS style definitions.
XData Style
{
}
/// Contents of this composite component.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
}
}
• formThree — yet another sample form:
Using Zen 389

Zen Application Programming
Class TestMe.Components.formThree Extends %ZEN.Component.composite
{
/// This is the XML namespace for this component.
Parameter NAMESPACE = "TestMe";
/// This Style block contains component-specific CSS style definitions.
XData Style
{
}
/// Contents of this composite component.
XData Contents [ XMLNamespace = "http://www.intersystems.com/zen" ]
{
}
/// colorChange
Method colorChange(color) [ Language = javascript ]
{
alert('You have selected: ' + color);
}
}
390 Using Zen

19
Zen Security
You can provide application-level security for Zen using CSP application settings. See the Caché
Security Administration Guide, chapter Assets and Resources, topic Application Resources and Their
Privileges.
There are additional techniques for controlling access to pages and components within a Zen application.
19.1 Controlling Access to Applications
By default, when a user starts your Zen application it prompts the user to log in by displaying the
standard Caché username and password dialog box. If you wish your application to present a custom
login form, you must create and configure this form as follows:
1. Create a new Zen page class.
2. Within XData Contents, provide a whose nextPage value is the first Zen page that you
want the user to see, upon successfully logging in:
3. Make sure that, at minimum, this contains the following controls:
• for the username
• for the password
Ensure that you provide a name attribute for each of these controls and that the corresponding
name values are exactly as shown above: "CacheUserName" and "CachePassword". You
Using Zen 391

Zen Security
may provide other attributes for the controls as desired; a label is useful for each control so that
the user knows what to enter.
4. Provide a button. Your minimal user login form now looks like this:
5. Define other characteristics of the form as desired.
6. Start the Caché System Management Portal.
7. Navigate to the [Home] > [Security Management] > [CSP Applications] page.
8. Find your Zen application in the list and click its Edit button. The [Home] > [Security Management]
> [CSP Applications] > [Edit CSP Application] page displays.
9. In the Login Page field, enter the pathname of your new Zen page class. This pathname is relative
to the Caché installation directory, for example:
/csp/myApp/myLoginPage.cls
10. Click Save.
19.2 Controlling Access to Pages
Each Zen page has a class parameter called RESOURCE that, if defined, provides the name of a system
Resource for which the current user must hold USE privileges in order to view this page or to invoke
any of its server-side methods from the client.
19.3 Controlling Access to Components
Each Zen component (subclass of %ZEN.Component.component) has a server-only property called
%resource that determines whether or not this component should be added to the set of page components.
The component projects this property to XML as an attribute called resource. You can use this resource
when adding a component to XData Contents. For example:
392 Using Zen

Controlling Access to Components
If a resource value is specified, the current user must hold USE privileges on this resource or the
component will not be added to the set of page components when the user attempts to display the page.
This property is not available from the client.
Using Zen 393

20
Zen Localization
When you localize the text for an application, you create an inventory of text strings in one language,
then establish a convention for substituting translated versions of these messages when the application
locale is different. Most of the information you need to localize Zen pages can be found in the book
Using Caché Server Pages, chapter Localizing Text in a CSP Application. Everything described in
that chapter for development of CSP pages also applies to Zen pages.
There are a few additional details that apply only to Zen. This chapter:
• Summarizes the CSP information
• Describes Zen extensions to CSP techniques
20.1 CSP Localization
Important:
This topic briefly outlines material from the Localizing Text in a CSP Application
chapter in Using Caché Server Pages (CSP). If you are new to CSP, please read the
other chapter before continuing in this book.
For a simple demonstration of a localized CSP application, enter the following URI while Caché is
running. Substitute your Caché Web server port number for 57772:
http://localhost:57772/csp/samples/language.csp
20.1.1 Localization Practices
Caché supports the following process for localizing CSP application text:
1. Developers determine where text strings are displayed in the application user interface.
Using Zen 395

Zen Localization
2. Developers create an XML message file that contains text strings in the original language.
3. Developers import the XML into a Caché namespace.
This adds new entries to the Message Dictionary in that namespace.
4. Developers give the XML to a team of translators.
5. Translators produce a new XML message file by substituting translated text for the original.
6. Developers import the new XML into a Caché namespace.
Translated and original texts coexist in the Message Dictionary.
7. At runtime, the application chooses which text to display based on the browser default language.
20.1.2 Message Dictionary
A Message Dictionary is a simple database of text strings organized by domain name, language name,
and message ID:
• The text of each message is a string of up to 32K characters. A message may consist solely of
text, or it may also contain one or more parameters specified by %1, %2, etc.
• A domain name is any arbitrary string. It identifies a group of related text items, such as all
messages for a specific application or page.
• A language name is an all-lowercase language tag that conforms to RFC1766. It consists of one
or more parts: a primary language tag (such as en or ja) optionally followed by a hyphen (-) and
a secondary language tag (en-gb or ja-jp).
• A message ID is any arbitrary string; it uniquely identifies a message. The message ID only needs
to be unique within a domain. You may assign a message ID or allow Caché to assign one,
depending on the conventions you use to create the message.
Each user-defined namespace in Caché stores its Message Dictionary in a subscripted global called
^CacheMsg. The order of subscripts in ^CacheMsg is domain, language, and message ID.
20.1.3 $$$Text Macros
The easiest way to create a Message Dictionary is to automatically generate Message Dictionary entries
at compile time, by seeding the CSP class code with $$$Text macro calls. $$$Text automatically creates
the message at compile time and generates the code that retrieves the message at runtime, as this topic
explains.
When it comes time to translate the application messages into another language, you can export the
full list of messages for the original language out of the Message Dictionary by running an Export
396 Using Zen

command. This generates a complete XML message file in the original language. See Managing a
Message Dictionary in Using Caché Server Pages (CSP).
The return value of a $$$Text macro is a %String. The correct $$$Text macro to use depends on the
format you need for this output string:
• $$$Text
• $$$TextJS (applies JavaScript escaping to the $$$Text result)
• $$$TextHTML (applies HTML escaping to the $$$Text result)
The %String returned by $$$Text may be assigned to a variable, which you can use to represent the
message in subsequent calls. For example:
Set tmsg = $$$TextJS("Error saving production")
&js
Or, you can simply insert a $$$Text macro anywhere you need a string:
&js
20.1.3.1 $$$Text Arguments
CSP Localization
$$$Text has the arguments text, domain, and language as described in the following table. Only the
first argument, text, is required.
Using Zen 397

Zen Localization
Argument
text
Description
Non-empty string. text must be a literal string. It cannot use any type of
expression syntax. The format used for text may be:
"actualText"
Or:
"@textId@actualText"
Where textId is a message ID and actualText is the text of the message.
The string actualText may consist of any of the following items, separately
or in combination:
• Simple text, as permitted by the file format
• Substitution arguments %1, %2, %3, or %4
• HTML formatting
• A string expression in Caché ObjectScript format
If provided, the textId is used as the message ID. If @textId@ is not specified,
Caché generates a new textId by calculating the 32–bit CRC (Cyclic
Redundancy Check) of this text. If the textId is specified and a message
already exists with this ID, the existing message is checked to see if it has
the same text as actualText. If not, an error is reported.
domain
(Optional) A string specifying the domain for the new message. If not
specified, domain defaults to the value of the DOMAIN class parameter at
compile time and %response.Domain at runtime.
398 Using Zen

CSP Localization
Argument
language
Description
(Optional) An RFC1766 code specifying the language. Caché converts
this string to all-lowercase. If not specified, language defaults as follows:
• At compile time: $$$DefaultLanguage.
• At runtime: %response.Language, or if no value is defined for
%response.Language then $$$DefaultLanguage.
Tag-based CSP pages automatically acquire a value for
%response.Language from browser settings, so it is available as a
default language. This is not true for class-based CSP pages, which
must explicitly set a value for %response.Language to use it as a
default.
You can assign a value to %response.Language by giving it the return
value of the %Library.MessageDictionary class method MatchLanguage.
Given a list of languages and a domain name, this method uses HTTP
1.1 matching rules (RFC2616) to find the best-match language within
the domain.
20.1.3.2 $$$Text at Compile Time
When you compile a class that contains calls to $$$Text, $$$TextJS, or $$$TextHTML macros, each
call generates a message in the Message Dictionary, with text, message ID, domain, and language as
provided by the macro arguments.
20.1.3.3 $$$Text at Runtime
If the message text contains arguments (%1, %2, %3, %4) you must specify the corresponding substitution
text before displaying the text. Since $$$Text returns a string, you can use any string operation native
to your coding language. For example, in JavaScript:
var prompt = '#($$$TextHTML("Remove user %1 from this Role"))#';
prompt = prompt.replace(/%1/g,member.userName);
You can also input the $$$Text string into the first argument of the %response.FormatText method
or a $$$FormatText macro. For details see Localization from Class Code in Using Caché Server Pages
(CSP).
Using Zen 399

Zen Localization
20.2 Zen Localization
Zen pages are CSP pages. All CSP localization practices also apply to Zen pages. However, Zen adds
the following conventions to make localization even easier:
• Any Zen property that has its ZENLOCALIZE parameter set to 1 (true) automatically generates
a Message Dictionary entry. Caché generates the Message Dictionary using similar conventions
as when you use textid="" in and other localizable CSP tags. That is:
- The message text is the string value of the property
- The message ID is the 32–bit CRC of the text
- The domain takes the value of the DOMAIN class parameter
- The language takes the value of the browser default language (at runtime)
• The Zen datatype class, %ZEN.Datatype.caption, has a default value of 1 (true) for its ZENLOCAL-
IZE parameter, so any property defined as having a type of %ZEN.Datatype.caption is automatically
localized as described above.
• For these conventions to work, the Zen page class that defines the property must provide a value
for the DOMAIN class parameter.
20.2.1 Localization for Built-In Components
Essentially what happens when ZENLOCALIZE is true is that, when Zen generates the %CreatePage
method from your description, Zen inserts the call to $$$Text on your behalf (without your
needing to worry about setting the arguments properly). If you are using a component with a property
that uses a Zen datatype with ZENLOCALIZE set to 1 (such as %ZEN.Datatype.caption), and you
place this component within a element in XData Contents, and your page has a DOMAIN
parameter value defined, then the code that Zen generates to set this property in %CreatePage automatically
calls $$$Text. For example:
Generates code like this in %CreatePage:
Set bttn.caption = $$$Text("OK")
On the other hand, if you programmatically build pages (without using ) there is no automatic
localization of component properties, even if ZENLOCALIZE is true. In this case you must call $$$Text
yourself.
400 Using Zen

Zen Localization
20.2.2 Localization for Custom Components
If you are creating a new component, you can define properties that should be localized as datatype
%ZEN.Datatype.caption:
Property title As %ZEN.Datatype.caption;
Within your component simply use ..title to refer to the property. You do not need $$$Text within
your custom component code unless you have some static text that you wish to localize. Whenever a
references your component, your property is automatically localized in the same way as builtin
Zen components. For example:
Generates code like this in %CreatePage:
Set MyCmp = $$$Text("AAA")
Using Zen 401

21
Zen Reports
Zen provides an extensible framework for specifying database reports in XHTML or PDF format.
Report output in PDF format might look like the following sample.
It takes three steps to generate Zen report output:
Using Zen 403

Zen Reports
1. The developer creates a Zen report class and, within it, provides two XML documents:
• XData ReportDefinition describes the data
• XData ReportDisplay describes the display
2. The developer or end-user generates output by entering the report class URI in a browser, or by
invoking the GenerateReport method from the command line or from within the application.
The type of output must be specified:
• XHTML can be viewed in a browser
• PDF creates printer-friendly pages
3. The report class guides the data and display information through one of the two processing
sequences shown in the following figure: XHTML or PDF.
How a Zen Report Class Produces a Report
404 Using Zen

Building a Report
The two main processing sequences for Zen reports are as follows:
To XHTML
To PDF
For XHTML output, XData ReportDefinition causes a query to be run. Zen formats the data
from this query as XML. Meanwhile, XData ReportDisplay generates an XSLT transformation
called the To-HTML stylesheet. Zen applies this XSLT transformation to the XML file. The
result is the XHTML output file.
For PDF output, XData ReportDefinition causes a query to be run. Zen formats the data from
this query as XML. Meanwhile, XData ReportDisplay generates an XSLT transformation
called the To-XSLFO stylesheet. Zen sends this XSLT transformation and the XML file to
a third-party rendering tool, which uses them to generate a report in XSL-FO format. The
third-party tool then renders the XSL-FO as PDF.
The next several topics in this chapter explain how to develop a Zen report class:
• Building a Report
• Zen Report Parameters
• XData ReportDefinition
• XData ReportDisplay, which may contain:
- Layout and Display Elements
- Stylesheet Control Elements
The chapter then describes how to process the class to produce XHTML or PDF reports:
• Zen Reports from a Web Browser
• Configuring Zen for PDF Output
• Troubleshooting Zen Reports
• Zen Reports from a Command Line
21.1 Building a Report
This topic explains Zen report class structure by building a class in gradual steps.
If you have a new Caché installation, you must first generate data records for the SAMPLES namespace.
You only need to do this once per Caché installation. Enter the following URI in the browser:
Using Zen 405

Zen Reports
http://localhost:57772/csp/samples/ZENDemo.Home.cls
Where 57772 is the Web server port number that you have assigned to Caché.
Now you may begin the exercise as follows:
1. Start Caché Studio.
2. Choose File > Change Namespace or F4.
3. Choose the SAMPLES namespace.
4.
Choose File > New or Ctrl-N or the
5. Select the Custom tab.
6. Click the New Zen Report icon.
icon.
7. Click OK.
The Zen Report Wizard presents the fields shown in the following table. For this exercise, enter
the values shown in the right-hand column of the table.
Field
Package Name
Class Name
Application
Report Name
Description
Click Next.
Meaning
The package that will
contain the report class.
The report class name.
The package and class
name of the application
that this report belongs to.
The logical name of this
report within its
application.
Any text that you want to
use to describe the report.
Value to Enter
MyApp
ReportDemo
MyReport
Sample of building a new
report.
8. The wizard prompts you to enter an SQL query to provide data for the report. Type:
SELECT ID,Customer,Num,SalesRep,SaleDate
FROM ZENApp_Report.Invoice ORDER BY SalesRep,Customer
Click Finish.
The New Report Wizard creates and displays a Zen report page class with pre-defined parameter
values and the XML blocks XData ReportDefinition and XData ReportDisplay.
406 Using Zen

9. Find the following text in the XData ReportDefinition block. Place the cursor between this comment
and the closing element:
10. A report consists of one or more nested groupings. Define the first grouping inside the XData
ReportDefinition by adding the following element at the cursor position, before :
Building a Report
11.
12.
Choose Build > Compile or Ctrl-F7 or the icon.
Choose View > Web Page or the icon. If you have difficulty viewing the Zen report page from
Studio, start a browser session and enter the class name as follows:
http://localhost:57772/csp/samples/MyApp.ReportDemo.cls
Where 57772 is the Web server port number that you have assigned to Caché.
The XML view of your report data displays as follows. It has structure, but no content:
13. Add an element to the within XData ReportDefinition:
14. Compile the class and view the report. The XML output appears as follows. Each
element now includes an attribute, name, whose value is the SalesRep field returned by the SQL
query:
Using Zen 407

Zen Reports
15. Add an element to the group within XData ReportDefinition:
16. Compile the class and view the report. The XML output appears as follows. Each
element now includes an element called . The value within is the sum of all the
Num field values for the corresponding SalesRep field returned by the SQL query:
833
774
983
826
824
825
17. Add more , , and elements within XData ReportDefinition:
408 Using Zen

18. Compile the class and view the report. The XML output now displays a much larger data set for
each sales person. The aggregate elements , , and appear at the end of
each record.
19. Now that you have structured the report data as XML, you can specify how to display this data
in XHTML or PDF format.
Find the following text in the XData ReportDisplay block. Place the cursor between this comment
and the closing element:
20. At the cursor position, add a element to enclose the display items within the report. Within
the place a that displays a title for the report. Also add the title attribute to the
element to set the title of the browser window:
Tutorial Sales Report
21. Change the DEFAULTMODE class parameter value from "xml" to "html".
22. Compile the class and view the report.
23. Add a table to XData ReportDisplay as follows:
Tutorial Sales Report
Where:
Building a Report
• is a reference to the element in the generated
XML.
• is the syntax for referring to the attribute name.
• is the syntax for referring to the element .
Using Zen 409

Zen Reports
24. Compile the class and view the report.
25. Highlight the heading by formatting it using a pre-defined style class. Change the element in
XData ReportDisplay as follows:
Tutorial Sales Report
26. Compile the class and view the report.
27. Consider adding the following display modifications within XData ReportDisplay. Some of these
changes affect style and layout; others add data to the display:
Tutorial Sales Report
28. Compile the class and view the report.
21.2 Zen Report Parameters
A Zen report class may define the class parameters listed in the following table.
410 Using Zen

Zen Report Parameters
Report Class Parameters
Class Parameter
DATASOURCE
Description
(Optional) Identifies an XML document that contains the data
for the Zen report. This string can be the URI of any valid XML
document. Relative URIs are handled with respect to the current
URI.
If DATASOURCE is an empty string, the class generates its own
XML document using the specification in its XData ReportDefinition
block. If a Zen report class has both a non-empty, valid
DATASOURCE string and an XData ReportDefinition block, the
DATASOURCE parameter takes precedence over the XData
block.
The DATASOURCE string can refer to an XML document created
by another Zen report class in the same namespace. Use the
$MODE=xml query parameter to specify that you want to use the
XML output from that class:
Parameter DATASOURCE="MyApp.Report.cls$MODE=xml";
DEFAULTMODE
Default output mode for the report. This value is used only if the
URI parameter $MODE is not specified. Possible values are:
• "html" — Report display in XHTML format
• "pdf" — Report display in PDF format
• "tohtml" — To-HTML stylesheet in XSLT format
• "toxslfo" — To-XSLFO stylesheet in XSLT format
• "xml" — Report data in XML format
• "xslfo" — Report pre-display in XSL-FO format
If there is no DEFAULTMODE and no $MODE, the default is
"html".
Using Zen 411

Zen Reports
Class Parameter
HTMLSTYLESHEET
Description
Identifies the to-HTML stylesheet that controls XHTML output
for the Zen report. This string can be the URI of any valid XSLT
stylesheet. Relative URIs are handled with respect to the current
URI.
If HTMLSTYLESHEET is an empty string, the class generates
a to-HTML stylesheet using the specification in its XData
ReportDisplay block. If a Zen report class has both a non-empty,
valid HTMLSTYLESHEET string and an XData ReportDisplay
block, the HTMLSTYLESHEET parameter takes precedence
over the XData block.
The HTMLSTYLESHEET string can refer to a to-HTML
stylesheet created by another Zen report class in the same
namespace. Use the $MODE=tohtml query parameter to specify
that you want to use the to-HTML output from that class:
Parameter HTMLSTYLESHEET="MyApp.Report.cls$MODE=tohtml";
REPORTNAME
REPORTXMLNAMESPACE
XSLFOSTYLESHEET
Controls the filename suggested by the browser when you ask
to save a report in XHTML or PDF format.
(Optional) XML namespace to be used in the generated XML
report.
Identifies the to-XSLFO stylesheet that controls PDF output for
the Zen report. This string can be the URI of any valid XSLT
stylesheet. Relative URIs are handled with respect to the current
URI.
If XSLFOSTYLESHEET is an empty string, the class generates
a to-XSLFO stylesheet using the specification in its XData
ReportDisplay block. If a Zen report class has both a non-empty,
valid XSLFOSTYLESHEET string and an XData ReportDisplay
block, the XSLFOSTYLESHEET parameter takes precedence
over the XData block.
The XSLFOSTYLESHEET string can refer to a to-XSLFO
stylesheet created by another Zen report class in the same
namespace. Use the $MODE=toxslfo query parameter to
specify that you want to use the to-XSLFO output from that class:
Parameter HTMLSTYLESHEET="MyApp.Report.cls$MODE=toxslfo";
412 Using Zen

XData ReportDefinition
21.3 XData ReportDefinition
The XData ReportDefinition block specifies the data to gather for the report. It also describes how to
format this data as XML. An XData ReportDefinition block may contain references to the following
variable:
• %val — the value of the field attribute in the same element
And may contain the following XML elements:
• — Identifies the query that returns the data.
Contains the following elements in any order or quantity:
- — Writes an XML element to the output XML file
- — Writes an XML attribute to the output XML file
- — Calculates sums and averages for reporting purposes
Contains 0 or 1 of the following:
- — Groups items together so that operations can be performed on the group
The following is a sample XData ReportDefinition block:
XData ReportDefinition
{
}
You can omit or override the XData ReportDefinition block if you provide a valid value for the
DATASOURCE class parameter. If you provide both, the DATASOURCE value takes precedence.
Using Zen 413

Zen Reports
You can also omit XData ReportDefinition if you only plan to use this Zen report class to generate
XSLT stylesheets.
21.3.1 The %val Variable
%val is a variable that you can use only in an XData ReportDefinition block.
You can use %val in the expression attribute for , , or . %val represents
the value of the field from the field attribute in the same element. You can see this in the following
example:
Or in :
also supports %val. You can use %val in a breakOnExpression attribute to represent the
value of the field from the breakOnField value.
21.3.2
The element is the top level container within an XData ReportDefinition block.
Within an XData ReportDefinition block, a may contain multiple , ,
and elements in any order, but without nesting them. A may contain one .
Each may contain one . Only one may exist at each level of nesting within
the .
requires a name attribute and some combination of query attributes. supports the
same attributes as .
Important:
There is a different element for use within an XData ReportDisplay block.
21.3.3
The element is valid within a or in an XData ReportDefinition block.
Each adds an XML element to the XML document. has the attributes listed in
the following table.
414 Using Zen

XData ReportDefinition
Attribute
expression
Description
(Optional) Can be used to process the field value before outputting it. The
language of the expression must be Caché ObjectScript. Within the
expression, the %val variable represents the field value. For example, in a
Zen report class with a GetDisplayURL method:
The expression attribute can be used without the field attribute to return
static data such as the report run time:
field
name
Specifies which resultset field to get the data from.
Generates an XML element of this name in the output. An entry like this:
Yields an XML element like this:
July
21.3.4
The element is valid within a or in an XData ReportDefinition block.
works just like , but the data it captures is rendered as an attribute of the containing
or element.
21.3.5
The element may appear within a or . performs a calculation
over every record in the resultset returned by the query for the XData ReportDefinition block.
has the attributes listed in the following table.
Using Zen 415

Zen Reports
Attribute
class
method
Description
If the type is CLASS, the class attribute must specify the package and class
name of a class that extends %ZEN.Report.CustomAggregate.
You can create your own subclasses of %ZEN.Report.CustomAggregate, or
there are several built-in aggregate classes that you can reference.
If the type is CUSTOM, the method attribute must specify the name of a
server-side method within the Zen report class. The method must have the
following form:
ClassMethod MyAgg(pMode As %String,
pAccumValue As %String,
pValue As %String,
pCount As %Integer)
As %String
{
Quit
$Case(pMode,"Start":0,"Accum":pAccumValue+(pValue*2),"End":pAccumValue)
}
type
Specifies which kind of aggregation to perform. Valid values include the following
case-sensitive strings:
• "SUM" — the sum of all values
• "COUNT" — the total number of records
• "AVG" — the average of all values
• "MAX" — the maximum value in the set
• "MIN" — the minimum value in the set
• "CLASS" — (see the class attribute)
• "CUSTOM" — (see the method attribute)
21.3.5.1 Built-in Aggregate Classes
The following are the built-in custom aggregate classes:
• %ZEN.Report.Aggregate.CountDistinct
The number of distinct values in a set of data, as opposed to a simple COUNT.
• %ZEN.Report.Aggregate.Median
The median of a set of numerical data, as opposed to a simple AVG (average). The median is a
number with half of the data set of greater value than it, and half of lesser value.
416 Using Zen

For a data set with an odd size, the median is a member of the data set. For a data set with an even
size, the median is a value halfway between two members of the data set.
• %ZEN.Report.Aggregate.Mode
The statistical mode (most frequent observation) of a set of data.
• %ZEN.Report.Aggregate.StDev
The standard deviation of the values processed.
XData ReportDefinition
21.3.5.2 Creating a New Aggregate Class
If you need a new type of aggregate, you can develop and use a custom aggregate class as follows:
1. Subclass %ZEN.Report.CustomAggregate
2. Override the following methods:
• GetResult is invoked after every record has been processed to return the final value of the
aggregate.
• ProcessValue is called sequentially on each record returned by the report query or queries.
3. Save and compile the class as myPackage.myClassName
4. When referencing this calculation in the element, use these attributes:
• type="CUSTOM"
• class="myPackage.myClassName"
The following example may be useful to you if you are creating your own aggregate class. This is the
code for the built-in custom aggregate class %ZEN.Report.Aggregate.CountDistinct:
Using Zen 417

Zen Reports
/// Aggregate for counting the number of distinct values in a set of data
Class %ZEN.Report.Aggregate.CountDistinct Extends %ZEN.Report.CustomAggregate
{
/// Array of values processed
Property Values As array Of %String;
/// Running count of distinct values processed
Property Count As %Integer [ InitialExpression = 0 ];
/// Processes each new value
Method ProcessValue(pValue As %String) As %Status
{
If ..Values.GetAt(pValue) {
// seen it already
} Else {
Do ..Values.SetAt(1,pValue)
Set ..Count=..Count+1
}
}
Quit $$$OK
}
/// Return the count of distinct values processsed
Method GetResult() As %String
{
Quit ..Count
}
21.3.6
Within an XData ReportDefinition block, the element indicates that Zen should perform the
same set of operations on all records from the resultset that match a specified criteria. If the
specifies no criteria, Zen performs the operations on every record in the resultset. The elements
contained within the element specify what to do. A may contain multiple ,
, and elements in any order, but without nesting them.
A may contain one . Each may contain one . Only one
may exist at each level of nesting within the . You can see this convention in the sample XData
ReportDefinition block.
and have the general-purpose attributes listed in the following table.
418 Using Zen

XData ReportDefinition
Attribute
breakOnExpression
Description
Provides an expression to apply to the value of the field specified
by breakOnField. The language of the expression must be Caché
ObjectScript. The %val variable gets the value of the raw data,
and then the result of breakOnExpression string is returned.
For example, suppose you want to group by month, and you have
a method in the Zen report class called GetMonth which takes a
date and returns the month.Then you could provide a like
this:
...
breakOnField
name
The phrase breakOnField means “If you encounter this field, stop
to examine its value.” All of the records in the resultset that contain
the same value in the field specified by breakOnField are processed
together.
If the breakOnField attribute is omitted, or its value is left blank,
the processes every record in the resultset in the same
way.
If you are breaking on a field, the query for the report should be
ordered by that field. Field breaking examines the results sequentially
and creates a break whenever the specified field changes.
So if the query is not ordered by the field, a break may occur
unexpectedly.
The generates an XML element of this name in the output.
If you do not provide a value for name, the generates a
name based on the Zen report class name.
A Zen report or may specify a query. The following table lists the attributes that
support queries.
Using Zen 419

Zen Reports
Attribute
OnCreateResultSet
queryClass
queryName
runtimeMode
sql
Description
(Optional) The name of a server-side callback method to call to
create a %ResultSet object. The OnCreateResultSet value must be
the name of a server-only method defined in the Zen report class.
(Optional) The name of the class containing the query. You must
also provide a value for queryName.
(Optional) The name of the class query that will provide the
%ResultSet for this list. You must also provide a value for
queryClass.
SQL runtime mode to apply to the %ResultSet object used to fetch
results for this report. The default runtimeMode of 2 is appropriate
for most cases and usually does not need to be changed. Possible
values are: 0 for LOGICAL mode, 1 for ODBC mode, and 2 for
DISPLAY mode.
(Optional) Server-side SQL query to get contents of the
list.
This attribute has the underlying data type %ZEN.Datatype.sql. This
means it cannot be accessed from the client. Its value is encrypted
(using the current session key) when it is sent to the client. If this
value is returned to the server, it is automatically decrypted. This
makes it possible to place sensitive data on the client for future
processing on the server, without letting a user view this data.
For additional details, plus examples, see the Zen Tables chapter as follows:
• How to use query attributes with or :
- Specifying an SQL Query (sql)
- Referencing a Class Query (queryClass, queryName)
- Using a Callback Method (OnCreateResultSet)
• How to provide elements within or :
- Query Parameters
420 Using Zen

XData ReportDisplay
21.4 XData ReportDisplay
The previous topic explained how to structure the XML data upon which the Zen report is based. This
topic explains how to write a specification for displaying this data. The specification consists of an
XData ReportDisplay block in the Zen report class.
Styles in the XData ReportDisplay block are independent of the output format. At runtime, the choice
of format depends on a parameter supplied by the caller in one of the following ways:
• In a browser URI string (see Reports in a Web Browser)
• At the Terminal command line (see Zen Reports from the Command Line)
The exact value of the parameter depends on whether it is being used in the browser or at the command
line. However, its meaning is the same in each environment. It instructs the Zen report class to create
report output in one of the following formats:
• XHTML — The Zen report class creates an XSLT stylesheet and uses this stylesheet to transforms
its XML data into an XHTML report.
• PDF — The Zen report class creates an XSLT stylesheet, then passes this XSLT stylesheet and
the XML data file to a third-party rendering tool, which produces XSL-FO and then PDF output.
An XData ReportDisplay block may contain the following XML elements:
• — Identifies the title. Contains these elements (in the following order):
- — general page characteristics, primarily for PDF output
- — page headers, used in PDF and optionally in HTML
- — page footers, used in PDF and optionally in HTML
- — the container for elements that control:
• Graphical layout (see Layout and Display Elements)
• Style and appearance (see Stylesheet Control Elements)
The following is a simple example that uses very few of the available elements:
Using Zen 421

Zen Reports
XData ReportDisplay
{
Tests
}
You can omit the XData ReportDisplay block entirely, if you provide a valid value for the HTML-
STYLESHEET and XSLFOSTYLESHEET class parameters. For details, see Zen Report Parameters.
If you provide both an XData ReportDisplay block and parameter values, the parameter values take
precedence.
You can also omit XData ReportDisplay if you only plan to use this Zen report class to generate XML
data files.
422 Using Zen

XData ReportDisplay
21.4.1 Dimension and Size
An XData ReportDisplay block allows you to specify sizes (widths, heights, lengths, etc.) in a variety
of units, just as you would in HTML or XSL-FO syntax. 2in, 5cm, 12px, 14pt, 3em, or 75% are all
valid sizes. Generally, Zen measures percentage values with respect to the containing element.
21.4.2
The element is the top level container in an XData ReportDisplay block.
Important:
There is a different element for use within an XData ReportDefinition block.
Within an XData ReportDisplay block, may contain the following elements only. It must
contain them in the following order and quantities:
• (0 or 1)
• (0 or 1)
• (0 or 1)
• (1 is required)
A element that appears in an XData ReportDisplay block has the attributes listed in the following
table.
Attribute
name
style
title
Description
The report name, which should match the top-level element name in the XML
data for the report.
If the XData ReportDefinition block from the same Zen report class is used
to generate this XML, then the name attribute for the element in
XData ReportDisplay should match the name attribute for the element
in XData ReportDefinition.
If style="none", the standard Zen stylesheet is not rendered, otherwise it is.
The standard stylesheet is a collection of available style classes that includes
p.banner1, table.table1, td.table1, th.table1, ..., th.table6, as well as table, td,
and th.grid.
For more on style classes, see the element.
The report title, used for items such as the PDF filename or XHTML page
title.
Using Zen 423

Zen Reports
21.4.3
The element applies primarily to PDF output. specifies physical layout
characteristics such as page dimensions and margins. can contain multiple ,
, and elements for custom styling.
The element can be omitted from a , even if PDF output is intended. The result
in this case is an 8.5x11 inch page with 1.25–inch left and right margins and 1–inch top and bottom
margins.
If more than one element is included in the , all but the first are ignored.
has the attributes listed in the following table.
Attribute
footerHeight
headerHeight
height
marginBottom
marginLeft
Description
Like headerHeight, but refers to the .
HTML length value that specifies a block of empty space to be reserved
beneath the top margin, but above the main body of the report.
headerHeight should be specified if this report has a
element indicating a header to appear on every page.
HTML length value that specifies the page height.
HTML length value that specifies the bottom margin
HTML length value that specifies the left margin.The margin is contained
within the width of the page, so the width of the available area of the
page is:
width - (marginLeft + marginRight)
marginRight
marginTop
width
HTML length value that specifies the right margin.
HTML length value that specifies the top margin
HTML length value that specifies the page width.
21.4.3.1
The element renders style information into a CSS class in the XHTML report, and into
equivalent XSLT stylesheet information for the PDF report.
elements can only occur as children of . Multiple elements may be present.
Each element has the attribute listed in the following table.
424 Using Zen

XData ReportDisplay
Attribute
name
Description
Identifies a style class. Style class names are of the form tag.class, as in
cascading style sheets (CSS). Possible names include:
• table (referring to general table layout)
• th (table header cells)
• td (table cells)
• a (links)
• p (paragraphs)
For more on style classes, see the class attribute as described in Layout
and Display Elements.
The element contains elements that specify the styling information for the class.
can only occur as a child of . It specifies a piece of style information for that class. has
the attributes listed in the following table.
Attribute
name
value
Description
The attribute name. This corresponds to a CSS attribute name (color,
background-color, font-size, font-family, width, etc). Zen simply passes the
attributes on to CSS and XSL-FO, so the user can specify anything; it
is up to the browser or PDF rendering tool to be able to interpret the attribute.
The value to assign to the attribute.
To provide the equivalent of the CSS document fragment given here:
th.myTable {
background-color: blue;
color: white;
}
The following element is needed:
21.4.3.2
The element applies to XHTML output only. When producing the XSLT stylesheet for
PDF output, the class simply ignores any elements.
Using Zen 425

Zen Reports
Multiple elements may be present within a element. Each
element has has the attribute listed in the following table.
Attribute
href
Description
URI of an external CSS stylesheet to include in the HTML stylesheet.
The href string can be a comma-delimited list of URIs, and each will be
included; this the same as providing multiple elements.
Some browsers struggle when the file referenced does not end in .css.
21.4.3.3
The element applies to the XSLT stylesheet for PDF output only. When producing the
HTML version of the report, the class simply ignores any elements.
Multiple elements may be present within a element. Each
element has the attribute listed in the following table.
Attribute
href
Description
Filename of an external XSLT file to include in the to-XSLFO stylesheet.
This feature is potentially very powerful, but XSLT can be difficult to write.
In practice, the main purpose of the element is for the external
XSLT stylesheet to contain elements, which can do the
same work as CSS classes.
To continue the previous example, to import the th.myTable class from external files, the
element would look something like this:
With myStyle.css containing:
th.myTable {
background-color: blue;
color: white;
}
And myStyle.xsl containing:
blue
white
426 Using Zen

Layout and Display Elements
21.4.4
The element, if present in the , must occur before the element.
can contain the same layout and display elements as , but everything contained
within is rendered in the blank space provided by the element headerHeight
attribute.
XHTML reports do not support page-by-page headers, so in XHTML reports the contents of
are simply rendered at the beginning of the report.
21.4.5
The element, if present in the , must occur before the element.
is like . However, elements are not displayed in XHTML
reports.
21.4.6
The element is the required child of . It has no attributes, but contains the bulk of the
report information. contains elements that control:
• Graphical layout — see Layout and Display Elements
• Style and appearance — see Stylesheet Control Elements
21.5 Layout and Display Elements
This topic describes the elements that display the visual content of the report. Any of these elements
may be a child of , , , or . The elements are:
• — Bar chart
• — Group of items for a table row or column
• — Group of items for a page footer
• — Group of items for repeated actions
• — Group of items for a page header
• — Image
• — Data value
Using Zen 427

Zen Reports
• — Horizontal line
• — Line chart
• — Bulleted or numbered list
• — Raw text of any length
• — Page break
• — Pie chart
• — Table
Each of these elements has the three attributes described in the following table. It may have other
attributes also; the next several topics describe them.
Report Display Attributes
Attribute
class
Description
CSS style class to apply to the element. Style classes are defined by the
element, and some are given by the standard style sheet.
When specifying a value for the class attribute, do not include the element
name that is given when creating the class. For example, if you have a style
class named table.myTable that you want to use, in the specify:
Parent elements propagate their class attribute value to children that do not
have a class specified. So if you define table.myTable, th.myTable, and
td.myTable, you only need to give the element a class attribute.You
can even put a class attribute on the element to give a class for
every element in the report (at least, for those that do not override it with a
class attribute of their own).
style
Similar to the style attribute in CSS, this attribute may provide a semicolondelimited
list of attribute:value pairs. For example:
style="fill: yellow; font-size: 6pt ;"
Information contained within the style attribute takes precedence over style
information given by the class.
width
HTML length value that defines the element’s width. The exact meaning
depend on the individual element. If widths are omitted, the PDF rendering
tool can produce unexpected results.
428 Using Zen

Layout and Display Elements
21.5.1
The element renders all of its child elements sequentially. It can be used anywhere in the
as a kind of spanning element, but it is most useful as a container within a . In general,
a treats every child element as a new row or column, so the element can be used to
group multiple elements into a single row or column.
The element may contain any of the same common display elements as .
has the common display attributes style, width, and class.
21.5.2
Within an XData ReportDisplay block, the element allows the Zen report class to respond to
the hierarchically structured data that is typical of XML.
Important:
There is a different element for use within an XData ReportDefinition block.
is a display element, so has the common display attributes style, width, and class.
also has the attributes listed in the following table.
Attribute
line
Description
HTML length value that specifies the thickness of the line to be drawn
between each iteration of the group. If line is 0, no line is drawn.
Using Zen 429

Zen Reports
Attribute
name
Description
Required. displays the contents of each element in the XML data
whose name matches this attribute. So if your XML data contains
elements, your XData ReportDisplay block could contain:
...
The elements within the container determine how the display
handles the data within the container. can contain
any of the common display elements listed at the beginning of this topic.
elements can be nested. Suppose each elements
contains multiple elements. To specify how to display each sale
within the display for each sales representative, you would provide something
like:
...
...
To display a group as a table, see the group attribute of .
pagebreak
If true, put a page break after each iteration of the group.
This attribute has the underlying data type %ZEN.Datatype.boolean. It has the
value "true" or "false" in XData Contents, 1 or 0 in server-side code, true or
false in client-side code. See Datatype Classes.
21.5.3 and
The and elements are simple containers used for clarity, but they can be useful to
organize style within the report. Each can propagate its class attribute to its children.
and have no attributes in addition to the common display attributes style, width,
and class.
21.5.4
The element inserts an image into the report.
In addition to the common display attributes style, width, and class, has the attributes listed in
the following table.
430 Using Zen

Layout and Display Elements
Attribute
height
src
width
Description
HTML length value that specifies the image height.
URI for source of the image. If the src attribute begins with an exclamation
point, it is interpreted as an XPath expression just as in the field attribute of
the element. This allows you to dynamically generate URIs within
the XML data, and then use these customized URIs as the image source.
When using ! to dynamically generate the image URI, the resulting string
must be an absolute URI or it will not appear in the PDF report.
HTML length value that specifies the image width.
21.5.5
The element outputs literal values or data from the XML into the report. must have
exactly one of its value, field, or special attributes specified.
In addition to the common display attributes style, width, and class, has the attributes listed in
the following table.
Attribute
field
Description
If the field attribute is specified, the renders the value of that
field in the XML data. field is actually used as an XPath expression, so
if you have the data:
MegaPlex
Systems
To get the value of the id attribute you need the XPath expression:
field= "@id"
Whereas to obtain the value of the element you need the
XPath expression:
field="customer"
The field attribute is interpreted with respect to the current
matched. For an within , only
attributes and children of are available.
formatNumber
String specifying the number format to use. This string uses the same
conventions as the XSLT format-number function, such as ###.# for
a three-digit number with one decimal place.
Using Zen 431

Zen Reports
Attribute
link
special
Description
Optional hyperlink to place around the item’s data. If the link attribute
begins with an exclamation point, it is interpreted as an XPath
expression just as in the field attribute. This allows you to dynamically
generate URIs within the XML data, and then use these customized
URIs in the display. If link is specified, the item’s style class will use the
"a" option.
If the special attribute is specified, the renders a pre-defined
piece of dynamic data. Possible values for special are:
• number — gives the record number within the group.
• page-number — inserts the page number within a PDF report. Is
rendered as '##' in XHTML.
• page-count — inserts the number of pages within a PDF report. It
is rendered as '##' in XHTML.
• page-number-of — inserts the page number in the form '2 of 18'. It
is rendered as '## of ##' in XHTML.
• page-number-/ — inserts the page number in the form '2/18'. It is
rendered as '##/##' in XHTML.
References to the total page count can be slow in extremely large PDF
reports. If speed is essential and you run into problems with speed,
avoid page-count, page-number-of, and page-number-/.
value
If the value attribute is specified, the renders it as a literal value.
21.5.6
The element inserts a line break into the report. This can either be a visible horizontal line or
an empty line break.
In addition to the common display attributes style, width, and class, has the attributes listed in
the following table.
Attribute
align
color
Description
Alignment within the report page. Possible values are "left", "right", and
"center".
CSS color value that specifies the line color. color only applies to solid or
dashed lines
432 Using Zen

Layout and Display Elements
Attribute
count
length
lineHeight
pattern
thickness
Description
The number of line breaks to draw.This is the same as repeating the
element.
HTML length value that specifies the line length. length only applies to solid
or dashed lines.
HTML length value that specifies how much space to leave for displaying
the line. This is not the same as the line thickness when pattern is "solid"
or "dashed". lineHeight applies to "empty" lines as well.
Despite using this attribute, line spacing can vary between XHTML and
XSL-FO (that is, PDF). This can be overcome using and elements.
Possible values are "empty", "solid", and "dashed"
HTML length value that specifies the line thickness. The default value is
1px. thickness only applies to solid or dashed lines.
21.5.7
The element is used to display an itemized or ordered list within a Zen report.
The style attribute on the applies to its bullets or numbers.
In addition to the common display attributes style, width, and class, has the attributes listed in
the following table.
Attribute
group
image
startvalue
type
Description
Required. group identifies the entry that provides the data for this
list. The group value in must match the name value of some
in XData ReportDefinition.
The URI of an image to use as a custom bullet. If you provide an image
value, the type attribute is ignored.
The first number value for ordered lists. startvalue is always specified as an
integer. If type is "A" and startvalue is "3", the first element in the list is
labeled "C".
The bullet or numbering style to use for list items. Possible values are:
"none", "circle", "square", "disc", "1", "A", "a", "I", "i". PDF reports do not
support "square" or "circle".
Using Zen 433

Zen Reports
21.5.8
The element renders a large block of static content. It treats its contents as raw text and uses the
"p" option for its style class.
has no attributes in addition to the common display attributes style, width, and class.
21.5.9
The element inserts a page break in PDF output. It inserts a dashed line in the XHTML
report on screen, and causes a page break when you print the XHTML report.
21.5.10
The element outputs a table into the report.
In addition to the common display attributes style, width, and class, has the attributes listed
in the following table.
Attribute
align
altcolor
group
Description
Aligns the table within the report. Possible values are "left," "right," and
"center".
CSS color value that specifies the background color of the alternate rows
(2, 4, 6, etc.).This is only possible when orient is "col" and group is specified.
A table can be used to display a group of data. If the group attribute is
specified, the table displays a row or column in the table for each item in
the group. If no group is specified, there is only one row or column in the
table (plus an optional header and optional footer row or column).
434 Using Zen

Layout and Display Elements
Attribute
layout
Description
Possible layout values are "auto" and "fixed". For PDF output, the XEP
rendering tool supports both "auto" and "fixed" formats. FOP supports "fixed"
only.
When layout is "fixed", it is important that you specify a width for each column.
The code produces a good result from minimal width information, but
you can gain closer control as follows:
• If orient is "col," then each child of the table class should have a width
attribute specified.
• If orient is "row", then only one child of the table needs to have its widths
specified. However, if that element within the table has a or
child element to define a header column or footer column,
it is necessary that these elements also specify their width.
orient
Each element contained within the table is treated as either a row or column,
depending on the value of the orient attribute. If orient is "row," each child
element of table will be placed in a new row. Similarly, if orient is "col" each
child element will be placed in a new column. Possible values are "row"
and "col". The default is "col".
Every cell the table renders uses the "td" option for its style class, except for the header cells, which
use "th".
21.5.10.1
To include a caption for a row or column of the table, an element within a table can contain a
element.
The element works just like , and has the same attributes. When you place it as a
child of an element within a table, it indicates that that row or column has a header, which it gets from
the value of the element.
When you have nested tables, it is possible for the inner table to have element within it, but
that does not mean the is something for that table to display. It actually refers to giving the
inner table a caption within the outer table.
21.5.10.2
The element is the same as , except that it creates a footer for the row or column.
Using Zen 435

Zen Reports
21.6 Charts in Zen Reports
Important:
Like Zen Charts, charts in Zen reports use SVG for graphics. Support for SVG is built
into Firefox 1.5 or later. If you are using Internet Explorer 6.0 or later, you must
download the free SVG Viewer from Adobe to use charts in Zen reports.
The syntax for placing charts in Zen reports is identical to the syntax for placing charts on Zen pages,
with exceptions as noted in this topic. Zen reports support the , and
elements only. Zen reports support chartPivot, but not chartStacked. does not support
markers or filled line charts in Zen reports. Also, Zen report charts are not interactive.
When used in Zen reports, the , and elements support the following
attributes:
Attribute
Zen report
attributes
Chart
attributes
dataFields
dataGroup
seriesColors
seriesCount
Description
General-purpose report display attributes: style, width, and class.
General-purpose attributes that apply to any chart (see Zen Charts) plus
the unique attributes that apply to , or .
All charts: Comma-delimited list of fields to acquire data from. If a
dataGroup is also provided, only the first data field in dataFields is used.
Pie charts: A pie chart looks at the first field specified by dataFields and
totals the value that each series has for this field. Each series then gets
a slice proportional to its percentage of the total for this field.
All charts: Specifies the group that provides the data elements for the
chart.
Pie charts: If dataGroup is specified, the pie chart determines the value
for a series by summing the dataFields for each element in the
dataGroup.
Comma-delimited list of CSS color values used for data series. The
colors can be acquired dynamically by using the form "!fieldname".
Number of data series to display on this chart. If "", this is computed
automatically from the chart’s data source.
436 Using Zen

Stylesheet Control Elements
Attribute
seriesGroup
seriesNames
seriesSize
Description
All charts: The group that provides the list of series for the chart.
Pie charts: seriesGroup is required. If series were specified statically,
the series would be looking at the same data, and so the pie chart would
be divided evenly no matter what.
Comma-delimited list of names used to label each data series in the
legend box. Series names can be acquired dynamically by beginning
the value with a ! character. If seriesGroup is provided, only the first
series name field is considered.
Number of items within each data series to display on this chart. If
omitted, Zen computes this number automatically from the chart’s data
source.
A or in a Zen report may contain and elements. When used
in Zen reports, and support the following attributes:
Attribute
Axis
attributes
labelValues
Description
General-purpose attributes for chart axes.
All charts: Comma-delimited list of label values of category axes. If left
blank, the category number is used.
Pie charts: labelValues cannot be specified on the chart, as pie charts
do not have axes.
21.7 Stylesheet Control Elements
The following elements are valid anywhere within the element of an XData ReportDisplay
block.
21.7.1
The element can contain the same common display elements as , but everything contained
within is rendered in the XSL-FO (that is, PDF) report only.
is useful for correcting issues where the XHTML report and PDF report do not look alike due to
inherent page differences, such as page breaks.
Using Zen 437

Zen Reports
21.7.2
The element is similar to , but renders its contents in the XHTML report only.
21.7.3
The element writes directly to the stylesheet, instead of to the report.
The element is a common display element, in the sense that it may legally appear anywhere
within a or element. However, can be most useful within
or . For example:
This is HTML! ]]>
This is XSL-FO ]]>
21.8 Zen Reports from a Web Browser
The XHTML and PDF reports can be viewed in a browser by entering the URI of the Zen report .cls
file. To specify the output type, use a $MODE parameter in the query string. In the following examples,
57772 is the port assigned to the Caché server:
• To view the HTML report:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=html
The report displays in HTML format.
• To view the PDF report, first use the instructions in Configuring Zen for PDF Output, then provide
the following URI:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=pdf
The report displays in PDF format. Depending on your settings, the browser might first prompt
you to save the file. If so, click Save to view the PDF.
• To view raw data for a report in XML format:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=xml
Colorized XML displays in the browser.
438 Using Zen

Zen Reports from a Web Browser
You can override the current DATASOURCE setting for the report class by providing a $DATA-
SOURCE parameter in the URI.
Note:
The examples above use 57772, the default port number assigned to the Caché server. The
port number in your configuration might be different. You can double-check the port number
by navigating to the System Management Portal [Home] > [Configuration] > [Memory and
Startup] page.
21.8.1 Sample XHTML Output
Using Zen 439

Zen Reports
21.8.2 Sample XML Data View
21.9 Configuring Zen for PDF Output
When you load a Zen report class into a browser with a request to view the output as PDF, Caché calls
out to the command line to run a third-party PDF rendering tool. The rendering tool applies the XSLT
stylesheet to the XML data to transform the XML into XSL-FO. Finally, the tool transforms the XSL-
FO into PDF.
This works only if you have performed the required configuration steps, as follows:
1. Install an XSL-FO to PDF rendering tool. Two of the available options are:
• An open source project from Apache called FOP. You can download it from the following
Web site:
http://xmlgraphics.apache.org/fop
To install, simply extract the files from the kit.
440 Using Zen

• The XEP product from RenderX. You can download a free trial version that produces a
RenderX watermark on each output page, or you can buy the XEP product. See this Web site
for details:
http://www.renderx.com/tools/xep.html
To install, follow the instructions in the kit.
2. Set the Caché global ^%SYS("zenreport","transformerpath") to location of the batch
file or shell script that calls the rendering tool. Once you have installed FOP or XEP, this file is
already present on your system. Find its location, then set the global accordingly:
• For FOP, something like:
Set ^%SYS("zenreport","transformerpath")="C:\fop-0.92beta\fop.bat"
• Or similarly, for XEP:
Set ^%SYS("zenreport","transformerpath")="C:\XEP\XEP.bat"
Troubleshooting Zen Reports
3. (Optional) You can create custom configuration files for FOP as described in:
http://xmlgraphics.apache.org/fop/0.92/configuration.html
If you want the Caché callout to FOP to use a custom configuration file, you can set the global
^%SYS("zenreport","transformerconfig") to the path of the configuration file. Configuration
files are important for adding fonts to FOP. You must first create font metrics, and then
register them with FOP. The process is described on the FOP Web site at:
http://xmlgraphics.apache.org/fop/0.92/fonts.html
Note:
PDF rendering can consume a lot of memory. If you run into trouble, you might want to
modify the FOP.bat or XEP.bat file to increase the amount of memory available to the Java
Virtual Machine. The respective products provide documentation that explains how to do
this.
21.10 Troubleshooting Zen Reports
When specifying $MODE=html or $MODE=pdf you can also set the query parameter $LOG=1. This
allows you to view the output of the transformation from XML to XHTML or the transformation from
XML via XSLT to XSL-FO to PDF, respectively. This information can be useful when the transformation
fails. For example:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=pdf&$LOG=1
Using Zen 441

Zen Reports
Where 57772 is the port number assigned to the Caché server.
XSL-FO to PDF Transformation Log
Note:
Syntax errors in ReportDisplay are sometimes reported as FOP errors without being caught
on the Caché side. $LOG=1 can be useful for exploring this type of bug.
You can also display diagnostic information for a Zen report by providing special values for the
$MODE query parameter when you supply the .cls URI to the browser. For example:
• To view the XSLT stylesheet that turns XML into XHTML:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=tohtml
• To view the XSLT stylesheet that turns XML into XSL-FO:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=toxslfo
• To view the XSL-FO stylesheet before PDF rendering:
http://localhost:57772/csp/myPath/myApp.myReport.cls$MODE=xslfo
Note:
The examples above use 57772, the default port number assigned to the Caché server. The
port number in your configuration might be different. You can double-check the port number
by navigating to the System Management Portal [Home] > [Configuration] > [Memory and
Startup] page.
442 Using Zen

XSL-FO Prior to PDF Rendering
Zen Reports from a Command Line
21.11 Zen Reports from a Command Line
You can run a Zen report from the Terminal command line as follows:
1. Change to the namespace containing the Zen report class:
ZN "mySpace"
2. Create an instance of the Zen report class:
Set report=##class(myPackage.myClassName).%New()
3. Run the report:
Do report.GenerateReport("C:\Temp\mySample.pdf",2)
Where:
• C:\Temp\mySample.pdf is the pathname of the output file
• 2 is an integer that tells Zen which type of report output to generate.
Possible values include:
- 0 — XML
- 1 — XHTML
Using Zen 443

Zen Reports
- 2 — PDF. This works only if you have already used the instructions in the topic Configuring
Zen for PDF Output.
And for debugging purposes:
- 3 — To-HTML stylesheet
- 4 — To-XSLFO stylesheet
• You may also provide an optional third parameter value of 1 (true):
Do report.GenerateReport("C:\Temp\mySamplePDF.log",2,1)
If so, the output file contains the transformation log rather than the report. This log is similar
to the result in the browser when you supply the query parameter $LOG=1.
444 Using Zen

22
Zen Wizards
This chapter describes the Caché Studio wizards that Zen provides:
• Wizards for creating new application, component, page, or report classes.
• Studio Assist (word completion) to help you rapidly add components to page classes.
• Wizards for adding charts, elements, methods, and styles to page classes.
22.1 New Zen Application Wizard
Note:
For background information, see Zen Application Concepts and Zen Application Programming.
The Zen Tutorial chapter provides a sample New Zen Application Wizard session in the topic
Creating a Zen Application.
You can use the New Zen Application Wizard as follows:
1. Start Studio.
2.
Choose File > New or Ctrl-N or the icon.
3. Click the Custom tab.
4. Click the New Zen Application icon.
5. Click OK. The Zen Application Wizard dialog displays.
6. Enter data in the following fields:
• Package Name — Package that will contain the new application class.
• Class Name — Class name of the new application class.
Using Zen 445

Zen Wizards
• Application Name — Logical name of the application.
• Description — Any text that you want to use to describe the application.
7. Click Finish. The dialog closes and your new Zen application class displays in Studio.
8. Modify the Zen application class as desired.
To supply style definitions that apply to all pages in this application, use the Zen Style Wizard to
edit XData Style or set the CSSINCLUDES class parameter.
9.
Choose Build > Compile or Ctrl-F7 or the
icon.
22.2 New Zen Component Wizard
Note:
For background information, see Custom Components.
You can use the New Zen Component Wizard as follows:
1. Start Studio.
2.
Choose File > New or Ctrl-N or the
3. Click the Custom tab.
4. Click the New Zen Component icon.
icon.
5. Click OK. The Zen Component Wizard dialog displays.
6. Enter data in the following fields:
• Package Name — Package that will contain the new component class.
• Class Name — Class name of the new component class.
• Type — Choose a parent class for the component:
- component — See Creating Custom Components
- composite — See Building Composite Components
- control — See Zen Controls and Custom Components
- svgComponent — See Zen and SVG and Creating a Custom Meter
• XML Namespace — If the component is a composite, you must reference this namespace when
you place the component on a Zen page, using the syntax . A
446 Using Zen

namespace also helps to organize other types of custom component; see the chapter Custom
Components, topic XML Namespace.
• Description — Any text that you want to use to describe the component.
7. Click Finish. The dialog closes and your new Zen component class displays in Studio.
8. Modify the Zen component class as desired:
New Zen Page Wizard
• Be sure to implement the %DrawHTML method. The wizard provides a template for this
method in the class.
• If you want to supply style definitions for the custom component, consult the chapter Custom
Components, topic Custom Style. You can use the Zen Style Wizard to add style definitions.
9.
Choose Build > Compile or Ctrl-F7 or the
icon.
22.3 New Zen Page Wizard
Note:
For background information, see Zen Application Concepts and Zen Application Programming.
The Zen Tutorial chapter provides a sample New Zen Page Wizard session in the topic Creating
a Zen Page.
You can use the New Zen Page Wizard as follows:
1. Start Studio.
2.
Choose File > New or Ctrl-N or the icon.
3. Click the Custom tab.
4. Click the New Zen Page icon.
5. Click OK. The Zen Page Wizard dialog displays.
6. Enter data in the following fields:
• Package Name — Package that will contain the new page class.
• Class Name — Class name of the new page class.
• Application — Package and class name of the application that this page belongs to.
• Page Name — Logical name of this page within its application.
• Domain — Domain this page will use for localization of caption text.
Using Zen 447

Zen Wizards
• Description — Any text that you want to use to describe the page.
• Page type — Choose one of the following:
- Page — Normal page class.
- Subclass of Template Page — Subclass of a template page class. If you choose this option,
the Super class combo box displays. If you click the down-arrow in this box, a list of
page class names displays. The list is alphabetical by package name. Choose a page class
from this listp;.
7. Click Next.
8. Choose an initial page layout:
• Column 2 — Two columns, plus space for a title along the top
• Title Page — Space for a title along the top
• Default — No pre-defined layout
9. Click Finish. The dialog closes and your new Zen page class displays in Studio.
10. Modify the Zen page class as desired:
• To supply style definitions for the page, use the Zen Style Wizard to edit XData Style.
• To supply page contents, edit XData Contents. Within XData Contents you may add components
using Studio Assist or the Zen Element Wizard. A wizard is also available for adding
charts.
• To add server-side and client-side methods, use the Zen Method Wizard.
11.
12.
Choose Build > Compile or Ctrl-F7 or the icon.
Choose View > Web Page or the icon. The page displays in the browser.
22.4 New Zen Report Wizard
Note:
For background information and a sample wizard session, see Zen Reports.
You can use the New Zen Report Wizard as follows:
1. Start Studio.
448 Using Zen

New Zen Report Wizard
2.
Choose File > New or Ctrl-N or the icon.
3. Select the Custom tab.
4. Click the New Zen Report icon.
5. Click OK. The Zen Report Wizard dialog displays.
6. Enter data in the following fields:
• Package Name — Package that will contain the report class.
• Class Name — Report class name.
• Application — Package and class name of the application that this report belongs to.
• Report Name — Logical name of this report within its application.
• Description — Any text that you want to use to describe the report.
7. Click Next. The wizard prompts for an SQL query to provide data for the report.
8. Type an SQL query into the text box
9. Click Finish. The dialog closes and your new Zen report class displays in Studio.
10. Find the following text in the XData ReportDefinition block:
Delete this comment. Add a element between and the closing element.
Note:
For background information, see the Zen Reports topic XData ReportDefinition.
11. Find the following text in the XData ReportDisplay block.
Delete this comment. Add a element between and the closing element.
Note:
For background information, see the Zen Reports topic XData ReportDisplay.
12. Set the DEFAULTMODE class parameter value to indicate the report output format.
13. Modify the Zen report class as desired.
14.
15.
Choose Build > Compile or Ctrl-F7 or the icon.
Choose View > Web Page or the icon. The report displays in the browser.
Using Zen 449

Zen Wizards
22.5 Studio Assist
Note:
The Zen Tutorial chapter explores Studio Assist in the topics Hello World and Creating a
Zen Page.
You can use Studio Assist (word completion as you type) within Zen classes as follows:
1. Start Studio.
2. Open a Zen page or report class.
3. Position the cursor in one of the following elements:
• XData Contents, between and
• XData ReportDefinition, between and
• XData ReportDisplay, between and
4. Begin typing. At the first meaningful character, Studio provides a context-sensitive list of appropriate
XML elements and attributes. This list includes the built-in Zen components as well as any
custom or composite components that you have defined.
5. To choose an item from this list, click on it and press Enter.
6. Studio completes the word and adds it to the code.
22.6 Zen Chart Wizard
Note:
For background information, see Zen Charts.
Every chart is an SVG component as described in Zen and SVG. This means that charts follow the
layout and style conventions for SVG components, with the additional characteristics described in Zen
Charts. Most importantly, a Zen chart must appear within an container. Remember this
when adding a chart to XData Contents.
You can use the Zen Chart Wizard as follows:
1. Start Studio.
2. Open the class.
3. Position the cursor inside XData Contents.
4. Press CTRL-T to display the list of Zen templates.
450 Using Zen

Zen Chart Wizard
5. Select the Zen Chart Wizard.
6. Click OK. The Zen Chart Wizard dialog displays.
7. The Type field presents a list of chart types.
• barChart — See Bar Charts
• diffChart — See Difference Charts
• hilowChart — See High/Low Charts
• lineChart — See Line Charts
• pieChart — See Pie Charts
• xyChart — See Scatter Diagrams
8. Choose a chart type.
9. Click Next. The Zen Chart Wizard displays a split screen:
• At left is an illustration of how the current attributes affect chart style.
• At right is a list of attributes. Above this list, you can click Chart, X Axis, or Y Axis to view
the attributes for these different aspects of the chart.
10.
To provide a value for any attribute, click in the field beside it. A popup button displays in
the field. Click on the popup button. The Zen Value Editor dialog pops up. The entry field in this
dialog is sensitive to the data type of the property. For example:
• If the type is boolean, the dialog provides a checkbox.
• If one value must be selected from a set, the dialog displays radio buttons.
• If the type is a CSS style definition, the CSS Declaration Editor pops up.
• If the type is a JavaScript expression, a text area offers room to type the entry.
In all cases, a brief description of the property appears on the dialog, below the entry field. For
details, and for descriptions of how the individual properties work together, you can find documentation
in the chapter Zen Charts.
Click OK to save your changes and return to the Zen Chart Wizard. The list of chart attributes now
contains your entry. You may repeat this step as often as needed to supply attributes for this chart.
11. To accept the result of all your changes to this chart definition, click Finish. The Zen Chart Wizard
dialog closes and the completed chart definition appears in the XData Contents block of your Zen
page class.
Using Zen 451

Zen Wizards
22.7 Zen Element Wizard
Note:
For background information, see Zen Layout.
You can use the Zen Element Wizard as follows:
1. Start Studio.
2. Open the class.
3. Position the cursor inside XData Contents.
4. Press CTRL-T to display the list of Zen templates.
5. Select the Zen Element Wizard.
6. Click OK. The Zen Element Wizard dialog displays.
7. In the Element field, click the down-arrow to display a dropdown list of Zen components. This
list includes the built-in Zen components as well as any custom or composite components that
you have defined. Components in this list are sorted alphabetically by package name, so the order
is:
• Auxiliary components, such as for
• Built-in Zen components, such as
• User-defined components, such as composites or custom components
8. Click on a component name.
9. Click Next. The Zen Element Wizard displays an alphabetical list of the properties of the component
that you selected.
10. To provide a value for any property, click the Edit button beside its name. The Zen Value Editor
dialog pops up. The entry field in this dialog is sensitive to the data type of the property. For
example:
• If the type is boolean, the dialog provides a checkbox.
• If one value must be selected from a set, the dialog displays radio buttons.
• If the type is a CSS style definition, the CSS Declaration Editor pops up.
• If the type is a JavaScript expression, a text area offers room to type the entry.
In all cases, a brief description of the property appears on the dialog, below the entry field. For
details, and for descriptions of how the individual properties work together, you can find documentation
in this manual, particularly:
452 Using Zen

Zen Method Wizard
• Zen Layout
• Zen Style
• Zen Tables
• Zen and SVG
• Zen Charts
• Zen Forms
• Zen Controls
• Model View Controller
• Zen Navigation
• Popup Windows and Dialogs
• Other Zen Components
• Custom Components
Click OK to save your changes and return to the Zen Element Wizard. The list of properties now
contains your entry. You may repeat this step as often as needed to supply values for properties
of this component.
11. To accept the result of all your changes to this component definition, click Finish. The Zen Element
Wizard dialog closes and the completed component definition appears in the XData Contents
block of your Zen page class.
22.8 Zen Method Wizard
Note:
For background information, see Zen Application Programming. The Zen Tutorial chapter
provides sample Zen Method Wizard sessions in the topics Step 3: Client-side Method and
Step 5: Server-side Method.
You can use the Zen Method Wizard as follows:
1. Start Studio.
2. Open a Zen page class.
3. Position the cursor at the end of the class, but before the final closing brace }.
4. Press CTRL-T to display the list of Zen templates.
5. Select the Zen Method Wizard.
Using Zen 453

Zen Wizards
6. Click OK. The Zen Method Wizard dialog displays.
7. Choose a method Scope, either instance or class.
8. Choose a Location where the method will execute, and enter a Method Name.
By convention, method execution and names are related as follows. See the chapter Zen Tutorial,
topic Zen Naming Conventions for details:
Location Choice
runs on the client
runs on the server
is only available on the server
is a server-side callback for a component
Method Type
Client-only
Zen method
Server-only utility
Server-only callback
Naming
Convention
myMethod
MyMethod
%MyMethod
MyMethod
9. If you choose the option is a server-side callback for a component in the previous step, the Zen
Method Wizard dialog adds a Server-side callback field. This field offers a dropdown list of
attributes whose value is the name of a server-side callback method. These include attributes such
as OnSubmitForm or OnDrawContent. Choose a component and attribute from
this list.
The Server-side callback entry adds a comment to your method body, reminding you which component
and attribute you intend to associate with this callback method. You must still add the
relevant attribute to the component definition in XData Contents, but the reminder can be useful
as you work with the class.
10. In the Description field, enter any text that you want to use to describe the method.
11. Leave the Try/Catch box checked if you want the wizard to write a try/catch error processing
template into your method. For details, see the Using Caché ObjectScript chapter, Error Processing.
In a client-side method the template looks like this:
Method mMethod() [Language = JavaScript]
{
try {
alert('Client Method');
// TODO: implement
}
catch (ex) {
zenExceptionHandler(ex,arguments);
}
}
In a server-side method the template looks like this
454 Using Zen

Zen Style Wizard
Method MyMethod() [ZenMethod]
{
Try {
// TODO: implement
&js
}
Catch(ex) {
&js
}
Quit
}
To skip this feature, uncheck the Try/Catch box.
12. Click Finish. The dialog closes and your new method definition displays within the Zen page class
in Studio.
13. Implement the method as desired.
22.9 Zen Style Wizard
Note:
For background information, see Zen Style.
You can use the Zen Style Wizard as follows:
1. Start Studio.
2. Open the class whose XData Style block you want to edit.
3. Within the XData Style block, position the cursor between and .
4. Press CTRL-T to display the list of Zen templates.
5. Select the Zen Style Wizard.
6. Click OK. A list of pre-defined styles appears. This list is organized alphabetically by component
name. As discussed in the chapter Zen Style, topic Overriding Built-in Styles, some of the component
names may be unfamiliar. These are the parent classes for components that you actually place
on the Zen page. For example, to edit styles for tablePane (the child) you must select styles from
the list provided for simpleTablePane (the parent).
7. Scroll down the list to see the styles that it offers.
8. Select the radio button next to the name of the CSS style you want to edit.
9. Click Next. The Zen Style Wizard echoes your selection and provides a sample of its current
appearance.
10. Click Edit. The CSS Declaration Editor displays. You can add, remove, or edit statements as many
times as needed to define the CSS rule.
Using Zen 455

Zen Wizards
11. To add a CSS name-value pair:
• Click on the item --New-- in the CSS Declarations text box.
• Click the down-arrow on the Property box to display an alphabetized list of CSS argument
names (background-color, font-weight, width, etc). Click on a name to choose it.
• Either type a CSS value in the Value field or click the Edit button to display the CSS Value
Editor.
• The CSS Value Editor is sensitive to the values that can be entered for the CSS argument you
chose. If there is a fixed list of options, you can choose them from a dropdown list. If there
is the option of typing in a value other than the fixed list, you can do that too.
• If you choose a compound CSS style argument such as border-top, the editor prompts you
for each choice independently, for example:
- width — thin, medium, thick, 1px, 2px, 3px, 4px, inherit
- style — none, hidden, dotted, dashed, solid, double, groove, ridge, inset, outset, inherit
- color — A dropdown list of standard CSS color names including black, blue, red, darkred,
etc. Alternatively you can click the Browse button to display a detailed color choice
dialog where you can make a visual color selection. When you click on a color sample
in this dialog and click OK, Zen provides this color to your CSS statement as an HTML
color value.
The result is then something like this: border-top: 1px solid #70DFF0;
• Click OK to save your changes and return to the CSS Declaration Editor. The CSS Declarations
text box now contains the new name-value pair, as well as any others you have previously
added.
12. To remove a CSS name-value pair:
• Click on the corresponding line in the CSS Declarations text box.
• Click the Remove button to the right of the Property box.
• Click OK to save your changes and return to the CSS Declaration Editor. The CSS Declarations
text box no longer displays the name-value pair that you removed.
13. To edit a CSS name-value pair:
• Click on the corresponding line in the CSS Declarations text box.
• Either type a CSS value in the Value field or click the Edit button to display the CSS Value
Editor.
• Use the CSS Value Editor to choose and enter values as in step 11.
456 Using Zen

• Click OK to save your changes and return to the CSS Declaration Editor. The CSS Declarations
text box now contains the modified version of the name-value pair, as well as any others you
have previously added.
14. When you are satisfied with your modifications in the CSS Declaration Editor dialog, click OK.
The Zen Style Wizard echoes your choices and displays a sample of the resulting style. After
examining this sample you may do one of the following:
• To resume changes to this style definition, return to step 10.
Zen Style Wizard
• To accept the result of all your changes to this style definition, click Finish. The Zen Style
Wizard dialog closes and the completed style definition appears in the XData Style block of
your class.
Using Zen 457

Index
Symbols
$$$Text, 396
$$$TextHTML, 396
$$$TextJS, 396
$DATASOURCE, 439
$LOG, 441
$MODE, 438
&html
%Attr, 348
%DrawHTML, 343
OnDrawCell, 82
OnDrawContent
expando, 281
html element, 47
%application, 365
%Attr, 348
%composite, 365
%DrawHTML, 28, 343
%GetEventHandlers, 348
%id, 252
%MakeId, 346
%OnGetSubtitle, 301
%OnGetTitle, 301
%OnSubmit, 164
%page, 366
%query, 365
%seriesCount, 252
%seriesNames, 252
%session, 365
%this, 366
%url, 365
%val, 414
%zenContext, 367
A
action, 175
aggregate, 415
AJAX, 376
align
components, 57
line, 432
table, in reports, 434
altcolor, 434
animate, 113
APPLICATION, 364
APPLICATIONNAME, 362
applications, 31
programming, 361
security, 391
wizard, 445
see also %application
APPLYBUTTON, 302
att, 425
Attr
see %Attr
attribute, 415
autoExecute, 92
AUTOLOGOUT, 364
autoRefresh, 225
autoValidate, 158
auxColumn, 198
axes, 152
B
backgroundStyle
charts, 146
radialNavigator, 123
svgFrame, 105
backgroundTimerInterval, 379
bandLower, 146
bandLowerStyle, 146
bandUpper, 146
bandUpperStyle, 146
barChart, 131
baseValue, 152
block, 429
body, 427
bodyHeight, 84
breakOnExpression, 419
breakOnField, 419
browsers, 4
button, 174
buttonCaption, 193
buttonImage, 193
buttonImageDown, 193
buttonTitle, 194
Using Zen 459

C
Caché Server Pages, 25
calendar, 202
caption
button, 174
checkbox, 179
datatype, and localization, 400
expando, 282
links, 264
locatorLink, 266
menus, 269
radialNode, 124
radioButton, 184
reports, 435
submit, 175
tab, 279
tablePane, 84
captionClass, 179
radioButton, 184
radioSet, 183
case-sensitivity, 22
cellAlign, 51
cellSize, 51
cellStyle
condition, 85
groups, 51
cellTitle, 82
cellVAlign, 52
chartFilled, 130
chartPivot
barChart, 132
hilowChart, 135
lineChart, 130
charts, 127
axis attributes, 152
barChart, 131
common attributes, 145
diffChart, 133
hilowChart, 135
lineChart, 129
ongetData, 143
pieChart, 138
reports, 436
wizard, 450
xAxis, 152
xyChart, 136
yAxis, 152
chartStacked
barChart, 132
lineChart, 130
checkbox, 178
childIndent
dynaTree, 320
expando, 282
choiceColumn, 198
class
attribute
for aggregate, 416
in reports, 428
element, in reports, 424
clearSnapshot, 88
client and server, 25
clientType, 170
code examples, 23
colExpression, 82
colName
column, 82
condition, 85
color, 432
color definitions, 337
colorList, 180
colorPane, 311
colorPicker, 180
colorSelect, 300
cols, 177
column, 81
columnHeaders, 199
columnName, 214
combobox, 191
comboType, 194
components
common attributes, 57
concepts, 37
layout, 43
security, 392
wizard, 446
see also SVG components
composite, 328
see also %composite
condition, 57, 85
containerStyle, 58
CONTAINS, 86
content, 306
controlClass, 170
controller
see Model View Controller
460 Using Zen

controllerId
charts, 144
data views, 226
dynaGrid, 215
forms, 159, 166
meters, 113
controls, 155
button, 174
calendar, 202
checkbox, 178
colorPicker, 180
combobox, 191
common attributes, 169
dataCombo, 195
dataListBox, 189
dateText, 205
dynaForm, 243
dynaGrid, 207
fileUpload, 179
hidden, 207
image, 174
label, 176
listBox, 188
password, 177
radioButton, 183
radioSet, 180
select, 185
submit, 175
text, 176
textarea, 177
controlStyle, 170
count, 433
createComponent, 288
CSP, 25
CSS
cascade of styles, 63
custom components, 334
overriding styles, 65
style wizard, 455
cssinclude, 425
CSSINCLUDES
application class, 362
page class, 364
currCol, 312
currColumn
dynaGrid, 215
tablePane, 97
currPage
dynaGrid, 215
tablePane, 88
currRow
colorPane, 312
dynaGrid, 215
currSlice, 312
currTab, 275
D
dashboards, 101
dataBinding
controls, 170
data views, 226
meters, 113
dataCombo, 195
dataController, 222
dataFields, 436
dataGlobal, 320
dataGroup, 436
dataListBox, 189
dataSource, 73
DATASOURCE, 411
see also $DATASOURCE
dateText, 205
dayList, 203
defaultGroupId, 166
DEFAULTMODE, 411
defaultSeries, 223
defs, 336
delay, 194
demo applications, 7
dialog windows, 299
dictionary, message, 396
diffChart, 133
disabled
controls, 170
groups, 52
links, 264
menus, 269
svgFrame, 105
svgGroup, 109
displayColumns, 199
displayList
combobox, 192
radioSet, 181
select, 186
document, 424
DOMAIN
and dialogs, 302
Using Zen 461

and localization, 400
page class parameter, 364
dragCanvas, 105
DrawHTML
see %DrawHTML
dropdownHeight, 194
dropdownWidth, 194
dynaForm, 166
control labels, 241
control selection, 243
dynaGrid, 207
DYNAMICPROPERTIES, 253
dynaTree, 316
dynaView, 322
E
editable, 194
editMode, 105
element
in reports, 414
on pages
layout, 43
wizard, 452
emptyCaption, 183
enclosingClass, 58
enctype, 159
endYear, 203
EQ, 86
escape, 298
events
%GetEventHandlers, 348
charts
get chart labels, 147
update chart, 143
user clicks, 151
colorPane, 313
controls, 171
dataController, 224
dynaGrid, 216
dynaTree, 321
dynaView, 324
eventHandler, 341
expando, 283
forms, 159
link, 264
lookoutMenu, 278
menus
submenus, 271
user clicks, 270
meters, 114
modalGroup, 297
ownerDraw, 125
radialNavigator, 123
radialNode, 124
SVG components, 110
svgFrame, 106
tablePane
row and column selection, 96
user key clicks, 95
tabs, 275
timer, 309
zenEvent, 367
examples, 23
expandable, 277
expanded
expando, 282
lookoutMenu, 278
expando, 279
expression, 415
runtime, 368
EXTEQ, 86
extraColumnWidth, 84
F
face, 312
field attribute
for element, 415
for item, 431
fieldSet, 309
fileSelect, 300
fileUpload, 179
filterEnum, 90
filterEnumDisplay, 90
filterLabel, 90
filterOp, 91
filterQuery, 91
filtersDisabled, 92
filterTitle, 91
filterType, 91
filterValue, 91
findElement, 347
findSVGElement, 347
firstDayOfWeek, 203
fixedHeaders, 84
462 Using Zen

fixedMonth, 203
fo, 437
footer, 430
footerHeight
document, 424
formatNumber, 431
forms, 155
common attributes, 158
controls, 169
dynamic, 166
Model View Controller, 228
submit, 164
validation, 162
frameAlign, 307
frameBorder, 307
frameStyle, 105
fuelGauge, 115
G
gapWidth, 203
getComponentById, 286
getDialogValue, 301
GetEventHandlers
see %GetEventHandlers
getRowData, 88
graphics
dynamic, using SVG, 101
static images
clickable, 174
display-only, 307
gridLabel, 215
gridStyle, 147
gridX, 105
gridY, 106
groupByClause, 74
groupClass, 52
groups
in reports
list, 433
table, 434
XData ReportDefinition, 418
XData ReportDisplay, 429
on pages
common attributes, 50
dialog windows, 299
dynaForm, 166
expando, 279
fieldSet, 309
form, 158
forms, 155
hgroup, 48
layout, 48
menus, 267
modal groups, 285
page, 45
pane, 54
repeatingGroup, 313
svgGroup, 109
tabs, 271
vgroup, 49
groupStyle, 52
groupTitle, 297
GT, 86
GTEQ, 87
H
header, 82, 430
headerHeight
document, 424
headerLayout, 93
height
components, 58
document, 424
gridRow, 212
img, 431
SVG components, 110
help
menus, 269
hgroup, 48
see also groups
hidden, 207
column, 82
components, 58
gridColumn, 214
gridRow, 212
SVG components, 110
highLampColor
fuelGauge, 116
lightBar, 118
speedometer, 120
Using Zen 463

highStyle, 117
hilowChart, 135
hmenu, 270
HOMEPAGE, 362
horizontal, 48
href
cssinclude, 426
link, 264
locatorLink, 266
xslinclude, 426
HTML, 3
see also &html
html element
for page titles, 47
for static HTML content, 305
in reports, 438
HTMLSTYLESHEET, 412
hubStyle, 123
I
id
components, 58
locatorLink, 266
modelId, 224
SVG components, 111
see also %id
iframe, 307
image
attribute, for list, 433
element, on pages, 174
menus, 269
imageContracted
dynaTree, 320
expando, 282
imageExpanded
dynaTree, 320
expando, 282
imageHeight, 269
imageWidth, 269
img, 430
import, 58
independentOdometer, 120
indicatorLamp, 116
initialExecute, 73
invalid, 171
invalidDateMessage, 206
invalidMessage
controls, 171
forms, 159
item, 431
itemCount, 191
J
JavaScript, 14, 375
JSINCLUDES
application class, 362
page class, 364
K
key, 159
L
label
components, 59
dynaForm, 241
element, in forms, 176
gridColumn, 214
gridRow, 212
meter components, 113
labelAngle, 152
labelClass, 59
labelPosition, 52
labelStyle
axes, 152
charts, 147
components, 59
meter components, 114
labelsVisible, 147
labelUnits, 152
labelValues, 437
language, application locale and, 395
lastUpdate, 99
layout
components, 43
groups, 52
svgFrame, 106
svgGroup, 109
table, in reports, 435
see also style
legend, 311
legendHeight, 149
legendLabelStyle, 150
legendStyle, 150
legendVisible, 150
legendWidth, 150
464 Using Zen

legendX, 150
legendY, 150
length, 433
lightBar, 118
line
between groups, 429
for line breaks, 432
lineChart, 129
lineHeight, 433
link
column, 93
element, in navigation, 263
item, 432
menus, 269
linkCaption, 93
linkConfirm, 94
linkResource, 270
list, 433
listBox, 188
common attributes, 189
listHeight, 189
listWidth, 189
loadingMessage, 199
localization, 395
locatorBar, 265
locatorLink, 266
LOG
see $LOG
logo
fuelGauge, 116
speedometer, 120
longdesc, 307
lookoutMenu, 275
lowLampColor
fuelGauge, 116
lightBar, 118
speedometer, 120
lowStyle, 117
LT, 87
LTEQ, 87
M
mainLabel, 123
mainLabelStyle, 123
majorGridLines, 153
majorGridStyle, 153
majorUnits, 153
makeId, 346
see also %MakeId
marginBottom
charts, 146
document, 424
marginLeft
charts, 146
document, 424
marginRight
charts, 146
document, 424
marginTop
charts, 146
document, 424
markerScale, 149
markerShapes, 149
markerStyle, 149
markersVisible, 149
maxDate
calendar, 203
dateText, 206
maxlength
combobox, 194
fileUpload, 179
password, 177
text, 176
maxRows
radioSet, 182
select, 187
tables, 74
maxValue, 153
menu, 267
menuItem, 268
menuSeparator, 271
message dictionary, 396
meters, 112
common attributes, 113
custom, 353
fuelGauge, 115
indicatorLamp, 116
lightBar, 118
smiley, 119
speedometer, 119
trafficLight, 121
method
aggregate, 416
conventions, 375
wizard, 453
Using Zen 465

minDate
calendar, 204
dateText, 206
minorGridLines, 153
minorGridStyle, 153
minorUnits, 153
minValue, 153
modalGroup, 285
MODE
see $MODE
modelClass, 223
modelId, 224
Model View Controller, 219
month, 204
monthList, 204
multiColumn, 199
multiSelect, 97
MVC, 219
N
name
att, 425
components, 59
CSS style class, in reports, 425
element, 415
group
XData ReportDefinition, 419
XData ReportDisplay, 430
locatorLink, 266
report, 423
SVG components, 111
naming conventions, 22
navigation
tables, 89, 95
NEQ, 87
nextPage
forms, 159
submit, 176
nodeStyle, 123
normalStyle, 117
nowrap, 84
O
odometerValue, 120
offsetX, 106
offsetY, 106
okCaption, 297
onaction, 297
onactivate, 271
onblur, 171
onchange
colorPane, 313
controls, 171
dynaTree, 321
dynaView, 324
forms, 159
onchangecell, 216
onclick
controls, 171
dynaTree, 321
dynaView, 324
link, 264
menus, 270
radialNode, 124
SVG components, 110
onclickcolumn, 216
onclickrow, 216
oncontract
expando, 283
lookoutMenu, 278
oncreate, 224
OnCreateResultSet
group, in reports, 420
tablePane, 77
ondblclick
colorPane, 313
controls, 171
dynaTree, 321
dynaView, 324
tablePane, 97
ondefault, 160
ondelete, 224
ondragCanvas, 106
ondrawcell, 216
OnDrawCell, 82
OnDrawContent
expando, 283
html, 307
OnDrawFilter, 91
OnDrawItem, 191
oneditcell, 216
onelementClick, 151
onerror, 224
OnExecuteResultSet, 77
onexpand
expando, 283
466 Using Zen

lookoutMenu, 278
onfocus, 171
ongetData, 143
ongetLabelX, 147
ongetLabelY, 147
OnGetNodeInfo, 321
OnGetPropertyInfo, 166
OnGetQuickLinks, 266
OnGetSubtitle
see %OnGetSubtitle
OnGetTitle
see %OnGetTitle
OnGetViewContents, 324
onheaderClick, 97
onhideGroup, 297
onhideTab, 275
oninvalid, 160
onkeydown, 172
onkeypress
controls, 172
tablePane, 95
onkeyup, 172
OnLoadForm, 160
onmousedown, 172
onmouseout, 172
onmouseover, 172
onmouseup, 172
onmouseWheel, 106
onmoveItem, 106
onmultiselect, 97
onnotifyController, 224
onnotifyView
charts, 144
data views, 226
dynaGrid, 217
forms, 160, 167
meters, 114
onPopupAction, 299
onrender, 125
onrenderPlotArea, 148
onreset, 160
onresizeItem, 107
onsave, 224
onselectItem, 107
onselectNode, 123
onselectrow, 97
onshowGroup, 297
onshowHelp, 271
onshowTab, 275
onsubmit
controls, 172
forms, 161
see also %OnSubmit
OnSubmitForm, 160
ontimeout, 309
onvalidate
controls, 172
forms, 161
onzoom, 107
option
combobox, 192
listBox, 188
optionValue, 184
orderByClause, 75
orient, 435
originalValue, 172
ownerDraw, 125
P
p, 434
page, 31
element, 45
programming, 363
security, 392
template page, 53
wizard, 447
see also %page
pagebreak
attribute, for group, 430
element, in reports, 434
pagefooter, 427
pageheader, 427
PAGENAME, 364
pageSize, 88
PAGETITLE, 364
pane, 54
dialog window, 301
see also groups
panel
see fieldSet
paneName, 54
parameters
dynaTree, 318
dynaView, 322
queries, 80
SVG page references, 108
Zen application class, 362
Using Zen 467

Zen component class, 329
Zen datatype, 338
Zen page class, 363
Zen page URI, 373
Zen report class, 410
paramName
dynaTree, 318
dynaView, 323
password, 177
pattern, 433
PDF
as report output, 403
configuring Zen for PDF output, 440
pieChart, 138
pieScale, 138
plotAreaStyle, 148
plotBy, 138
plotStyle, 148
plotToEdge, 148
popup windows
dialogs, 299
modal groups, 285
predicate, 86
preserveAspectRatio, 111
preserve mode, exceptions to, 27
Q
query
dataCombo, 196
list box
dataListBox, 190
select, 187
property parameters for, 254
radioSet, 182
repeatingGroup, 314
report, 420
to define a table, 73
see also %query
queryClass
group, in reports, 420
radioSet, 182
select, 187
tables, 76
queryName
group, in reports, 420
radioSet, 182
select, 187
tables, 76
R
radialNavigator, 122
radialNode, 122
radioButton, 183
radioSet, 180
rangeLower, 114
rangeUpper, 114
readOnly
controls, 172
gridColumn, 214
gridRow, 213
readOnlyMessage, 161
READONLYMODEL, 253
rect, 109
refLineStyle, 134
remember
expando, 283
tab groups, 275
repeatingGroup, 313
see also tables
REPORTNAME, 412
reports, 403
common attributes, 428
wizard, 448
XData ReportDefinition, 413
XData ReportDisplay, 421
REPORTXMLNAMESPACE, 412
required, 173
requiredMessage, 173
RESOURCE, 364
rowCount, 99
rowLabelWidth, 217
rowName, 213
rows
dynaView, 324
textarea, 177
rowSelect, 97
rowStyle, 86
runtime expression, 368
runtimeMode, 420
rx, 110
S
SAMPLES, 23
scaleFactor, 114
scrolling, 307
scrollIntoView, 194
468 Using Zen

searchKeyLen, 199
security
Zen application, 391
Zen component, 392
Zen page, 392
seed
column, 82
html, 307
modalGroup, 297
select, 185
selectedIndex
combobox, 195
dynaTree, 321
dynaView, 324
listBox, 189
radialNavigator, 123
tablePane, 97
selectedItem, 151
selectedItemStyle, 151
selectedRows, 98
selectedSeries, 151
seriesColors
charts, 148
reports, 436
seriesCount
charts, 142
reports, 436
see also %seriesCount
seriesGroup, 437
seriesNames
charts, 148
reports, 437
see also %seriesNames
seriesSize
charts, 142
reports, 437
server and client, 25
session
see also %session
show, 295
showColumnLabels, 217
showEmpty
dataCombo, 199
select, 186
showFilters, 93
showPercentage, 138
showQuery, 77
showRowLabels, 217
showRowNumbers, 84
showRowSelector, 98
showTabBar, 275
showTime
calendar, 204
dateText, 206
showValueInTooltip, 84
showZebra, 85
size
combobox, 195
dateText, 207
fileUpload, 179
password, 177
select, 187
text, 176
slice, 59
smiley, 119
snapshot mode, for tables, 87
snapToGrid, 107
sortOrder, 96
spacer, 49
special, 432
speedometer, 119
sql
group, in reports, 420
radioSet, 182
select, 187
tables, 74
sqlLookup
dataCombo, 200
dataListBox, 191
src
iframe, 308
image, 175
img, 431
srcDisabled, 175
STARTSWITH, 87
startvalue, 433
startYear, 204, 205
streamId, 175
Studio, 7
Using Zen 469

style
attribute
column, 83
gridColumn, 214
gridRow, 213
in reports, 423, 428
link, 264
option element, in combobox, 193
option element, in listBox, 189
radialNode, 124
rect, 110
components, 57
element
XData Style, 66, 334
XData SVGStyle, 336
inheritance, 62
wizard, 455
see also layout
submit, 175
see also %OnSubmit
subtitle
dialog windows, 301
titleBox, 46
summary, 435
svgAutoSize, 107
SVG components, 101
common attributes, 110
custom style, 336
svgFrame, 102
svgGroup, 109
svgHeight, 107
svgPage, 108
svgSpacer, 109
svgWidth, 108
T
tab, 278
tabGroup, 272
tableName, 75
tableNavigator, 95
tableNavigatorBar, 95
tablePaneId, 95
tables
in reports, 434
on pages, 72
see also repeatingGroup
tabResource, 279
targetCol, 86
template page, 53
text
element, 176
language localization, 395
listBox, 189
option element
combobox, 193
listBox, 189
see also $$$Text
see also $$$TextHTML
see also $$$TextJS
textarea, 177
thickness, 433
this, 366
see also %this
thresholdLower, 114
thresholdUpper, 114
timeCaption, 205
timeout, 309
timer, 308
title
axes, 153
charts, 150
column, 83
components, 59
dialog windows, 301
fieldSet, 311
gridColumn, 214
gridRow, 213
links, 265
locatorLink, 266
page, 45
radialNavigator, 124
report, 423
titleBox, 46
titleBox, 46
titleList, 183
titlePane, 46
titleStyle
charts, 150
radialNavigator, 124
titleBox, 46
titleX, 150
titleY, 150
trafficLight, 121
translation, 395
type
aggregate, 416
list, 433
470 Using Zen

U
style, 334
style element, 66
unrestricted, 195
url
see %url
useKeys, 96
USERPACKAGES, 364
application class, 362
USERSVGPACKAGES, 364
application class, 362
useSnapshot, 88
V
val
see %val
valign, 59
value
att, 425
colorPane, 313
condition, 86
controls, 173
dialog windows
retrieving, 299
returning, 301
item, 432
meters, 115
modal groups, 290
option element
combobox, 193
listBox, 189
parameter element
dynaTree, 318
dynaView, 323
SVG page references, 108
table queries, 80
radialNode, 124
tablePane, 98
valueColumn
dataCombo, 200
tablePane, 98
valueList
combobox, 192
radioSet, 181
select, 186
vertical, 48
vgroup, 49
see also groups
view
see Model View Controller
viewBoxHeight, 111
viewBoxWidth, 111
viewType, 324
vmenu, 270
W
whereClause, 75
width
attribute, in reports, 428
column, 83
components, 59
document, 424
gridColumn, 214
img, 431
SVG components, 111
wizards, 7, 445
write, 438
WRITE
%Attr, 348
%DrawHTML, 343
OnDrawCell, 82
OnDrawContent
expando, 281
html element, 47
X
x, 111
xAxis, 152
XData Contents, 44
XData dialogBody, 301
XData for panes, 54
XData ReportDefinition, 413
XData ReportDisplay, 421
XData Style, 61
XData SVGDef, 336
XData SVGStyle, 336
XHTML, 403
XMLNamespace, 12
xmlns, 45
XSL-FO, 403
XSLFOSTYLESHEET, 412
xslinclude, 426
XSLT, 403
Using Zen 471

xyChart, 136
Y
y, 111
yAxis, 152
Z
ZENATTRS, 253
zenContext
see %zenContext
ZENCONTROL, 253
ZENDISPLAYCOLUMN, 253
ZENENCRYPT, 338
zenEvent, 367
ZENEXPRESSION, 339
ZENGROUP, 254
ZENHIDDEN, 254
ZENLABEL
and data models, 241
datatype parameter, 254
zenLaunchPopupWindow
colorSelect, 301
fileSelect, 300
popup windows, 298
utility function, 373
zenLink
popup windows, 298
utility function, 373
ZENLOCALIZE
and localization, 400
datatype parameter, 339
ZenMethod, 375
zenPage, 366
ZENREADONLY, 254
ZENSETTING, 339
ZENSIZE, 254
ZENSQL, 254
ZENSQLLOOKUP, 254
zenSynchronousMode, 373
ZENTAB, 254
zenThis, 366
ZENTITLE, 254
ZENURL, 373
zoom, 108
zoomLevels, 108
zoomWithWheel, 108
472 Using Zen