How to get Efficient Support"

From Documentation
(45 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
 +
=Support Channel=
 +
If you are a ZK customer and your package comes with remote consulting hours, you can contact mailto:[email protected] to request technical support. Please include your Invoice Number or License Certificate number when you submit your question so that we can associate you with the right company.
  
 +
If you do not have remote consulting hours or if you are not sure, please read [https://www.zkoss.org/wiki/Customers/FAQ#What_is_my_current_ZK_Package.3F Customer FAQ] or contact us at [email protected].
  
 +
= [https://tracker.zkoss.org/issues/ Find Known Issues]=
 +
If you think you encounter a bug,  you can search for the bug in [https://tracker.zkoss.org/issues our tracker]. If it's a known bug, there is sometimes a workaround mentioned in the tracker. You can apply the workaround before you get the official release.
  
 
=Getting prompt and efficient support from ZK=
 
=Getting prompt and efficient support from ZK=
When you encounter an issue in ZK, following this document can help you to provide the support team with informative data, thus speeding up the investigation and get prompt and efficient feedback. Here is a sample screenshot of an error. However with only a screenshot, it is difficult for the support team to find enough clues and provide timely support. Please follow the tips and instructions below when submitting your issue.
+
When you run into an issue in ZK, following this document can help you to provide the support team with sufficient data, thus speeding up the investigation and get prompt and efficient feedback. Here is a sample screenshot of an error. However, with only a screenshot, it is difficult for us to find enough clues and provide timely support. Instead of providing a screenshot, please follow the tips and instructions below when submitting your issue.
  
 
[[File:ZK_MeetRpoblem01.png]]
 
[[File:ZK_MeetRpoblem01.png]]
==Provide general information and reproducible samples==
+
==Provide Sufficient information ==
  
 +
Providing sufficient information helps us support you more efficiently.
  
=== A runnable example is the best for us ===
+
=== The Sufficient Information Includes: ===
You can:
+
# the complete server-side error or the client-side error if any (read [[#Check JavaScript Error]])
 +
# complete exception stack trace (if any)
 +
# A reproducible sample (please read [[#Tips for creating a reproducible sample]]
 +
# Precise and clear steps to reproduce the issue
 +
# ZK version and edition
 +
#: e.g. ZK 9.0.1 PE
 +
# Browser and its version
 +
#: e.g. Firefox 60
 +
# If it is hard to create a sample, you can provide an URL so that the support team can access it. When providing this URL, remember to [https://www.zkoss.org/wiki/ZK%20Configuration%20Reference/zk.xml/The%20client-config%20Element/The%20debug-js%20Element  turn on the js debug] in your zk.xml.
 +
# Application servers (e.g. JBoss 6, if it's necessary).
 +
# If your case happens only in your specific environment, it is recommended to request an online meeting or provide a virtual machine as a copy of your actual environment
 +
# anything else that can help us understand your issue better
 +
 
 +
=== Tips for creating a reproducible sample ===
 +
====You can provide: ====
  
 
# Use [http://zkfiddle.org zkfiddle]
 
# Use [http://zkfiddle.org zkfiddle]
# Zip your maven project with pom.xml and include necessary source code
+
# Zip your maven project with pom.xml and include necessary source code
 
# Provide zul and its related Java source
 
# Provide zul and its related Java source
 
# Provide a public URL that we can visit
 
# Provide a public URL that we can visit
# Remember to turn on the js debug in your zk.xml.
 
  
 +
==== Steps:====
 +
# Clone the original zul with the issue and remove irrelevant components.
 +
# Replace your database data with static sample data in order to run without a database.
  
=== Tips for creating a reproducible example ===
+
=== Check JavaScript Error ===
 +
You can check if there is any JavaScript error by opening the developer tool.
 +
For example, press F12 to open the chrome developer tool/ Console tab:
  
* Clone the original zul with the issue, remove irrelevant components
+
[[File:chrome-js-error.png | center]]
* You could move your Java codes (mostly event listeners) into <zscript>
 
* Replace your database data with static sample data in order to run without a database.
 
  
 
+
You can extract the error message by:
=== Please provide the following information: ===
+
* select and copy the whole text or
:#ZK version and edition (e.g. ZK 5.0.7.1 PE).
+
* right-click, select "Save as..."
:#Browser and Browser version (e.g. Firefox 3.6).
 
:#Servers (e.g. JBoss 6).
 
:#A sample with the steps so that the support team can reproduce the issue.
 
:#If it is not easy to come out a sample, you can provide an URL so that the support team can access to and try to debug with it. When providing this URL, remember to [[#If you cannot provide a reproducible sample | turn on]] the js debug in your zk.xml.
 
:#If your case happens only in your specific environment, it is recommended to provide a virtual machine as a copy of your actual environment.
 
  
 
==If you cannot provide a reproducible sample==
 
==If you cannot provide a reproducible sample==
:Snapshot the ''error'', ''request'' and ''response'' with Browser. Remember to''' turn on''' js debug in your zk.xml
+
Then you can choose the following alternatives:
<source type="xml">
 
<client-config>
 
<debug-js>true</debug-js>
 
</client-config>
 
</source>
 
:As Firefox has a very useful tool Firebug, it is recommended to log your issue with [http://getfirebug.com/ firebug] (Hot-key: F12) and snapshot the following images, then send to zk support team.
 
{| border="1px" | width="100%" | cellspacing="0"
 
|-
 
!style="width:100px"|
 
!|
 
|-
 
| Server side error
 
|
 
'''1. Request'''
 
  
[[File:ZK_MeetRpoblem_FF01.png]]
+
=== Provide a Public URL of Your Web Application===
----
+
Provide an URL so that the support team can access it. When providing this URL, remember to turn on the js debug in your zk.xml.
  
'''2. Response'''
+
=== Provide ZK AU Request/Response Details ===
 +
# open developer tool before start to reproduce your issue
 +
# do the steps to reproduce your bug
 +
# Send request details as HAR to us
 +
#: * [https://developers.google.com/web/tools/chrome-devtools/network/reference#save-as-har Save all network requests to a HAR file in Chrome]
 +
#: * Save request details as HAR in Firefox [[File:save-har-firefox.png| center]]
 +
#: * [https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/network Save request details as HAR in Edge]
  
[[File:ZK_MeetRpoblem_FF02.png]]
+
If your browser doesn't support to save as HAR, or just 1 request is related, you can also send us the screenshot of AU request like:
|-
 
|Client side error
 
|
 
[[File:ZK_MeetRpoblem_FF03.png]]
 
----
 
  
*Click the link (the blue text) then go to the line of error.
+
[[File:au-request.png | center]]
[[File:ZK_MeetRpoblem_FF04.png]]
 
|}
 
  
== If you cannot reproduce it with Firefox ==
+
=== Provide Related Source ===
:Some issues are browser-dependent. If the issue does not happen in your Firefox, please follow the instructions below and provide the support team with corresponding debug information.
+
By checking your zul and Java source, we can try to simulate your case. This is better than inferring what you describe in natural language.
=== Chrome ===
 
*Enable "Developer tools" by F12
 
{| border="1px" | width="100%" | cellspacing="0"
 
|-
 
!style="width:100px"|
 
!|
 
|-
 
| Server side error
 
|
 
'''1. Request'''
 
  
[[File:ZK_MeetRpoblem_Chrome01.png]]
+
= How to Include a JavaScript file =
----
+
When you need to apply a js patch or include a 3rd-party js library, you have to include the js file in your application. This section describes how you can include the js file for different scopes.
  
'''2. Response'''
+
== Page-Scope==
 +
* Use the script directive [[ZUML%20Reference/ZUML/Processing%20Instructions/script | <?script?>]]
 +
* Use the script component [[ZK%20Component%20Reference/Essential%20Components/Script | <script>]]
  
[[File:ZK_MeetRpoblem_Chrome02.png]]
+
== Application-Scope ==
|-
+
If you need to include a javascript file on every zul, there are 2 ways:
|Client side error
 
|
 
  
*Click the error icon in the lower right corner.
+
=== By language addon===
*Click the link (test.zul:22) then go to the line where the error occurred.
+
Create a <code>lang-addon.xml</code>  according to [[ZK_Client-side_Reference/Language_Definition#Language_Addon | ZK Client-side Reference/Language Definition#Language_Addon]] and include the javascript file with <code><javascript></code>. For example:
[[File:ZK_MeetRpoblem_Chrome03.png]]
 
  
|}
+
<syntaxhighlight lang='xml' line highlight='4, 5, 6'>
 +
<language-addon>
 +
    <addon-name>patch-addon</addon-name><!-- give a meaningful name -->
 +
    <language-name>xul/html</language-name>
 +
    <depends>zul</depends>
 +
    <javascript src="~./mypatch.js" />
 +
    <javascript src="/zkpatch/mypatch2.js"/>
 +
</language-addon>
 +
</syntaxhighlight>
 +
* Line 4: see the next section
 +
* Line 5: a path starting with <code>~./</code> is a [[ZK_Developer%27s_Reference/UI_Composing/ZUML/Include_a_Page#Classpath_Web_Resource_Path | classpath web resource path]] which is a special path supported by ZK
 +
* Line 6: You can also link a file under your web application context root
  
=== IE ===
+
==== Dependent Addon ====
*As there are less tools in IE6 and 7, it is recommended to reproduce and log the debug info with IE8 or 9.
+
If you override a component's widget or extend an existing component, it's crucial to specify <code><depends></code> correctly, so that your land addon will take effect. According to which component you override, you need to specify the corresponding addon name. For example:
*With IE8 or later, enable "Developer tools" by F12
 
{| border="1px" | width="100%" | cellspacing="0"
 
|-
 
!style="width:100px"|
 
!|
 
|-
 
| Client side error
 
|
 
[[File:ZK_MeetRpoblem_IE01.png]]
 
|}
 
  
*Change '''Document mode''' to emulate IE6,7 if the issue happens only in these versions
+
* If you override a component in zul language e.g. <code><button></code>, you specify
[[File:ZK_MeetRpoblem_IE02.png]]
+
<code><depends>zul</depends></code>
:'''Quirks Mode''': IE6
+
* If you override a component provided by zkmax e.g. <code><nav></code>, you specify
:'''Internet Explorer 7 Standards''': IE7
+
<code><depends>zkmax</depends></code>
 +
* If you override something about accessibility, e.g. override aria attribute, you specify
 +
<code><depends>za11y</depends></code>
  
 +
=== Use [[ZK_Configuration_Reference/zk.xml/The_device-config_Element/The_embed_Element | <embed>]] ===
  
 
= How to Run a Sample Maven Project =
 
= How to Run a Sample Maven Project =
In order to get rid of all your project's environment effect and narrow down problems, we send you a sample maven project that reproduces a case. To run the project, you need to [http://maven.apache.org/download.cgi download maven ] and [http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html setup] first.
+
In order to narrow down the problem and eliminate differences caused by different environments, we often send you a sample maven project that tries to simulate and reproduce your issue. To run the project, you need to [http://maven.apache.org/download.cgi download maven ] and [http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html setup] first.
  
 
# Run your command line interface
 
# Run your command line interface
# switch to the sample project's root folder that has a <tt>pom.xml</tt>
+
# switch to the sample project's root folder that has a <code>pom.xml</code>
 
# Start jetty server with the command below
 
# Start jetty server with the command below
#:  <tt>mvn jetty:run</tt>
+
#:  <code>mvn jetty:run</code>
# Visit the project's pages with your browser.
+
# Visit the project's pages with your browser
  
If you don't know the zul's path or the path is incorrect, you can just visit http://localhost:8080, and the browser will show a link with correct context path:
+
If you don't know the zul's path or if the path is incorrect, just visit http://localhost:8080. A browser will show a link with the correct context path:
 
[[File:jettyRoot.png | center | 800px]]
 
[[File:jettyRoot.png | center | 800px]]
  
 
Click the link and it will list folders then you can navigate to find the zul.
 
Click the link and it will list folders then you can navigate to find the zul.
 
[[File:listFolder.png | center]]
 
[[File:listFolder.png | center]]
 
----
 
If you have any feedback regarding this book, please email to [email protected]
 
 
 
  
 
= How to get Browser Performance Profile =
 
= How to get Browser Performance Profile =
 +
If you are running into a performance issue, you can first check out [https://www.zkoss.org/wiki/ZK_Developer's_Reference/Performance_Monitoring/Step_by_Step_Trouble_Shooting Step by Step Trouble Shooting] and do a first step analysis using browser's developer tools.
  
== Firefox==
+
== [https://developers.google.com/web/tools/chrome-devtools/evaluate-performance By Chrome developer tool] ==
# visit a web page
+
== [https://developer.mozilla.org/en-US/docs/Tools/Performance By Firefox developer tool] ==
# open firefox developer tool (pressing F12)
+
== [https://docs.microsoft.com/en-us/microsoft-edge/devtools-guide/performance By Edge developer tool] ==
# click Performance tab, click "clock" icon to start recording the browser performance
 
# do the action
 
# click "clock" icon to stop
 
# click save to json file
 
 
 
[[File:firefox-performance.png | center]]
 
  
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Revision as of 03:07, 3 April 2023


DocumentationZK Developer's ReferenceHow to get Efficient Support
How to get Efficient Support


Support Channel

If you are a ZK customer and your package comes with remote consulting hours, you can contact mailto:[email protected] to request technical support. Please include your Invoice Number or License Certificate number when you submit your question so that we can associate you with the right company.

If you do not have remote consulting hours or if you are not sure, please read Customer FAQ or contact us at [email protected].

Find Known Issues

If you think you encounter a bug, you can search for the bug in our tracker. If it's a known bug, there is sometimes a workaround mentioned in the tracker. You can apply the workaround before you get the official release.

Getting prompt and efficient support from ZK

When you run into an issue in ZK, following this document can help you to provide the support team with sufficient data, thus speeding up the investigation and get prompt and efficient feedback. Here is a sample screenshot of an error. However, with only a screenshot, it is difficult for us to find enough clues and provide timely support. Instead of providing a screenshot, please follow the tips and instructions below when submitting your issue.

ZK MeetRpoblem01.png

Provide Sufficient information

Providing sufficient information helps us support you more efficiently.

The Sufficient Information Includes:

  1. the complete server-side error or the client-side error if any (read #Check JavaScript Error)
  2. complete exception stack trace (if any)
  3. A reproducible sample (please read #Tips for creating a reproducible sample
  4. Precise and clear steps to reproduce the issue
  5. ZK version and edition
    e.g. ZK 9.0.1 PE
  6. Browser and its version
    e.g. Firefox 60
  7. If it is hard to create a sample, you can provide an URL so that the support team can access it. When providing this URL, remember to turn on the js debug in your zk.xml.
  8. Application servers (e.g. JBoss 6, if it's necessary).
  9. If your case happens only in your specific environment, it is recommended to request an online meeting or provide a virtual machine as a copy of your actual environment
  10. anything else that can help us understand your issue better

Tips for creating a reproducible sample

You can provide:

  1. Use zkfiddle
  2. Zip your maven project with pom.xml and include necessary source code
  3. Provide zul and its related Java source
  4. Provide a public URL that we can visit

Steps:

  1. Clone the original zul with the issue and remove irrelevant components.
  2. Replace your database data with static sample data in order to run without a database.

Check JavaScript Error

You can check if there is any JavaScript error by opening the developer tool. For example, press F12 to open the chrome developer tool/ Console tab:

Chrome-js-error.png

You can extract the error message by:

  • select and copy the whole text or
  • right-click, select "Save as..."

If you cannot provide a reproducible sample

Then you can choose the following alternatives:

Provide a Public URL of Your Web Application

Provide an URL so that the support team can access it. When providing this URL, remember to turn on the js debug in your zk.xml.

Provide ZK AU Request/Response Details

  1. open developer tool before start to reproduce your issue
  2. do the steps to reproduce your bug
  3. Send request details as HAR to us
    * Save all network requests to a HAR file in Chrome
    * Save request details as HAR in Firefox
    Save-har-firefox.png
    * Save request details as HAR in Edge

If your browser doesn't support to save as HAR, or just 1 request is related, you can also send us the screenshot of AU request like:

Au-request.png

Provide Related Source

By checking your zul and Java source, we can try to simulate your case. This is better than inferring what you describe in natural language.

How to Include a JavaScript file

When you need to apply a js patch or include a 3rd-party js library, you have to include the js file in your application. This section describes how you can include the js file for different scopes.

Page-Scope

Application-Scope

If you need to include a javascript file on every zul, there are 2 ways:

By language addon

Create a lang-addon.xml according to ZK Client-side Reference/Language Definition#Language_Addon and include the javascript file with <javascript>. For example:

1 <language-addon>
2     <addon-name>patch-addon</addon-name><!-- give a meaningful name -->
3     <language-name>xul/html</language-name>
4     <depends>zul</depends>
5     <javascript src="~./mypatch.js" />
6     <javascript src="/zkpatch/mypatch2.js"/>
7 </language-addon>
  • Line 4: see the next section
  • Line 5: a path starting with ~./ is a classpath web resource path which is a special path supported by ZK
  • Line 6: You can also link a file under your web application context root

Dependent Addon

If you override a component's widget or extend an existing component, it's crucial to specify <depends> correctly, so that your land addon will take effect. According to which component you override, you need to specify the corresponding addon name. For example:

  • If you override a component in zul language e.g. <button>, you specify

<depends>zul</depends>

  • If you override a component provided by zkmax e.g. <nav>, you specify

<depends>zkmax</depends>

  • If you override something about accessibility, e.g. override aria attribute, you specify

<depends>za11y</depends>

Use <embed>

How to Run a Sample Maven Project

In order to narrow down the problem and eliminate differences caused by different environments, we often send you a sample maven project that tries to simulate and reproduce your issue. To run the project, you need to download maven and setup first.

  1. Run your command line interface
  2. switch to the sample project's root folder that has a pom.xml
  3. Start jetty server with the command below
    mvn jetty:run
  4. Visit the project's pages with your browser

If you don't know the zul's path or if the path is incorrect, just visit http://localhost:8080. A browser will show a link with the correct context path:

JettyRoot.png

Click the link and it will list folders then you can navigate to find the zul.

ListFolder.png

How to get Browser Performance Profile

If you are running into a performance issue, you can first check out Step by Step Trouble Shooting and do a first step analysis using browser's developer tools.

By Chrome developer tool

By Firefox developer tool

By Edge developer tool


Last Update : 2023/04/03

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