ZUL Editor"

From Documentation
m (correct highlight (via JWB))
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{ZKStudioEssentialsPageHeader}}
 
{{ZKStudioEssentialsPageHeader}}
  
ZUL Editor is an intelligent text editor designed for authoring *.zul & *.zhtml files. When you double click the zul file or zhtml file in the Navigator View, Package Explorer View or Project Explorer View the file will be opened in the ZUL Editor automatically. The editor provides '''Syntax Coloring''', '''Syntax Check''', '''Mark Occurrence''', '''Content Assistance''', '''JAVA Doc Hovering''', '''Hyperlink Navigation''' and '''ZUL file formatting'''.
+
ZUL Editor is an intelligent text editor designed for authoring *.zul & *.zhtml files. When you double click the zul file or zhtml file in the '''Navigator View''', '''Package Explorer View''' or '''Project Explorer View''' the file will be opened in the ZUL Editor automatically. The editor provides <i>Syntax Coloring</i>, <i>Syntax Check</i>, <i>Mark Occurrence</i>, <i>Content Assist</i>, <i>Java Doc Hovering</i>, <i>Hyperlink Navigation</i> and <i>ZUL file formatting</i>.
  
== Coding Conventions for Embedding Java Code in Web Pages ==
+
<!--
1. Use Java within '''<nowiki><zscript>...</zscript></nowiki>''' and '''<nowiki><attribute name='onXXX'>...</attribute></nowiki>''' tags
+
= Embedding Java Code in ZUL Pages =
 
+
1. You can write Java within '''<code><zscript><![CDATA[...]]></zscript></code>''' or '''<code><attribute name='onXXX'><![CDATA[...]]></attribute></code>''' tags, for example:  
2. Surround scripting code with a '''<nowiki><![CDATA[</nowiki>''' ''']]>''' tag, for example:  
 
  
 
<source lang="xml" >
 
<source lang="xml" >
<zscript>   <![CDATA[
+
<zk>
    System.out.println("Hello World!");
+
<zscript><![CDATA[
]]></zscript>
+
System.out.println("Hello World!");
 +
]]></zscript>
  
 
+
<button label="SayHello">
<button label="SayHello">
+
<attribute name="onClick"><![CDATA[
    <attribute name="onClick">
+
alert("Hello World!");
    <![CDATA[
+
]]></attribute>
        alert("Hello World!");
+
</button>
    ]]>
+
</zk>
    </attribute>
 
</button>
 
 
</source>
 
</source>
  
Line 31: Line 29:
 
<zk>
 
<zk>
 
<zscript><![CDATA[
 
<zscript><![CDATA[
import java.math.*;
+
import java.math.*;
 
 
int x = 500;
+
int x = 500;
int y = 300;
+
int y = 300;
System.out.println(Math.max(x,y));
+
System.out.println(Math.max(x,y));
 
]]></zscript>
 
]]></zscript>
 
</zk>
 
</zk>
Line 45: Line 43:
 
<zk>
 
<zk>
 
<zscript><![CDATA[
 
<zscript><![CDATA[
boolean getResult(){
+
boolean getResult(){
return true;
+
return true;
}
+
}
 
 
class Bean{
+
class Bean{
String name;
+
String name;
public String getName(){
+
public String getName(){
return name;
+
return name;
 +
}
 
}
 
}
}
 
 
 
if(getResult()){
+
if(getResult()){
new Bean().getName();
+
new Bean().getName();
}
+
}
 
]]></zscript>
 
]]></zscript>
 
</zk>
 
</zk>
Line 64: Line 62:
  
 
=== Toggle Zscript Comment ===
 
=== Toggle Zscript Comment ===
To toggle comments within the zscript, you should use the keyboard shortcut (default key is ''Ctrl + /'') when the zscript code has focus. You can also toggle multiple lines of comments using the same shortcut but by selecting multiple lines of zscript code in editor.  You can reconfigure the keyboard shortcut as described in [[#B-1_Configure_keyboard_shortcuts | B-1 Configure keyboard shortcuts]].
+
To toggle comments within the zscript, you should use the keyboard shortcut (default key is ''Ctrl + /'') when the zscript code has focus. You can also toggle multiple lines of comments using the same shortcut but by selecting multiple lines of zscript code in editor.  You can reconfigure the keyboard shortcut as described in [[ZK_Studio_Essentials/Eclipse_Tips#Configure_Keyboard_Shortcuts|Configure Keyboard Shortcuts]].
  
 
=== Zscript Formatting ===
 
=== Zscript Formatting ===
Line 70: Line 68:
 
You can format codes inside zscript now. The menu sequence is '''Source->Format'''.
 
You can format codes inside zscript now. The menu sequence is '''Source->Format'''.
  
== Mark Occurrences ==
+
-->
Mark Occurrence is a useful function when you need to trace a certain variable or component within the 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 corresponding tokens (read/write access) in the currently opened zul file will be marked.
+
= Mark Occurrences =
 +
Mark Occurrence is a useful function when you need to trace a certain variable or component within the code. Move the cursor to a certain variable, object, method, or class declaration, and selected token's all occurrences (read/write access) in the currently opened zul file will be marked.
  
[[Image:mark1.png]]
+
[[Image:mark1.png | center | frame]]
  
Mark Occurrence also works when the token is located within EL Expressions.
+
Mark Occurrence also works when the token is located within an EL Expression.
  
[[Image:el_mark.png]]
+
[[Image:el_mark.png | center | frame]]
  
== Syntax Checking ==
+
= Syntax Checking =
Syntax checking verifies the Java code within '''<nowiki><zscript>...</zscript></nowiki>''' and '''<nowiki><attribute name='onXXX'>...</attribute></nowiki>''' tags against the Java syntax.
+
Syntax checking verifies the Java code within zscript against the Java syntax and MVVM binding expressions.
  
The script code must be enclosed within a '''<nowiki><![CDATA[ ]]></nowiki>''' tag, and remember to add '''//@DECLARATION''' and '''//@IMPORT''' as mentioned [[ZK_Studio_Features#Coding conventions for embedding Java code in Web pages | above]] when embedding Java Code in a zul file.
+
The vertical ruler indicators on the right hand side will help you discover how many errors are present in the zul file and the location of said errors. By clicking on the marker you can jump to the line which contains the error.
  
The vertical ruler indicators on the right hand side will help you discover how many errors are present in the zul file and the location of said errors. By clicking on the marker you can jump to the line which contains the error.
+
[[Image:syntaxCheckRightBar.png | center]]
  
[[Image:syntaxCheckRightBar.png]]
 
  
 
The markers on the left hand side show an appropriate error message when clicked.
 
The markers on the left hand side show an appropriate error message when clicked.
  
[[Image:syntaxCheckLeftMark.png]]
+
[[Image:syntaxCheckLeftMark.png | center]]
  
Move the mouse to the occurrence of the error, marked by a red or yellow line and the error message will be display in a tooltip.
 
  
[[Image:syntaxCheckTooltip.png]]
+
Move the mouse on the occurrence of the error marked by a red wavy line (or the warning marked by a yellow wavy line) and the error message will be display in a tooltip.
  
==Syntax Coloring==
+
[[Image:syntaxCheckTooltip.png | center]]
Java code enclosed within <zscript> tags, <attribute> tags and the <![CDATA[*information*]]> tag are colored appropriately according to the syntax.
 
  
[[Image:Syntax.png]]
 
  
== Content Assistance ==
+
Syntax checking also works on data binding expressions.  
Content Assistance helps you edit a zul file by providing context sensitive content within a list for ease of insertion.
 
  
For basic usage scenario, please refer to eclipse official tutorial:
+
[[Image:studio-syntax-checking-mvvm.png | center | 700px]]
  
:[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]
+
=Syntax Coloring=
 +
Java code enclosed within <code><zscript></code> and <code><attribute></code> tags are colored appropriately according to the syntax.  
  
:[http://help.eclipse.org/ganymede/topic/org.eclipse.wst.sse.doc.user/topics/tsrcedt005.html http://help.eclipse.org/ganymede/topic/org.eclipse.wst.sse.doc.user/topics/tsrcedt005.html]
+
[[Image:studio-syntax-coloring.png | center | frame ]]
  
=== ZUL & XML Tag Content Assistance ===
+
= Content Assist =
ZUML & XML tags support content assistance and can be invoked by using the default content assistance keyboard shortcut.
+
Content Assist helps you edit a zul file by providing context-sensitive proposals within a list for ease of insertion.
  
[[Image:contentAssistXMLTag.png]]
+
You need to press "'''Ctrl + Space'''" to open the content assist popup. You can change this shortcut in the menu '''[Window]/ [Preferences]'''.
  
=== Zscript Content Assistance ===
+
For basic usage scenario, please refer to Eclipse official tutorial:
Zscript content assistance allows you to rapidly implement code by providing auto completion functionality within '''<nowiki><zscript>...</zscript></nowiki>''', '''<nowiki><attribute name='onXXX'>...</attribute></nowiki>''' code blocks and event attribute values in the ZUML tag.
 
  
[[Image:contentAssistZscript.png]]
+
* http://help.eclipse.org/indigo/topic/org.eclipse.jdt.doc.user/gettingStarted/qs-ContentAssist.htm
 +
* http://help.eclipse.org/indigo/topic/org.eclipse.wst.sse.doc.user/topics/tsrcedt005.html
  
Classes located in JAR files can also be included in content assistance. In addition to that if the associated source for the JAR file is present JavaDoc can be shown beside the content assistance window.
+
== ZUL & XML Tag Content Assist ==
 +
ZUL & XML tags support content assist and can be invoked by using the default content assist keyboard shortcut.
  
[[Image:contentAssistJavaDoc.png]]
+
[[Image:contentAssistXMLTag.png | center]]
  
=== EL Expression Content Assistance ===
+
This feature doesn't work on those add-on components like ZK Charts and ZK Spreadsheet.
 +
 
 +
 
 +
=== Tag Attribute Content Assist ===
 +
The content within '''use''' and '''apply''' attributes also supports content assist.
 +
 
 +
[[Image:contentAssistinAttribute.png | center]]
 +
 
 +
== Zscript Content Assist ==
 +
Zscript content assist allows you to rapidly implement code by providing auto completion functionality within '''<code><zscript>...</zscript></code>''', '''<code><attribute name='onXXX'>...</attribute></code>''' code blocks and event attribute values in the ZUML tag.
 +
 
 +
[[Image:contentAssistZscript.png | center]]
 +
 
 +
Classes located in JAR files can also be included in content assist. In addition to that if the JAR's source code is available, JavaDoc can be shown beside the content assist window.
 +
 
 +
[[Image:contentAssistJavaDoc.png | center]]
 +
 
 +
== EL Expression Content Assist ==
 
Inside the EL Expression you can also invoke the content assist via a keyboard shortcut.
 
Inside the EL Expression you can also invoke the content assist via a keyboard shortcut.
  
[[Image:contentAssistEL.png]]
+
[[Image:contentAssistEL.png | center]]
  
=== ZUL Tag Attribute Content Assistance ===
 
The content within '''use''' & '''apply''' attributes also support content assistance.
 
  
[[Image:contentAssistinAttribute.png]]
+
== MVVM Content Assist ==
  
'''Tips: Keyboard shortcut for Content Assist'''
+
Content assist also helps you write data binding expressions in the following places:
  
The default keyboard shortcut for content assist in the English Version of Eclipse is "''Ctrl + Space''", you can change this shortcut in the Preferences Window. Please refer to [[Studio_userguide#B-1_Configure_keyboard_shortcuts | B-1 Configure keyboard shortcuts]] for more detail.
+
===Annotation name ===
  
=== Java Doc Hovering ===
+
[[Image:studio-contentassist-mvvm-annotation.png | center | 500px]]
For more information as you develop, ZK Studio provides Java Doc hovering functionality. When hovering over the code, Java Doc belonging to the element will be shown in a tooltip.
 
  
[[Image:JAVADocHover.png]]
 
  
Please note in order for content assistance and JavaDoc to work with JAR files you need to set source and/or Java Doc of said files, please refer to [http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.jdt.doc.user/reference/ref-properties-source-attachment.htm Eclipse help] for more information on how to do this.
+
=== ViewModel's properties ===
 +
When you enter a '''dot''' ('.'), it list a ViewModel's properties.
 +
[[Image:studio-contentassist-mvvm-properties.png| center | 600px]]
  
== Hyperlink Navigation ==
+
=== Available variables ===
 +
 
 +
[[Image:studio-contentassist-mvvm-variables.png | center | 700px]]
 +
 
 +
= JavaDoc Hovering =
 +
ZK Studio provides Javadoc hovering functionality. When a cursor hovers over the code, Javadoc belonging to the element will be shown in a tooltip.
 +
 
 +
[[Image:JAVADocHover.png | center]]
 +
 
 +
Please note in order for content assist and Javadoc to work with JAR files you need to set source and/or Javadoc of said files, please refer to [http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.jdt.doc.user/reference/ref-properties-source-attachment.htm Eclipse help] for more information on how to do this.
 +
 
 +
= Hyperlink Navigation =
 
Hyperlink Navigation allows you to navigate through project resources easily. To make use of this feature please follow these steps:
 
Hyperlink Navigation allows you to navigate through project resources easily. To make use of this feature please follow these steps:
  
# Move your cursor to a certain element within the ZUL Editor and press F3
+
# Move your cursor to a certain element within the ZUL Editor and press F3.
# Hold Ctrl key on keyboard, move the mouse pointer over an element, if that element can be convert to hyperlink (that is, if the resource supports hyperlink functionality), the element will be underlined and clicking the hyperlink will take you to the subsequent resource.
+
# Hold the Ctrl key on your keyboard, move the mouse pointer over an element, if that element can be converted to a hyperlink (that is, if the resource supports hyperlink functionality), the element will be underlined and clicking the hyperlink will take you to the subsequent resource.
  
=== URL Hyperlinks ===
+
== URL Hyperlinks ==
All elements in the ZUL Editor that represent a URL are usable in this manner.
+
All elements in the ZUL Editor that represents a URL are usable in this manner.
  
=== Project Resource Hyperlinks ===
+
== Project Resource Hyperlinks ==
 
If a literal string within a zul file is a relative path to a resource in the projects WebContent folder, then it can be accessed using Hyperlink Navigation. However, please note that the zul file must have been opened by the ZUL Editor to perform this functionality.
 
If a literal string within a zul file is a relative path to a resource in the projects WebContent folder, then it can be accessed using Hyperlink Navigation. However, please note that the zul file must have been opened by the ZUL Editor to perform this functionality.
  
=== ZUL Tag Attribute Hyperlinks ===
+
== ZUL Tag Attribute Hyperlinks ==
Using the ZUL Editor, you can navigate to the Java class specified in '''use="'''ClassName'''"''' & '''apply="'''ClassName'''"''' attributes using Hyperlink Navigation.
+
In the ZUL Editor, you can navigate to the Java class specified in '''use="'''ClassName'''"''' and '''apply="'''ClassName'''"''' attributes using Hyperlink Navigation.
 +
 
 +
[[Image:studio-hyperlink.png | center | 700px]]
 +
[[Image:studio-hyperlink-class.png | center | 700px]]
  
[[Image:javaclass_hyperlink.png]]
 
  
(For this to work you need to set a source file for that class. If the class is within a JAR File which does not have a corresponding source file, please refer to [[#B-2_Add_Source_Code_and_Javadoc_Resource_to_JAR_File | B-2 Add Source Code and Javadoc Resource to JAR File]] for more information on how to do this.)
+
(For this to work you need to set a source file for that class. If the class is within a JAR File which does not have a corresponding source file, please refer to [[ZK_Studio_Essentials/Eclipse_Tips#Add_Source_Code_and_Javadoc_Resource_to_JAR_File | Add Source Code and Javadoc Resource to JAR File]] for more information on how to do this.)
  
=== Zscript Hyperlinks ===
+
== Zscript Hyperlinks ==
 
Zscript hyperlink navigation also works in the same manner as Eclipse's Java editor. Within '''<nowiki><zscript>...</zscript></nowiki>''' and '''<nowiki><attribute name = "onXXX">...</attribute></nowiki>''' tags you are able to navigate to other functions using hyperlink functionality (Ctrl + click the resource).
 
Zscript hyperlink navigation also works in the same manner as Eclipse's Java editor. Within '''<nowiki><zscript>...</zscript></nowiki>''' and '''<nowiki><attribute name = "onXXX">...</attribute></nowiki>''' tags you are able to navigate to other functions using hyperlink functionality (Ctrl + click the resource).
  
 
A ZUML tag's event attribute value is also accessible using Hyperlink Navigation.
 
A ZUML tag's event attribute value is also accessible using Hyperlink Navigation.
  
[[Image:attrHyperlink.png]]
+
[[Image:attrHyperlink.png | center]]
 +
 
 +
= ZUL File Formatting =
 +
ZUL Editor supports zul file source formatting function, in a currently opened zul editor, right click on a zul file and select '''Source / Format''', the source code will be formatted like a standard xml file, but the code content in '''<zscript>...</zscript>''' and '''<attribute name = "onEventName">...</attribute>''' will be preserved. To format part of the content, you should make a selection first and then follow the above instruction.
 +
 
 +
You can use a keyboard shortcut to accomplish this task, the default source format keyboard shortcut is ''''Ctrl + Shift + F'''.  You can reconfigure the keyboard shortcut as described in [[ZK_Studio_Essentials/Eclipse_Tips#Configure_Keyboard_Shortcuts|Configure Keyboard Shortcuts]].
 +
 
 +
[[Image:sourceFormat.png | center]]
  
In order to format the content of a zul file, including the zul and zscript code, you need to right click on the editor and select 『』Source > Format』』.
 
  
In order to format part of the content, you should make a selection first and then follow the above instruction.
 
  
You can use a keyboard shortcut to accomplish this task, the default source format keyboard shortcut is ''Ctrl + Shift + F'' You can reconfigure the keyboard shortcut as described in [[#B-1_Configure_keyboard_shortcuts | B-1 Configure keyboard shortcuts]].
 
  
== 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.
 
  
[[Image:sourceFormat.png]]
 
  
Also you can use keyboard shortcut to accomplish this task, the default source format keyboard shortcut is Ctrl + Shift + F.
 
  
 
{{ZKStudioEssentialsPageFooter}}
 
{{ZKStudioEssentialsPageFooter}}

Latest revision as of 13:22, 19 January 2022


ZUL Editor is an intelligent text editor designed for authoring *.zul & *.zhtml files. When you double click the zul file or zhtml file in the Navigator View, Package Explorer View or Project Explorer View the file will be opened in the ZUL Editor automatically. The editor provides Syntax Coloring, Syntax Check, Mark Occurrence, Content Assist, Java Doc Hovering, Hyperlink Navigation and ZUL file formatting.


Mark Occurrences

Mark Occurrence is a useful function when you need to trace a certain variable or component within the code. Move the cursor to a certain variable, object, method, or class declaration, and selected token's all occurrences (read/write access) in the currently opened zul file will be marked.

Mark1.png

Mark Occurrence also works when the token is located within an EL Expression.

El mark.png

Syntax Checking

Syntax checking verifies the Java code within zscript against the Java syntax and MVVM binding expressions.

The vertical ruler indicators on the right hand side will help you discover how many errors are present in the zul file and the location of said errors. By clicking on the marker you can jump to the line which contains the error.

SyntaxCheckRightBar.png


The markers on the left hand side show an appropriate error message when clicked.

SyntaxCheckLeftMark.png


Move the mouse on the occurrence of the error marked by a red wavy line (or the warning marked by a yellow wavy line) and the error message will be display in a tooltip.

SyntaxCheckTooltip.png


Syntax checking also works on data binding expressions.

Studio-syntax-checking-mvvm.png

Syntax Coloring

Java code enclosed within <zscript> and <attribute> tags are colored appropriately according to the syntax.

Studio-syntax-coloring.png

Content Assist

Content Assist helps you edit a zul file by providing context-sensitive proposals within a list for ease of insertion.

You need to press "Ctrl + Space" to open the content assist popup. You can change this shortcut in the menu [Window]/ [Preferences].

For basic usage scenario, please refer to Eclipse official tutorial:

ZUL & XML Tag Content Assist

ZUL & XML tags support content assist and can be invoked by using the default content assist keyboard shortcut.

ContentAssistXMLTag.png

This feature doesn't work on those add-on components like ZK Charts and ZK Spreadsheet.


Tag Attribute Content Assist

The content within use and apply attributes also supports content assist.

ContentAssistinAttribute.png

Zscript Content Assist

Zscript content assist allows you to rapidly implement code by providing auto completion functionality within <zscript>...</zscript>, <attribute name='onXXX'>...</attribute> code blocks and event attribute values in the ZUML tag.

ContentAssistZscript.png

Classes located in JAR files can also be included in content assist. In addition to that if the JAR's source code is available, JavaDoc can be shown beside the content assist window.

ContentAssistJavaDoc.png

EL Expression Content Assist

Inside the EL Expression you can also invoke the content assist via a keyboard shortcut.

ContentAssistEL.png


MVVM Content Assist

Content assist also helps you write data binding expressions in the following places:

Annotation name

Studio-contentassist-mvvm-annotation.png


ViewModel's properties

When you enter a dot ('.'), it list a ViewModel's properties.

Studio-contentassist-mvvm-properties.png

Available variables

Studio-contentassist-mvvm-variables.png

JavaDoc Hovering

ZK Studio provides Javadoc hovering functionality. When a cursor hovers over the code, Javadoc belonging to the element will be shown in a tooltip.

JAVADocHover.png

Please note in order for content assist and Javadoc to work with JAR files you need to set source and/or Javadoc of said files, please refer to Eclipse help for more information on how to do this.

Hyperlink Navigation

Hyperlink Navigation allows you to navigate through project resources easily. To make use of this feature please follow these steps:

  1. Move your cursor to a certain element within the ZUL Editor and press F3.
  2. Hold the Ctrl key on your keyboard, move the mouse pointer over an element, if that element can be converted to a hyperlink (that is, if the resource supports hyperlink functionality), the element will be underlined and clicking the hyperlink will take you to the subsequent resource.

URL Hyperlinks

All elements in the ZUL Editor that represents a URL are usable in this manner.

Project Resource Hyperlinks

If a literal string within a zul file is a relative path to a resource in the projects WebContent folder, then it can be accessed using Hyperlink Navigation. However, please note that the zul file must have been opened by the ZUL Editor to perform this functionality.

ZUL Tag Attribute Hyperlinks

In the ZUL Editor, you can navigate to the Java class specified in use="ClassName" and apply="ClassName" attributes using Hyperlink Navigation.

Studio-hyperlink.png
Studio-hyperlink-class.png


(For this to work you need to set a source file for that class. If the class is within a JAR File which does not have a corresponding source file, please refer to Add Source Code and Javadoc Resource to JAR File for more information on how to do this.)

Zscript Hyperlinks

Zscript hyperlink navigation also works in the same manner as Eclipse's Java editor. Within <zscript>...</zscript> and <attribute name = "onXXX">...</attribute> tags you are able to navigate to other functions using hyperlink functionality (Ctrl + click the resource).

A ZUML tag's event attribute value is also accessible using Hyperlink Navigation.

AttrHyperlink.png

ZUL File Formatting

ZUL Editor supports zul file source formatting function, in a currently opened zul editor, right click on a zul file and select Source / Format, the source code will be formatted like a standard xml file, but the code content in <zscript>...</zscript> and <attribute name = "onEventName">...</attribute> will be preserved. To format part of the content, you should make a selection first and then follow the above instruction.

You can use a keyboard shortcut to accomplish this task, the default source format keyboard shortcut is 'Ctrl + Shift + F. You can reconfigure the keyboard shortcut as described in Configure Keyboard Shortcuts.

SourceFormat.png





Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.