Better Scaffolding with jQuery - Part I

Grails scaffolding works great out of the box.  Today I want to see how we can improve adding data to the many side of a one-to-many relationship using jQuery, jQueryUI's Dialog, and some Ajax.  Using the same domain objects as my previous article I want to show how we can add Reminders to an Event without needing to navigate to a new page, assuming it is ok to create events without reminders.  For the sake of clarity, here are the domain objects.

class Event {

  String name

  static hasMany = [reminders: Reminder]

  static constraints = {
  }
}

class Reminder {

  ReminderType reminderType
  Integer duration

  static belongsTo = [event:Event]

  static constraints = {
  }

  String toString() {
    "${reminderType} : ${duration}"
  }
}

Note that in Reminder I've added a ReminderType.  This is a simple Enum with the values Email and SMS.  I did this to add a bit of meat to the Reminder form.  Once you have a new grails application up and running you'll need to download a couple of things.  The first is jQuery.  The easiest way to get this in grails is to simply install the plugin.  Execute "grails install-plugin jquery" and then in the views/layout/main.gsp modify the g:javascript tag to use "jquery" instead of "application" for the library attribute.  

We're going to be using jQueryUI's Dialog widget so you'll need to grab a copy of jQueryUI.  You can download it from here.  The simplest thing is to just include everything and select a theme.  Once you extracted the contents of the ZIP file place the jqueryui javascript file in your web-app/js directory and the entire theme folder under web-app/css.  Then add the following to your main.gsp:

<link rel="stylesheet" href="${resource(dir: 'css/ui-lightness', file: 'jquery-ui-1.8.custom.css')}"/>
<script type="text/javascript" src="${resource(dir: 'js', file: 'jquery-ui-1.8.custom.min.js')}"></script>

Modify any paths as necessary.  Next you'll need to go ahead and create the Event and Reminder domains.  Once you've done that we just need the basic scaffolding for all the CRUD.  We actually need to generate it (not using def scaffold = true) because we'll need to modify some of the scaffolding code.  So execute the following commands:

grails generate-all com.package.Event

grails generate-all com.package.Reminder

Go ahead and run your application and make sure things are working as expected.  We're going to focus the next part of our discussion on the edit page for Event.  Go ahead and create an event and go to the edit form.  It should look like this:

If you click Add Reminder right now you are going to be taken to the reminder create screen.  What we want to do is change the behavior so that when Add Reminder is clicked a Dialog is shown with the Reminder form in it.  Then when we hit a save button, an ajax POST is sent to the server and then we'll use the response to populate the unordered list with the newly created Reminder.

First we need a new JavaScript file.  I created one called tutorial.js and placed it in web-app/js.  Feel free to call it whatever you want.  Just make sure you include it in your main.gsp.  Next we need to make some modifications to Event's edit.gsp.  In this tutorial we are going to hard code the Reminder create form inside the Event's edit.gsp and use jQueryUI's Dialog API to show and hide it when we need it.  In a future tutorial I'll show how we can pull the form in via ajax but for now, I want to keep things as simple as possible.

Open views/event/edit.gsp and just before the closing body tag, add the following (this is actually just a copy and paste from views/reminder/create, btw):

<div id="dialog-form" title="Create new Reminder">
  <g:form action="save" method="post">
    <div class="dialog">
      <table>
        <tbody>
        <tr class="prop">
          <td valign="top" class="name">
            <label for="duration"><g:message code="reminder.duration.label" default="Duration"/></label>
          </td>
          <td valign="top" class="value ${hasErrors(bean: reminderInstance, field: 'duration', 'errors')}">
            <g:textField name="duration" value="${fieldValue(bean: reminderInstance, field: 'duration')}"/>
          </td>
        </tr>

        <tr class="prop">
          <td valign="top" class="name">
            <label for="reminderType"><g:message code="reminder.reminderType.label" default="Reminder Type"/></label>
          </td>
          <td valign="top" class="value ${hasErrors(bean: reminderInstance, field: 'reminderType', 'errors')}">
            <g:select name="reminderType" from="${com.wbr.tutorial.ReminderType?.values()}" value="${reminderInstance?.reminderType}"/>
          </td>
        </tr>
        </tbody>
      </table>
    </div>
  </g:form>
</div>

I've wrapped the form inside a div with an id of dialog-form.  jQueryUI will use this id for it's selector.  Let's go create some javascript.  Open up your new javascript file (mine was called tutorial.js) and begin by adding the following skeleton code:

$(function() {

    $('#dialog-form').dialog({
        autoOpen: false,
        height: 300,
        width: 350,
        modal: true,
        buttons: {
            'Create a Reminder': function() {
               
            },
            Cancel: function() {
                $(this).dialog('close');
            }

        }        
    });
});

If you've used jQuery before this code will look pretty familiar.  I'm not going to go into any major details here as it is out of scope for this tutorial.  We've created 2 buttons for this dialog.  When the 'Create a Reminder' button is clicked, it's callback function is triggered.  This is where we'll issue the ajax request to post the form.  If the cancel button is triggered, we simply close the dialog.

Next, we need to modify the 'Add Reminder' link on the edit page and then add an event handler for it in our javascript so that it displays the Reminder form.  Remove or comment out the following line:

<g:link controller="reminder" action="create" params="['event.id': eventInstance?.id]">${message(code: 'default.add.label', args: [message(code: 'reminder.label', default: 'Reminder')])}</g:link>

And add this in its place:

<a href="#" id='add_reminder'>${message(code: 'default.add.label', args: [message(code: 'reminder.label', default: 'Reminder')])}</a>

The reason we didn't just give the g:link tag an id is because it will render the id as the Reminder.id and we simply need it to wire up the event.  There are several other options we could have gone with here but this is a simple solution.  We now need to wire up the event.  I'm showing the full javascript file up to this point with the added code so you can see where it goes:

$(function() {

    $('#dialog-form').dialog({
        autoOpen: false,
        height: 300,
        width: 350,
        modal: true,
        buttons: {
            'Create a Reminder': function() {
                
            },
            Cancel: function() {
                $(this).dialog('close');
            }

        }
    });

    $('#add_reminder').click(function() {
        $('#dialog-form').dialog('open');
    });


});

Go ahead and try it.  Create a new Event and go to it's edit page.  Click the Add Reminder and you should see something like this 

If you click Cancel the dialog should close.  If you click Create a Reminder, nothing happens.  We still need to add this code.  Go back to your javascript file and let's fill out the Create a Reminder callback function.  Again, I've included the entire javascript file and then I'll talk about the added code.

$(function() {

    $('#dialog-form').dialog({
        autoOpen: false,
        height: 300,
        width: 350,
        modal: true,
        buttons: {
            'Create a Reminder': function() {
                var duration = $("#duration").val();
                var reminderType = $("#reminderType option:selected").val();
                var event = $("#id").val();
                $.post(contextPath + '/reminder/save', {'event.id':event, duration:duration, reminderType:reminderType}, function(data) {
                }, 'json');
                $(this).dialog('close');
            },
            Cancel: function() {
                $(this).dialog('close');
            }

        },
        close: function() {

        }

    });

    $('#add_reminder').click(function() {
        $('#dialog-form').dialog('open');
    });

});

The first thing we do is we get the form parameters we want to pass back to the server.  So we need the duration value, the reminderType value, and we need to pass back the event id so that the new reminder is added to the correct event.  Note that the event.id is simply a hidden field on the edit form.  Then we issue the $.post() to the server giving it the URL, our parameters, and we define a callback function.  I've also defined the response type as json.  This will be explained in a bit.  We need to do something with the response but first we need to modify our ReminderController's save method to render json instead of the typical redirect that normally would happen.  Open ReminderController and replace the following code:

flash.message = "${message(code: 'default.created.message', args: [message(code: 'reminder.label', default: 'Reminder'), reminderInstance.id])}"
redirect(action: "show", id: reminderInstance.id)

with this code:

render reminderInstance as JSON

Just for clarity here is the entire save method from ReminderController.groovy.

def save = {
    def reminderInstance = new Reminder(params)
    if (reminderInstance.save(flush: true)) {
        render reminderInstance as JSON
    }
    else {
        render(view: "create", model: [reminderInstance: reminderInstance])
    }
}

Make sure you add the import statement for JSON if not using an IDE that reminds you to do so.  We save the new reminder and we return the reminder as json.  This is great because we need to add a new list item to the unordered list on the event's edit page, just as it does when edting an event with existing reminders.  Here comes more javascript, again, the entire file and then I'll explain the new code:

$(function() {

    $('#dialog-form').dialog({
        autoOpen: false,
        height: 300,
        width: 350,
        modal: true,
        buttons: {
            'Create a Reminder': function() {
                var duration = $("#duration").val();
                var reminderType = $("#reminderType option:selected").val();
                var event = $("#id").val();
                $.post(contextPath + '/reminder/save', {'event.id':event, duration:duration, reminderType:reminderType}, function(data) {
                    var item = $("<li>");
                    var link = $("<a>").attr("href", contextPath + "/reminder/show/" + data.id).html(data.reminderType.name + " : " + data.duration);
                    item.append(link);
                    $('#reminder_list').append(item);
                }, 'json');
                $(this).dialog('close');
            },
            Cancel: function() {
                $(this).dialog('close');
            }

        }
    });

    $('#add_reminder').click(function() {
        $('#dialog-form').dialog('open');
    });
});

The newly added code here is the callback for $.post().  First we create a new LI element.  Then we create a new anchor element and add the href attribute.  Notice how when we need the reminder properties, since it is a json object, we can just reference the properties directly.  The HTML of the anchor tag mimicks what is done in the toString method of Reminder.  That way, when we come back to this page with existing reminders, and add new ones, they appear the same way.  The last thing you need to do is add an id of "reminder_list" to the UL on th edit page so that we can append the item to it.

And that's it.  In the next article I'll show how we deal with validation errors when saving a Reminder who's constraints fail.