Embedded ZK Application"
m (moved ZK Developer's Reference/Integration/Miscellaneous/Embedded ZK Application to ZK Developer's Reference/Integration/ZK Embedded/Embedded ZK Application: collate zk embedded pages) |
m (use syntaxhighlight (via JWB)) |
||
| Line 23: | Line 23: | ||
'''index.html''' | '''index.html''' | ||
| − | < | + | <syntaxhighlight line lang="html" high="11,13"> |
<!DOCTYPE html> | <!DOCTYPE html> | ||
<html> | <html> | ||
| Line 40: | Line 40: | ||
</body> | </body> | ||
</html> | </html> | ||
| − | </ | + | </syntaxhighlight> |
* line 11: load the zk embedded JS API script | * line 11: load the zk embedded JS API script | ||
| Line 57: | Line 57: | ||
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. | 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') | zEmbedded.load('embeddedZK', 'http://zkembedded-app/demo.zul') | ||
.then(function(result) { | .then(function(result) { | ||
| Line 64: | Line 64: | ||
alert('ZK mounting error: ' + 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 "then" method of the promise is invoked when the embedding has completed, and the embedded page has been loaded. | ||
| Line 82: | Line 82: | ||
In Cross Origin scenarios the responses from the ZK application need to set at least the following CORS headers: | In Cross Origin scenarios the responses from the ZK application need to set at least the following CORS headers: | ||
| − | < | + | <syntaxhighlight line lang="javascript"> |
Access-Control-Allow-Origin: [allowed embedding origins] | Access-Control-Allow-Origin: [allowed embedding origins] | ||
Access-Control-Allow-Headers: zk-sid | Access-Control-Allow-Headers: zk-sid | ||
| Line 88: | Line 88: | ||
Access-Control-Allow-Credentials: true | Access-Control-Allow-Credentials: true | ||
Access-Control-Allow-Methods: GET, POST | Access-Control-Allow-Methods: GET, POST | ||
| − | </ | + | </syntaxhighlight> |
This can be done by configuring your server (e.g. nginx, apache-httpd, tomcat, spring-boot...) appropriately and is '''not''' ZK-specific. | This can be done by configuring your server (e.g. nginx, apache-httpd, tomcat, spring-boot...) appropriately and is '''not''' ZK-specific. | ||
Revision as of 09:34, 24 June 2021
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:
-
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.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
| Version | Date | Content |
|---|---|---|
| 9.0.0 |