Making our RESTful grid editable

In my last post, I showed you how to hook up the new dojo grid component to a RESTful resource in Rails. Now we're ready to make it editable. I promise this will be a shorter post than last time. The key piece is making a new model object to handle our edits. The dojo grid already provides the key pieces to make editing happen; we just need to provide a way to pass the edited values into our Jester-made object to send them along to our application. The way we do this is by creating our own model class which extends dojox.grid.data.Objects. Then we create an instance of this class. This is what the code looks like:

    dojo.declare("MyModel", dojox.grid.data.Objects, {
      beginModifyRow : function() {},
      endModifyRow : function() {} ,
      setDatum: function(inDatum, inRowIndex, inColIndex)
      {
        this.data[inRowIndex][this.fields.get(inColIndex).key] = inDatum;
        this.data[inRowIndex].save();
        this.datumChange(inDatum, inRowIndex, inColIndex);
      }
    });

    var model = new MyModel([{key: "make"}, {key: "year"}], cars);  

I'm definitely doing some hackery to make it simpler for myself here. The beginModifyRow and endModifyRow are dojo methods that get called at the beginning and end of editing a cell. In the normal dojo implementation these methods make a copy of the object being edited so it can be restored if a user cancels the edit. In a final version of this code we would want to clone our Car object when we start an edit, but we're just not worrying about it yet.

The code which actually handles the edit is in the setDatum method. It get's called with 3 arguments, the new value to set, the row index, and the column index. We have an array of cars to which makes it easy to lookup the right row, but how do we know which field is in which column? Well, dojo holds that information for us in the fields property of our model. The fields property provides a method to get a field object by index, and this field object has a key property which is the name of the property of car that lives in this column. This allows us to set the right property of car. Saving our changes back is a snap thanks to Jester. We call save on our car object and we are done.

Finally, we need to make some changes to our structure object to tell it which cells we want to be editable. We'll use dojo's simplest built in editor and make both cells editable. Here's how we do it:

 var structure = [ {
    rows: [[
         {name: 'Make', editor: dojox.grid.editors.Input},
         {name: 'Year', editor: dojox.grid.editors.Input}
    ]]
 } ];

So this is it. We now have an editable dojo grid saving changes by making REST calls into our Rails app.

Using a JS component framework like Dojo (or ext, mootools, etc, etc) in combination with Jester seems like it opens up a new way to approach web application development. I might expound on this in another post.

Dojo Grid + Jester + Rails = RESTful grid goodness

I've been experimenting with Javascript component frameworks lately, and that let me to look at Dojo. With their 1.0 release, they have added what looks to be a very powerful Grid component. I thought it would be fun to see how easy it is to get it talking with Rails. It proved to be not much code at all, and I think, kind of nifty. Here's how to do it.

Create a Rails app with a RESTful service

Not gonna go thru how to make a rails app, I'll assume you know that already. I created a little RESTful service with the scaffold generator something like this:

script/generate scaffold_resource Car make:string year:integer

Install Jester

When I found Jester it was one of those Open Source Moments for me. You know, the ones where you think: "Hey, wouldn't it be cool if you could..." and then Google and find out someone has already done it. Jester is basically ActiveResource in Javascript. The result makes so ridiculously easy to talk to RESTful services it's not even funny. I installed by unzipping the script and dropping jester.js in public/javascripts in my Rails app.

Install Dojo 1.0

Go get it, unzip it, drop it into public/javascripts. Nuff said

Write the code

And now for the fun part :) We'll start with a simple grid that pulls in data by making a RESTful call to our Rails app using Jester. Later on we'll enhance it to make it editable. First thing you need to know about Dojo is that it is CSS driven. This is definitely a good thing IMO, but it does mean you have to include the right CSS or it won't work at all, trust me ;) So make you sure you include the Dojo Grid CSS like so:

 5     <style type="text/css">
 6       @import "/javascripts/dojo-release-1.0.0/dijit/themes/tundra/tundra.css";
 7       @import "/javascripts/dojo-release-1.0.0/dojox/grid/_grid/Grid.css";
 8       @import "/javascripts/dojo-release-1.0.0/dojox/grid/_grid/tundraGrid.css";
 9  
10     </style>

Next, we'll need to include Jester and Dojo:

12     <%= javascript_include_tag :defaults %>
13     <%= javascript_include_tag "jester" %>
14     <script type="text/javascript"
15             src="/javascripts/dojo-release-1.0.0/dojo/dojo.js"
16             djConfig="parseOnLoad: true"></script>

Including Jester is just a matter of including using the standard javascript_include_tag helper, but dojo is a little wierd. You'll notice the djConfig attribute for starters. How does this even work? djConfig is not even a valid attribute for a script tag, right? As best I understand it, and someone please jump in if I'm wrong, dojo has a parser of it's own that comes along after your page load sand does things to it. This let's you add dojo components to your page "declaratively", or in html, instead of have to use so much javascript. Kind of interesting.

Now let's look at the script block that sets up the objects our grid will need:

18     <script type="text/javascript">
19     dojo.require("dojo.parser");
20     dojo.require("dojox.grid.Grid");
21     dojo.require("dojox.grid._data.model");
22
23     Resource.model("Car");
24     cars = Car.find("all");
25
26     var model = new dojox.grid.data.Objects([{key: "make"}, {key: "year"}], cars);
27
28     var structure = [ {
29        rows: [[
30             {name: 'Make'},
31             {name: 'Year'}
32        ]]
33     } ];
34
35
36     </script>

The first thing you'll notice is those dojo.require statements. These are how you tell dojo to go get all of the pieces it needs. Dojo is broken down into lots of individual javascript files, and while you could just include them all in script tags, that would be kind of a pain. dojo.require basically says "go get this piece and all of it's dependencies". It makes it easier to use some of dojo and not all of dojo as well.

Next we see Jester in action. Kind of puts dojo to shame from an ease of use standpoint, doesn't it? You tell Jester which model you want, and it makes a javascript class for you. We then call find all and it gives us back an array javascript proxy objects with the fields and methods you would expect. Like I said, ridiculously easy. There are options to have it do find (and save) asynchronously as well, which you would probably want to use for a real application.

Next we setup some objects our dojo grid needs. The first is a model, it tells dojo where to get it's data from. We're able to use of the built in types of models, dojo.grid.data.Objects. This kind of model will display an array of Javascript objects, which, conveniently enough, is exactly what we got back from the call to find. We have to give it a little more information, though, namely what properties to display in which columns of our grid. This is what we're doing in the first argument to the constructor. The second argument is our array of cars we got back from the call to Car.find("all").

Finally, we have an object that tells how we want our grid organized. I have to say this seems a lot more complicated than I'd like. It seems to me sometimes dojo is more focused on making the hard things possible than making the simple things simple. So I'm not even going to try to cover all the details of the structure object here, but briefly dojo grid structures consist of an array of views which have an array of rows which have an array of subrows. Phew. I think it would be possible to come up with a simpler structure object for simpler cases, but that would require more dojo-fu than I have yet.

At last, we're ready to put in the html for our grid. Here it is:

42   <div id="grid" dojoType="dojox.Grid"

43        model="model" structure="structure"
44        autoWidth="true" autoHeight="true">

45   </div>

Not much to it is there. Notice how we can set properties of our grid with html attributes. This is what the dojo parser does for us, as I understand it. Here we're passing in the model and structure we created in our script block.

So this is all that's required to use the dojo grid component and have it pull data from a REST service implemented in Rails. In my next post I'll show you how to have it be editable and save it's data using thru REST as well. It's easier than you might think.