Building Logic Tutorial - OpenXava User Interface

It is a common requirement to tune default interfaces to provide polished, production worthy applications.  In most products, you do this by editing HTML files containing complex tags and markups for data binding.

OpenXava provides higher level abstractions to customize your applications, by using the following basic approaches:
  • Layout: declare annotations to your Domain Objects, in exactly the same manner you define persistence and business logic.  A few illustrative examples are shown below.  Consult the OpenXava documentation for a complete discussion.

  • Editors: you can build editors that render / update attribute values, such as a calendar, and (typically on an exception basis) to drop down to JSP code

  • Controllers: you can define buttons whose behavior is implemented in Java/Groovy

Note: to avoid mis-communications, the non-customized versions are shown in thumbnails - click to see them full size.

UI Layout Annotations

Here are the Layout Annotations we have used for basic UI customization in this Tutorial.  Their effects are described in the sections below.

All of the User Interface Annotations used in the Tutorial are shown above, except the List Properties for the Customer's Purchaseorder list attributes, which is specified just as shown above for Purchaseorder Lineitems.


OpenXava supports extensible styles, which enable you to make the page look like this (note the shading of the field, group and tab controls):

Quick aside - while this is a very attractive style, we have used the standard style in some of the screen shots below.  Why?  We do this to illustrate both alternatives, and because our screen shot technology is too blurry using this (more shaded) style when there are layered dialogs.

Mobile Rendering

OpenXava will also render your app appropriately for an iPad (try an address like

Click the thumbnail at the right to see how to set the style.

In addition to the visual style, there are several interesting User Interface elements shown above, such as the Tab Sheets and Attribute Groups.   These are described in the following sections.

Tab Sheets and Attribute Groups

Making good use of screen real estate is a critical interface function.  A well-accepted approach is to utilize tab sheets, in conjunction with multi-column displays.  Additionally, groups can clarify screen content.

By default, fields are not grouped and presented in a single, and each child collection is presented in a separate table, such as the Purchaseorders and Audits for a Customer as at right:

A better interface is shown in the screen shot above:
  1. Customer attributes are grouped - note the Customer / Financial group boxes
  2. Purchaseorders and Audits are combined into a Tab Sheet

You can easily do this with by using
  1. the @View annotation as shown for the Customer entity in the first diagram to define the groups and tab sheets
  2. the @ListProperties controls the Purchaseorder attributes shown, including a footer field from the Customer row

Collection Lists: Show/Choose Parent

Entering child data typically requires that the End User assign a related Parent, such as the Product for a Line item.  A familiar paradigm is a combo box.  

By default, OpenXava generates a form as shown at right, where:
  1. The Line Item List does not show the Product Name
  2. A Product is selected by Number, not from a list of Names
  3. Products are shown with a list of other associated Line Items, which is unnecessary and confusing
A better interface is illustrated in the diagram below (it is a nested dialog, which is why originating page is dark).   In particular, note:
  1. In the page "Purchaseorder"
    • The Lineitems list displays joined Product Names (Hammer, Shovel) and Images, not Product Numbers; this is accomplished with the @ListProperties annotation
  2. In "Edit - Lineitem"
    • We have provided a Combo Box of Product Names (not Product Numbers) for assigning a Product to a Lineitem
    • We are suppressing the list of the other Lineitems for this Product

There effects are achieved as shown in the first diagram, specifically note:
  1. The DescriptionList Annotation for LineItem.product, and

  2. The ListProperty Annotation for Purchaseorder.lineitems

Display Parent Data on Detail: @ReferenceView

In the screen shot above, observe the Purchaseorder page shows the Customer (parent of Purchase Order) Name and Balance.  You achieve this by
  1. On the Purchaseorder Domain object...

    1. Specify customer on the Purchaseorder @View members

    2. Define the Reference View on the Purchaseorder.customer instance variable, specifying the header view

  2. On the Customer Domain Object

    1. Define @Views/View for the header, specifying the subset of attributes to be displayed. 

Choose Parent Data with Filters: @ReferenceView

The screen shot above illustrates the use of a Combo Box to choose Products.  This is great for cases where the set of "parent" data is very small (such as the Tutorial), but it is not efficient when the list is large.  No one wants a combo box of hundreds or thousands of items.

So, OpenXava also provides a mechanism for this.  In the example below, Edit - Lineitem provides a "lantern" to search for and Choose a new value for Product, which provides for filtering (e.g, filter on name as shown the cursor position).

You achieve this as shown below.  At the cursor position, we have commented out the @DescriptionsList which generates the Combo Box.  We have defined our filtered chooser by:
  1. Selecting a ReferenceView (see cursor).  This means use the named view (here, "reference") to display the Product information
  2. The reference view is defined as a named entry in @Views in the Product Domain Object (see the high-lit line), where we designate the columns to display using the usual syntax for multi/new lines.

Data in Tab Sheets

The diagram below illustrates you can specify Tab Sheets not only for child collections, but also for attributes of the current Domain Object, here a rich text field.

Stereotypes: Photos, Money, HTML Text etc

By default, each Domain Attribute is displayed in a text box.  OpenXava enables you to customize the control with @Stereotype - typical examples:

@Column @Stereotype("MONEY")
BigDecimal price;

@Column @Stereotype("PHOTO")
byte [] photo;

@Column  @Stereotype("HTML_TEXT")  // rich text field - see screen shot above
String notes;

The Tutorial illustrates that the Images control not only displays images, but enables you to upload them.   The delivered Tutorial data was previously initialized to contain images as follows:
  1. Navigate to the row you wish to contain the image
  2. Click the Change link (shown below to the right of the hammer image)
  3. Select your image using OpenXava's image chooser (shown below)
  4. Save the updated row

Optional Filters

OpenXava builds filter controls by default, enabling the End User to specify search criteria applied to the list as shown above.  If you find these unnecessary for collections, you can specify the following in your properties/ file with the following:


System Extensibility

It's beyond the scope of this introduction to do more than just hint, but OpenXava is architected as a standard Java web app.  Hence, you can extend the system with new Controllers, and new Editors.  In the example below, we have altered the standard MONEY editor to designate that "$" (the default) is replaced by "$US":

OpenXava 4.5 Layout Extensions

Here is a comparison of the same screen using the 4.5 extended Layout Manager.  Note that (click the diagrams to view in full screen):
  1. Less line-wrap on captions (see Placed On)
  2. Less line-wrap on editor extensions (see trailing $ on Amount Total)