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:support@potix.com 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 info@zkoss.org.
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.
Provide Sufficient information
Providing sufficient information helps us support you more efficiently.
The Sufficient Information Includes:
- 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 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 zkfiddle
- Zip your maven project with pom.xml and include necessary source code
- Provide zul and its related Java source
- Provide a public URL that we can visit
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.
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:
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
- Open the browser developer tool before starting to reproduce your issue
- Do the steps to reproduce your problem
- 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 request details as HAR in Edge
If your browser doesn't support saving requests as HAR, or just 1 request is related, you can also send us the screenshot of AU request like:
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
- Use the script directive <?script?>
- Use the script component <script>
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 Apply a Java Patch
When there is a bug, we provide a workaround with a Java file. Here are the steps to apply it:
- Put the patched Java file in its package under your project source
- Compile it with your project source
Then it can override the Java class in the ZK jar.
Example
Got a patched org.zkoss.bind.impl.BinderImpl
.
- create a package
org.zkoss.bind.impl
in your project source - put
BinderImpl.java
under the package
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.
- Run your command line interface
- switch to the sample project's root folder that has a
pom.xml
- Start jetty server with the command below
mvn jetty:run
- 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:
Click the link and it will list folders then you can navigate to find the zul.
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