ZK in Action [4] : Styling and Layout

In the previous ZK in Action posts we went through implementing a CRUD feature using ZK MVVM. We also quickly went through some styling code that may deserve more explanation.

In this post, we'll go over how to append new CSS styling rules onto ZK widgets and how to override the existing styling. We'll also introduce some basics of UI layout in ZK.

Objective

• Use ZK's layout and container widgets to host the inventory CRUD feature we built in the previous posts.
  
• Style the ZK widgets 

ZK Features in Action

• Borderlayout
• Hlayout
• Tabbox
• Include
• sclass

Using Layouts and Containers

The Borderlayout and Hlayout

The Borderlayout divides the window into 5 sections as shown below:

Without further ado let's dissect the markup and see how it works:

<window ...">
 <borderlayout width="100%" height="100%">
  <north size="15%">
   <hlayout width="100%" height="100%">
   <label hflex="9" value="Alpha Dental" />
   <label hflex="1" value="Sign Out" ></label>
   </hlayout>
  </north>
  <east size="10%"></east>
  <center>
   <tabbox width="100%" height="100%" orient="vertical">
    <tabs width="15%">
     <tab label="Inventory" />
     <tab label="TBD" />
     <tab label="TBD"/>
    </tabs>
    <tabpanels>
     <tabpanel>
      <include src="inventory.zul"/>
     </tabpanel>
     <tabpanel></tabpanel>
     <tabpanel></tabpanel>
    </tabpanels>
   </tabbox>
  </center>
  <west size="10%" ></west>
  <south size="10%"></south>
 </borderlayout>

• line 3 and 27, the north and south widgets can be adjusted for height but not width
• line 9 and 26, the east and west widgets can be adjusted for width but not height
• line 10, the center widget's dimensions are dependent on those entered for the north, west, south, and east widgets
• from line 4 through 7, we wrap the two labels with an Hlayout so they'll be displayed side by side proportionally with respect to the "hflex" attribute we specified. That is, the Label assigned with hflex="9" has 9 times the  width of the Label assigned with hflex="1".
• each inner widget (north, west, etc.) can accept only a single child component, hence, multiple widgets must be wrapped by a single container widget such as Hlayout before placed inside the Borderlayout inner widgets (north, west, etc.)
• line 11, we place a Tabbox element and set its orientation as vertical in anticipation of embedding our inventory CRUD feature inside it
• line 12 to 16, we put the heading for each tab
• line 18, a Tabpanel is a container that holds a tab's content
• line 19, we embed our inventory CRUD feature inside an Include tag. The widgets on inventory.zul will be attached to this page

Overriding the Existing ZK Styling Rules

The ZK default font properties and the background colours were modified so headings would be presented more prominently. Let's quickly explain how this is accomplished.
Using Chrome Developer Tool or the Firebug extension, we could easily inspect the source of our Borderlayout and find the ZK styling class for the ZK widgets as shown below:

From here we learned that the naming pattern for the highlighted region is z-north-body. Similarly, we could do the same for all the markup of interest and go ahead overriding their CSS styling rules:

<zk>
<style>
  .z-tab-ver .z-tab-ver-text { font-size: 18px; } 
  .z-north-body, .z-south-body { background:#A3D1F0 }
  .z-east-body, .z-west-body { background:#F8F9FB }
</style>
<window border="none" width="100%" height="100%">
 <borderlayout width="100%" height="100%">
  <north size="15%">...</north>
  <east size="10%"></east>
  <center>...</center>
  <west size="10%"></west>
  <south size="10%"></south>
 </borderlayout>
</window>
</zk>

Appending Additional Styling Rules via Style Attribute

Here we're modifying the styling of the Labels contained in the North widget. Since we only want these two Labels, not all of them, to be affected by our new styling, it does not make sense for us to override the original styling as we did before. For these isolated modifications, it suffice to simply assign the styling rules to the "style" attribute that comes with the ZK widgets:

<north size="15%">
   <hlayout width="100%" height="100%">
   <label value="Alpha Dental" style="font-size: 32px; font-style: italic; font-weight:bold; color:white; margin-left:8px;"/>
   <label value="Sign Out" style="font-size: 14px; font-weight:bold; color:grey; line-height:26px"></label>
   </hlayout>
  </north>...

Appending Additional Styling Rules via Sclass

An alternative to assign styling rules directly in the markup and pollute the code is to declare a styling class, abbreviated as "sclass", and assign the rules to the "sclass" attribute as shown here:

<zk>
<style>
  .company-heading {
   font-size: 32px; 
   font-style: italic; 
   font-weight:bold; 
   color:white; 
   margin-left:8px;
  }
</style>
<window ...>
 <borderlayout ...>
  <north ...> <label value="Alpha Dental" sclass="company-heading"/></north>
  ...
 </borderlayout>
</window>
</zk>

In a Nutshell

• Three ways to modify the default ZK styling is covered in this post: override the existing ZK styling class, assign styling rules directly to a widget's style attribute, or define a CSS class in a CSS file or inside a Style tag then assign the class to the widget's sclass attribute
• Use a developer tool(such as Firebug) to inspect the ZK widgets and find out which ZK style class to override
• The hlex attribute allows developers to define widgets' width proportionally with respect to each other
• Layout widgets help developers to divide the presentation window into sections

References

ZK Styling Guide
Borderlayout
Hlayout
Hflex

jQuery Selector Inspired Controller in ZK 6's MVC Pattern

The MVC pattern is adopted pervasively among Web frameworks. Various flavours exist for the pattern but the common goal is to achieve separation of concerns.

Under the ZK framework, MVC implementation ultimately requires the Controller to gain reference to, and listen events coming from, the UI components in View. An interesting bit of ZK 6's MVC pattern is the CSS/jQuery Selector inspired mechanism in its Controller that makes this plumbing task simpler and more flexible.

ZK Primer

In simplicity, ZK is a component based and event driven Ajax Java framework. Understanding this basic description alone is enough to take us through its MVC pattern.

Component based

A component either declared in XML or in Java has its state maintained as a POJO in the JVM. A component is then rendered with a set of JavaScript instructions at client side.

Event Driven

Each UI component can listen to event(s). There's a variety of ways to register event listeners to the components.
Just to name a few here,
in XML:

<button onclick="...">
</button>

in Java:

Button btn = new Button();
btn.addEventListener("onClick", new EventListener(){...});       

MVC Nomenclature in ZK

The component declarations make up the View. Although it's possible to construct the UI in Java, akin to GWT or Swing, most would prefer writing mark-up in XML. A ZUL in ZK is an XML compliant page that contains the UI mark-up. One can consider a ZUL page as an Ajax enabled JSP page.

The Controller in ZK is a Java class that implements the Composer interface or extends any one of Composer's implementations. SelectorComposer is the target of our investigation in this post.

Selector Inspired Controller in Action

Consider a simple window that prompts a user to enter her name, email address, and select the journal she'd like to subscribe:

We'll examine how the server-side selector mechanism works in our controller class as we implement the following features:

1. Displaying a list of the available journals for subscription in a combo box
2. Clear all fields in this simple form when the "Clear" button is clicked

Let's first see the components in mark-up which our controller will work with:

<grid apply="lab.zkoss.mvc.SubscriptionComposer">
        ...
    <rows>
        <row>
            <label value="User Name"/>
            <textbox mold="rounded"/> 
        </row>
        <row>
            <label value="email"/>
            <textbox mold="rounded"/> 
        </row>
        <row>
            <cell ...>
                <label value="Please subscribe me to "></label>
                <combobox model="${journalListModel}">
                    <template name="model">
                       <comboitem label="${each.title}"/>
                    </template>
                </combobox>
            </cell>
        </row>
        <row>
            <cell ...>
                <button label="Clear" ..."/>
                <button label="Submit" ..."/>
            </cell>
        </row>
        </rows>
</grid>

In our controller class, to implement the said features under the ZK framework, we'd need to gain reference to the UI components so the list of available journals can be rendered in the combo box and the onClick event for the Clear button can be handled.

public class SubscriptionComposer extends SelectorComposer{

 @Wire("combobox")
 Combobox journalbox;

 @Wire("textbox, combobox")
 List<InputElement> inputs;
 
 
 public void doAfterCompose(Component comp) throws Exception{ 
  super.doAfterCompose(comp);
  JournalDAO jdao = new JournalDAO();
  List<Journal> journalList = jdao.findAll();
  ListModelList journalListModel = new ListModelList(journalList);
  journalbox.setModel(journalListModel);
  
 }
 
 @Listen("onClick = button[label='Clear']")
 public void clearAll(){
  for(InputElement i:inputs) i.setText("");
 }
}

Let's elaborate on how selectors are used.

The Controller's Scope

When a controller is "applied" to a component, all of the component's children components also become accessible to the controller. 

In our implementation, the grid component is applied with our controller:

<grid apply="lab.zkoss.mvc.SubscriptionComposer">
...
</grid>

Hence the grid and all of its children components define the scope which our controller SubscriptionComposer can take effect.

Component Wiring

The @Wire annotation on line 3 and 6 take in a CSS selector pattern as its parameter. With the pattern "combobox, the annotation associates the sole combo box in our UI mark-up with the Combobox instance, journalbox declared in the controller class.
One of the many alternatives to achieve the same exact wiring is to give the Combox an ID, for instance:

<combobox id="thisworks2">
...
</combobox>

and the parameter for the annotation would be:

@Wire("#thisworks2")
Combobox journalbox;

Component Initialization

Once we've obtained references to the UI components in View, we could initialize them accordingly.
The doAfterCompose method allows developers to insert instructions to be executed right after the component under effect and its children are created. It's a method invoked by the framework and must be implemented for all classes implementing the Composer interface; such as the SelectorComposer class which we're extending our SubscriptionComposer from.

For our hypothetical feature, we need to initialize our combo box by populating it with a list of journals available for subscription.

@Wire("combobox")
 Combobox journalbox;

 ...
 
 public void doAfterCompose(Component comp) throws Exception{ 
  super.doAfterCompose(comp);
  JournalDAO jdao = new JournalDAO();
  List<Journal> journalList = jdao.findAll();
  ListModelList<Journal> journalListModel = new ListModelList(journalList);
  journalbox.setModel(journalListModel);
  
 }

On line 11, the combo box which we obtained reference to via the selector mechanism, is given the model data we prepared on line 10. ListModelList is a wraper class that enables changes made in its wrapped collection to be updated on its host UI component accordingly.

<combobox model="${journalListModel}">
        <template name="model">
            <comboitem label="${each.title}"/>
        </template>
    </combobox>

Once the combo box is supplied with a list model, the template tag will iteratively create a combo item for each entry in the list model.

Event Listening

The @Listen annotation adds method clearAll, as an event listener for the onClick event, to the button matching the pattern button[label="Clear"].

@Wire("textbox, combobox")
 List<InputElement> inputs;
 
 @Listen("onClick = button[label='Clear']")
 public void clearAll(){
  for(InputElement i:inputs) i.setText("");
 }

As before, there're many alternatives to the selector pattern shown here. One possibility is cell:first-child button, since the "Clear" button is the only component that matches this pattern.

<cell ...>
        <button label="Clear" ..."/>
        <button label="Submit" ..."/>
    </cell>

The brevity of the clearAll method is made possible because a single annotation @Wire("textbox, combobox") in fact wired all fields in the UI to a list of ZK components.

In a Nutshell

In a typical ZK controller class implementation, before we can initialize a UI component, listen to its events, or change its state, we must first obtain a reference to that component.
This CSS/jQuery selector inspired controller gives us great flexibility in referencing the UI components of interest. A reference can be made by matching a component's ID, class name, component attributes, or by traversing through the component tree.
With this flexibility, changes made in the UI cause us minimum grief since the controller code can be updated as easily as coming up with new selector patterns.

References

ZK SmallTalks
ZK Developer's Reference