ZK Developer's Reference For ZK 6.0.0 PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information. PDF generated at: Tue, 14 Feb 2012 02:00:20 CST Contents Articles ZK Developer's Reference 1 Overture 1 Architecture Overview 1 Technology Guidelines 5 Extensions 10 UI Composing 14 Component-based UI 14 ID Space 20 ZUML 24 XML Background 25 Basic Rules 28 EL Expressions 31 Scripts in ZUML 35 Conditional Evaluation 40 Iterative Evaluation 42 On-demand Evaluation 45 Include 47 Load ZUML in Java 48 XML Namespaces 52 Richlet 53 Macro Component 57 Inline Macros 61 Implement Custom Java Class 63 Composite Component 66 Client-side UI Composing 71 Event Handling 71 Event Listening 72 Event Firing 76 Event Forwarding 78 Event Queues 80 Client-side Event Listening 87 MVC 87 Controller 89 Composer 89 Wire Components 97 Wire Variables 103 Wire Event Listeners 107 Model 109 List Model 111 Groups Model 115 Tree Model 125 Chart Model 134 View 135 Template 135 Listbox Template 136 Grid Template 141 Tree Template 142 Combobox Template 143 Selectbox Template 144 Renderer 144 Listbox Renderer 145 Grid Renderer 146 Tree Renderer 147 Combobox Renderer 148 Selectbox Renderer 149 Annotations 150 Annotate in ZUML 150 Annotate in Java 152 Retrieve Annotations 152 Annotate Component Definitions 153 MVVM 154 ViewModel 156 Initialization 158 Data and Collections 159 Commands 162 Notification 165 Data Binding 171 EL Expression 175 BindComposer 177 Binder 179 Initialization 180 Command Binding 181 Property Binding 184 Children Binding 189 Form Binding 191 Converter 196 Validator 198 Global Command Binding 208 Advance 215 Parameters 216 Wire Components 221 Access Arguments 222 Avoid Tracking 223 Syntax 224 ViewModel 224 @Init 224 @NotifyChange 225 @NotifyChangeDisabled 227 @DependsOn 228 @Command 229 @GlobalCommand 230 @Immutable 231 Parameters 232 @BindingParam 232 @QueryParam 233 @HeaderParam 234 @CookieParam 235 @ExecutionParam 236 @ExecutionArgParam 237 @ScopeParam 238 @SelectorParam 239 @ContextParam 241 @Default 243 Data Binding 244 @id 245 @init 246 @load 247 @save 248 @bind 249 @command 250 @global-command 251 @converter 252 @validator 253 @template 254 UI Patterns 255 Message Box 255 Layouts and Containers 256 Hflex and Vflex 269 Grid's Columns and Hflex 277 Tooltips, Context Menus and Popups 283 Keystroke Handling 288 Drag and Drop 290 Page Initialization 293 Forward and Redirect 296 File Upload and Download 298 Browser Information and Control 299 Browser History Management 303 Session Timeout Management 306 Error Handling 309 Actions and Effects 312 HTML Tags 315 The html Component 315 The native Namespace 317 The XHTML Component Set 320 Long Operations 322 Use Echo Events 323 Use Event Queues 324 Use Piggyback 327 Communication 328 Inter-Page Communication 328 Inter-Desktop Communication 330 Inter-Application Communication 332 Templating 333 Composition 334 Templates 336 XML Output 338 Event Threads 340 Modal Windows 341 Message Box 342 File Upload 343 Theming and Styling 345 Molds 346 CSS Classes and Styles 347 Theme Customization 349 Theme Providers 351 Internationalization 356 Locale 356 Time Zone 359 Labels 361 The Format of Properties Files 367 Date and Time Formatting 370 The First Day of the Week 372 Locale-Dependent Resources 374 Warning and Error Messages 376 Server Push 377 Event Queues 377 Synchronous Tasks 378 Asynchronous Tasks 380 Configuration 381 Clustering 383 ZK Configuration 383 Server Configuration 386 Programming Tips 386 Integration 390 Use ZK in JSP 390 Spring 394 JDBC 398 Hibernate 404 Struts 411 Portal 413 ZK Filter 415 CDI 417 EJB and JNDI 418 Google Analytics 421 Embed ZK Component in Foreign Framework 422 Start Execution in Foreign Ajax Channel 425 Use ZK as Fragment in Foreign Templating Framework 427 Performance Tips 431 Use Compiled Java Codes 431 Use Native Namespace instead of XHTML Namespace 434 Use ZK JSP Tags instead of ZK Filter 436 Defer the Creation of Child Components 437 Defer the Rendering of Client Widgets 438 Client Render on Demand 439 Listbox, Grid and Tree for Huge Data 440 Use Live Data and Paging 440 Turn on Render on Demand 441 Implement ListModel and TreeModel 443 Minimize Number of JavaScript Files to Load 445 Load JavaScript and CSS from Server Nearby 447 Specify Stubonly for Client-only Components 449 Reuse Desktops 452 Miscellaneous 453 Security Tips 454 Cross-site scripting 454 Block Request for Inaccessible Widgets 455 Performance Monitoring 456 Performance Meters 457 Event Interceptors 458 Loading Monitors 459 Testing 459 Testing Tips 460 ZTL 462 Customization 463 Packing Code 463 Component Properties 465 UI Factory 467 Init and Cleanup 469 AU Services 471 AU Extensions 472 How to Build ZK Source Code 472 Supporting Utilities 474 Logger 474 DSP 477 iDOM 479 References Article Sources and Contributors 480 Image Sources, Licenses and Contributors 486 ZK Developer's Reference 1 ZK Developer's Reference If you are new to ZK, you might want to take a look at the Tutorial and ZK Essentials sections first. Documentation:Books/ZK_Developer's_Reference If you have any feedback regarding this book, please leave it here. <comment>http:/ / books. zkoss. org/ wiki/ ZK_Developer's_Reference</comment> Overture The ZK Developer's Reference is a reference of general features and advanced topics. If you are new to ZK, you might want to start with the Tutorial and ZK Essentials sections first. For information on individual components, please refer to ZK Component Reference. For information on ZUML, please refer to the ZUML Reference. Architecture Overview Architecture Overview 2 From the Application Developer's Perspective The ZK application runs on the server. It can access to backend resources, assemble UI with components, listen to user's activity, and then manipulate components to update UI. All of the above activities can be accomplished on the server. The synchronization of the states of the components between the browser and the server is done automatically by ZK and transparently to the application. When running on the server, the application can access to full Java technology stacks. User activities, such as Ajax and Server Push, are abstracted to event objects. UI are composed by POJO-like components. It is the most productive approach to develop a modern Web application. With ZK's Server+client Fusion architecture, your application will never stop running on the server. The application can enhance the interactivity by adding optional client-side functionality, such as client-side event handling, visual effect customizing or even UI composing without server-side coding. ZK enables seamless fusions ranging from pure server-centric to pure client-centric. You can have the best of two worlds: productivity and flexibility. From the Component Developer's Perspective Each UI object in ZK consists of a component and a widget. A component is a Java object running on the server representing a UI object which can be manipulated by a Java application. A component has all the behavior of a UI object except that it does not have a visual part. A widget is a JavaScript object[1] running at the client. This object represents the UI object which interacts with the user. Therefore, a widget usually has a visual appearance and it handles events happening at the client. The relationship between a component and a widget is one-to-one. However, if a component is not attached to a page, there will not be a corresponding widget at the client. On the other hand, the application is allowed to instantiate widgets at the client directly without a corresponding component. How state synchronization and load distribution might occur depends really on the component. The ZK Client Engine and the Update Engine will work together to provide an elegant and robust channel to simplify the implementation. For example, assuming that we want to implement a component that allows a user to click on a DOM element to show some detailed information of a component and there are at least two approaches to implement it. Firstly, we could load the detailed information to the client when the widget is instantiated, and then show the details with pure client code. Alternatively, we may choose not to load the detailed information at the very beginning before sending a request back to the server for fulfilling the details when the user clicks on it. Obviously, the first approach consumes more bandwidth at the initial request but at the same time it also provides faster responses when users click on the DOM element. This is generally more transparent to the application developers, and the implementation of a component can be enhanced later as the project progresses. Architecture Overview 3 [1] It depends on the client. For Ajax-enabled browsers, it is a JavaScript object. For ZK Reach for Android (http:/ / code. google. com/ p/ zkreach/ ), it is a Java object running on an Android device. Execution Flow of Loading a Page 1. When a user types a URL or clicks a hyperlink in the browser, a request is sent to the Web server. If the requested URL matches with the ZK's configured URL pattern[1] , a ZK loader will be invoked to serve this request. 2. The ZK loader loads a specified page and interprets that page to create proper components accordingly[2] . 3. After interpreting the whole page, the ZK loader will render the result to an HTML page. The HTML page is then sent back to the browser accompanied with the ZK Client Engine[3] . 4. The ZK Client Engine renders the widgets into DOM elements and then inserts the DOM elements into the browser's DOM tree to make them visible to users. 5. After that, the ZK Client Engine will sit at the browser to serve requests made by the users, widgets or the applications.