ZK Developer's Reference For ZK 6.5.4 PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information. PDF generated at: Mon, 11 Nov 2013 07:15:41 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 58 Inline Macros 61 Implement Custom Java Class 63 Composite Component 68 Client-side UI Composing 73 Event Handling 73 Event Listening 74 Event Firing 78 Event Forwarding 80 Event Queues 82 Client-side Event Listening 89 MVC 89 Controller 91 Composer 91 Wire Components 99 Wire Variables 105 Wire Event Listeners 108 Subscribe to EventQueues 110 Model 111 List Model 113 Groups Model 117 Tree Model 128 Chart Model 138 Matrix Model 139 View 142 Template 142 Listbox Template 143 Grid Template 148 Tree Template 149 Combobox Template 150 Selectbox Template 151 Biglistbox Template 151 Chosenbox Template 152 Tabbox Template 153 Renderer 155 Listbox Renderer 156 Grid Renderer 157 Tree Renderer 158 Combobox Renderer 159 Selectbox Renderer 160 Biglistbox Renderer 161 Chosenbox Renderer 162 Tabbox Renderer 162 Annotations 163 Annotate in ZUML 163 Annotate in Java 165 Retrieve Annotations 166 Annotate Component Definitions 166 MVVM 168 ViewModel 170 Initialization 172 Data and Collections 174 Commands 177 Notification 180 Data Binding 186 EL Expression 190 BindComposer 193 Binder 195 Initialization 196 Command Binding 197 Property Binding 201 Children Binding 208 Form Binding 210 Reference Binding 216 Converter 217 Validator 220 Global Command Binding 233 Collection and Selection 241 Advanced 253 Parameters 253 Binding in Special Attribute 259 Wire Variables 260 Wire Components 263 Wire Event Listeners 264 Avoid Tracking 265 Communication between ViewModel and Composer 266 Displaying Huge Amount of Data 268 Binding Annotation for a Custom Component 271 Pass Arguments to Include Component 274 Syntax 275 ViewModel 276 @Init 276 @AfterCompose 277 @NotifyChange 279 @NotifyChangeDisabled 280 @DependsOn 281 @Command 282 @DefaultCommand 283 @GlobalCommand 284 @DefaultGlobalCommand 285 @Immutable 286 Parameters 287 @BindingParam 287 @QueryParam 288 @HeaderParam 289 @CookieParam 290 @ExecutionParam 291 @ExecutionArgParam 292 @ScopeParam 293 @SelectorParam 294 @ContextParam 296 @Default 297 Data Binding 298 @id 299 @init 300 @load 301 @save 302 @bind 303 @ref 304 @command 305 @global-command 306 @converter 307 @validator 308 @template 309 Configuration 310 UI Patterns 315 Responsive Design 315 Message Box 325 Layouts and Containers 326 Hflex and Vflex 339 Grid's Columns and Hflex 348 Tooltips, Context Menus and Popups 355 Keystroke Handling 360 Drag and Drop 362 Page Initialization 365 Forward and Redirect 368 File Upload and Download 370 Browser Information and Control 371 Browser History Management 375 Session Timeout Management 378 Error Handling 381 Actions and Effects 384 Useful Java Utilities 387 HTML Tags 390 The html Component 391 The native Namespace 393 The XHTML Component Set 396 Long Operations 398 Use Echo Events 399 Use Event Queues 400 Use Piggyback 403 Communication 404 Inter-Page Communication 404 Inter-Desktop Communication 406 Inter-Application Communication 408 Templating 409 Composition 410 Templates 412 XML Output 414 Event Threads 416 Modal Windows 417 Message Box 418 File Upload 419 Theming and Styling 421 Molds 422 CSS Classes and Styles 423 Understanding the Theming Subsystem 425 Information about a Theme 426 Registering your Theme 427 Switching Themes 428 Providing Theme Resources 430 Resolving Theme URLs 435 Customizing Standard Themes 436 Creating Custom Themes 438 Archive-based Themes 438 Folder-based Themes 442 ZK Provided Theme 446 Internationalization 449 Locale 449 Time Zone 453 Labels 455 The Format of Properties Files 461 Date and Time Formatting 464 The First Day of the Week 466 Locale-Dependent Resources 468 Warning and Error Messages 470 Server Push 471 Event Queues 471 Synchronous Tasks 472 Asynchronous Tasks 474 Configuration 475 Clustering 478 ZK Configuration 478 Server Configuration 480 Programming Tips 481 Integration 485 Presentation Layer 485 JSP 485 Struts 489 Portal 491 ZK Filter 493 Foreign Templating Framework 495 Middleware Layer 499 Spring 499 CDI 505 EJB 509 Persistence Layer 511 JDBC 511 Hibernate 518 JPA 531 Security 540 Spring Security 540 Miscellenous 552 Google Analytics 552 Start Execution in Foreign Ajax Channel 553 Embed ZK Component in Foreign Framework 555 Performance Tips 559 Use Compiled Java Codes 559 Use Native Namespace instead of XHTML Namespace 561 Use ZK JSP Tags instead of ZK Filter 563 Defer the Creation of Child Components 565 Defer the Rendering of Client Widgets 566 Client Render on Demand 567 Listbox, Grid and Tree for Huge Data 569 Use Live Data and Paging 569 Turn on Render on Demand 569 Implement ListModel and TreeModel 572 Minimize Number of JavaScript Files to Load 576 Load JavaScript and CSS from Server Nearby 578 Specify Stubonly for Client-only Components 580 Reuse Desktops 583 Miscellaneous 584 Security Tips 585 Cross-site scripting 585 Block Request for Inaccessible Widgets 586 Denial Of Service 587 Cross-site Request Forgery 589 Performance Monitoring 591 Performance Meters 591 Event Interceptors 593 Loading Monitors 594 Testing 594 Testing Tips 595 ZATS 597 ZTL 600 Customization 601 Packing Code 601 Component Properties 603 UI Factory 605 Init and Cleanup 607 AU Services 609 AU Extensions 610 How to Build ZK Source Code 610 Handle AU Request Resend 612 Supporting Utilities 613 Logger 613 DSP 617 iDOM 618 References Article Sources and Contributors 619 Image Sources, Licenses and Contributors 626 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 [1] 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. References [1] http:/ / www. zkoss. org/ documentation#Getting_Started Architecture Overview Architecture Overview 2 From the Application Developer's Perspective The ZK application runs on the server. It can access backend resources, assemble UI with components, listen to user's activities, and then manipulate components to update UI. All of the above activities can be accomplished on the server. The synchronization of components' states between the browser and the server is done automatically by ZK and transparently to the application. When running on the server, the application has 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.