{ height: 1%; } - Ruby on Rails and User Interface Design

On the NEW Ajax Scaffold Generator

Posted by Richard White Tue, 21 Feb 2006 02:05:00 GMT

AjaxScaffold has been deprecated in favor of ActiveScaffold

So I just gemmed and uploaded the v2.0 release of the ajax scaffold generator. There are quite a few improvements in this version, most notably:

• The generated scaffold code looks production ready: valid XHTML, CSS, fully styled.
• It now uses a <table>
• Its designed to be used as a component so you can easily create an admin console with a couple generated scaffolds.
• A number of CSS styles have already been included for commonly used elements like required field labels, example field input and for some basic form layout control (explained later in this article).
• Works on Firefox 1+, IE 6+ and Safari 2+ (It may work on others, but I haven’t tested anywhere else, so let me know what you find out)

Why not jump over to the demo page and check it out and then come back here for the walkthrough. (and it wouldn’t hurt if you went and Dugg this article somewhere in between ;) ).

Some of this information is outdated as of version 3.0.0, check out the 3.0.0 release notes

Getting Started

Getting up and running is fairly straightforward, but I’ll hold your hand just in case :)

• Install the Ajax Scaffold Generator gem

gem install ajax_scaffold_generator

• Create a database table (using Rails Migrations hopefully) and configure your config/database.yml
• Run the generator against the database table you just created, for our purposes here our table is named widgets our model is named Widget and our controller is named Widget (generation options are the same as for the regular Rails scaffold which you can read about here).

ruby script/generate ajax_scaffold Widget

or on *nix

script/generate ajax_scaffold Widget

• Start up WEBrick or whatever RoR server you use and go to http://localhost:3000/widgets/ (obviously this will be different depending on what you have named your objects and if you are running on something other than the default WEBrick port)

Thats it! You have a fully working ajaxified scaffold page.

Adding form validation

Of course we probably want to add some validation to our objects so lets start by making widget.name required.

We add the following to models/widget.rb

class Widget
  <strong>validates_presence_of :name</strong>
end

And now for some UI sugar we will add a class and an asterisk to the name label in views/widget/_form.rhtml:

<div class="form-element">
  &lt;label <strong>class="required"</strong> for="widget_name"&gt;Name<strong>*</strong>&lt;/label&gt;
  &lt;%= text_field 'widget', 'name'  &gt;
&lt;/div&gt;

And now when we attempt to create a widget without a name we get this helpful message.

UI Sugar

I also find it good practice to give people examples of what their form input should look like (help text is good too but I prefer examples). So lets put an example on the version field:

<div class="form-element">
  <label for="widget_version">Version</label>
  <%= text_field 'widget', 'version' %>
<strong>  &lt;label class="example">ex: v1.0, v0.2.4, rc4&lt;/label&gt;</strong>
&lt;/div&gt;

Obviously putting the example under the input is just personal preference and when I have client-side errors I will usually put the example on top, but thats neither here nor there.

Next I may want to make sure that a certain set of fields always appear on a new line. A good example of this might be a situation where I want First Name and Last Name on one line and Address to always be on a line beneath those two elements. To accomplish this we simply wrap each “section” of form elements in a <div class=”row”> in our views/widgets/_form.rhtml:

<fieldset>
  <strong>&lt;div class="row"&gt;</strong>
    &lt;div class="form-element"&gt;
      &lt;label class="required" for="widget_name"&gt;Name*&lt;/label&gt;
      &lt;%= text_field 'widget', 'name'  %&gt;
    &lt;/div&gt;
  &lt;/div&gt;
  <strong>&lt;div class="row"&gt;</strong>
    &lt;div class="form-element"&gt;
      &lt;label for="widget_version"&gt;Version&lt;/label&gt;
      &lt;%= text_field 'widget', 'version'  %&gt;
      &lt;label class="example"&gt;ex: v1.0, v0.2.4, rc4&lt;/label&gt;
    &lt;/div&gt;
  &lt;/div&gt;
&lt;/fieldset&gt;

And voila!

General Error Messages

This information is outdated as of version 3.0.0, check out the 3.0.0 release notes

Handling when something goes very wrong is an oft overlooked part of many systems. Your generated scaffold has a fairly simple way of passing general errors back to the user. For the same of example I am going to short circuit the controller method for creating a new widget to always return one of these general errors:

def new
...

#render :layout => false
<strong>render :inline => "Muwhahah! No new widget for you!", 
  :layout => false, :status => 500</strong>
end

Now watch what happens when I try to create a new widget:

Ouch denied!

Embedding multiple scaffolds on the same page

One of the beauties of AjaxScaffolds is that they are designed to be used as components that you can embed on other pages. I’ve documented this in a later article here.

A Few Caveats

There are just a few caveats to all of this. These should hopefully be resolved in future versions (which anyone is more than welcome to pitch in on).

• The scaffold only generates properly when both element names are the same, thus the following doesn’t work (without some tweaks to the code generated

  <strike>ruby script/generate ajax_scaffold Widget WidgetConsole</strike>

• There is no graceful degredation for clients without JS Added in 2.2.0
• There is no pagination or find feature (thanks to Craig for reminding me to point this out) Added in 3.0.0

Future Direction & Wrapping Up

Well that’s is about all we have for the first release of Ajax Scaffold Generator v2.

Just to give you an idea of where we are going here are some future improvements in the development queue:

• Make the tables sortable
• Export table data to CSV
• Ability to specify different types of messages sent to the client (info, warning, etc) without having the operation fail (ie not having to set status = 500)
• Have it update regularly to pick up on changes made by other users
• Client side validation
• Use JSTs to create the forms (update, create) to save server requests
• Print stylesheet
• Fix those caveats I listed previously

Undoubtedly, as with any first release, there will be some bugs to please forward those and any feedback you might have either via the comments on this blog or by email me at rrwhite AT gmail.com.

And finally, I need to give a shout out to Mark James for his Silk icons and stay tuned to this blog as I’ll be writing up more of the interesting implementation details and technical workarounds that I had to do to make this all work (If your into that sort of thing).

Happy generating.