Introduction

Instead of using iframe, since ZK 9, there is a new way to embed ZK applications into an external application such as a NodeJS or Python-based web page.

In other words, with this feature we can easily combine ZK with other front-end frameworks. By using ZK client binding in Javascript, we can also control ZK components in these non-ZK web applications.

Demo

Before launching both applications, we need to do some settings.
First, we have to turn on the embedded API by setting the library property in zk.xml. (More Information)

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

Second, we have to configure Nginx (or other routing mechanism) with the following settings.

location / {
	proxy_pass http://127.0.0.1:9000;
	root   html;
	index  index.html;
}

location /zkembedded-app/ {
	proxy_pass http://127.0.0.1:8080;
}

The ZUL file used in the demo is as follows:

ZUL

<zk>
 <window id="win" hflex="1" vflex="1"
viewModel="@id('vm') @init('zk.demo.DemoVM')">
 <spreadsheet maxVisibleRows="200" maxVisibleColumns="40" hflex="1" vflex="1" 
src="@bind(vm.zssSrc)" showContextMenu="true"
showToolbar="@bind(vm.toolbarVisible)" showSheetbar="@bind(vm.sheetbarVisible)"
showFormulabar="@bind(vm.formulabarVisible)">
 </spreadsheet>
 </window>
</zk>

We use ZK MVVM in this demo, but you can definitely use a different pattern here.

In the NodeJS application, we use HTML + Bootstrap.

To use the new feature and embed ZK into the HTML file, we need to load the specific script and run the “load” method.

In HTML file:

<div id="embeddedZK" style="height:80%">  
  Loading...
</div>
<script id="embeddedScript"
src="/zkembedded-app/zkau/web/js/zkmax/embedded/embedded.js">

The DIV which has an id “embeddedZK” is now prepared for including ZK content.

After loading the embedded script, we can use the two methods in embedded.js to load or destroy ZK contents.

API in embedded.js

We provide two API methods for embedding ZK:

• zEmbedded.load(domId, ZKSrc)
  The “domId” means after loading resource from “ZKSrc”, the content of “domId” (HTML DOM Element) will be replaced with the ZK content.
• zEmbedded.destory(domId, skipError)
  We can remove the specific ZK desktop in the HTML DOM Element. If “skipError” is true, the function will skip error messages when any error occurs.

Control ZK Components when using embedded ZK

After loading the ZK contents, we can use ZK Client Binding to control the ZK components in the view.
To read more information, please refer to ZK MVVM Book – Client Binding

I hope you find this component interesting. Please download ZK 9.0 to try it out and let us know how you like it!
For further information, please check out ZK Developer’s Reference – Embedded ZK Application.

Downloads

The runnable demo project is available on Github – Embedded ZK Demo.