ZUL Editor"

From Documentation
m (correct highlight (via JWB))
 
(38 intermediate revisions by 3 users not shown)
Line 1: Line 1:
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'''.
+
{{ZKStudioEssentialsPageHeader}}
  
== Coding Conventions for Embedding Java Code in Web Pages ==
+
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>.
1. Use Java within '''<nowiki><zscript>...</zscript></nowiki>''' and '''<nowiki><attribute name='onXXX'>...</attribute></nowiki>''' tags
 
  
2. Surround scripting code with a '''<nowiki><![CDATA[</nowiki>''' ''']]>''' tag, for example:  
+
<!--
 +
= 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:  
  
 
<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 29: 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 43: 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>
 
  </source>
 
  </source>
  
=== 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 ===
  
 
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. 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 | center | frame]]
 +
 +
Mark Occurrence also works when the token is located within an EL Expression.
 +
 +
[[Image:el_mark.png | center | frame]]
 +
 +
= 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.
 +
 +
[[Image:syntaxCheckRightBar.png | center]]
  
== 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.
+
The markers on the left hand side show an appropriate error message when clicked.
  
[[Image:mark1.png]]
+
[[Image:syntaxCheckLeftMark.png | center]]
  
Mark Occurrence also works when the token is located within EL Expressions.
 
  
[[Image:el_mark.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 checking ==
+
[[Image:syntaxCheckTooltip.png | center]]
Syntax checking verifies the Java code within '''<nowiki><zscript>...</zscript></nowiki>''' and '''<nowiki><attribute name='onXXX'>...</attribute></nowiki>''' tags against the Java syntax.
 
  
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.
+
Syntax checking also works on data binding expressions.  
  
[[Image:syntaxCheckRightBar.png]]
+
[[Image:studio-syntax-checking-mvvm.png | center | 700px]]
  
The markers on the left hand side show an appropriate error message when clicked.
+
=Syntax Coloring=
 +
Java code enclosed within <code><zscript></code> and <code><attribute></code> tags are colored appropriately according to the syntax.  
  
[[Image:syntaxCheckLeftMark.png]]
+
[[Image:studio-syntax-coloring.png | center | frame ]]
  
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.
+
= Content Assist =
 +
Content Assist helps you edit a zul file by providing context-sensitive proposals within a list for ease of insertion.
  
[[Image:syntaxCheckTooltip.png]]
+
You need to press "'''Ctrl + Space'''" to open the content assist popup. You can change this shortcut in the menu '''[Window]/ [Preferences]'''.
  
==Syntax coloring==
+
For basic usage scenario, please refer to Eclipse official tutorial:
Java code enclosed within <zscript> tags, <attribute> tags and the <![CDATA[*information*]]> tag are colored appropriately according to the syntax.
 
  
[[Image:Syntax.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
  
== Content assistance ==
+
== ZUL & XML Tag Content Assist ==
Content Assistance helps you edit a zul file by providing context sensitive content within a list for ease of insertion.
+
ZUL & XML tags support content assist and can be invoked by using the default content assist keyboard shortcut.
  
For basic usage scenario, please refer to eclipse official tutorial:
+
[[Image:contentAssistXMLTag.png | center]]
  
:[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]
+
This feature doesn't work on those add-on components like ZK Charts and ZK Spreadsheet.
  
:[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]
 
  
=== ZUL & XML Tag Content Assistance ===
+
=== Tag Attribute Content Assist ===
ZUML & XML tags support content assistance and can be invoked by using the default content assistance keyboard shortcut.
+
The content within '''use''' and '''apply''' attributes also supports content assist.
  
[[Image:contentAssistXMLTag.png]]
+
[[Image:contentAssistinAttribute.png | center]]
  
=== Zscript Content Assistance ===
+
== Zscript Content Assist ==
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.
+
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]]
+
[[Image:contentAssistZscript.png | center]]
  
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.
+
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]]
+
[[Image:contentAssistJavaDoc.png | center]]
  
=== EL Expression Content Assistance ===
+
== 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]]
 +
 
 +
 
 +
== MVVM Content Assist ==
 +
 
 +
Content assist also helps you write data binding expressions in the following places:
 +
 
 +
===Annotation name ===
 +
 
 +
[[Image:studio-contentassist-mvvm-annotation.png | center | 500px]]
  
=== ZUL Tag Attribute Content Assistance ===
 
The content within '''use''' & '''apply''' attributes also support content assistance.
 
  
[[Image:contentAssistinAttribute.png]]
+
=== ViewModel's properties ===
 +
When you enter a '''dot''' ('.'), it list a ViewModel's properties.
 +
[[Image:studio-contentassist-mvvm-properties.png| center | 600px]]
  
'''Tips: Keyboard shortcut for Content Assist'''
+
=== Available variables ===
  
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.
+
[[Image:studio-contentassist-mvvm-variables.png | center | 700px]]
  
=== Java Doc hovering ===
+
= JavaDoc Hovering =
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.
+
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]]
+
[[Image:JAVADocHover.png | center]]
  
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 [[Studio_userguide#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.
+
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 =
 
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 ==
 +
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.
  
=== Project resource hyperlinks ===
+
== ZUL Tag Attribute 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.
+
In the ZUL Editor, you can navigate to the Java class specified in '''use="'''ClassName'''"''' and '''apply="'''ClassName'''"''' attributes using Hyperlink Navigation.
  
=== ZUML tag attribute hyperlink ===
+
[[Image:studio-hyperlink.png | center | 700px]]
Using the ZUL Editor, you can navigate to the Java class specified in '''use="'''ClassName'''"''' & '''apply="'''ClassName'''"''' attributes using Hyperlink Navigation.
+
[[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 hyperlink ===
+
== 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]].
+
{{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






Last Update : 2022/01/19

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