Chee-keong has posted 2 posts at DZone. View Full User Profile

Creating Master-Detail Forms with Vaadin and Grails

05.31.2010
| 30922 views |
  • submit to reddit

In the article, Groovy, Grails and Vaadin, Petter Holmström outlined an example of using Vaadin with Grails, to build a simple data bound UI for a single database table. This was a great article that showed how one can quickly build a web-based solution that behaves very much like a typical client-server application. However, there are many instances where we need to be able to build an entry screen which allows the user to update both the master record and its detail records at the same time, such as in an Invoice entry screen. In this article I looked at extending the example in the above article, leveraging the simplicity of the Vaadin framework and the GORM capabilities, to build a master-detail example.

After years of doing development using Oracle Forms, I liked the way it provides generic functions on each form (or data block) to allow users to add new records, delete them, query them and navigate from one record to the next. Furthermore, in Oracle Forms, you could provide a data grid to allow the user to edit the related detail table (such as the invoice lines in an Invoice document) and keeps these records in sync with the Invoice header (master) record.

This is a first attempt at reproducing some of these capabilities using Vaadin and Grails.

The master-detail data model


The example here is an extension of the Petter Holmström model of the Trip Planner.  In the original example, there is a table holding information on trips taken by the user. We will extend that example by having a one-to-many relation with a table of the places that are visited in each trip.

This is the code for the Trip domain class. Notice that we are using Grails 1.3.1 which, by default, puts the domain class into the tripplanner package.

package tripplanner

class Trip {

static constraints = {
name(nullable: true)
city(nullable: true)
startDate(nullable: true)
endDate(nullable: true)
purpose(nullable: true)
notes(nullable: true)
}

String name
String city
Date startDate
Date endDate
String purpose
String notes

static hasMany = [ places : Place ]

static mapping = {
places lazy:false, cascade:"all,delete-orphan"
}
}


We have made the fields nullable for ease of inserting the record into the table. We also created the one-to-many relation with the Place domain class, and put in the mapping to cascade the deletion and updates to the sub-table class. We also need to change the relation from lazy to eager to ensure that the all detail records are loaded at the same time as the master (header) record.

As for the Place domain class, we have 2 fields; name of the place we visited and a description field.  In addition, we also put in a transient field, "_deleted", hich we will use to mark a detail record for deletion.

package tripplanner

class Place {

static constraints = {
name(nullable: true)
description(nullable: true)
}

String name
String description
boolean _deleted

static transients = [ '_deleted' ]

static belongsTo = [trip:Trip]
}

 

The master-detail form

Now, we need to change the VaadinApp class. Instead of listing the master record in a table to be selected for editing, I have opted to follow the Oracle Forms style for letting the user query for master records using Query By Example (QBE).  The standard GORM and Hibernate infrastructure allows the use of a "example" object as a query pattern to extract a subset of records.  This unfortunately is not exactly how Oracle
Forms QBE works as Oracle Forms allows the user to put in "A%" patterns to query for values that starts with "A" and ">999" to query for values that is bigger than 999. The QBE in GORM only allows exact matches. We will accept this limitation for this example.

So now we need a set of buttons to allow the user to:

  • New - Add a new record data entry
  • Save - Saves the current record to the database, including the changes done to the detail table
  • Del - Deletes the current master record and the associated detail records
  • EnterQ - Enters into Query mode which allows the user to provide a pattern for a QBE search
  • ExecQ - Executes the Query and shows the first matching record from the query
  • ExitQ - Exits out of Query mode and goes back to New record mode
  • Prev - Go to previous record if there any queried records
  • Next - Go to next record if there are any queried records
These buttons are located at the top of the master record form.

Sample screen
Error messages which arise from the save / update button are listed at the top of the master record form fields (in the "description field" of the Vaadin Form).

There is also a status indicator label located at the footer of the master record form ("footer section" of the Vaadin Form). The status label will show the current mode of the master record entry screen and also the current record number if this is part of a query set.

Below the master record form is the editable, selectable detail records table which is located in its own panel.  Users are allowed to edit the detail record table only if the master record is in Edit mode.  This means that users need to save the newly created master (header) record before that they can add any detail records.

The detail record table has a column for all the editable, visible records excluding the "_deleted" field which is for internal use only. To manipulate the detail records, we provide 2 buttons to add a new detail record (the "+" button) or delete the selected detail record (the "-" button).  All additions, deletions or even updates are only saved to the database after the user clicks on the "Save" button in the master (header) record form.

As the user moves from one master record to the next using the "Prev" and "Next" buttons in the master table form, the detail table will be synchronized accordingly.

package tripplanner

import com.vaadin.ui.*
import com.vaadin.data.*
import com.vaadin.data.util.*

class VaadinApp extends com.vaadin.Application {

def query
def rec_pos
def container = new BeanItemContainer<Place>(Place.class)
def master_fields = ["name", "purpose", "startDate", "endDate", "city", "notes"]

def saveButton
def newButton
def delButton
def entQButton
def exeQButton
def extQButton
def prevButton
def nextButton
def statusLabel
def pnlDetail

void new_mode(editor) {
def tripInstance = new Trip()
editor.itemDataSource = new BeanItem(tripInstance)
editor.visibleItemProperties = master_fields
editor.description = ""
container.removeAllItems()

saveButton.setEnabled(true)
delButton.setEnabled(false)
entQButton.setEnabled(true)
extQButton.setEnabled(false)
statusLabel.setValue "New Mode"
pnlDetail.setEnabled(false)
}


void init() {
//def window = new Window("Trip Maintenance", new SplitPanel(SplitPanel.ORIENTATION_HORIZONTAL))
def window = new Window("Trip Maintenance")
setMainWindow window

// Form Panel
def panel = new Panel("Trip Maintenance")
panel.setSizeFull()
panel.setLayout(new VerticalLayout());

// Trip editor
def tripEditor = new Form()
tripEditor.setSizeFull()
tripEditor.layout.setMargin true
tripEditor.immediate = true
tripEditor.visible = true

// status bar - shows the mode of the form
statusLabel = new Label("New Mode")

// define master form buttons
saveButton = new Button("Save")
newButton = new Button("New")
delButton = new Button("Del")
entQButton = new Button("EnterQ")
exeQButton = new Button("ExecQ")
extQButton = new Button("ExitQ")
prevButton = new Button("Prev")
nextButton = new Button("Next")

// set initial state of buttons
delButton.setEnabled(false)
extQButton.setEnabled(false)

// default is New Mode
def v_tripInstance = new Trip()
tripEditor.itemDataSource = new BeanItem(v_tripInstance)
tripEditor.visibleItemProperties = master_fields
//new_mode(tripEditor)

// panel for detail form
pnlDetail = new Panel()
pnlDetail.setEnabled(false)

// table to hold the detail form rows
def table = new Table()
table.containerDataSource = container
table.selectable = true
table.editable = true
table.setSizeFull()
table.visibleColumns = ["name", "description"]
table.immediate = true

// toolbar for the detail form manipulation
def toolbar = new HorizontalLayout()

// buttons for detail form

// button to add new row to detail form
def addRowButton = new Button("+", new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
def placeInstance = new Place()
def tripInstance = tripEditor.itemDataSource.bean
tripInstance.addToPlaces(placeInstance)
container.addBean placeInstance
}
})
toolbar.addComponent addRowButton

// button to delete current row from detail form
def delRowButton = new Button("-", new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
if (table.value) {
def placeInstance = table.value
placeInstance._deleted = true
container.removeItem(placeInstance)
table.value = null
}
}
})
toolbar.addComponent delRowButton

// detail panel has the table rows and the toolbar
pnlDetail.addComponent toolbar
pnlDetail.addComponent table

// master form buttons
// save record button
saveButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
Trip.withTransaction { status ->
table.commit()
def tripInstance = tripEditor.itemDataSource.bean

def _toBeDeleted = tripInstance.places.findAll {it._deleted}
if (_toBeDeleted) {
tripInstance.places.removeAll(_toBeDeleted)
}

if (!tripInstance.save(flush:true)) {
tripEditor.description = "Error:<ul>"
tripInstance.errors.allErrors.each { error ->
tripEditor.description = tripEditor.description + "<li>" + "Field [${error.getField()}] with value [${error.getRejectedValue()}] is invalid</li>"
}
tripEditor.description = tripEditor.description + "</ul>"
window.showNotification "Could not save changes"
} else {
tripEditor.description = ""
window.showNotification "Changes saved"
delButton.setEnabled(true)
statusLabel.setValue("Edit Mode");
pnlDetail.setEnabled(true)
populate_container(container,tripInstance.places)
}
}
}
})

// new record button
newButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
new_mode(tripEditor)
}
})

// delete record button
delButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
if (tripEditor.itemDataSource.bean) {
Trip.withTransaction { status ->
def tripInstance = tripEditor.itemDataSource.bean
tripInstance.delete(flush:true)
}
}
new_mode(tripEditor)
}
})

// enter query mode
entQButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
def tripInstance = new Trip()
def newBean = new BeanItem(tripInstance)
tripEditor.itemDataSource = newBean
tripEditor.visibleItemProperties = master_fields
tripEditor.description = ""

saveButton.setEnabled(false)
delButton.setEnabled(false)
entQButton.setEnabled(false)
extQButton.setEnabled(true)
statusLabel.setValue("Query Mode");
pnlDetail.setEnabled(false)
}
})

// execute query
exeQButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
tripEditor.commit()
def example = (Trip) tripEditor.itemDataSource.bean
query = Trip.findAll(example)
rec_pos = 0
tripEditor.description = ""
entQButton.setEnabled(true)
extQButton.setEnabled(false)

if (query.size > 0) {
def next_rec = query[rec_pos]
tripEditor.itemDataSource = new BeanItem(next_rec)
tripEditor.visibleItemProperties = master_fields

saveButton.setEnabled(true)
delButton.setEnabled(true)
statusLabel.setValue("Edit Mode. Record " + (rec_pos+1) + "/" + query.size);
pnlDetail.setEnabled(true)
populate_container(container,next_rec.places)
} else {
window.showNotification "No record found"
new_mode(tripEditor)
}
}
})

// exit query mode. Back to New mode
extQButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
new_mode(tripEditor)
}
})

// edit mode, previous record
prevButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
if (!query) {
window.showNotification "No query result"
return
}

if (rec_pos > 0) {
rec_pos--
def next_rec = query[rec_pos]
tripEditor.itemDataSource = new BeanItem(next_rec)
tripEditor.visibleItemProperties = master_fields

saveButton.setEnabled(true)
statusLabel.setValue("Edit Mode. Record " + (rec_pos+1) + "/" + query.size)
pnlDetail.setEnabled(true)
populate_container(container,next_rec.places)
}
}
})

// edit mode, next record
nextButton.addListener(new Button.ClickListener() {
void buttonClick(Button.ClickEvent event) {
if (!query) {
window.showNotification "No query result"
return
}

if (rec_pos < query.size - 1) {
rec_pos++
def next_rec = query[rec_pos]
tripEditor.itemDataSource = new BeanItem(next_rec)
tripEditor.visibleItemProperties = master_fields

saveButton.setEnabled(true)
statusLabel.setValue("Edit Mode. Record " + (rec_pos+1) + "/" + query.size)
pnlDetail.setEnabled(true)
populate_container(container,next_rec.places)
}
}
})

// put the status bar on the footer of the master form
tripEditor.footer = new HorizontalLayout()
tripEditor.footer.addComponent statusLabel

// put all master form buttons into a horizontal panel
def btnPanel = new HorizontalLayout()
btnPanel.addComponent saveButton
btnPanel.addComponent newButton
btnPanel.addComponent delButton
btnPanel.addComponent entQButton
btnPanel.addComponent exeQButton
btnPanel.addComponent extQButton
btnPanel.addComponent prevButton
btnPanel.addComponent nextButton

// construct master-detail form panel
panel.addComponent btnPanel
panel.addComponent tripEditor
panel.addComponent pnlDetail

// set panel to main window
mainWindow.addComponent panel
}

// routine to populate the container with the detail records
void populate_container(container, details) {
container.removeAllItems()

details.each {
if (!it._deleted) container.addBean it
}
}
}

A walkthrough of the above VaadinApp code is as follows.
  • The query object stores the list of "Trip" instances that is returned from a QBE query. The rec_pos is an index into the above list for the currently displayed record.
  • The master_fields stores the list of master record fields that is visible on the form
  • We put some of the buttons, status label and detail panel object as the object variables so that they can be access by helper routines
  • The new_mode routine is to put the form into the New mode, which occurs multiple times in the whole code
  • The init routine is where the whole window and form is defined
  • The form is laid out with the master record buttons at the top, followed by the master record
    form, and then the detail table sub-panel below that
  • In the detail sub-panel, there are 2 buttons, "+" and "-" which adds a detail to the Table and the master record instance and removes a detail record, respectively.  These are not put into a GORM Transaction as we only want to save (flush) the record when the "Save" button is saved.
  • The really tricky part of the whole form is in the master record buttons. For the "Save" button, we first force the detail table to update the source records in the master collection. Then we delete all the detail records which are marked for deletion, where the "_deleted" field is set to true. Finally the master record is saved by calling the "save" method in the tripInstance bean object. Any error messages are put into the "description field" of the master record form. If everything is fine, then the form is put into "Edit" mode for further editing including adding detail records into the Table below.
  • The new button just puts a new Trip instance into the master record form (and disables the detail table panel)
  • The delete button just deletes the master record. There is no need to "commit" the transaction as it is done automatically, and this differs from Oracle Forms
  • The enter-query button just clears the fields to collect the parameters to search. If all the fields are null, then the QBE will match all records in the database
  • Executing the query will run the "findAll(object)" method of the GORM domain instance. The return result is a List of matching instances. This is not quite scalable as the List needs to be stored in memory for the duration of the session or until the next query is run. This will need to be improved further. If there are any returned records, then the master form will display the first record and put it in "Edit" mode
  • Exiting the Query mode will return the form to the New mode
  • The previous and next buttons will update the master record form and the container of the detail table panel, thus keeping both screens in synchrony.


Sample with detail recordsThe picture on the left shows the data entry screen with the detail records for the current master record.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Future Direction

To improve on this, we will need to componentize the whole form so that developers do not need to copy and paste the above template code and modify it for each form. Furthermore the "container" object above should be changeable to allow for other types of containers to be used but they should not be data-bound and leave the data-binding to the GORM objects and layer.

Another suggestion is to create a Container component which is manipulated by the master table form buttons (add, save, delete, enter query, execute query, previous record, next record) and it then controls the master table entry Form.

Finally, as mentioned in the Petter Holmström article, we are not really using any feature of Grails other than the GORM, and so, this entire example can be build using just Groovy, GORM and Vaadin.

AttachmentSize
tripplanner.zip177.62 KB
Published at DZone with permission of its author, Chee-keong Lee.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Chee-keong Lee replied on Mon, 2010/06/07 - 1:55am

Since GORM currently doesn't allow Query By Example where you can use wild-cards, I found a way to code around this limitation by using Hibernate Example class.  To use it, first you need to add 2 new imports to the code in VaadinApp.

import org.hibernate.criterion.Example
import org.hibernate.criterion.MatchMode

Then, replace the line

query = Trip.findAll(example) 

in the execute query button listener with

def crit = Trip.createCriteria()
def exmp = Example.create(example)
                 .enableLike(MatchMode.ANYWHERE)
                 .excludeZeroes()
                 .ignoreCase()
query = crit.add(exmp).list()

This will allow the use to specify a partial word to be use for the query matching.

Clement Tchamtcheu replied on Fri, 2011/02/11 - 8:03am

please can i have a source code of this tutorials?

 

majid Latif replied on Sun, 2011/10/23 - 11:18am

Hi, Your help is appreciated if you put the source code for this example. majidnakit@yahoo.com thanks

Chee-keong Lee replied on Fri, 2012/06/01 - 2:07am

I have minor corrections to the code and cleaned up some pasting errors. Also, as requested, I have uploaded the example project, which is created on Grails 1.3.7.

Andrea Taini replied on Fri, 2012/11/02 - 12:12pm

How is VaadinApp class created and where?

Should I create by hand or I have a command to do it? Or is created automatically?

Thank you!


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.