ZK Studio New Features 0.9.5

__NOTOC__
{{Template:Smalltalk_Author|
|author=Peter Kuo, Engineer, Potix Corporation
|date=July 3, 2009
|version=ZK Studio 0.9.5
}}

=Version=
*[http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/galileor Eclipse 3.5.x (Galileo) with WTP platform &nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>]
*[http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/ganymedesr2 Eclipse 3.4.X (Ganymede) with WTP platform]
* ZK Version 2.4 and later

=Installation=
* [http://docs.zkoss.org/wiki/ZK_Studio_Installation_Guide Installation Guide]
* [http://www.zkoss.org/download/zkstudio.dsp Download ZK Studio]

=Introduction=
In this article, I will demonstrate the features available in ZK Studio to facilitate the development of Ajax applications.
<div style="font-size:120%">
<ul>
<li>[[#Welcome_Page | Welcome Page]] </li>
<li>[[#New_ZK_Project | New ZK Project ]] </li>
<li>[[#ZK_perspective | ZK perspective]] </li>
<li>[[#Sample_Code_Wizard | Sample Code Wizard ]] </li>
	<li>[[#Zeta : A DB Form Builder for ZK | Zeta : A DB Form Builder for ZK]] </li>
        <li>[[#WYSIWYG_Editor|WYSIWYG Editor]]
		<ul>
			<li>[[#Library_Quick_Switch | Library Quick Switch]]</li>
			<li>[[#Preview in a pure Java project|Preview in a pure Java project]]</li>
		</ul>
	</li>
	<li>[[#ZK_Style_Designer|ZK Style Designer]]</li>
  <li>[[#The ZUL widget palette|The ZUL widget palette]]
	  <ul>
  		<li>[[#ZUL Palette|ZUL Palette]]</li>
		<li>[[#Filtering|Filtering]]</li>
	   </ul>
  </li>
  <li>[[#Intelligent_Editor|Intelligent Editor]]
    <ul>
      <li>[[#Content&nbsp;Assistance&nbsp;&#40;a&#46;k&#46;a&#58;&nbsp;Code&nbsp;Assist&#41;|Content&nbsp;Assistance&nbsp;&#40;a&#46;k&#46;a&#58;&nbsp;Code&nbsp;Assist&#41;]]</li>
      <li>[[#Java_Doc_hovering|Java Doc hovering]]</li>
      <li>[[#Syntax_checking|Syntax checking]]</li>
      <li>[[#Syntax_coloring|Syntax coloring]]</li>
      <li>[[#Toggle_comment_in_ZScript_.C2.A0.C2.A0New.21|Toggle comment in ZScript &nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>]]</li>
      <li>[[#ZScript_formatting_.C2.A0.C2.A0New.21|ZScript formatting &nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>]]</li>
      <li>[[#Highlight_Occurrence|Highlight Occurrence]]</li>
      <li>[[#Hyperlink_navigation|Hyperlink navigation]]</li>
    </ul>
  </li>
  <li>[[#Smart_Assist|Smart Assist]]
     <ul><li>[[#Hierarchical_view_of_ZUL_pages|Hierarchical view of ZUL pages]]</li>
            <li>[[#Properties_view_of_ZUML_tags|Properties view of ZUML tags]]</li>
     </ul></li>
  <li>[[#Preference_settings|Preference&nbsp;settings]]</li>
  </li>
  <li>[[#Troubleshooting|Troubleshooting]]</li>
</ul>
</div>

== Welcome Page ==
The Welcome Page's aim is to provide useful links for new ZK developers.
The page uses HTML to display information and is auto updated by the ZK Studio server. The page's hyperlinks consist of two types:
*'''Action''': An action link will start a predefined ZK Studio task, such as '''Opening the ZK perspective'''
*'''Webpage''': A webpage link will take the user to the online documention or community.


The Welcome Page can be opened by clicking '''<nowiki>[Help]/[ZK Help]/[ZK Welcome Page]</nowiki>'''

== New ZK Project ==
With the release of ZK Studio 0.9.4 you no longer have to create a new '''Dynamic Web Project''' and configure the settings for ZK! You can create a new '''ZK Project''', choose your ZK Package and sit back while ZK Studio does the rest for you.


The following swf demonstrates how to create a new ZK project using Eclipse 3.4 and ZK Studio 0.9.4:
<gflash width="945" height="685">Zk_studio_094_new_zk_project.swf</gflash>

== ZK perspective ==
We have now introduced the ZK perspective, gone are the days where you would have to open each window individually. The perspective will now show default ZK Studio views automatically, including the '''Properties''' view, the '''ZUL Visual Editor''',  the '''ZK Storage View''',  the '''Outline''' and the '''ZUL Palette'''.

You can open the ZK perspective by clicking '''<nowiki>[Window]/[Open Perspective]/[Others]</nowiki>''' and selecting '''ZK'''.

The default ZK perspective:


[[Image:zk_studio_094_perspective.JPG]]

== Sample Code Wizard ==

The Sample Code Wizard aims to help new ZK developers learn how to implement ZK quickly by providing well organized examples.
You can open the Sample Code Wizard by clicking '''<nowiki>[File]/[New]/[Other]</nowiki>''' and selecting '''ZK > ZK Sample Code'''. Alternatively you can '''<nowiki>[Right click on the target project]/[New]/[Other]</nowiki>''' and select '''ZK > ZK Sample Code'''.

Currently, ZK studio provides 4 categories of sample code 

:'''Basic Samples''':
:'''Application Samples''':
:'''Data Samples''':
:'''Layout Samples''':

[[Image:zk_studio_094_sample_code.JPG]]

The following swf demos demonstrate how to add the example source files to you project using the sample wizard.
<gflash width="800" height="700">Zk_studio_094_sample_code.swf</gflash>

After selection, the zul files, java files and related resources are added to the target project.

Why not give it a try? It is a great way to learn!

In the future ZK studio will provide a mechanism for users to add their own sample code, we welcome and appreciate any contributions you want to make!

== Zeta : A DB Form Builder for ZK ==
Zeta can be used to generate CRUD functions and an interface for a table of data in seconds.

Using Zeta you can link to a Database, retrieve information, and within 7 steps generate a ZUL page which can perform all CRUD operations (Create, read, update and delete) utilizing the Model-View-Control (MVC) design pattern. 

Please note that the Zeta DB Form Builder is based upon Spring and Hibernate. If you would like to know how to integrate ZK with these technologies, this is a good start!


<gflash width="840" height="650">Zeta_demo.swf</gflash>

<!--
<nowiki>[[Image:Zeta_step_by_step_005_new_zeta_strategy.png]]</nowiki>
 -->

If you would like to know more on how to rapidly create a Zeta Form please take a look at the [[Small_Talks/2009/July/ZK_Studio_New_Features_0.9.5| Step by Step Guide]]. 

'''Notes:'''<br/>Zeta is for use with ZK version 3.6.0 and above only.

== WYSIWYG Editor ==

The ZUL Visual Editor allows you to preview the result of the currently edited zul file in an Intelligent Editor. You can open the Visual Editor by clicking <b>Window > Show View > Others > ZK > ZUL Visual Editor</b> in Eclipse menu.

<gflash width="700" height="700">ZulVEDemo.swf</gflash>

The ZUL Visual Editor will display changes in zul file instantly. Having selected a certain component in the Intelligent Editor, the component in question is marked with blue dash-lined outline in the ZUL Visual Editor and is highlighted within the Hierarchical View of the ZUL page. 

If that component has an id attribute, this id will be displayed within the visualized content area in a blue tag.

[[Image:VeIDIndicator.png]]


=== Library Quick Switch === 
By clicking the triangle button on the ZUL Visual Editor's toolbar you are able to change the ZK package which is currently used by the project. You can configure the available packages in the preferences.

[[image:zulVisualEditorMenu.png]]

===Preview in a pure Java project===
You can preview the ZUL file when not using a Dynamic Web Project. With ZKs Package management, it is easy to include ZK packages using Eclipse's Global settings. The Loading and unloading of the ZK Library is done automatically and the user is not required to manually add or remove any JAR files.


[[Image:ProjectPreferenceVusalEditorPureJava.png]]

==ZK Style Designer==
The ZK Style Designer <span style="font-style: italic;font-weight:bold">(*Note: for ZK v3.5.2 and above only.)</span> provides a friendly GUI to edit CSS styles for various ZUML components. Used alongside the ZUL Visual Editor, you can see customized results immediately.

[[Image:ZkStyleDesignerGUI.png]]

<!--
Currently supported components are:
* '''<image />'''
* '''<label />'''
* '''<hbox />'''
* '''<vbox />'''
* '''<panel />'''
* '''<listbox />''' ''default'' mold
* '''<tabbox />''' ''horizontal'' orient

We are continuously developing the other components.
-->

The following videos introduce basic usage of the ZK CSS Designer:


'''1. Customizing a component using the Style Designer'''
<gflash width="816" height="620">SDcustomCOMP.swf</gflash>


'''2. Applying the style to zul files and inspecting the rendered result in the ZUL Visual Editor:'''
<gflash width="816" height="620">SDapplytoZUL.swf</gflash>

==The ZUL widget palette==

Instead of directly typing code into the Intelligent Editor, ZK Studio provides drag-and-drop development of zul files.

===ZUL Palette===
ZUL Palette is a custom studio view and can be opened by clicking <b>Window > Show View > Others > ZK > ZUL Palette</b>.

ZUL Palette lists the components and directives of ZK as items in the palette, these items are categorized in different groups. 

You can select an item and drag it to ZUL Editor or Outline. When you drag an item to ZUL Editor, it will insert template text at the position you dropped the item. When you drag an item to Outline View on a special tree node, it will insert a template XML node in the position where you dropped the item. 


===Filtering===
The ZUL Palette now supports filtering, which means you can type component's name and find it quickly. With the aid of Visual Editor, your productivity can be boosted significantly. 
<gflash width="300" height="400">PaletteFiltering.swf</gflash>

==Intelligent Editor==

The Intelligent Editor is the editor of ZUL pages for developing AJAX applications. It currently supports editing of *.zul & *.zhtml files. 

===Content&nbsp;Assistance&nbsp;&#40;a&#46;k&#46;a&#58;&nbsp;Code&nbsp;Assist&#41;===
The content assistance works in the same manner as the functionality supplied with Eclipse's Java & JSP Editors. By pressing the Content Assistance shortcut key (the English version default is <tt>ctrl + space</tt>) the Intelligent Editor will display a list of appropriate suggestions. 


[[#CAZL|<span style="font-size:120%;font-weight:bold">Content Assistance in ZUML & XML</span>]]

The Intelligent Editor supports auto-completion.

[[Image:CodeA1.png||none|Content Assistance in ZUML & XML tag]]

[[#CAZS|<span style="font-size:120%;font-weight:bold">Content Assistance in Zscript</span>]]

Content assistance works for ZUML tags, Java code enclosed in <zscript> tags and event code blocks! 

[[Image:Zscript_content_assist.png||none|Content Assistance in <tt><zscript></tt>]]

[[#CAEL|<span style="font-size:120%;font-weight:bold">Content Assistance in EL Expression</span>]]

EL Expressions in zul files are also supported. 

[[Image:El_content_assist.png‎||none|Content Assistance in EL Expression]]

[[#JDA|<span style="font-size:120%;font-weight:bold">Content Assistance with Helper JAVA Doc</span>]]

In addition to showing the proposals list, supplementary Java documentation can be shown. 

[[Image:Javadoc.png‎||none|Show Java Doc next to Content Assistance pop-up menu]]

===Java Doc hovering===
As with Eclipse's Java editor, the Intelligent Editor will display Java Doc information when a user hovers the mouse pointer over the code. 


[[Image:JavaDocHover.png||none]]

===Syntax checking===
Supported code enclosed within <tt><zscript></tt> tags, <tt><attribute></tt> tags and the <tt><![CDATA[*information*]</tt> tag is syntactically verified automatically. The indicators on the right hand vertical ruler and the left side show appropriate error messages when clicked. 

<gflash width="640" height="450">SyntaxCheck.swf</gflash>

===Syntax coloring===
Java code enclosed within <zscript> tags, <attribute> tags and the <![CDATA[*information*]]> tag are colored appropriately according to the syntax. 

[[Image:Syntax.png||none]]

=== Toggle comment in ZScript &nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>===
Just like in java editor, you can use hot key like "ctrl+/" to toggle comment in zscript now. It will add/remove "//" for zscript code.

=== ZScript formatting &nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>===

You can format codes inside zscript now. The menu sequence is '''Source->Format'''.

===Highlight Occurrence===
Highlight Occurrence is a useful function when you need to trace certain variables or components within the code. It can show the variable both inside and outside of zscript tags. 
<gflash width="790" height="550">Mark.swf</gflash>

===Hyperlink navigation===
To use this feature just hold the <b>Ctrl</b> key and click on the portion of code you want to navigate to. Currently we support linking to URLs, Project Resources, Java classes specified in the ZUML tag attribute and code inside <tt><zscript></tt> tags utilizing default JavaScript. 

[[Image:Url_hyperlink.png‎|frame|none|Ctrl-Click the URL, jump to that file!]]


Here is the project resource hyperlink navigation; certain attributes like src or image have values which correspond to URI patterns. These resources can be opened by ZK Studio.

[[Image:Project_resource_hyperlink.png‎|frame|none|Ctrl-Click the path, jump to that resource file!]]

You can also navigate to the Java class specified in <tt>use="ClassName"</tt> attribute 

[[Image:TheUSE_hyperlink.png|frame|none|Ctrl-Click the Class Name, jump to that source file!]]

If your <tt><zscript></tt> and <tt><attribute name = "onEventName"></tt> tags contain a code section using the default JavaScript language, you can utilize Hyperlink functionality just as you would in Eclipse's Java Editor. The default keyboard shortcut F3 for the "Open Declaration" function in Eclipse is also available. 

[[image:zscriptHyperlink.png]]


In addition special attributes which point to specific Java code can also utilize hyperlinks and "Open Declaration" functionality too.

[[Image:AttrHyperlink.png]]

==Smart Assist==

ZK studio supports the following features of smart assist: 

===Hierarchical view of ZUL pages===
The whole zul page structure is shown in a tree view similar to Eclipse's Outline View, with visual icons to distinguish different elements and an additional id notation in brackets. 

[[Image:Outline.png||none]]

===Properties view of ZUML tags===

When you select a ZUML tag element in the ZUL Editor or in the Component Outline View, the associated attribute information, ordered by category, will be listed in the Eclipse's property view. 

[[Image:Property.png||none]]

Using the properties grid you are able to edit the value directly. For some properties with enumeration attributes (e.g. true/false, normal/none, left/center/right), an informative combo box editor is used to help you input the correct value.

==Preference settings==
You can configure many options of the ZUL Editor and ZUL Visual Editor in ZK Studio. These are done using Eclipse's property editor. The configuration tools even allow you to change the library path.

[[Image:ProjectPreferenceZK.png||none]]

==Troubleshooting==

:[[#Q1|1.]]
::; Q&#58; : Why can't I see the Syntax Colored zscript code in my zul page?
::; A&#58; :  You have to insert the <tt><![CDATA[</tt> and <tt>]]></tt> tag into the <tt><zscript>...</zscript></tt> and <tt><attribute name=&#34;onXXX&#34;>...</attribute></tt> code blocks.

:[[#Q2|2.]]
::; Q&#58; : I have installed the ZK Studio plugin for Eclipse. When I open a zul file by double clicking the entry in Project Explorer in Eclipse, it is opened by the Default Eclipse XML Editor ([[Image:OpenInXMLEditor.png]]) instead of the Zul File Editor ([[Image:OpenInZulEditor.png]]). What's wrong?
::; A&#58; : In some of our older documentation, it instructed ZK developers to set *.zul files to be handled by Eclipse's built-in XML Editor; this should be cleared on installation of the plug-in. 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 <tt>*.zul</tt> files.


:::[[image:zulAssoc.png]]

:::You can force Eclipse to open zul file in ZUL Editor by right-click menu entry in Navigator, Package Explorer, Project Explorer View.

:::[[Image:OpenWithZulEditor.png||none]]



:[[#Q3|3. &nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>]]
::; Q&#58; : Why do I always have JAVA Syntax Error marks [[Image:Error.png]] in my code, even if it runs correctly on ZK?
::; A&#58; : Currently you have to append two special comments: '''//@DECLARATION''' and '''//@IMPORT''' within the <tt><zscript>...</zscript></tt> code block. The <tt>//@DECLARATION</tt> tag is used when declaring classes and functions and the <tt>//@IMPORT</tt> tag is used when there is a Java import directive. These two comments can only be used once per code section surrounded with <tt><![CDATA[ ]]></tt>.<br/>If you define a class in zscript, please do not use the public access modifier, use the default access modifier.

:::<span style="color: #F39E61"><em>New&#33;</em></span>
:::Since ZK Studio 0.9.5, you don't have to add <tt>//@DECLARATION</tt>, <tt>//@IMPORT</tt> anymore. You can set it at '''Window->Preferences->ZK->ZUL Editor->Auto detect zscript for IMPORT and DECLARATION statement.''' 

:[[#Q4|4.]]
::; Q&#58; : I use non-Java Syntax such as var zoom = self.zoom in my code. Why does ZUL Editor display that the code is wrong?
::; A&#58; : Currently Syntax Checking is for Java only, so code like <tt>var zoom = self.zoom</tt> will cause warnings.

:[[#Q5|5.]]
::; Q&#58; : Why do URL Hyperlinks not work when I use <tt>src="someFile.zul"</tt>?
::; A&#58; : You have to specify Absolute URL Paths. Such as <tt>src="/someFile.zul"</tt>.

:[[#Q6|6.]]
::; Q&#58; : My code completion (Content Assist) is not working. How do I fix it?
::; A&#58; : There are some things you should verify:
<div style="margin-left:50px;">
<ol>
<li>Make sure your hot key for code completion is what you expected, and doesn't conflict with other Eclipse functions (you can define it in '''[Windows]/[Preferences]/[General]/[Keys]''').</li>
<li>Write a simple zul file:
<source lang="xml" >
<zk>
  <zscript><![CDATA[
  System.out.println("test");
  ]]><zscript>
</zk>
</source>
and see if the Content Assist can be auto-initiated inside the <tt><zscript></tt></li>
<li> If code completion within ZK Classes is not working, please make sure you have the ZK jar files in the library path of the project that contains the zul file</li>
<li> Make sure there are no other serious errors, such as grammatical or syntax errors in your zul file</li>
<li> Make sure there are no other serious errors in Eclipse's Error View

'''Note:''' To have code assist automatically invoked in ZUML tag, you can change auto content assist trigger, replace "'''.'''" with "&nbsp;".</li>
<li> Some files of the project may be out of sync. You can goto '''[Project]'''/'''[Clean]''' and  clean and rebuild the project</li>
</ol>
</div>




<comment>http://docs.zkoss.org/wiki/ZK_Studio_0.9.3_New_Features</comment>


[[Category:Small Talk]]
[[Category:ZK Studio]]

{{Template:Smalltalk_Footer|
|name=Potix Corporation
}}