New Features of ZK Studio 0.9.2

__NOTOC__

<div style="border:1px solid #cccccc;background:#EDFFEA;font-weight:bold;padding:2px 5px;">
New features for latest ZK studio, Please refer to [[Small_Talks/2009/December/ZK_Studio_New_Features | ZK Studio New Features]]
</div>

{{Template:Smalltalk_Author|
|author=Charles Pao, Engineer, Potix Corporation
|date=January 15, 2009
|version=ZK Studio 0.9.2
}}

=Version=
*[http://www.eclipse.org/downloads/moreinfo/jee.php Eclipse 3.4.X (Ganymede) with WTP platform]
*[http://www.eclipse.org/downloads/moreinfo/jee.php Eclipse 3.3.X (Europa) with WTP platform]
* ZK Version 2.4 and later

=Installation=
* [[Small_Talks/2008/November/ZK_Studio_Installation_Guide |Installation Guide]]
* [http://www.zkoss.org/download/zkstudio.dsp Download ZK Studio]

=Introduction=
In this article, I'll demonstrate those features in ZK Studio to facilitate developing Ajax application.
<div style="font-size:120%">
<ul>
	<li>[[#WYSIWYG_Editor|WYSIWYG Editor]]
		<ul>
			<li>[[#Library_Quick_Switch&nbsp;&nbsp;New&#33;|Library Quick Switch&nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>]]</li>
			<li>[[#Preview_in_Pure_Java_Project|Preview in Pure Java Project]]</li>
		</ul>
	</li>
	<li>[[#ZK_Style_Designer&nbsp;&nbsp;New&#33;|ZK Style Designer&nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>]]</li>
  <li>[[#Ajax_Widget_Palette|Ajax 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_Check|Syntax Check]]</li>
      <li>[[#Syntax_Coloring|Syntax Coloring]]</li>
      <li>[[#Mark_Occurrence|Mark Occurrence]]</li>
      <li>[[#Hyperlink_Navigation|Hyperlink Navigation]]</li>
    </ul>
  </li>
  <li>[[#Smart_Assist|Smart Assist]]
     <ul><li>[[#Hierarchy_View_of_ZUL_Page|Hierarchy View of ZUL Page]]</li>
            <li>[[#Property View of ZUML Tag|Property View of ZUML Tag]]</li>
     </ul></li>
  <li>[[#Preference&nbsp;Setting|Preference&nbsp;Setting]]</li>
  </li>
  <li>[[#Troubleshooting|Troubleshooting]]</li>
</ul>
</div>

==WYSIWYG Editor==
The ZUL Visual Editor can let you preview the result of the currently edited zul file in 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 your changes in zul file instantly, and when you select certain component in Intelligent Editor, that component shown inside the ZUL Visual Editor will be marked with blue dash-line rectangle frame, and if you click certain component inside the ZUL Visual Editor, the corresponding code segment in Intelligent Editor and the component in Hierarchy View of ZUL Page will also be highlighted, if that component has an id attribute, there is a blue tag shown in the visualized content area for indication.

[[Image:VeIDIndicator.png]]


===Library Quick Switch&nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>=== 
The ZUL Visual Editor can not only preview the result via the current project that the zul file reside in, but also the ZK packages that configured in ZK Package setting in Preference, you can easily change the applied package of ZUL Visual Editor by a drop-down menu that invoked by the triangular button on its toolbar.

[[image:zulVisualEditorMenu.png]]


===Preview in Pure Java Project===
You can preview the ZUL file result even if the project is only a pure Java Project. With the ZKs Package management, it is very convenient to manage ZK packages in Eclipse Global setting and the ZK Library using in your project via project Preference. Loading / unload ZK Library can be done without user manually removes JAR files in his project.


[[Image:ProjectPreferenceVusalEditorPureJava.png]]

==ZK Style Designer&nbsp;&nbsp;<span style="color: #F39E61"><em>New&#33;</em></span>==
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 interface to edit CSS styles for various ZUML components, used with ZUL Visual Editor, you can see customized result immediately.

[[Image:ZkStyleDesignerGUI.png]]


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

Other components are continuously developing.

You can customize a component with Style Designer:
<gflash width="816" height="620">SDcustomCOMP.swf</gflash>
And you can apply the style to zul files and immediately inspect the rendering result in ZUL Visual Editor:
<gflash width="816" height="620">SDapplytoZUL.swf</gflash>

==Ajax Widget Palette==

Instead of directly typing code in Intelligent Editor, ZK Studio provides a drag-and-drop development to edit zul file.

===ZUL Palette===
ZUL Palette is a custom view of studio, you can open it by clicking '''Window > Show View > Others > ZK > ZUL Palette'''.

ZUL Palette shows the full components/directives of ZK as an item in palette, those 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 a template text to the position where you dragged. When you drag an item to Outline View on a special tree node, it will insert a template XML node to the position where you dragged.

===Filtering===
The ZUL Palette now supports filtering, which means you can type component's name and find it quickly. And with the aid of Visual Editor, it can boost the coding speed greatly.
<gflash width="300" height="400">PaletteFiltering.swf</gflash>

==Intelligent Editor==

The Intelligent Editor is the file editor of ZUL pages for developing ajax application, it supports editing *.zul & *.zhtml files.

===Content&nbsp;Assistance&nbsp;&#40;a&#46;k&#46;a&#58;&nbsp;Code&nbsp;Assist&#41;===

As the Content Assistance functionality in Java Editor and JSP Editor in Eclipse, Now just press the Content Assistance shortcut key (default in English version of Eclipse is <code>ctrl + space</code>), and the Intelligent Editor will pop up for you the proper suggestions in a list.

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

The Intelligent Editor supports auto-complete.

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

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

Works not only for ZUML tag, but also for Java codes in <code><zscript></code> and event code blocks!

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

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

The EL Expression in zul file is 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 in Content Assistance, the supplementary Java Doc can be shown aside.

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

===JAVA Doc Hovering===
Just as the Java Editor in Eclipse, the Intelligent Editor will also pop up Java Doc when a user hovers the mouse pointer on the code.

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

===Syntax Check===
Codes in <code><zscript></code> element and <code><attribute></code> element, enclosed in <code><![CDATA[</code> and <code>]]></code> with default JAVA scripting language, are verified against Java syntax automatically. The indicators on the right side vertical ruler and the left side markers will show the appropriate message to guide you correct the code.
<gflash width="640" height="450">SyntaxCheck.swf</gflash>

===Syntax Coloring===
Codes in <code><zscript></code> element and <code><attribute></code> element, enclosed in <code><![CDATA[</code> and <code>]]></code> with default JAVA scripting language are supported with syntax coloring.

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

===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.
<gflash width="790" height="550">Mark.swf</gflash>

===Hyperlink Navigation===
Press <b>Ctrl</b> key and click mouse button on the portion of code you want to navigate to. Currently we support link to URL, Project Resource, and the Java class as specified in the use ZUML tag attribute and code inside the <code><zscript></code> with the default JAVA script language.

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


Here is the Project Resource Hyperlink Navigation, certain attribute like src or image which has value of URI-like patterns, ZK Studio can open the resource that attribute value specified.

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

And you can navigate to the Java class specified in <code>use="ClassName"</code> attribute

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

You can use Hyperlink functionality just as Java Editor in Eclipse in <code><zscript>...</zscript></code> and <code><attribute name = "onEventName">...</attribute></code> code section which use the default JAVA script language. And the default keyboard shortcut '''F3''' for the <em>&#34;Open Declaration&#34;</em> function in Eclipse is also available.

[[image:zscriptHyperlink.png]]


And some special attribute which points to specific JAVA code can also have hyperlinking and <em>&#34;Open Declaration&#34;</em> function too.

[[Image:AttrHyperlink.png]]

==Smart Assist==

ZK studio supports the following features of smart assist:

===Hierarchy View of ZUL Page===
It can show you the whole zul page structure in a tree view like in Eclipse Outline View, with visual icons to distinguish different tag elements and an additional id notation in parentheses to distinguish the same kind of tag element.

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

===Property View of ZUML Tag===

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

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

Certainly, you can 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&nbsp;Setting==
There are many options for Intelligent ZUL Editor and WYSIWYG ZUL Visual Editor of ZK Studio that you can config, and the library path used in project can be config in its preference setting.

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

==Troubleshooting==

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

:[[#Q2|2.]]
::; Q&#58; : 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 Editor ([[Image:OpenInZulEditor.png]]), but is opened by the Default Eclipse XML Editor([[Image:OpenInXMLEditor.png]]). What's wrong?
::; A&#58; : 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 <code>*.zul</code> files.


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

:::And 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.]]
::; Q&#58; : Why I always got JAVA Syntax Error mark [[Image:Error.png]] in my code, even if it can run correctly on ZK?
::; A&#58; : Currently you have to append two special comments: '''//@DECLARATION''' and '''//@IMPORT''' in zscript code block inside the <code><zscript>...</zscript></code>. The <code>//@DECLARATION</code> is used when declaring classes and functions; the <code>//@IMPORT</code> is used when there is a JAVA import directive; these two comments can only be used only once in one code section surrounded with <code><![CDATA[ ]]></code>.<br/>And if you define a class in zscript, don't use the access modifier public, just use the default access modifier.

:[[#Q4|4.]]
::; Q&#58; : 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&#58; : Currently Syntax Check is for JAVA only, so the code like <code>var zoom = self.zoom</code> will cause warning.

:[[#Q5|5.]]
::; Q&#58; : Why the URL Hyperlink doesn't work when I use <code>src="someFile.zul"</code>?
::; A&#58; : You have to specify Absolute URL Path. Such as <code>src="/someFile.zul"</code>.

:[[#Q6|6.]]
::; Q&#58; : The code completion (Content Assist) is not working. How do I solve 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 function in Eclipse (you can define it in '''[Windows]/[Preferences]/[General]/[Keys]''').</li>
<li>Write a simple zul:
<source lang="xml" >
<zk>
  <zscript><![CDATA[
  System.out.println("test");
  ]]><zscript>
</zk>
</source>
see if the Content Assist can be auto-initiated inside the <code><zscript></code></li>
<li> If code completion of zk Class not working, please make sure you have zk jar files in the library path of project that contains that simple zul file.</li>
<li> Make sure there is no other serious error, such as grammar error in your zul file.</li>
<li> Make sure there is no other serious error in Problem View of your project in Eclipse.<br/>'''Note:''' To have code assist automatically invoked in ZUML tag, you can change auto content assist trigger, replace "'''.'''" with "&nbsp;".</li>
<li> Some file of the project may be out of sync. You can goto '''[Project]/[Clean]''' then clean and rebuild the project.</li>
</ol>
</div>


<comment>/smalltalks/zkstudio0.9/index.dsp</comment>



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

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