Overview

Project Documentation

User Guide

Introduction

GuidATE is a system of adapters for the ZK web framework that simplify the use of this framework with ApplicATE and DominATE.

GuidATE follows the classic MVC principle. Imagine your ApplicATE services as your model and create views using ZK zul pages, then bind them together so that anywhere something changes the other side of the bind changes too.

Suppose, for example, that you have an ApplicATE command with two properties, say propertyA and propertyB and imagine that propertyB value changes when propertyA is set.

Suppose now that you have a zul page bound to this service with two text boxes bound to propertyA and propertyB respectively. If the user types something in the former text box, propertyA is set, propertyB changes and fires a PropertyChangeEvent. The latter text box listen to propertyB event and update its content.

Back beans

The main concept behind GuidATE binding implementation is that of "back bean".

A "back bean" is an object, typically an ApplicATE service, bound to a container ZK component like a window, a vbox (or hbox), etc. The binding is performed applying the BackBeanComposer to the component and specifying the back bean with the "backBean" custom attribute, like in the following example:

You can specify a String. In this case the real back bean will be created calling the createService method on the ApplicateSession passing in the specified string. The ApplicateSession subclass and service factory used can be specified in the GuidATE configuration as described in the Configuration section.

If you have a component inside this window, i.e. a button, you can find its back bean using the BackBeans utility class:

Object backBean = BackBeans.findBackBean(comp);

where comp is a reference to the button. The findBackBean method will look upside the parent-child components structure until it find a container component bound to a back bean.

If you are interested in this container instead of the back bean, use the findContainer method:

Component container = BackBeans.findContainer(comp);

If you are inside an event handler you can look for the event target back bean:

Properties

Inside a back bean bound container you can put property bound components.

Non-editable properties

The simplest property component is "propertyValue". This is a label that shows the value of a property of the back bean. The label is bound to the property so as to update its content if the back bean fires a PropertyChangeEvent for the bound property.

Like all the other property bound components, a "propertyValue" component can be specified in two ways:

For properties whose class is a collection you can use the "propertyGrid" component. It shows a grid with a row for each element of the collection. Obviously every time the back bean fires a PropertyChangeEvent for the collection the grid is update.

If you don't specify anything inside the "propertyGrid" component, like in the latter example, the grid will have one column without header and the content will be determined using the same type conversion algorithm used for the propertyValue component.

If you need a more complex behavior you can specify columns and a row prototype:

There are situations where informations can better be described by an image rather than words. For example we can show a boolean value with two alternate images. In this cases we can use the "imageProperty" composer:

Generally speaking the imageProperty composer can be used when you have a property that assumes a small set of predefined values like a boolean or an enumeration. You have to give a "valueImage" for each possible value the property can assume. The associated value must be indicated in the value attribute of the valueImage.

Editable properties

Properties can be edited too. To do this for a String property we can use a "textProperty" component:

<textProperty propertyName="myProperty"/>

Now the binding is bidirectional. Like for "propertyValue" the component is updated when the property value changes but, if the user edit it, when the focus leaves the component the property is set.

The component does validation on the property too. At this purpose it uses the DominATE validation facility. If the back bean implements the Validator interface the component uses its methods to validate the property value before setting it. The value is set in the back bean only if validation succeeds.

If the back bean does not implement the Validator interface a DefaultValidator is used.

A special case is represented by the @Length Hibernate Validator annotation. If you annotate your property with it, like in the following snippet:

@Length(max=20)
public String getMyProperty() {
return myProperty;
}

a textProperty component bound to this property will have the maxlength attribute set to the maximum length specified in the annotation so the user will not be able to digit more than the given number of characters.

For properties of other types you have similar components:

intProperty

dateProperty

decimalProperty

timeIntervalProperty

The checkProperty component shows a checkbox bound to a boolean property in the back bean. When the property is true the checkbox is checked, otherwise it is unchecked.

The listProperty component is more complicated. Generally speaking it shows a listbox but we need to distinguish various cases.

The items that will be shown will be each element of the list obtained calling the getList() method on the back bean.

The listbox should have a listhead section and a listitemPrototype. The listitemPrototype is similar in purpose to the rowPrototype we saw for the propertyGrid: it works like a prototype for each listitem that will be visible in the listbox.

When the user select a row in the listbox the corresponding object in the browser is selected too. Using getSelectedObject() in the browser allow you to retrieve this object.

Instead of the standard ZK "listheader" component you can use the browserListheader one. This component allows automatic ordering of the browser content (calling the setOrder() method on the browser) each time the user clicks on the column header. To specify the property name to be passed to the setOrder() method you have two options:

if you used a labelListcell component for the corresponding cell in the prototype the property name is retrieved from its propertyName attribute

if you are not using a labelListcell or if you want to override what's in the labelListcell propertyName attribute you can specify an orderColumn attribute in the browserListHeader

When GuidATE finds the spcial syntax "parentBean.xxx" in the backBean custom attribute it will look for the bean defined in the outside container and it will get its "xxx" property. This will be the actual back bean.

The two textProperty components defined inside the vbox will be bound to properties of the editor, and not of the command.

If you use the same editor in multiple commands you can even define a macro-component and use it where you want passing the property name as an argument.