ZK Developer's Reference/Integration/ZK Embedded/Embed ZK Component in Foreign Framework

Employment/Purpose

Here describes how to embed ZK component(s) as a native element of a foreign framework. For example, how to embed ZK components as a native JSF component. It allows application developers to use the native element without knowing the existence of ZK.

For sake of description, we call it the embedded component.

---

Note: if it is OK for your developers to work on ZUL directly. it is more convenient and powerful to use the inclusion (such as <jsp:include>) or ZK JSP Tags, and you don't have to wrap them into a native element.

Embed a component directly

The simplest way to embed is to invoke Renders.render(ServletContext, HttpServletRequest, HttpServletResponse, Component, String, Writer) when it is time to output the content of the native element.

For example, if you are implementing a JSP tag, then you can invoke the render method in doTag() as follows.

<syntax lang="java"> public void doTag() throws JspException, IOException {

   //prepare variables
   final JspContext jspctx = getJspContext();
   final PageContext pgctx = Jsps.getPageContext(jspctx);
   final ServletContext svlctx = pgctx.getServletContext();
   final HttpServletRequest request = (HttpServletRequest)pgctx.getRequest();
   final HttpServletResponse response = (HttpServletResponse)pgctx.getResponse();

   //create components
   Listbox listbox = new Listbox();
   listbox.appendChild(new Listitem("Item 1"));
   listbox.appendChild(new Listitem("Item 2"));

   //render the result
   final StringWriter out = new StringWriter();
   Renders.render(config.getServletContext(), request, response, listbox, null, out);
   getJspBody().invoke(out);

} </syntax>

Embed by implementing a richlet

If you want to have more control, such as applying a composer provided by users or creating components from a ZUL page, you could implement a richlet (Richlet) and then invoke Renders.render(ServletContext, HttpServletRequest, HttpServletResponse, Richlet, String, Writer) instead.

Environment setup for using an embedded component

To use an embedded component, ZK Update Engine (DHtmlUpdateServlet) is required, while ZK Loader (DHtmlLayoutServlet) is not (though it is safe to install it too. If ZK Loader is not installed, it assumes the udpate URI is /zkau, which can be overriden by setting a library property called org.zkoss.zkplus.embed.updateURI.

<syntax lang="xml"> <servlet> <servlet-name>auEngine</servlet-name> <servlet-class>org.zkoss.zk.au.http.DHtmlUpdateServlet</servlet-class> </servlet>

<servlet-mapping> <servlet-name>auEngine</servlet-name> <url-pattern>/zkau/*</url-pattern> </servlet-mapping> </syntax>

Version History

Version	Date	Content
5.0.5	September 2010	Renders was introduced to simplify the making of a native element for a foreign framework.