Embedded ZK Application"

From Documentation
(31 intermediate revisions by 4 users not shown)
Line 4: Line 4:
 
Instead of using iframe, there is a new way to use ZK in a non-ZK web container. For example, we could use NodeJs, Python, etc. as the web application, and embed another ZK application in the web pages.
 
Instead of using iframe, there is a new way to use ZK in a non-ZK web container. For example, we could use NodeJs, Python, etc. as the web application, and embed another ZK application in the web pages.
 
{{ZK EE}}
 
{{ZK EE}}
[ since 9.0.0 ]
+
{{versionSince| 9.0.1 }}
  
 
=Prerequisite=
 
=Prerequisite=
Line 17: Line 17:
 
</source>
 
</source>
  
==Settings in the other application==
+
=[https://github.com/zkoss-demo/zkembedded-demo Demo Example]=
When using Embedded ZK, we need to handle all of the requests, whose target URL point to ZK application.
+
In the [https://github.com/zkoss-demo/zkembedded-demo Demo project], there are 2 web applications, one is a non-ZK web application (http://localhost:8080), and another one is a ZK application (http://zkembedded-app).
  
To deal with this problem, we should handle the requests whose target is ZK application.
+
We'll embed ZK into the non-ZK web application.
  
We could use Nginx or some apache solutions to redirec those requests to the ZK URL.
+
'''index.html'''
 
+
<syntaxhighlight line lang="html" high="11,13">
For example, we could add the following setting in Nginx : (ZK application - zktest)
 
<source>
 
location / {
 
  #Non-ZK Application
 
  proxy_pass http://127.0.0.1:9000;
 
}
 
 
 
location /zktest/ {
 
  #ZK Application
 
  proxy_pass http://127.0.0.1:8090;
 
}
 
</source>
 
 
 
=Example=
 
After doing all the settings in the ZK application and the non-ZK application, now we could embed ZK pages in our web application.
 
<syntax lang="html" high="11,13">
 
 
<!DOCTYPE html>
 
<!DOCTYPE html>
 
<html>
 
<html>
Line 47: Line 31:
 
</head>
 
</head>
 
<body>
 
<body>
<div id="embeddedZK">
+
<div id="embeddedZK" style="height:80%">
Loading...
+
Loading...
 
</div>
 
</div>
<script src="/zk90test/zkau/web/js/zkmax/embedded/embedded.js"></script>
+
<script id="embeddedScript" src="http://zkembedded-app/zkau/web/js/zkmax/embedded/embedded.js" />
 
<script>
 
<script>
zEmbedded.load('embeddedZK', 'http://localhost/zk90test/demo.zul');
+
zEmbedded.load('embeddedZK', 'http://zkembedded-app/demo.zul');
 
</script>
 
</script>
 
</body>
 
</body>
 
</html>
 
</html>
</syntax>
+
</syntaxhighlight>
 +
 
 +
* line 11: load the zk embedded JS API script
 +
* line 13: load '''demo.zul''' (of the ZK application) into the DOM Element with id '''embeddedZK'''.
 +
 
 +
To see more information, please download the [https://github.com/zkoss-demo/zkembedded-demo Demo project].
 +
 
 +
=API in embedded.js=
 +
 
 +
We provide two methods to embed ZK.
 +
 
 +
==zEmbedded.load(domId, ZKSrc)==
 +
 
 +
The "domId" means after loading resource from "ZKSrc", the content of "domId" (HTML DOM Element) would be replaced with the ZK content.
 +
 
 +
This function returns a [https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promise object], which means that we can call functions after ZK is ready.
 +
 
 +
<syntaxhighlight line lang="javascript">
 +
zEmbedded.load('embeddedZK', 'http://zkembedded-app/demo.zul')
 +
  .then(function(result) {
 +
    zk.log('ZK is ready!' + result.widget.uuid); //result contains the first widget
 +
  }).catch(reason => {
 +
    alert('ZK mounting error: ' + reason);
 +
});
 +
</syntaxhighlight>
 +
 
 +
The "then" method of the promise is invoked when the embedding has completed, and the embedded page has been loaded.
 +
 
 +
The "catch" method of the promise is invoked when the embedding process encounters a failure. The reason object contains the error message associated with the failure.
 +
 
 +
==zEmbedded.load(domId, ZKSrc, ZKHost)==
 +
{{versionSince| 9.6.0 }}
 +
 
 +
To handle the URL redirection, we can specify the ZK Host URL.
 +
<syntaxhighlight line lang="html">
 +
<script id="embeddedScript" src="/embedded/embedded.js"></script>
 +
<script>
 +
zEmbedded.load('embeddedZK', '/embedded/demo.zul', '/embedded');
 +
</script>
 +
</syntaxhighlight>
 +
 
 +
Notice that the URL redirection should rewrite the locations:
 +
 
 +
<syntaxhighlight line lang="javascript">
 +
/embedded/embedded.js -> http://zkembedded-app/zkau/web/js/zkmax/embedded/embedded.js
 +
</syntaxhighlight>
 +
 
 +
<syntaxhighlight line lang="javascript">
 +
/embedded -> http://zkembedded-app/embedded
 +
</syntaxhighlight>
 +
 
 +
==zEmbedded.destroy(domId, skipError)==
 +
 
 +
This will destroy the embedded ZK desktop at server side and clear the DOM Element. Use "skipError = true" to ignore error messages.
 +
 
 +
=Control ZK Components when using embedded ZK=
 +
After loading the ZK contents, we could use the ZK Client binding to control the ZK components in the view.
 +
 
 +
To see more information, please refer to [http://books.zkoss.org/zk-mvvm-book/8.0/data_binding/client_binding_api.html ZK MVVM Book - Client Binding].
 +
 
 +
=Cross-Origin Resource Sharing=
 +
In Cross Origin scenarios the responses from the ZK application need to set at least the following CORS headers:
  
In line 11, we use <script> to load ZK embedded JS.
+
<syntaxhighlight line lang="javascript">
 +
Access-Control-Allow-Origin: [allowed embedding origins]
 +
Access-Control-Allow-Headers: zk-sid
 +
Access-Control-Expose-Headers: zk-sid, zk-error
 +
Access-Control-Allow-Credentials: true
 +
Access-Control-Allow-Methods: GET, POST
 +
</syntaxhighlight>
  
In line 13, we call zEmbedded to load the demo.zul, and the "embeddedZK" means that the embedded ZK page would be rendered in the corresponding DOM Element (DOM id).
+
This can be done by configuring your server (e.g. nginx, apache-httpd, tomcat, spring-boot...) appropriately and is '''not''' ZK-specific.
 +
Please refer to the related documentation (e.g. [https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS MDN: Cross-Origin Resource Sharing (CORS)]) and your specific server configuration guides.
  
 
=Version History=
 
=Version History=

Revision as of 23:03, 11 July 2021


Embedded ZK Application


Employment/Purpose

Instead of using iframe, there is a new way to use ZK in a non-ZK web container. For example, we could use NodeJs, Python, etc. as the web application, and embed another ZK application in the web pages.

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png

Since 9.0.1

Prerequisite

Settings in the ZK application

We use library property to enable the embedded feature. For example: (In zk.xml)

<library-property>
	<name>org.zkoss.web.servlet.http.embedded.enabled</name>
	<value>true</value>
</library-property>

Demo Example

In the Demo project, there are 2 web applications, one is a non-ZK web application (http://localhost:8080), and another one is a ZK application (http://zkembedded-app).

We'll embed ZK into the non-ZK web application.

index.html

 1 <!DOCTYPE html>
 2 <html>
 3 	<head>
 4 		<meta charset="UTF-8">
 5 		<title>Title</title>
 6 	</head>
 7 	<body>
 8 		<div id="embeddedZK" style="height:80%">  
 9 			 Loading...
10 		</div>
11 		<script id="embeddedScript" src="http://zkembedded-app/zkau/web/js/zkmax/embedded/embedded.js" />
12 		<script>
13 			zEmbedded.load('embeddedZK', 'http://zkembedded-app/demo.zul');
14 		</script>
15 	</body>
16 </html>
  • line 11: load the zk embedded JS API script
  • line 13: load demo.zul (of the ZK application) into the DOM Element with id embeddedZK.

To see more information, please download the Demo project.

API in embedded.js

We provide two methods to embed ZK.

zEmbedded.load(domId, ZKSrc)

The "domId" means after loading resource from "ZKSrc", the content of "domId" (HTML DOM Element) would be replaced with the ZK content.

This function returns a Promise object, which means that we can call functions after ZK is ready.

1 zEmbedded.load('embeddedZK', 'http://zkembedded-app/demo.zul')
2   .then(function(result) {
3     zk.log('ZK is ready!' + result.widget.uuid); //result contains the first widget
4   }).catch(reason => {
5     alert('ZK mounting error: ' + reason);
6 });

The "then" method of the promise is invoked when the embedding has completed, and the embedded page has been loaded.

The "catch" method of the promise is invoked when the embedding process encounters a failure. The reason object contains the error message associated with the failure.

zEmbedded.load(domId, ZKSrc, ZKHost)

Since 9.6.0

To handle the URL redirection, we can specify the ZK Host URL.

1 <script id="embeddedScript" src="/embedded/embedded.js"></script>
2 <script>
3 	zEmbedded.load('embeddedZK', '/embedded/demo.zul', '/embedded');
4 </script>

Notice that the URL redirection should rewrite the locations:

1 /embedded/embedded.js -> http://zkembedded-app/zkau/web/js/zkmax/embedded/embedded.js
1 /embedded -> http://zkembedded-app/embedded

zEmbedded.destroy(domId, skipError)

This will destroy the embedded ZK desktop at server side and clear the DOM Element. Use "skipError = true" to ignore error messages.

Control ZK Components when using embedded ZK

After loading the ZK contents, we could use the ZK Client binding to control the ZK components in the view.

To see more information, please refer to ZK MVVM Book - Client Binding.

Cross-Origin Resource Sharing

In Cross Origin scenarios the responses from the ZK application need to set at least the following CORS headers:

1 Access-Control-Allow-Origin: [allowed embedding origins]
2 Access-Control-Allow-Headers: zk-sid
3 Access-Control-Expose-Headers: zk-sid, zk-error
4 Access-Control-Allow-Credentials: true
5 Access-Control-Allow-Methods: GET, POST

This can be done by configuring your server (e.g. nginx, apache-httpd, tomcat, spring-boot...) appropriately and is not ZK-specific. Please refer to the related documentation (e.g. MDN: Cross-Origin Resource Sharing (CORS)) and your specific server configuration guides.

Version History

Last Update : 2021/07/11


Version Date Content
9.0.0



Last Update : 2021/07/11

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