Zk Studio Userguide
This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA
Overview
Download & View Zk Studio Userguide as PDF for free.
More details
- Words: 5,860
- Pages: 55
SIMPLY RICH
ZK
TM
Studio User Guide Version 0.9.1
December 2008
Potix Corporation
Copyright © Potix Corporation. All rights reserved. The material in this document is for information only and is subject to change without notice. While reasonable efforts have been made to assure its accuracy, Potix Corporation assumes no liability resulting from errors or omissions in this document, or from the use of the information contained herein. Potix Corporation may have patents, patent applications, copyright or other intellectual property rights covering the subject matter of this document. The furnishing of this document does not give you any license to these patents, copyrights or other intellectual property. Potix Corporation reserves the right to make changes in the product design without reservation and without notification to its users. The Potix logo and ZK are trademarks of Potix Corporation. All other product names are trademarks, registered trademarks, or trade names of their respective owners.
ZK Studio : User Guide
Page 2 of 55
Potix Corporation
Table of Contents Introduction................................................................................................................5 About ZK Studio.........................................................................................................5 Main Features Introduction......................................................................................6 Installation.................................................................................................................8 Prerequisite...............................................................................................................8 Java SE Development Kit (JDK)................................................................................8 Eclipse IDE for Java EE Developers...........................................................................8 Application Servers.................................................................................................9 Install ZK Studio........................................................................................................9 Begin Your First Web Project....................................................................................11 Setup and Configure ZK Library..................................................................................11 Download ZK Library:............................................................................................11 Configure ZK Library:............................................................................................11 Work with New Dynamic Web Project..........................................................................14 Create New ZUL File:............................................................................................20 Running the ZUL File:............................................................................................23 Work with Existing Dynamic Web Project.....................................................................25 Work with Java Project..............................................................................................25 Features of ZK Studio................................................................................................26 ZUL Editor...............................................................................................................26 Coding Convention while Embedding Java Code in Web page:....................................26 Mark Occurrence & Syntax Check...........................................................................27 Syntax Check.......................................................................................................28 Content Assistance...............................................................................................30 Hyperlink Navigation.............................................................................................33 ZUL file formatting................................................................................................36 ZK Studio : User Guide
Page 3 of 55
Potix Corporation
ZUL Visual Editor......................................................................................................37 WYSIWYG Development........................................................................................37 Use Visual Editor in pure Java Project......................................................................38 Ajax Widget Palette...................................................................................................39 Drag & Drop.........................................................................................................39 Name Filtering......................................................................................................39 Hierarchy View of Web Page.......................................................................................41 Drag & Drop support.............................................................................................41 Property View of UI Tag.............................................................................................42 Edit ZK Configuration File..........................................................................................43 Preference................................................................................................................44 Global Preference.....................................................................................................44 Services..............................................................................................................44 Project Properties – for Different Type of Project...........................................................48 Dynamic Web Project configured with ZK Library:.....................................................48 Dynamic Web Project without ZK Library:................................................................52 Pure Java project:.................................................................................................53 Appendix A - Q & A....................................................................................................56 Usage Issue.............................................................................................................56 Appendix B – Eclipse Configuration...........................................................................58 B-1 Config keyboard shortcuts...................................................................................58 B-2 Add Source Code and Javadoc Resource to JAR File.................................................58 Appendix C................................................................................................................59 Uninstallation...........................................................................................................59
ZK Studio : User Guide
Page 4 of 55
Potix Corporation
Introduction
About ZK Studio ZK Studio is a Eclipse IDE plug-in to help developers developing Direct Rich Internet Application (RIA) Web Application with ZK Ajax Framework rapidly. With the aid of ZK Studio, you can develop ZK Web Application easily and quickly. For information about what is ZK Ajax Framework: http://www.zkoss.org/product/zk.dsp For a quick overview of ZK Ajax Framework: http://zkoss.org/doc/quickstart/ For a tutorial about developing ZK Web Application with ZK Ajax Framework: http://www.zkoss.org/doc/tutorial.dsp For a detailed knowledge of ZK Ajax Framework: http://www.zkoss.org/doc/devguide/
ZK Studio : User Guide
Page 5 of 55
Potix Corporation
Main Features Introduction
ZK Studio has these GUI tools: (1)ZUL Editor: ZUL Editor is your main editor for editing *.zul & *.zhtml file. (2)Ajax Widget Palette: Provides a Drag & Drop component palette toolbox for ZUL File. (3)ZUL Visual Editor: It shows a instant view of zul file. (4)Hierarchy View of Web Page: It presents a tree structure view of the content in the currently selected ZUL Editor. (5)Property View of UI tag: It shows a list of applicable attribute & their value of currently selected node in ZUL Editor or Hierarchy View of Web Page.
ZK Studio : User Guide
Page 6 of 55
Potix Corporation
Besides the above GUI tools, ZK Studio also provide these features: New ZK Wizard: there are two main feature, one is to help you create or modify an existing Eclipse Dynamic Web Project to support ZK Ajax framework, the other one, New ZUL File Wizard is a wizard to create a new *.zul file easily. zk.xml Editor: It helps you to edit zk.xml, the configuration file of ZK Ajax Framework
ZK Studio : User Guide
Page 7 of 55
Potix Corporation
Installation
Prerequisite There are three softwares you need to download and install prior to use ZK Studio:
Java SE Development Kit (JDK) the version 6 or 5 are supported in order to run Eclipse IDE, download at JDK 6: http://java.sun.com/javase/downloads/index.jsp JDK 5: http://java.sun.com/javase/downloads/index_jdk5.jsp select the "Java SE Development Kit (JDK)" to download, not JRE. Installation Instructions: http://java.sun.com/javase/6/webnotes/install/index.html http://java.sun.com/j2se/1.5.0/install.html
Eclipse IDE for Java EE Developers Because ZK-Studio is an Eclipse Plug-in, so you must install Eclipse. We recommend to use the Eclipse IDE for Java EE Developers package. currently Eclipse v3.3 (Europa) http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/europawinter and v3.4(Ganymede) http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/ganymedesr1 are supported. Install: Extract the "eclipse" folder from downloaded zip file to a proper location. To make sure Eclipse IDE can be run in your system, execute the eclipse.exe (in windows environment) or eclipse (in *nix environment) in that eclipse folder to start up the Eclipse IDE.
ZK Studio : User Guide
Page 8 of 55
Potix Corporation
We recommend to set the default JRE of Eclipse to JDK, refer to the Setup/Preferences section in WTP Tutorials – Building and Running a Web Application http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.ht ml Tips: We recommend to modify some parameters in the configuration file eclipse.ini to gain performance, please refer to http://www.eclipsezone.com/eclipse/forums/t61618.html and http://blog.xam.dk/archives/68-Eclipse-and-memory-settings.html
Application Servers Before developing web applications in Java with ZK Ajax Framework, you have to install a application server. Apache Tomcat is one of the most popular Web containers, download it at http://tomcat.apache.org/ , both v5.5 and v6.x are supported. Install: Download the zip file of Tomcat distribution, extract it to a proper location (with no illegal characters or space in the path). We will have to config it with Eclipse IDE in “Running the ZUL File” section. Tips: If you are not only want to develop Web Applications, but also need to deploy them on Apache Tomcat; Here's the official installation instructions for directly running Apache Tomcat in your environment: v6.x: http://tomcat.apache.org/tomcat-6.0-doc/setup.html v5.5: http://tomcat.apache.org/tomcat-5.5-doc/setup.html
Install ZK Studio Since ZK Studio is an Eclipse plugin, we recommend to install ZK Studio via Eclipse Update Manager. It provides a better installation experience and online update mechanism for maintain our release. We have a detailed step-by-step install procedures in ZK Studio Installation Guide: http://www.potix.com/smalltalks/zkstudioins/ Please follow the link according to the Eclipse version number (v3.3 or v3.4) of your Eclipse
ZK Studio : User Guide
Page 9 of 55
Potix Corporation
Installation to complete the installation.
ZK Studio : User Guide
Page 10 of 55
Potix Corporation
Begin Your First Web Project
Setup and Configure ZK Library Download ZK Library: You have to download the ZK binary distribution in order to run or develop the ZK Web Application, please download the last one in "ZK Recommended Releases" section in http:// www.zkoss.org/download/zk.dsp and save it to a proper location. You can also extract the content, but it is not necessary.
Configure ZK Library: 1.Start the Eclipse which already has ZK Studio installed. 2.Click [Window]/[Preferences] in Eclipse main menu. 3.On the Preferences Window, select ZK/ZK Packages. 4.On the right panel of the ZK Packages preference page in Preferences Window, select Add Directory if you have extract the ZK Library zip file, point the location to the extracted file folder, then click OK; Otherwise select Add File if you didn't had extract the zip file, then select the ZK Package zip file.
ZK Studio : User Guide
Page 11 of 55
Potix Corporation
5.It will popup a confirm window, click OK.
6.Type the alias name as you like for this imported package on next window, click OK.
ZK Studio : User Guide
Page 12 of 55
Potix Corporation
7.ZK Studio will import the selected ZK Library. In ZK Packages preferences page, you can check the check box of the imported ZK Packages on the ZK Package list as the default ZK library for any ZK Web application you will create later. If you don't select anyone as a default ZK library, ZK Studio will automatically choose the latest version of those imported ZK Packages.
You can remove unwanted ZK package in ZK Packages preferences page in Preferences Window by select the row in ZK Package then click Remove.
ZK Studio : User Guide
Page 13 of 55
Potix Corporation
Work with New Dynamic Web Project Eclipse 3.3: 1.Click [File]/[New]/[Project...] in Eclipse main menu 2.Select Web/Dynamic Web Project click Next.
3.Type Project Name, click Next. 4.Select ZK Supports in Project Facet list, click Next.
ZK Studio : User Guide
Page 14 of 55
Potix Corporation
5.If you don't want to modify the default directory of Context Root, Content Directory, Java Source Directory, just click Next. 6.On the next page you can choose which ZK packages you want to use for this Dynamic Web Project. It will automatically choose the default ZK packages configured in the ZK Packages preferences
page
in
Preferences
Window
of
Eclipse.
You can select other ZK packages installed in Eclipse by click the combo box. 7.Click Finish, the New Project Wizard will setup a Dynamic Web Project ready for development.
Eclipse 3.4: 1.Click [File]/[New]/[Dynamic Web Project] in Eclipse main menu 2.Type the project name, click "Modify..." in the Configuration Column
ZK Studio : User Guide
Page 15 of 55
Potix Corporation
3.On the left side of pop-up Project Facets Window, select ZK Supports, then Click OK.
ZK Studio : User Guide
Page 16 of 55
Potix Corporation
4.Click Next 5.If you don't want to modify the default directory of Context Root, Content Directory, Java Source Directory, just click Next. 6.On the next page you can choose which ZK packages you want to use for this Dynamic Web Project. It will automatically choose the default ZK packages configured in the ZK Packages preferences page in Preferences Window of Eclipse.
ZK Studio : User Guide
Page 17 of 55
Potix Corporation
You can select other ZK packages installed in Eclipse by click the combo box. 7.Click Finish, the New Project Wizard will setup a Dynamic Web Project ready for development. Tips: You can see a ZK mark on the project's right top icon to indicate that this project is support ZK:
ZK Studio : User Guide
Page 18 of 55
Potix Corporation
Create New ZUL File:
Using New File Command You can create new ZUL file via [File]/[New]/[File] command in Eclipse main menu.
ZK Studio : User Guide
Page 19 of 55
Potix Corporation
But you have to input the ".zul" extension for that file yourself, and the newly create zul file will be empty content without any template code inside.
Using New ZUL File Wizard 1.There are two ways to open New ZUL File Wizard: (1)Right click on the opened project which has been created as Dynamic Web Project in "Project Explorer" view or "Package Explorer" view, select [New]/[ZUL].
ZK Studio : User Guide
Page 20 of 55
Potix Corporation
(2)Click [File]/[New]/[ZUL] in Eclipse main menu when you select an opened project which has been created as Dynamic Web Project. 2.Type the file name you want in File name textbox, select the options your want in the beneath check box. (you can refer to developer's guide for the meaning of these instructions: http://www.zkoss.org/doc/devguide-single/index.html#id457941 http://www.zkoss.org/doc/devref-single/index.html#id385772 ), click Finish.
ZK Studio : User Guide
Page 21 of 55
Potix Corporation
3.The newly created ZUL File will be opened in ZUL Editor.
Running the ZUL File: To run the ZUL File (that is, to run a ZK Web application in Eclipse), follow the instructions: 1.Configure Apache Tomcat server configuration in Eclipse: You have to create a valid Apache Tomcat server configuration of the Apache Tomcat Server (The extracted tomcat zip file which is described in Application Servers section) in Server/Runtime Environments preference page in Eclipse's Preference Window.
ZK Studio : User Guide
Page 22 of 55
Potix Corporation
Please refer to the "Choose a Server Runtime Environment" section in the "WTP Tutorials – Building and Running a Web Application" article on Eclipse: website http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.ht ml Or you can refer "2.Define a Server Runtime" in this smalltalk: http://www.zkoss.org/smalltalks/eclipse/ek.html 2.Create a Server instance in Eclipse's Servers View: Please follow the "Create a Server" section in the "WTP Tutorials – Building and Running a Web Application" article on Eclipse: website http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.ht ml or refer "3.Define a Server Instance" in http://www.zkoss.org/smalltalks/eclipse/ek.html to create a runnable server in Eclipse. 3.Start server, view result: Please refer to the "Start the Server", "Running the Application" and "Running the Application" sections section in the "WTP Tutorials – Building and Running a Web Application" article on Eclipse: website http://www.eclipse.org/webtools/community/tutorials/ BuildJ2EEWebApp/BuildJ2EEWebApp.html
ZK Studio : User Guide
Page 23 of 55
Potix Corporation
Work with Existing Dynamic Web Project If you create the project without selecting the ZK Supports facet during the New Dynamic Web Project Wizard, you have to set that project install the ZK Supports facet to support ZK Ajax Framework. Right click the project root node icon and select Properties. On the pop-up project preference window, select Project Facets on left part, select the ZK Support on right panel, click Apply, then click OK to close project preference window.
Work with Java Project For Eclipse Java Project which is only a Java Project, you can still have New ZUL File Wizard (but the context menu option only available in Package Explorer & Navigator view in Eclipse )& Hierarchy View of Web Page, Property View of UI Tag, Ajax Widget Palette. But if you want to preview zul file with Visual Editor, you need to do some extra configuration, refer to ZUL Visual Editor section for more detail.
ZK Studio : User Guide
Page 24 of 55
Potix Corporation
Features of ZK Studio
ZUL Editor ZUL Editor is an intelligent text editor design for authoring *.zul & *.zhtml file, when you double click the zul file or zhtml file in Navigator View, Package Explorer View, Project Explorer View, the file will be opened in ZUL Editor automatically. It provides Syntax Coloring, Syntax Check,
Mark
Occurrence,
Content
Assistance,
JAVA
Doc
Hovering,
Hyperlink
Navigation, ZUL file formatting.
Coding Convention while Embedding Java Code in Web page: 1.Use Java Language as script code language in... , ... . 2.Surround the script code with , for example:
With th add of surrounding in zscript, ZK Studio can provide powerful Content Assist and the code inside the will be syntax colored as Java code. 3.When import package in zscript, use //@IMPORT comment, and separate import section with other zscript code by :
ZK Studio : User Guide
Page 25 of 55
Potix Corporation
]]>
4.When you declare method in zscript, use //@DECLARATION comment, and separate method declaration section with other zscript code by :
Mark Occurrence & Syntax Check
Mark Occurrence: Mark Occurrence is a useful functionality when you need to trace certain variable or component accessing activities in code. It can show the variable both inside and outside zscript. Move the cursor to a certain variable, object, method or class declaration, all the correspondingtokens
ZK Studio : User Guide
(read/write
access)
in
currently
Page 26 of 55
opened
zul
will
be
marked.
Potix Corporation
Mark Occurrence also works when token is in EL Expressions.
Syntax Check Syntax
Check
verify
the
JAVA
code
in
...
and
name='onXXX' rel="nofollow">... against JAVA syntax in ZUL Editor. The script code must be enclosed in . The indicators on the right side vertical ruler can help you quickly find out how many error and where the error is in current zul file, click the marker on it can jump to the line which has grammar error.
ZK Studio : User Guide
Page 27 of 55
Potix Corporation
Also the left side markers will show the appropriate error message to guide you correct the code when you click it.
Move the mouse to the error occur position (marked with red or yellow wavy line), the error message will be shown in tooltip.
ZK Studio : User Guide
Page 28 of 55
Potix Corporation
Content Assistance Content Assistance helps you in editing zul file by provide context sensitive content as a candidate list that you can choose them directly to quickly complete the code. For basic usage scenario, please refer to eclipse official tutorial: http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/gettingStarted/qsContentAssist.htm http://help.eclipse.org/ganymede/topic/org.eclipse.wst.sse.doc.user/topics/tsrcedt005.html
ZUML & XML tag Content Assist ZUML & XML tag support content assist, you can invoke it by default Content Assist keyboard shortcut.
Zscript Content Assist Zscript Content Assist can let you coding Zscript code rapidly, it can provide you auto-complete function in... , ... code block and event attribute value in the ZUML tag. The class that is located in JAR file also can be content-assisted, and if you had set the associated source for that JAR file, the Java Doc can be shown aside the candidate list (For how to set source for a certain JAR file, refer to B-2 Add Source Code and Javadoc Resource to JAR File).
ZK Studio : User Guide
Page 29 of 55
Potix Corporation
EL Expression Content Assist Inside the EL Expression you can also invoke the Content Assist by keyboard shortcut.
ZUML Tag Attribute Content Assist The content in use & apply attribute also support Content Assist.
ZK Studio : User Guide
Page 30 of 55
Potix Corporation
Tips: Keyboard shortcut for Content Assist The default keyboard shortcut for Content Assist in English Version of Eclipse is "Ctrl + Space", you can change the keyboard shortcut in Preference Window, please refer to B-1 Config keyboard shortcuts for detail.
JAVA Doc Hovering For easily understanding the source code, ZK Studio support the JAVA Doc hovering. When move the mouse pointer on the code and stand for a while, the JAVA Doc belong to the element
that
is
under
the
mouse
pointer
will
be
shown
in
tooltip.
You need to set source or JAVA Doc for some JAR files if they don't contain source inside, refer to B-2 Add Source Code and Javadoc Resource to JAR File for how to do it.
Hyperlink Navigation Hyperlink Navigation let you easily navigate through project resource, you can invoke it by: 1.Move cursor to a certain element belongs to the content of ZUL Editor and press F3.
ZK Studio : User Guide
Page 31 of 55
Potix Corporation
2.Hold Ctrl key on keyboard, move the mouse pointer over an element, if that element can be convert to hyperlink (that is, it has the resource that we can trace to), there will be a underline for the element, and you can click the hyperlink to reach that resource.
URL Hyperlink All elements in ZUL Editor that presents an URL are able to use Hyperlink Navigation.
Project Resource Hyperlink If a literal string in zul file opened by ZUL Editor is a relative path to certain resource in this project's WebContent folder, it can be access though Hyperlink Navigation.
ZUML tag attribute Hyperlink In ZUL Editor, you can navigate to the Java class specified in use="ClassName" & apply="ClassName" attribute by Hyperlink Navigation.
(You have to set source for that class if the class is in a JAR File that doesn't had set source, refer to B-2 Add Source Code and Javadoc Resource to JAR File for how to do it.)
ZK Studio : User Guide
Page 32 of 55
Potix Corporation
Zscript Hyperlink You can use hyperlinking functionality just as Java Editor in Eclipse in... and ... code block which use the default JAVA language.
For event attribute of ZUML tag, the content Java code in that attribute value is accessible by Hyperlink Navigation.
ZUL file formatting ZUL Editor support zul file source formatting function, in the current opened zul editor, right click and select the Format option, the source code will be formatted as standard xml file, but the code content in... and ... will be preserved. Also you can use keyboard shortcut to accomplish this task, the default source format keyboard shortcut is Ctrl + Shift + F, you can config the keyboard shortcut as described in B-1 Config keyboard shortcuts.
ZK Studio : User Guide
Page 33 of 55
Potix Corporation
ZUL Visual Editor ZUL Visual Editor provides a WYSIWYG result preview of the currently edited zul file in ZUL Editor, it can be opened by clicking [Window]/[Show View]/[Others], select ZK > ZUL Visual Editor.
WYSIWYG Development ZUL Visual Editor display the result preview of the ZUL document, the preview will be updated instantly according to the changes of the content of ZUL file in ZUL Editor. When you select certain component in Intelligent Editor, that whole area of that component inside the ZUL Visual Editor will be marked with blue dash-line rectangle frame, and if that component has an id attribute, there will be a ID tag shown in the visualized content area for indication.
There are two control buttons on ZUL Visual Editor, right one is to refresh the content shown in ZUL Visual Editor, right one is to refresh preview if the ZUL Visual Editor doesn't change the preview when you update zul file, left one is used to completely restart ZUL Visual Editor when you manually change your JAR file in project's library. If you click certain component in the result preview of the ZUL Visual Editor, the corresponding code segment in ZUL Editor and the component in Hierarchy View of Web Page will be highlighted.
ZK Studio : User Guide
Page 34 of 55
Potix Corporation
There are some options for ZUL Visual Editor you can configure in ZK Studio, refer to Preference for details.
Use Visual Editor in pure Java Project ZUL Visual Editor can present the preview of your zul file even if they are in a Java Project that is not a Dynamic Project. You have to set a folder as the WebContent path in project preference and make sure at least one ZK Package has been installed in Eclipse.
ZK Studio : User Guide
Page 35 of 55
Potix Corporation
Ajax Widget Palette Ajax Widget Palette Provides a Drag & Drop component palette toolbox for ZUL File, you can open it by clicking [Window]/[Show View]/[Others], select ZK > ZUL Palette.
Drag & Drop You can select an item in Widget Palette and drag it to ZUL Editor. When you drop that item in ZUL Editor, it will insert a template text to the spot where you dropped. When you drag an item to the Hierarchy View of Web Page, it will insert a template ZUML code to appropriate position in ZUL Editor and the hierarchy of the outline will change accordingly.
Name Filtering The Ajax Widget Palette support ZUML tag name filtering, you can type the component name in the top Filter text box to search for a component, the candidate lists of components will show out.
ZK Studio : User Guide
Page 36 of 55
Potix Corporation
ZK Studio : User Guide
Page 37 of 55
Potix Corporation
Hierarchy View of Web Page Hierarchy View of Web Page presents is a tree structure view of the content in the currently selected ZUL Editor, it can be open by clicking [Window]/[Show View]/[Outline].
Drag & Drop support Each component in this tree structure has a special icon to distinguish different tag elements. Any modify on the zul file will update the tree content in Hierarchy View of Web Page immediately. You can also modify the file content by using mouse dragging node inside the Hierarchy View of Web Page or using right-click menu.
ZK Studio : User Guide
Page 38 of 55
Potix Corporation
Property View of UI Tag Property View of UI Tag is a tabulated view, list of applicable attribute & their value of currently selected node in ZUL Editor in Hierarchy View of Web Page. It can be open it by clicking [Window]/[Show View]/[Properties]. When selecting a tag in ZUL Editor or a node in Hierarchy View of Web Page, the associated attribute information of the selected tag will show in it. For some properties which are enumerations (ex: true/false, normal/none, left/center/right), an informative combo box editor is used to help you input the correct value.
ZK Studio : User Guide
Page 39 of 55
Potix Corporation
Edit ZK Configuration File The zk.xml Editor helps you to edit the configuration file (the zk.xml inside your project's WEBINF folder) of ZK Ajax Framework, it can be opened by right click the zk.xml and select [Open With]/[XML Editor for zk.xml] in context menu.
zk.xml Editor provides the content assistance functionality in editing the zk.xml configuration file, for detail description of every element in zk.xml, please refer to ZK Developer's Reference: http://www.zkoss.org/doc/devref/ch07.html
ZK Studio : User Guide
Page 40 of 55
Potix Corporation
Preference
Global Preference The global preference for ZK Studio can be access by select [Window]/[Preferences] in Eclipse main menu.
Services
Error Reporter ZK Studio can upload it's error log to Potix to improve the quality and performance for future version of ZK Studio. check this to enable error log functionality. Visual Editor This page is to config some presentation style of Visual Editor.
ZK Studio : User Guide
Page 41 of 55
Potix Corporation
Auto restart visual editor if a project is failed to be hosting The ZUL Visual Editor will try to restart if it failed to start at beginning, turn this off to improve the performance of ZUL Visual Editor. Show border when mouse over a component Check this to have a dash-line border for a certain component in preview result of Visual Editor when move mouse pointer over a component. Show border on non-selected components Check this to have a dash-line border on all components in preview result of Visual Editor. ZK Packages All the installed ZK Package in Eclipse will be listed here, you can select default ZK Package for used in creating new Dynamic Web Project. You can also add/remove installed packages in this page.
ZK Studio : User Guide
Page 42 of 55
Potix Corporation
ZUL Editor This page is to config some options of ZUL Editor.
ZK Studio : User Guide
Page 43 of 55
Potix Corporation
Use plugin build-in zul.xsd Because the Content Assist feature requires a zul.xsd file to be functional, by default it will read the zul.xsd that is already included in ZK Studio, if this option is unchecked, ZK Studio will use the zul.xsd on ZK Website. Enable auto content assist If this option has been checked, then when you type in the ZUL Editor, the Content Assist will be automatically triggered to show auto-complete candidate list when you type the Auto content assist trigger, otherwise, you have to use keyboard shortcut to invoke the Content Assist when you're editing in ZUL Editor. Auto content assist triggers Set what character will auto invoke Content Assist in ZUL Editor, the default value is the same as Eclipse Java Development tools(JDT).
ZK Studio : User Guide
Page 44 of 55
Potix Corporation
Project Properties – for Different Type of Project In the Project Explorer, Package Explorer, Navigator view of Eclipse, select Dynamic Web Project or Pure Java Project, right click and select Properties, according to the kind of project you selected, there will be different preference pages.
Dynamic Web Project configured with ZK Library: ZK
This preference page list the version number, library location, and the included add-on library list of the currently used ZK package for this project. The Refresh ZK Library button is used to refresh the above add-on library list in case of addon library jar files in this project were out of sync.
Package Setting
ZK Studio : User Guide
Page 45 of 55
Potix Corporation
This preference page is for user easily change the currently used ZK library of this project. To change the used ZK library of this project, select different ZK Package on ZK Package list and then click Apply. Force override project's existing resources When copying Data This controls whether to copy and overwrite all ZK library files from ZK Packages installed in Eclipse which are listed in Global Preference to the project when you change the applied ZK Package option.
Visual Editor This preference page config the ZK library that used to generate preview result in Visual Editor
ZK Studio : User Guide
Page 46 of 55
Potix Corporation
Startup Library This option is to config which ZK library that used to generate preview result in Visual Editor, select Use WEB-INF / lib to use the ZK library configured for this project; Select Use ZKs to use the ZK Packages installed in Eclipse which are listed in Global Preference.
ZUL Editor This preference page list some option you can turn on/off to improve the performance of ZUL Editor.
ZK Studio : User Guide
Page 47 of 55
Potix Corporation
Enable mark occurrence Check this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost. Enable syntax check Check this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost. Enable hyperlinking Check this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.
ZK Studio : User Guide
Page 48 of 55
Potix Corporation
Dynamic Web Project without ZK Library: It lacks the Package Setting preference page, to enable that page, you must install ZK Supports Facet in Project Facets page in this project's preference window, refer to Import ZK to an exist 'Dynamic Web Project section for detail.
Visual Editor This preference page config the ZK library that used to generate preview result in Visual Editor
Startup Library This option is to config which ZK library that used to generate preview result in Visual Editor, select Use WEB-INF / lib to use the ZK library configured for this project; Select Use ZKs to use the ZK Packages installed in Eclipse which are listed in Global Preference.
ZUL Editor This preference page list some option you can turn on/off to improve the performance of ZUL Editor
ZK Studio : User Guide
Page 49 of 55
Potix Corporation
Enable mark occurrence Check this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost. Enable syntax check Check this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost. Enable hyperlinking Check this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.
Pure Java project: It lacks the Package Setting preference page, to enable that page, you have to use Dynamic Web Project instead of pure Java project.
ZK Studio : User Guide
Page 50 of 55
Potix Corporation
Visual Editor This preference page config the ZK library that used to generate preview result in Visual Editor.
Startup Library This option is to config which ZK library that used to generate preview result in Visual Editor, select Use WEB-INF / lib to use the ZK library configured for this project; Because this is a pure Java Project, only the ZK Packages installed in Eclipse are applicable. WEB Content Config which folder to be the WebContent folder for this project. Tips: the WebContent folder is the folder which contains the file you need to deploy to server for this Web application.
ZUL Editor This preference page list some option you can turn on/off to improve the performance of ZUL Editor.
ZK Studio : User Guide
Page 51 of 55
Potix Corporation
Enable mark occurrence Check this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost. Enable syntax check Check this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost. Enable hyperlinking Check this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.
ZK Studio : User Guide
Page 52 of 55
Potix Corporation
Appendix A - Q & A
Usage Issue 1.Q:Why I can't see the Syntax Colored zscript code in my zul page? A:You have to insert inside the and code block. 2.Q:I have installed the ZK Studio plugin in my Eclipse. When I open a zul file by double clicking the entry in Project Explorer in Eclipse, it is not opened by the Intelligent ZUL Editor , but is opened by the Default Eclipse XML Editor . What's wrong? A:In some our older smalltalks and documents, they instructed ZK developers to set *.zul file to be handled by Eclipse's built-in XML Editor; this should be cleared before install the plugin. If not, please open the Eclipse preference setting dialog ([Window]/ [Preferences...]/General/Editors/File Associations) and set the "ZUL Editor" as the default editor for *.zul files.And You can force Eclipse to open zul file in ZUL Editor by rightclick menu entry in Navigator, Package Explorer, Project Explorer View.
3.Q:Why I always got JAVA Syntax Error mark in my code, even if it can run correctly on ZK? A:Currently you have to append two special comments: //@DECLARATION and //@IMPORT in zscript code block inside the. The //@DECLARATION is used when declaring classes and functions; the //@IMPORT is used when there is a JAVA import directive; these two comments can only be used only once in one code section surrounded with . And if you define a class in zscript, don't use the access modifier public, just use the default access modifier. 4.Q:I use the non-JAVA Syntax such as var zoom = self.zoom in my code. Why the ZUL Editor shows me that the code is wrong? A:Currently Syntax Check is for JAVA only, so the code like var zoom = self.zoom will be highlighted as warning in ZUL Editor. 5.Q:Why the URL Hyperlink doesn't work when I use src="someFile.zul"? A:You have to specify Absolute URL Path. Such as src="/someFile.zul".
ZK Studio : User Guide
Page 53 of 55
Potix Corporation
Appendix B – Eclipse Configuration
B-1 Config keyboard shortcuts Many keyboard shortcuts are configurable via Preference Window (click [Windows]/ [Preferences] in Eclipse main menu), the preference page to configure keyboard shortcuts (or so called "hotkey") is located in General/Keys preference page. Refer to the "Customizing Key bindings" section of Eclipse official help: http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.user/concepts/accessibility/ke yboardshortcuts.htm
B-2 Add Source Code and Javadoc Resource to JAR File Set source for JAR file You can attach a source archive (another JAR file which include the source code) or source folder to this library. Eclipse will then use this resource to show the source instead of a the decompiled code. Setting the source attachment also allows source level stepping with the debugger. please refer to Eclipse help: http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-propertiessource-attachment.htm The source JAR files of ZK Package is under the dist/src folder in the already extracted ZK package.
Set Javadoc for JAR file Please refer to Eclipse help: http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-dialog-javadoclocation.htm
ZK Studio : User Guide
Page 54 of 55
Potix Corporation
Appendix C
Uninstallation For uninstall ZK Studio on Eclipse 3.3: http://www.zkoss.org/smalltalks/zkstudioins/installE33.dsp#Uninstall For uninstall ZK Studio on Eclipse 3.4: http://www.zkoss.org/smalltalks/zkstudioins/installE34.dsp#Uninstall
ZK Studio : User Guide
Page 55 of 55
Potix Corporation
ZK
TM
Studio User Guide Version 0.9.1
December 2008
Potix Corporation
Copyright © Potix Corporation. All rights reserved. The material in this document is for information only and is subject to change without notice. While reasonable efforts have been made to assure its accuracy, Potix Corporation assumes no liability resulting from errors or omissions in this document, or from the use of the information contained herein. Potix Corporation may have patents, patent applications, copyright or other intellectual property rights covering the subject matter of this document. The furnishing of this document does not give you any license to these patents, copyrights or other intellectual property. Potix Corporation reserves the right to make changes in the product design without reservation and without notification to its users. The Potix logo and ZK are trademarks of Potix Corporation. All other product names are trademarks, registered trademarks, or trade names of their respective owners.
ZK Studio : User Guide
Page 2 of 55
Potix Corporation
Table of Contents Introduction................................................................................................................5 About ZK Studio.........................................................................................................5 Main Features Introduction......................................................................................6 Installation.................................................................................................................8 Prerequisite...............................................................................................................8 Java SE Development Kit (JDK)................................................................................8 Eclipse IDE for Java EE Developers...........................................................................8 Application Servers.................................................................................................9 Install ZK Studio........................................................................................................9 Begin Your First Web Project....................................................................................11 Setup and Configure ZK Library..................................................................................11 Download ZK Library:............................................................................................11 Configure ZK Library:............................................................................................11 Work with New Dynamic Web Project..........................................................................14 Create New ZUL File:............................................................................................20 Running the ZUL File:............................................................................................23 Work with Existing Dynamic Web Project.....................................................................25 Work with Java Project..............................................................................................25 Features of ZK Studio................................................................................................26 ZUL Editor...............................................................................................................26 Coding Convention while Embedding Java Code in Web page:....................................26 Mark Occurrence & Syntax Check...........................................................................27 Syntax Check.......................................................................................................28 Content Assistance...............................................................................................30 Hyperlink Navigation.............................................................................................33 ZUL file formatting................................................................................................36 ZK Studio : User Guide
Page 3 of 55
Potix Corporation
ZUL Visual Editor......................................................................................................37 WYSIWYG Development........................................................................................37 Use Visual Editor in pure Java Project......................................................................38 Ajax Widget Palette...................................................................................................39 Drag & Drop.........................................................................................................39 Name Filtering......................................................................................................39 Hierarchy View of Web Page.......................................................................................41 Drag & Drop support.............................................................................................41 Property View of UI Tag.............................................................................................42 Edit ZK Configuration File..........................................................................................43 Preference................................................................................................................44 Global Preference.....................................................................................................44 Services..............................................................................................................44 Project Properties – for Different Type of Project...........................................................48 Dynamic Web Project configured with ZK Library:.....................................................48 Dynamic Web Project without ZK Library:................................................................52 Pure Java project:.................................................................................................53 Appendix A - Q & A....................................................................................................56 Usage Issue.............................................................................................................56 Appendix B – Eclipse Configuration...........................................................................58 B-1 Config keyboard shortcuts...................................................................................58 B-2 Add Source Code and Javadoc Resource to JAR File.................................................58 Appendix C................................................................................................................59 Uninstallation...........................................................................................................59
ZK Studio : User Guide
Page 4 of 55
Potix Corporation
Introduction
About ZK Studio ZK Studio is a Eclipse IDE plug-in to help developers developing Direct Rich Internet Application (RIA) Web Application with ZK Ajax Framework rapidly. With the aid of ZK Studio, you can develop ZK Web Application easily and quickly. For information about what is ZK Ajax Framework: http://www.zkoss.org/product/zk.dsp For a quick overview of ZK Ajax Framework: http://zkoss.org/doc/quickstart/ For a tutorial about developing ZK Web Application with ZK Ajax Framework: http://www.zkoss.org/doc/tutorial.dsp For a detailed knowledge of ZK Ajax Framework: http://www.zkoss.org/doc/devguide/
ZK Studio : User Guide
Page 5 of 55
Potix Corporation
Main Features Introduction
ZK Studio has these GUI tools: (1)ZUL Editor: ZUL Editor is your main editor for editing *.zul & *.zhtml file. (2)Ajax Widget Palette: Provides a Drag & Drop component palette toolbox for ZUL File. (3)ZUL Visual Editor: It shows a instant view of zul file. (4)Hierarchy View of Web Page: It presents a tree structure view of the content in the currently selected ZUL Editor. (5)Property View of UI tag: It shows a list of applicable attribute & their value of currently selected node in ZUL Editor or Hierarchy View of Web Page.
ZK Studio : User Guide
Page 6 of 55
Potix Corporation
Besides the above GUI tools, ZK Studio also provide these features: New ZK Wizard: there are two main feature, one is to help you create or modify an existing Eclipse Dynamic Web Project to support ZK Ajax framework, the other one, New ZUL File Wizard is a wizard to create a new *.zul file easily. zk.xml Editor: It helps you to edit zk.xml, the configuration file of ZK Ajax Framework
ZK Studio : User Guide
Page 7 of 55
Potix Corporation
Installation
Prerequisite There are three softwares you need to download and install prior to use ZK Studio:
Java SE Development Kit (JDK) the version 6 or 5 are supported in order to run Eclipse IDE, download at JDK 6: http://java.sun.com/javase/downloads/index.jsp JDK 5: http://java.sun.com/javase/downloads/index_jdk5.jsp select the "Java SE Development Kit (JDK)" to download, not JRE. Installation Instructions: http://java.sun.com/javase/6/webnotes/install/index.html http://java.sun.com/j2se/1.5.0/install.html
Eclipse IDE for Java EE Developers Because ZK-Studio is an Eclipse Plug-in, so you must install Eclipse. We recommend to use the Eclipse IDE for Java EE Developers package. currently Eclipse v3.3 (Europa) http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/europawinter and v3.4(Ganymede) http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/ganymedesr1 are supported. Install: Extract the "eclipse" folder from downloaded zip file to a proper location. To make sure Eclipse IDE can be run in your system, execute the eclipse.exe (in windows environment) or eclipse (in *nix environment) in that eclipse folder to start up the Eclipse IDE.
ZK Studio : User Guide
Page 8 of 55
Potix Corporation
We recommend to set the default JRE of Eclipse to JDK, refer to the Setup/Preferences section in WTP Tutorials – Building and Running a Web Application http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.ht ml Tips: We recommend to modify some parameters in the configuration file eclipse.ini to gain performance, please refer to http://www.eclipsezone.com/eclipse/forums/t61618.html and http://blog.xam.dk/archives/68-Eclipse-and-memory-settings.html
Application Servers Before developing web applications in Java with ZK Ajax Framework, you have to install a application server. Apache Tomcat is one of the most popular Web containers, download it at http://tomcat.apache.org/ , both v5.5 and v6.x are supported. Install: Download the zip file of Tomcat distribution, extract it to a proper location (with no illegal characters or space in the path). We will have to config it with Eclipse IDE in “Running the ZUL File” section. Tips: If you are not only want to develop Web Applications, but also need to deploy them on Apache Tomcat; Here's the official installation instructions for directly running Apache Tomcat in your environment: v6.x: http://tomcat.apache.org/tomcat-6.0-doc/setup.html v5.5: http://tomcat.apache.org/tomcat-5.5-doc/setup.html
Install ZK Studio Since ZK Studio is an Eclipse plugin, we recommend to install ZK Studio via Eclipse Update Manager. It provides a better installation experience and online update mechanism for maintain our release. We have a detailed step-by-step install procedures in ZK Studio Installation Guide: http://www.potix.com/smalltalks/zkstudioins/ Please follow the link according to the Eclipse version number (v3.3 or v3.4) of your Eclipse
ZK Studio : User Guide
Page 9 of 55
Potix Corporation
Installation to complete the installation.
ZK Studio : User Guide
Page 10 of 55
Potix Corporation
Begin Your First Web Project
Setup and Configure ZK Library Download ZK Library: You have to download the ZK binary distribution in order to run or develop the ZK Web Application, please download the last one in "ZK Recommended Releases" section in http:// www.zkoss.org/download/zk.dsp and save it to a proper location. You can also extract the content, but it is not necessary.
Configure ZK Library: 1.Start the Eclipse which already has ZK Studio installed. 2.Click [Window]/[Preferences] in Eclipse main menu. 3.On the Preferences Window, select ZK/ZK Packages. 4.On the right panel of the ZK Packages preference page in Preferences Window, select Add Directory if you have extract the ZK Library zip file, point the location to the extracted file folder, then click OK; Otherwise select Add File if you didn't had extract the zip file, then select the ZK Package zip file.
ZK Studio : User Guide
Page 11 of 55
Potix Corporation
5.It will popup a confirm window, click OK.
6.Type the alias name as you like for this imported package on next window, click OK.
ZK Studio : User Guide
Page 12 of 55
Potix Corporation
7.ZK Studio will import the selected ZK Library. In ZK Packages preferences page, you can check the check box of the imported ZK Packages on the ZK Package list as the default ZK library for any ZK Web application you will create later. If you don't select anyone as a default ZK library, ZK Studio will automatically choose the latest version of those imported ZK Packages.
You can remove unwanted ZK package in ZK Packages preferences page in Preferences Window by select the row in ZK Package then click Remove.
ZK Studio : User Guide
Page 13 of 55
Potix Corporation
Work with New Dynamic Web Project Eclipse 3.3: 1.Click [File]/[New]/[Project...] in Eclipse main menu 2.Select Web/Dynamic Web Project click Next.
3.Type Project Name, click Next. 4.Select ZK Supports in Project Facet list, click Next.
ZK Studio : User Guide
Page 14 of 55
Potix Corporation
5.If you don't want to modify the default directory of Context Root, Content Directory, Java Source Directory, just click Next. 6.On the next page you can choose which ZK packages you want to use for this Dynamic Web Project. It will automatically choose the default ZK packages configured in the ZK Packages preferences
page
in
Preferences
Window
of
Eclipse.
You can select other ZK packages installed in Eclipse by click the combo box. 7.Click Finish, the New Project Wizard will setup a Dynamic Web Project ready for development.
Eclipse 3.4: 1.Click [File]/[New]/[Dynamic Web Project] in Eclipse main menu 2.Type the project name, click "Modify..." in the Configuration Column
ZK Studio : User Guide
Page 15 of 55
Potix Corporation
3.On the left side of pop-up Project Facets Window, select ZK Supports, then Click OK.
ZK Studio : User Guide
Page 16 of 55
Potix Corporation
4.Click Next 5.If you don't want to modify the default directory of Context Root, Content Directory, Java Source Directory, just click Next. 6.On the next page you can choose which ZK packages you want to use for this Dynamic Web Project. It will automatically choose the default ZK packages configured in the ZK Packages preferences page in Preferences Window of Eclipse.
ZK Studio : User Guide
Page 17 of 55
Potix Corporation
You can select other ZK packages installed in Eclipse by click the combo box. 7.Click Finish, the New Project Wizard will setup a Dynamic Web Project ready for development. Tips: You can see a ZK mark on the project's right top icon to indicate that this project is support ZK:
ZK Studio : User Guide
Page 18 of 55
Potix Corporation
Create New ZUL File:
Using New File Command You can create new ZUL file via [File]/[New]/[File] command in Eclipse main menu.
ZK Studio : User Guide
Page 19 of 55
Potix Corporation
But you have to input the ".zul" extension for that file yourself, and the newly create zul file will be empty content without any template code inside.
Using New ZUL File Wizard 1.There are two ways to open New ZUL File Wizard: (1)Right click on the opened project which has been created as Dynamic Web Project in "Project Explorer" view or "Package Explorer" view, select [New]/[ZUL].
ZK Studio : User Guide
Page 20 of 55
Potix Corporation
(2)Click [File]/[New]/[ZUL] in Eclipse main menu when you select an opened project which has been created as Dynamic Web Project. 2.Type the file name you want in File name textbox, select the options your want in the beneath check box. (you can refer to developer's guide for the meaning of these instructions: http://www.zkoss.org/doc/devguide-single/index.html#id457941 http://www.zkoss.org/doc/devref-single/index.html#id385772 ), click Finish.
ZK Studio : User Guide
Page 21 of 55
Potix Corporation
3.The newly created ZUL File will be opened in ZUL Editor.
Running the ZUL File: To run the ZUL File (that is, to run a ZK Web application in Eclipse), follow the instructions: 1.Configure Apache Tomcat server configuration in Eclipse: You have to create a valid Apache Tomcat server configuration of the Apache Tomcat Server (The extracted tomcat zip file which is described in Application Servers section) in Server/Runtime Environments preference page in Eclipse's Preference Window.
ZK Studio : User Guide
Page 22 of 55
Potix Corporation
Please refer to the "Choose a Server Runtime Environment" section in the "WTP Tutorials – Building and Running a Web Application" article on Eclipse: website http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.ht ml Or you can refer "2.Define a Server Runtime" in this smalltalk: http://www.zkoss.org/smalltalks/eclipse/ek.html 2.Create a Server instance in Eclipse's Servers View: Please follow the "Create a Server" section in the "WTP Tutorials – Building and Running a Web Application" article on Eclipse: website http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.ht ml or refer "3.Define a Server Instance" in http://www.zkoss.org/smalltalks/eclipse/ek.html to create a runnable server in Eclipse. 3.Start server, view result: Please refer to the "Start the Server", "Running the Application" and "Running the Application" sections section in the "WTP Tutorials – Building and Running a Web Application" article on Eclipse: website http://www.eclipse.org/webtools/community/tutorials/ BuildJ2EEWebApp/BuildJ2EEWebApp.html
ZK Studio : User Guide
Page 23 of 55
Potix Corporation
Work with Existing Dynamic Web Project If you create the project without selecting the ZK Supports facet during the New Dynamic Web Project Wizard, you have to set that project install the ZK Supports facet to support ZK Ajax Framework. Right click the project root node icon and select Properties. On the pop-up project preference window, select Project Facets on left part, select the ZK Support on right panel, click Apply, then click OK to close project preference window.
Work with Java Project For Eclipse Java Project which is only a Java Project, you can still have New ZUL File Wizard (but the context menu option only available in Package Explorer & Navigator view in Eclipse )& Hierarchy View of Web Page, Property View of UI Tag, Ajax Widget Palette. But if you want to preview zul file with Visual Editor, you need to do some extra configuration, refer to ZUL Visual Editor section for more detail.
ZK Studio : User Guide
Page 24 of 55
Potix Corporation
Features of ZK Studio
ZUL Editor ZUL Editor is an intelligent text editor design for authoring *.zul & *.zhtml file, when you double click the zul file or zhtml file in Navigator View, Package Explorer View, Project Explorer View, the file will be opened in ZUL Editor automatically. It provides Syntax Coloring, Syntax Check,
Mark
Occurrence,
Content
Assistance,
JAVA
Doc
Hovering,
Hyperlink
Navigation, ZUL file formatting.
Coding Convention while Embedding Java Code in Web page: 1.Use Java Language as script code language in
With th add of surrounding in zscript, ZK Studio can provide powerful Content Assist and the code inside the will be syntax colored as Java code. 3.When import package in zscript, use //@IMPORT comment, and separate import section with other zscript code by :
ZK Studio : User Guide
Page 25 of 55
Potix Corporation
]]>
4.When you declare method in zscript, use //@DECLARATION comment, and separate method declaration section with other zscript code by :
Mark Occurrence & Syntax Check
Mark Occurrence: Mark Occurrence is a useful functionality when you need to trace certain variable or component accessing activities in code. It can show the variable both inside and outside zscript. Move the cursor to a certain variable, object, method or class declaration, all the correspondingtokens
ZK Studio : User Guide
(read/write
access)
in
currently
Page 26 of 55
opened
zul
will
be
marked.
Potix Corporation
Mark Occurrence also works when token is in EL Expressions.
Syntax Check Syntax
Check
verify
the
JAVA
code
in
and
name='onXXX' rel="nofollow">... against JAVA syntax in ZUL Editor. The script code must be enclosed in . The indicators on the right side vertical ruler can help you quickly find out how many error and where the error is in current zul file, click the marker on it can jump to the line which has grammar error.
ZK Studio : User Guide
Page 27 of 55
Potix Corporation
Also the left side markers will show the appropriate error message to guide you correct the code when you click it.
Move the mouse to the error occur position (marked with red or yellow wavy line), the error message will be shown in tooltip.
ZK Studio : User Guide
Page 28 of 55
Potix Corporation
Content Assistance Content Assistance helps you in editing zul file by provide context sensitive content as a candidate list that you can choose them directly to quickly complete the code. For basic usage scenario, please refer to eclipse official tutorial: http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/gettingStarted/qsContentAssist.htm http://help.eclipse.org/ganymede/topic/org.eclipse.wst.sse.doc.user/topics/tsrcedt005.html
ZUML & XML tag Content Assist ZUML & XML tag support content assist, you can invoke it by default Content Assist keyboard shortcut.
Zscript Content Assist Zscript Content Assist can let you coding Zscript code rapidly, it can provide you auto-complete function in
ZK Studio : User Guide
Page 29 of 55
Potix Corporation
EL Expression Content Assist Inside the EL Expression you can also invoke the Content Assist by keyboard shortcut.
ZUML Tag Attribute Content Assist The content in use & apply attribute also support Content Assist.
ZK Studio : User Guide
Page 30 of 55
Potix Corporation
Tips: Keyboard shortcut for Content Assist The default keyboard shortcut for Content Assist in English Version of Eclipse is "Ctrl + Space", you can change the keyboard shortcut in Preference Window, please refer to B-1 Config keyboard shortcuts for detail.
JAVA Doc Hovering For easily understanding the source code, ZK Studio support the JAVA Doc hovering. When move the mouse pointer on the code and stand for a while, the JAVA Doc belong to the element
that
is
under
the
mouse
pointer
will
be
shown
in
tooltip.
You need to set source or JAVA Doc for some JAR files if they don't contain source inside, refer to B-2 Add Source Code and Javadoc Resource to JAR File for how to do it.
Hyperlink Navigation Hyperlink Navigation let you easily navigate through project resource, you can invoke it by: 1.Move cursor to a certain element belongs to the content of ZUL Editor and press F3.
ZK Studio : User Guide
Page 31 of 55
Potix Corporation
2.Hold Ctrl key on keyboard, move the mouse pointer over an element, if that element can be convert to hyperlink (that is, it has the resource that we can trace to), there will be a underline for the element, and you can click the hyperlink to reach that resource.
URL Hyperlink All elements in ZUL Editor that presents an URL are able to use Hyperlink Navigation.
Project Resource Hyperlink If a literal string in zul file opened by ZUL Editor is a relative path to certain resource in this project's WebContent folder, it can be access though Hyperlink Navigation.
ZUML tag attribute Hyperlink In ZUL Editor, you can navigate to the Java class specified in use="ClassName" & apply="ClassName" attribute by Hyperlink Navigation.
(You have to set source for that class if the class is in a JAR File that doesn't had set source, refer to B-2 Add Source Code and Javadoc Resource to JAR File for how to do it.)
ZK Studio : User Guide
Page 32 of 55
Potix Corporation
Zscript Hyperlink You can use hyperlinking functionality just as Java Editor in Eclipse in
For event attribute of ZUML tag, the content Java code in that attribute value is accessible by Hyperlink Navigation.
ZUL file formatting ZUL Editor support zul file source formatting function, in the current opened zul editor, right click and select the Format option, the source code will be formatted as standard xml file, but the code content in
ZK Studio : User Guide
Page 33 of 55
Potix Corporation
ZUL Visual Editor ZUL Visual Editor provides a WYSIWYG result preview of the currently edited zul file in ZUL Editor, it can be opened by clicking [Window]/[Show View]/[Others], select ZK > ZUL Visual Editor.
WYSIWYG Development ZUL Visual Editor display the result preview of the ZUL document, the preview will be updated instantly according to the changes of the content of ZUL file in ZUL Editor. When you select certain component in Intelligent Editor, that whole area of that component inside the ZUL Visual Editor will be marked with blue dash-line rectangle frame, and if that component has an id attribute, there will be a ID tag shown in the visualized content area for indication.
There are two control buttons on ZUL Visual Editor, right one is to refresh the content shown in ZUL Visual Editor, right one is to refresh preview if the ZUL Visual Editor doesn't change the preview when you update zul file, left one is used to completely restart ZUL Visual Editor when you manually change your JAR file in project's library. If you click certain component in the result preview of the ZUL Visual Editor, the corresponding code segment in ZUL Editor and the component in Hierarchy View of Web Page will be highlighted.
ZK Studio : User Guide
Page 34 of 55
Potix Corporation
There are some options for ZUL Visual Editor you can configure in ZK Studio, refer to Preference for details.
Use Visual Editor in pure Java Project ZUL Visual Editor can present the preview of your zul file even if they are in a Java Project that is not a Dynamic Project. You have to set a folder as the WebContent path in project preference and make sure at least one ZK Package has been installed in Eclipse.
ZK Studio : User Guide
Page 35 of 55
Potix Corporation
Ajax Widget Palette Ajax Widget Palette Provides a Drag & Drop component palette toolbox for ZUL File, you can open it by clicking [Window]/[Show View]/[Others], select ZK > ZUL Palette.
Drag & Drop You can select an item in Widget Palette and drag it to ZUL Editor. When you drop that item in ZUL Editor, it will insert a template text to the spot where you dropped. When you drag an item to the Hierarchy View of Web Page, it will insert a template ZUML code to appropriate position in ZUL Editor and the hierarchy of the outline will change accordingly.
Name Filtering The Ajax Widget Palette support ZUML tag name filtering, you can type the component name in the top Filter text box to search for a component, the candidate lists of components will show out.
ZK Studio : User Guide
Page 36 of 55
Potix Corporation
ZK Studio : User Guide
Page 37 of 55
Potix Corporation
Hierarchy View of Web Page Hierarchy View of Web Page presents is a tree structure view of the content in the currently selected ZUL Editor, it can be open by clicking [Window]/[Show View]/[Outline].
Drag & Drop support Each component in this tree structure has a special icon to distinguish different tag elements. Any modify on the zul file will update the tree content in Hierarchy View of Web Page immediately. You can also modify the file content by using mouse dragging node inside the Hierarchy View of Web Page or using right-click menu.
ZK Studio : User Guide
Page 38 of 55
Potix Corporation
Property View of UI Tag Property View of UI Tag is a tabulated view, list of applicable attribute & their value of currently selected node in ZUL Editor in Hierarchy View of Web Page. It can be open it by clicking [Window]/[Show View]/[Properties]. When selecting a tag in ZUL Editor or a node in Hierarchy View of Web Page, the associated attribute information of the selected tag will show in it. For some properties which are enumerations (ex: true/false, normal/none, left/center/right), an informative combo box editor is used to help you input the correct value.
ZK Studio : User Guide
Page 39 of 55
Potix Corporation
Edit ZK Configuration File The zk.xml Editor helps you to edit the configuration file (the zk.xml inside your project's WEBINF folder) of ZK Ajax Framework, it can be opened by right click the zk.xml and select [Open With]/[XML Editor for zk.xml] in context menu.
zk.xml Editor provides the content assistance functionality in editing the zk.xml configuration file, for detail description of every element in zk.xml, please refer to ZK Developer's Reference: http://www.zkoss.org/doc/devref/ch07.html
ZK Studio : User Guide
Page 40 of 55
Potix Corporation
Preference
Global Preference The global preference for ZK Studio can be access by select [Window]/[Preferences] in Eclipse main menu.
Services
Error Reporter ZK Studio can upload it's error log to Potix to improve the quality and performance for future version of ZK Studio. check this to enable error log functionality. Visual Editor This page is to config some presentation style of Visual Editor.
ZK Studio : User Guide
Page 41 of 55
Potix Corporation
Auto restart visual editor if a project is failed to be hosting The ZUL Visual Editor will try to restart if it failed to start at beginning, turn this off to improve the performance of ZUL Visual Editor. Show border when mouse over a component Check this to have a dash-line border for a certain component in preview result of Visual Editor when move mouse pointer over a component. Show border on non-selected components Check this to have a dash-line border on all components in preview result of Visual Editor. ZK Packages All the installed ZK Package in Eclipse will be listed here, you can select default ZK Package for used in creating new Dynamic Web Project. You can also add/remove installed packages in this page.
ZK Studio : User Guide
Page 42 of 55
Potix Corporation
ZUL Editor This page is to config some options of ZUL Editor.
ZK Studio : User Guide
Page 43 of 55
Potix Corporation
Use plugin build-in zul.xsd Because the Content Assist feature requires a zul.xsd file to be functional, by default it will read the zul.xsd that is already included in ZK Studio, if this option is unchecked, ZK Studio will use the zul.xsd on ZK Website. Enable auto content assist If this option has been checked, then when you type in the ZUL Editor, the Content Assist will be automatically triggered to show auto-complete candidate list when you type the Auto content assist trigger, otherwise, you have to use keyboard shortcut to invoke the Content Assist when you're editing in ZUL Editor. Auto content assist triggers Set what character will auto invoke Content Assist in ZUL Editor, the default value is the same as Eclipse Java Development tools(JDT).
ZK Studio : User Guide
Page 44 of 55
Potix Corporation
Project Properties – for Different Type of Project In the Project Explorer, Package Explorer, Navigator view of Eclipse, select Dynamic Web Project or Pure Java Project, right click and select Properties, according to the kind of project you selected, there will be different preference pages.
Dynamic Web Project configured with ZK Library: ZK
This preference page list the version number, library location, and the included add-on library list of the currently used ZK package for this project. The Refresh ZK Library button is used to refresh the above add-on library list in case of addon library jar files in this project were out of sync.
Package Setting
ZK Studio : User Guide
Page 45 of 55
Potix Corporation
This preference page is for user easily change the currently used ZK library of this project. To change the used ZK library of this project, select different ZK Package on ZK Package list and then click Apply. Force override project's existing resources When copying Data This controls whether to copy and overwrite all ZK library files from ZK Packages installed in Eclipse which are listed in Global Preference to the project when you change the applied ZK Package option.
Visual Editor This preference page config the ZK library that used to generate preview result in Visual Editor
ZK Studio : User Guide
Page 46 of 55
Potix Corporation
Startup Library This option is to config which ZK library that used to generate preview result in Visual Editor, select Use WEB-INF / lib to use the ZK library configured for this project; Select Use ZKs to use the ZK Packages installed in Eclipse which are listed in Global Preference.
ZUL Editor This preference page list some option you can turn on/off to improve the performance of ZUL Editor.
ZK Studio : User Guide
Page 47 of 55
Potix Corporation
Enable mark occurrence Check this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost. Enable syntax check Check this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost. Enable hyperlinking Check this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.
ZK Studio : User Guide
Page 48 of 55
Potix Corporation
Dynamic Web Project without ZK Library: It lacks the Package Setting preference page, to enable that page, you must install ZK Supports Facet in Project Facets page in this project's preference window, refer to Import ZK to an exist 'Dynamic Web Project section for detail.
Visual Editor This preference page config the ZK library that used to generate preview result in Visual Editor
Startup Library This option is to config which ZK library that used to generate preview result in Visual Editor, select Use WEB-INF / lib to use the ZK library configured for this project; Select Use ZKs to use the ZK Packages installed in Eclipse which are listed in Global Preference.
ZUL Editor This preference page list some option you can turn on/off to improve the performance of ZUL Editor
ZK Studio : User Guide
Page 49 of 55
Potix Corporation
Enable mark occurrence Check this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost. Enable syntax check Check this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost. Enable hyperlinking Check this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.
Pure Java project: It lacks the Package Setting preference page, to enable that page, you have to use Dynamic Web Project instead of pure Java project.
ZK Studio : User Guide
Page 50 of 55
Potix Corporation
Visual Editor This preference page config the ZK library that used to generate preview result in Visual Editor.
Startup Library This option is to config which ZK library that used to generate preview result in Visual Editor, select Use WEB-INF / lib to use the ZK library configured for this project; Because this is a pure Java Project, only the ZK Packages installed in Eclipse are applicable. WEB Content Config which folder to be the WebContent folder for this project. Tips: the WebContent folder is the folder which contains the file you need to deploy to server for this Web application.
ZUL Editor This preference page list some option you can turn on/off to improve the performance of ZUL Editor.
ZK Studio : User Guide
Page 51 of 55
Potix Corporation
Enable mark occurrence Check this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost. Enable syntax check Check this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost. Enable hyperlinking Check this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.
ZK Studio : User Guide
Page 52 of 55
Potix Corporation
Appendix A - Q & A
Usage Issue 1.Q:Why I can't see the Syntax Colored zscript code in my zul page? A:You have to insert inside the
3.Q:Why I always got JAVA Syntax Error mark in my code, even if it can run correctly on ZK? A:Currently you have to append two special comments: //@DECLARATION and //@IMPORT in zscript code block inside the
ZK Studio : User Guide
Page 53 of 55
Potix Corporation
Appendix B – Eclipse Configuration
B-1 Config keyboard shortcuts Many keyboard shortcuts are configurable via Preference Window (click [Windows]/ [Preferences] in Eclipse main menu), the preference page to configure keyboard shortcuts (or so called "hotkey") is located in General/Keys preference page. Refer to the "Customizing Key bindings" section of Eclipse official help: http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.user/concepts/accessibility/ke yboardshortcuts.htm
B-2 Add Source Code and Javadoc Resource to JAR File Set source for JAR file You can attach a source archive (another JAR file which include the source code) or source folder to this library. Eclipse will then use this resource to show the source instead of a the decompiled code. Setting the source attachment also allows source level stepping with the debugger. please refer to Eclipse help: http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-propertiessource-attachment.htm The source JAR files of ZK Package is under the dist/src folder in the already extracted ZK package.
Set Javadoc for JAR file Please refer to Eclipse help: http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-dialog-javadoclocation.htm
ZK Studio : User Guide
Page 54 of 55
Potix Corporation
Appendix C
Uninstallation For uninstall ZK Studio on Eclipse 3.3: http://www.zkoss.org/smalltalks/zkstudioins/installE33.dsp#Uninstall For uninstall ZK Studio on Eclipse 3.4: http://www.zkoss.org/smalltalks/zkstudioins/installE34.dsp#Uninstall
ZK Studio : User Guide
Page 55 of 55
Potix Corporation
