ZK Studio Userguide

SIMPLY RICH

ZKTM

Studio User GuideVersion 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


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


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/


http://www.zkoss.org/product/zk.dsp

http://www.zkoss.org/doc/devguide/

http://www.zkoss.org/doc/tutorial.dsp

http://zkoss.org/doc/quickstart/

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.


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


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.htmlhttp://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/ganymedesr1are 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.


http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/ganymedesr1

http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/ganymedesr1

http://java.sun.com/j2se/1.5.0/install.html

http://java.sun.com/javase/6/webnotes/install/index.html

http://java.sun.com/javase/downloads/index_jdk5.jsp

http://java.sun.com/javase/downloads/index.jsp

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.html

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.htmlv5.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


http://www.potix.com/smalltalks/zkstudioins/

http://tomcat.apache.org/tomcat-5.5-doc/setup.html

http://tomcat.apache.org/tomcat-6.0-doc/setup.html

http://tomcat.apache.org/

http://blog.xam.dk/archives/68-Eclipse-and-memory-settings.html

http://www.eclipsezone.com/eclipse/forums/t61618.html

http://www.eclipse.org/webtools/community/tutorials/BuildJ2EEWebApp/BuildJ2EEWebApp.html


Installation to complete the installation.


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.


http://www.zkoss.org/download/zk.dsp

http://www.zkoss.org/download/zk.dsp

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.


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.


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.


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


3.On the left side of pop-up Project Facets Window, select ZK Supports, then Click OK.


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.


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:


Create New ZUL File:

Using New File Command

You can create new ZUL file via [File]/[New]/[File] command in Eclipse main menu.


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].


(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#id457941http://www.zkoss.org/doc/devref-single/index.html#id385772 ), click Finish.


http://www.zkoss.org/doc/devref-single/index.html#id385772

http://www.zkoss.org/doc/devguide-single/index.html#id457941

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.


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.htmlOr 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.html 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





http://www.zkoss.org/smalltalks/eclipse/ek.html



http://www.zkoss.org/smalltalks/eclipse/ek.html



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.


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 <zscript>...</zscript>, <attribute name='onXXX'>...</attribute>.

2.Surround the script code with <![CDATA[ ]]>, for example:

<zscript><![CDATA[System.out.println("Hello World!");

]]></zscript>

<button label="SayHello"><attribute name="onClick"><![CDATA[

alert("Hello World!");]]></attribute>

</button>

With th add of surrounding <![CDATA[ ]]> in zscript, ZK Studio can provide powerful Content Assist and the code inside the <![CDATA[ ]]> 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 <![CDATA ]]>:

<zscript><![CDATA[

//@IMPORTimport java.io.*;


]]><![CDATA[

System.out.println("Hello World");]]></zscript>

4.When you declare method in zscript, use //@DECLARATION comment, and separate method declaration section with other zscript code by <![CDATA ]]>:

<zscript><![CDATA[

//@DECLARATIONvoid sayHello1() {

alert("Hello World 1!");}void sayHello2() {

alert("Hello World 2!");}

]]><![CDATA[

sayHello1();sayHello2();

]]></zscript>

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 (read/write access) in currently opened zul will be marked.


Mark Occurrence also works when token is in EL Expressions.

Syntax Check

Syntax Check verify the JAVA code in <zscript>...</zscript> and <attribute name='onXXX'>...</attribute> against JAVA syntax in ZUL Editor.

The script code must be enclosed in <![CDATA[ ]]>.

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.


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.


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/qs-ContentAssist.htmhttp://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 <zscript>...</zscript>, <attribute name='onXXX'>...</attribute> 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).


http://help.eclipse.org/ganymede/topic/org.eclipse.wst.sse.doc.user/topics/tsrcedt005.html

http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/gettingStarted/qs-ContentAssist.htm

http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/gettingStarted/qs-ContentAssist.htm

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.


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.


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.)


Zscript Hyperlink

You can use hyperlinking functionality just as Java Editor in Eclipse in <zscript>...</zscript> and <attribute name = "onXXX">...</attribute> 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 <zscript>...</zscript> and <attribute name = "onEventName">...</attribute> 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.


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.


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.


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.



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.


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.


Edit ZK Configuration File

The zk.xml Editor helps you to edit the configuration file (the zk.xml inside your project's WEB-INF 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


http://www.zkoss.org/doc/devref/ch07.html

Preference

Global Preference

The global preference for ZK Studio can be access by select [Window]/[Preferences] in Eclipse main menu.

Services

Error ReporterZK 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 EditorThis page is to config some presentation style of Visual Editor.


Auto restart visual editor if a project is failed to be hostingThe 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 componentCheck 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 componentsCheck 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.


ZUL Editor

This page is to config some options of ZUL Editor.


Use plugin build-in zul.xsdBecause 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 assistIf 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 triggersSet what character will auto invoke Content Assist in ZUL Editor, the default value is the same as Eclipse Java Development tools(JDT).


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 add-on library jar files in this project were out of sync.

Package Setting


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 DataThis 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


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.


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.


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


Enable mark occurrenceCheck this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost.

Enable syntax checkCheck this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost.

Enable hyperlinkingCheck 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.


Visual Editor

This preference page config the ZK library that used to generate preview result in Visual Editor.

Startup LibraryThis 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 ContentConfig 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.


Enable mark occurrenceCheck this option will enable mark occurrence feature in ZUL Editor. Turn this off to get some performance boost.

Enable syntax checkCheck this option will enable syntax check feature in ZUL Editor. Turn this off to get some performance boost.

Enable hyperlinkingCheck this option will enable Hyperlinking Navigation feature in ZUL Editor. Turn this off can get some performance boost.


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 <![CDATA[ and ]]> inside the <zscript> and <attribute> 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 right-click 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 <zscript>. 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 <![CDATA[ ]]>.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".


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/keyboardshortcuts.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-properties-source-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-javadoc-location.htm


http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-dialog-javadoc-location.htm

http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-dialog-javadoc-location.htm

http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-properties-source-attachment.htm

http://help.eclipse.org/ganymede/topic/org.eclipse.jdt.doc.user/reference/ref-properties-source-attachment.htm

http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.user/concepts/accessibility/keyboardshortcuts.htm

http://help.eclipse.org/ganymede/topic/org.eclipse.platform.doc.user/concepts/accessibility/keyboardshortcuts.htm

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


http://www.zkoss.org/smalltalks/zkstudioins/installE34.dsp#Uninstall

http://www.zkoss.org/smalltalks/zkstudioins/installE33.dsp#Uninstall

Documents

ZK Studio Userguide