Felipe Cypriano

You're about to read

Grails With ZK: Embedding ZUL in GSP

How about zk pages and gsp were so friends that we could use both together? Imagine the possibility to use Sitemesh to decorate your page or use UrlMapping to choose what the URL will be. Or you could move your project to ZK painlessly, you could update the pages one by one and the new code will work side by side.

ZKGrails plugin 0.7.6 has been released with this great new feature, you can use two simple tags to include any zul page in your GSP. To include the necessary css and javascript into head use <z:head/> and to insert the content anywhre you want in the body of your gsp you’ll use <z:body/>.

To see it in practice let’s change Grails Quick Start. Follow the steps described there and after you complete all the steps, go back here to update the list.gsp to use ZK Grid component. Don’t forget to use Grails 1.1.2 and ZKGrails 0.7.6 at least.

Embedding ZK in GSP

Firstly create this file: grails-app/conf/BuildConfig.groovy and configure ZKGrails repository:

grails.plugin.repos.discovery.zkgrails = "http://zkgrails.googlecode.com/svn/plugins"
grails.plugin.repos.resolveOrder = ['zkgrails','default','core']

Now you can install ZKGrails version 0.7.6 by executing grails install-plugin zk 0.7.6. After installing ZK plugin, create the zul page we’ll use: web-app/book/list.zul. You can let this file blank for now, before editing it we need to change automatic scaffolding by creating the the gsp pages executing this command:

grails generate-views Book

The command will create 4 gsp files in grails-app/views/book: create.gsp, edit.gsp, list.gsp and show.gsp. We will change the list.gsp to instead of use simple HTML table we’ll use ZK components. Now let’s get back to our web-app/book/list.zul, the objective is to create a grid using zk components and to add a new functionality to delete all selected books. Open list.zul file and put the following code in it:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<?variable-resolver class="org.zkoss.zkplus.spring.DelegatingVariableResolver"?>
<?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" arg0="./wnd"?>
<zk xmlns:n="http://www.zkoss.org/2005/zk/native">
    <window id="wnd" apply="${bookListComposer}">
        <listbox id="listBoxBooks" model="@{wnd$composer.booksModel}" checkmark="true" multiple="true"
                 fixedLayout="true" width="500px">
            <listhead>
                <listheader label="ID" sort="auto(id)" width="50px"/>
                <listheader label="Author" sort="auto(author)" width="225px"/>
                <listheader label="Title" sort="auto(title)" width="225px"/>
            </listhead>
            <listitem self="@{each=book}" value="@{book}">
                <listcell label="@{book.id}"/>
                <listcell label="@{book.author}"/>
                <listcell label="@{book.title}"/>
            </listitem>
        </listbox>
        <n:span class="buttons">
            <button id="btnDelete" sclass="delete" mold="os" label="Delete Selected"/>
        </n:span>
    </window>
</zk>

Next step is create the composer for this list.zul page, the composer is the thing that controls the page’s behavior, just like a controller. Create a BookListComposer.groovy file in grails-app/composers, and this is the content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
import org.zkoss.zkgrails.*
import org.zkoss.zkplus.databind.BindingListModelList

class BookListComposer extends GrailsComposer {

    def wnd
    def listBoxBooks
    def booksModel
    def binder

    def afterCompose = {
        booksModel = new BindingListModelList([], true)
        reloadBooks()
        binder = wnd.getVariable("binder", true)
    }

    public void onClick_btnDelete() {
        if (listBoxBooks.selectedCount > 0) {
            listBoxBooks.selectedItems.each { listItem ->
                def book = listItem.value
                book.delete(flush: true)
            }
            reloadBooks()
        }
    }

    private def reloadBooks() {
        def books = Book.list()
        booksModel.clear()
        booksModel.addAll(books)
        binder?.loadAll()
    }

}

Now we only need to put the zul page in the list.gsp replacing the HTML <table> tag to <z:body />, the final code is this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
        <meta name="layout" content="main" />
        <z:head />
        <title>Book List</title>
    </head>
    <body>
        <div class="nav">
            <span class="menuButton"><a class="home" href="${resource(dir:'')}">Home</a></span>
            <span class="menuButton"><g:link class="create" action="create">New Book</g:link></span>
        </div>
        <div class="body">
            <h1>Book List</h1>
            <g:if test="${flash.message}">
            <div class="message">${flash.message}</div>
            </g:if>

            <z:body />
        </div>
    </body>
</html>

As you can see - lines 5 and 19 - we only need to put the tags where we want it’s content to be in the page. But you might be wondering where is the path to list.zul file? By default the same convention used by Grails’ view, so for our example both tags - head and body - automatically resolves to /book/list.zul. And if you need to specify the files you want you can by setting the attribute zul, like:

<z:body zul="/path/to/file.zul" />

Now we can mashup our both favorite frameworks to make our projects look and behave even better.

# Update 1

Fixed a missing namespace on zul file; and the binder call on BookListComposer. Thanks André.

# Update 2

GitHub repository with full source code used to made this post: http://github.com/fmcypriano/embedding-zul-gsp