Mold: Form Validation for Seaside

A long time ago, I asked about systems for form validation that aren’t “model-based”. By “model-based validation”, I mean that the rules for whether a certain sort of input is acceptable are declared in (or attached to) a domain model that the form is operating on. This is the way that ActiveRecord (Rails) and Magritte (Seaside) work.

I don’t like the whole approach, for reasons I discussed in my earlier post. It breaks down when you want to edit an object in stages, and you end up managing lots of UI-related things down in the model code. But forms are boring and validation can be tedious, which is why frameworks like these have been built in the first place.

What I really wanted was a set of simple helpers that made this work easier — a “less is more” approach to the problem. That didn’t exist (at least in Seaside), so I built my own.

It’s called “Mold”, and it’s available both on SqueakSource and in the Cincom Public Repository. The name is a play on words: it’s a synonym for “form”, but it makes most normal people think of green fuzzy fungae. 

Design Principles

In building Mold, I had several specific goals:

  1. No new components. I didn’t want to have to remember to add anything to #children just because I was using this framework.
  2. Keep track of what the user types, even if it’s not valid, to allow for easy correction of mistakes. “r56” might not parse to a valid integer, but it’s better to let the user delete the “r” than force it to “0” and complain at him.
  3. Emit real objects, not just strings. If I’m asking the user to enter a date or a time, I want a Date or Time object when all is said and done.
  4. Use block-based validation criteria to keep things flexible. Error messages should allow blocks to be used too, so that your can put dynamic behavior in there too.
  5. Correlate errors closely to the problematic fields. It’s more helpful to show an error message right next to the field than to show it at the top of the page.
  6. Strip leading and trailing whitespace, and convert empty strings to nil. Semantically, an empty string almost always means “nothing” and is rarely worth keeping around.
  7. Callback or dictionary-like access to valid data. Sometimes you want to grab bits of data out of the form by name, but most of the time it’s nice to have the form dump valid results right into your model in one step.
  8. Don’t require all-or-nothing use. I might want to use the helpers to build part of the form, but handle other parts myself. It should be possible to completely customize the look of each form without sacrificing the benefits of the framework.

The Basics

To use a mold, you typically instantiate and hold a Mold in an instance variable of your component. For a simple form with no underlying model, you might build the mold when the component is initialized.

initialize
  super initialize.
  self buildMold

For editors with a model under the hood, it makes sense to build the mold when the model is passed in:

account: anAccount
  account := anAccount.
  self buildMold

The mold itself has a canvas-like API for declaring a form’s inputs and validation conditions.

buildMold
  mold := Mold new.
  (mold stringField)
    label: 'Username:';
    on: #username of: account;
    beRequired.
  (mold passwordField)
    label: 'Password:';
    on: #password of: account;
    beRequired. 

In this simple form, we only ask for 2 things, and we hook them directly to accessor methods on the model using #on:of:. This works just like it does in a regular Seaside form, and behind the scenes it simply creates a callback block. You can also create a custom callback block yourself.

When it comes time to render your form, you have to hand the `html` canvas to the mold, and then it gives you lots of handy shortcuts. Basic use will look something like this:

renderContentOn: html
  html form:
    [mold canvas: html.
    mold paragraphs.
    (html submitButton)
      callback: [self save];
      value: 'Save']

This usage tells the mold to render those fields as HTML paragraphs, like so:

Generated with Mold, using the #paragraphs helper

The labels are real HTML <label> tags, and each group is a single paragraph (<p><label for=”…”>Username:</label><br /><input … /></p>) We could have also used #tableRows:

renderContentOn: html
  html form:
    [mold canvas: html.
    html table:
      [mold tableRows.
      html tableRow:
        [html
          tableData;
          tableData: 
            [(html submitButton)
             callback: [self save];
             value: 'Save']]]]

It’s more work to build the framework around the table, but the end result looks like this:

These are the only two “canned” looks for an entire mold, but it’s also possible to take the reins yourself and ask Mold to render single components for a completely custom look. More on that below.

The final step in using this mold is hooking up the #save callback. Let’s assume you’re using the super cool SandstoneDb framework to save your models:

save
  mold isValid ifFalse: [^self].
  account save: [mold save].
  self answer 

That’s all there is to it. The mold can tell you whether its inputs were valid, and if not, it will display error messages on subsequent renders. If it is valid, telling it to save will fire all of its callbacks, thereby applying the changes to the underlying model.

The way I use Glorp, the save method looks nearly identical, but you have to register your model object in a unit of work. Using the mold’s save actions to apply your changes inside the unit of work keeps Glorp’s deep dark change-tracking voodoo working.

save
  mold isValid ifFalse: [^self].
  self database inUnitOfWorkDo:
    [:db |
      db register: account.
      mold save].
  self answer

Improving Looks

Let’s look at what interactions with the mold look like. We declared that both fields should be required, so if you don’t type anything (and just click “save”) you’ll see error messages by each field:

This form is a little bland, and it’s spacing is awkward because Mold uses unordered lists inside those table cells. Let’s apply some simple CSS:

style
  ^'
label.required { font-weight: bold; }
label.required:after { content: "*"; color: red; }
.error { background-color: #ecc; }
.errors { color: red; margin: 0; }
' 

That looks better — we call attention to the required fields, error messages are shown in red, and fields with errors have a reddish background too. Let’s make the username field a little wider. We’ll do this by adding a #customize: block in the mold declaration:

 

buildMold
  mold := Mold new.
  (mold stringField)
    label: 'Username:';
    on: #username of: account;
    customize: [:tag | tag size: 40];
    beRequired.
  (mold passwordField)
    label: 'Password:';
    on: #password of: account;
    beRequired. 

Now the next time we build one of these components (remember, we built the mold when the component was initialized, so it won’t automatically be rebuilt just from a browser refresh), our form will look like this:

 

More Conditions and Inter-Relationships

Let’s modify the field a little further. If we require usernames have to be at least 3 characters long and passwords to have a digit in them, we need some more conditions on these fields. We should also make the user type the password twice to guard against typos.

 

buildMold
  | passwordField confirmPasswordField |
  mold := Mold new.
  (mold stringField)
    label: 'Username:';
    on: #username of: account;
    customize: [:tag | tag size: 40];
    beRequired;
    addCondition: [:input | input size >= 3] labeled: 'Usernames must be at least 3 characters long'.
  (passwordField := mold passwordField)
    label: 'Password:';
    on: #password of: account;
    beRequired;
    addCondition: [:input | input matchesRegex: '.*\d.*']
      labeled: 'Please make sure your password has at least one number in it'.
 (confirmPasswordField := mold passwordField)
    label: 'Confirm Password:';
    beRequired.
  passwordField
    addCondition: [:input | input = confirmPasswordField input]
    labeled: 'Passwords did not match'.
  confirmPasswordField
    addCondition: [:input | input = passwordField input]
    labeled: 'Passwords did not match'. 
There’s a bit more going on here, but it’s all pretty straightforward to use. A few things to note:
  1. We’ve added conditions on required fields, so these won’t be evaluated unless some input is actually given. If these fields were optional, we’d have to check `input` to make sure it wasn’t nil before asking it for its size.
  2. The fields can refer to each other, even out of order. We didn’t technically have to put conditions on both fields, but it makes the error messages look nicer if we do.
  3. There is no callback on the confirmation field. It simply exists for use by the main password field.
  4. When referring to the other fields, we asked them for their #input. This is the string the user typed (having been trimmed of leading and trailing whitespace and converted to nil if it was empty). We could have also asked for its #value, but the value is only valid when the field is valid (incidentally, fields also understand #isValid).

The resulting form looks like this:

One “Gotcha”

Under the hood, the out-of-order field processing is done with a hidden input with a low-priority callback. This is hooked up when the mold’s canvas is set (mold canvas: html). The callback doesn’t fire until all of the other input’s callbacks are processed, but it fires before the action callback from the button.

That means that you must set the mold’s canvas inside the form: [] block. Failure to do so will mean that your validations never get run, and the mold will always answer `true` when sent #isValid.

There might be a cleaner way to do this, but I haven’t found it yet.

Advanced Moldiness

Mold fields can also be given a symbol for a key, which lets you refer to them directly. This makes custom rendering possible, with messages like:

mold paragraph: #confirmPassword.
mold widget: #username
mold errors: #someOtherField

When you use #on:of: to hook up a callback, the key for the widget is automatically assigned to the selector you passed as the first argument. You can also set the key directly using #key:, and a subsequent send of #on:of: will not clobber it.

Error messages can also be blocks, which means that you can put the user’s input into the error message:

(mold stringField)
  key: #username;
  addCondition: [:input | (Account find: [:each | each username = input]) notNil]
    labeled: [:input | 'The username "', input, '" is already taken'].

There’s also no reason why you can’t add two or more molds to a component — say, one for basic settings and one for advanced settings that aren’t shown unless the user clicks “more choices”.

Adding fields is a matter of adding a new protocol on Mold and optionally a new Field subclass. I say “optionally” because some fields can be built as specialized versions of existing fields, like a string field with a default validation rule. The emailField is currently implemented this way.

In Summary

I know not everyone believes that model-based validation is a problem. But if all you’re looking for is a simple way to build a custom form, you might find Mold helpful. We’ve been using it internally for nearly a year, so I figured it was time to touch it up and share it.

Mold makes no requirements of your components or your model objects. It doesn’t use any metadata; it allows you to choose how you want each form rendered; and it doesn’t require you to use it to build the entire form. It’s just a helper, and it gets out of your way when you don’t need it. 

Just don’t leave it alone in a cool dark place for too long, or it might start to grow on you. :)

16 Comments

Filed under Seaside, Smalltalk

Showing a “Session Expired” Notice in Seaside

When a Seaside session expires, many of its links become invalid. Sure, you can use the hooks to make certain URLs bookmarkable, but most URLs are session-specific out of necessity. When you click on one after the session expires, Seaside kicks you back to the starting point for the application with no explanation whatsoever. It’d be more polite to tell the user why this happened.

Hat tip to Boris Popov for the initial implementation.

In Seaside, the class WAApplication (via its superclass, WARegistry) knows when an expired session is being accessed, so in order to implement a notice like this, you first have to make your own custom WAApplication subclass.

WAApplication subclass: #MyApplication
  instanceVariableNames: ''
  classVariableNames: ''
  poolDictionaries: ''
  category: 'MySeasideStuff'

When a session expires, the core handling happens in WARegistry. But it gives us a chance to specify the URL path we want to use when something expires. In this case, we’ll tack the keyword “expired” onto the end:

MyApplication>>expiryPathFor: aRequest
  ^aRequest url , '/expired'

Once this is done, you have to register your Seaside application as an instance of MyApplication instead of WAApplication. This is how I did it:

MyRootClass class>>applicationNamed: aString
  | application |
  application := MyApplication named: aString.
  application configuration addAncestor: WARenderLoopConfiguration new.
  application preferenceAt: #rootComponent put: self.
  ^application

Then it’s just a matter of implementing the proper handling in your root component or one of its initial presenters. In my case, my root component holds a task, and the task calls a login component to prompt for username and password. The login component is already set up to display error messages, so we’ll use that here:

MyTask>>initialRequest: aRequest
  super initialRequest: aRequest.
  (aRequest url last: 7) = 'expired'
    ifTrue:
      [loginDialog error: 'Your session has expired. Please sign in again.']

This works the way we intend, but it has a side effect. Since we are using [self session expire] when a user clicks a “logout” link, even legitimate logouts look like a session expiration. We end up showing our expiration message every time somebody logs out, which is not what we want.

Instead, we need to force a redirect after a legitimate logout:

MySession>>logout
  self expire.
  self redirectTo: self currentRequest url.

Now we change our logout callbacks, and we’re done!

MyComponent>>renderContentOn: html
  (html anchor)
    callback: [self session logout];
    with: 'Logout'.

We can test this by logging into the application, clicking the logout link, and then using the back button to get back to an application screen. Clicking any link on the page takes us to the back to the initial screen with the new notice shown.

Dialog showing expired session message

2 Comments

Filed under Seaside

Seaside Presentation at 3CLUG

Travis Griggs and I will be giving a Seaside presentation titled “Lay Rails to REST” for the Tri-Cities Linux Users Group this coming Saturday (December 8th, 2007). If you’re in southeastern Washington state and interested in learning more about Seaside, and how it compares to Rails in particular, stop by West 248 at the WSU Tri-Cities campus at 1:00. It should be a fun and informative presentation.

Update: Yes, that’s south*eastern* Washington. Sorry for the typo earlier.

Leave a comment

Filed under Seaside, Smalltalk

One-Field Forms and IE Quirks

I encountered an old quirk in Internet Explorer again — one I hadn’t seen since I was doing most of my web programming in PHP. I had developed a style of PHP (and later Rails) coding that avoided it, but Seaside’s architecture makes you more likely to fall victim.

We often take for granted that the Enter key submits our forms. The Enter key always acts as if the first button in the form had been pressed. Whether this is written into the HTML spec or whether it just developed as a convention, I don’t know. But users expect it to work something like that, in that Enter is always expected to perform a normal submission (i.e. “Save”) instead of an exceptional one (i.e. “Cancel”).

Internet Explorer has a funny quirk with this submit-on-enter mode, and although many people claim to have found it and worked around it, many people seem to over-generalize it. You’ll find many web design blogs and forum posts asserting that “IE doesn’t post the submit button names if you press Enter”. That’s partly true. If you push Enter on some forms, IE leaves off the button data entirely. Click a button and IE faithfully submits the button data, but press Enter and the posted form data tells nothing of the user’s intent.

In PHP or Rails, I typically structured my forms with the “Save” button appearing first, and the “Cancel” button appearing second. When handling the POST, the code checked for Cancel and, if it wasn’t found, proceeded with the operation. That meant that the forms really didn’t care about any specific button’s value except “Cancel”, which always requires a real button click anyway. Problem solved.

But in Seaside, each button has a specific callback attached. If you don’t get the button data in the form posting, Seaside doesn’t evaluate any button callbacks.

Fortunately, there is a workaround: make sure you use two or more input fields on your form. When there are multiple input fields, IE is happy to behave in a sane manner and submit the name of the first (i.e., the expected “default”) button. It’s only in one-field forms that this problem occurs.

The only problem is that, well, some forms need to be one-field forms.

Seaside solves this problem rather nicely using the defaultAction callback. If you create a form and assign it a defaultAction, Seaside does two things: First, it creates a submit button as the very first child of the form that is set to fire the callback. Secondly, it creates an empty text input. Both of these get positioned wildly off the page using CSS, so they’re never visible but they still have their desired effects.

By assigning a default action, you can actually break the mold and arrange your submit buttons in whatever order you like. Or you can create forms that submit on Enter but don’t have any (user-visible) buttons at all. It’s a cool trick, and the fact that it solves the one-field form quirk seems secondary to its main purpose. Most of my forms don’t do anything fancy like that, so a default action isn’t necessary.

But forms with only one field need it for IE usability.

4 Comments

Filed under Seaside

Apple Intel Audio Noise

My only disappointment with my MacBook Pro has been the burst of white noise that I sometimes hear on my headphones and external speakers. It seems to happen as the audio chip is powered up and down, but that’s strictly a guess as to the cause. I’m no audiophile, but the noise is aggravating. My old iMac G5 never had this problem, though it did make a nasty pop every once in a while.

I posted a question to the Apple support forums, searched the web, but found no solutions. Part of the problem is that everybody uses different terms for it, and a search for “MacBook Pro Noise” gives articles about other unrelated (and in some cases, much more disturbing) sounds that emanate from some MBPs. So eventually I resigned myself to just live with it.

This morning’s software update (Apple Audio Update 2007-001) got me pretty excited, but alas, it doesn’t solve the particular noise problem I’m having. It seemed promising at first, but I can still hear the noise on my Klipsch speakers. It’s hard to say for certain, things may be slightly improved now, but definitely not resolved for good.

This problem makes it nearly impossible to use the laptop for any soundcard-based amateur radio programs. The noise corrupts the data that the computer is trying to send in the audio stream. I haven’t tried using Boot Camp yet, but that may be the next step. If that doesn’t work, I might need to buy an external sound board.

Leave a comment

Filed under Apple

Meaningful Seaside Links after Session Expiry

There’s something about Seaside’s URLs that has bothered me for a long time, and I just discovered a solution. I haven’t seen anything about this anywhere else, so I figured I’d write it down in case it’s useful to anyone else.

Since your URLs are managed by your Seaside session, they all become invalid when your session times out. Leave your browser alone for a while, then return and click a link. Instead of taking you where it said it would, the link ends up taking you back to the first page of the app.

The well-known pattern for creating “bookmarkable URLs” is part of the solution here. You override #updateUrl: in your component, and then you override #initialRequest: in your root component or one of its children (i.e. something that’s visible by default). However, that only solves the problem of returning to your current page and has nothing to do with meaningful links on your current page after your session expires.

For most applications, this sort of behavior is not a big deal. Your session times out, you click something, and you’re kicked back to the “please sign in” page. Users tolerate this, because they’re used to the idea that their computer shouldn’t stay signed in forever.

But on a public area of a site, this sort of behavior really can get frustrating. I often pull up a page, get interrupted, and don’t get back to the page for several hours or days. The SqueakSource site has done this to me more than once. Browse to a SqueakSource page, go have lunch, and then come back and click a link. You get shown the homepage instead. Argh!

Thankfully, there are hooks in Seaside that make meaningful links possible. But they’re not very well known, and I can’t find any reference to them anywhere online. The methods are on WAAnchorTag, named #extraPath: and #extraParameters:. These two methods allow you to mangle the URL on the front side, just like you can with #updateUrl: on the other end.

You can use them like this:

(html anchor)
 callback: [self registerVolunteer];
 extraPath: 'volunteer';
 with: 'Become a Volunteer!'

If you’re already using the hooks for bookmarkable URLs, then it’s simply a matter of putting in the right path or parameters when you build the link.

It’s entirely possible to build meaningful URLs in Seaside. The tools are all there. And even though it seems harder than in other frameworks, it’s really not. It just feels hard, because Seaside gives you such a nice abstraction the rest of the time.

And if you’re building a content management system, you’ll likely be creating an abstraction that hides these details anyway.

11 Comments

Filed under Seaside

Alternatives to Model-Based Validation?

Rails has an decent set of validation rules for its database models. You can specify that particular variables must be present or satisfy certain constraints, either by themselves (“must be two characters long”) or in relation to each other (“password can’t be blank for administrators”). I’ve written several of my own extensions to these for validating phone numbers, email addresses, tracking numbers, and the like.

It works fine, at first. But model-based validation breaks down in several situations. Here are a few examples:

1. Wizard-like interfaces break the rules. By definition, a wizard decomposes the process into several steps. Your model objects are often invalid until you finish the last step. I have yet to see a solution to this. Most people end up adding some sort of knowledge about the wizard to the model’s validation code (“If I’m only asking for the person’s name and address right now, don’t try to validate his email address”).

2. In Rails, you can’t save your models unless they satisfy all of the validity conditions. This problem probably won’t arise at first, but as your code base evolves, it can have some nasty side-effects. Like when a user can’t change his password, because the model has lately been changed to require a variable that used to be optional.

Seaside itself provides nothing to help you with validation. Search some archives and you’ll find people recommending Magritte, which is a metadata descriptor system for model objects. It was written by Lukas Renggli, who is one of the lead developers of Seaside itself.

Magritte improves the problematic situations above in a couple of significant ways. For one, Magritte descriptions can be configured on any object, not just on database models. In Seaside, a wizard is likely to be implemented with several components (one per page), so a corresponding model could be built with just the validation rules it needs. Additionally, Magritte is completely separate from your persistence layer, so you are free to save your model objects regardless of whether Magritte’s validation rules are satisfied.

But I’m still not satisfied with the approach. Model-based validation has a bad smell to me, though in some limited ways I am sure it is useful. But the more I look at systems that work this way, the more I see what looks like UI-specific code in the model. Should your model really be concerned whether the user has entered matching strings for “password” and “password confirmation”? What if I want to use real first-class objects to represent a phone number? Validation should happen before the data ever gets to the model. It strikes me that validation belongs in the form, not in the model. In Seaside, that means that validation would happen at the component level.

So I’m looking for a better way. How are others handling validation in Seaside? Beyond that, how do other frameworks help with form validation? The most intriguing thing I’ve seen so far is the “newforms” framework in Django, which couples form inputs to their validation.

It seems that this would be fairly easy to implement in Seaside. You could use blocks to make its behavior pluggable. If you end up using one particular form in several places, make your own subclass of Form and reuse it. Or if you only need it once, build the Form instance programmatically.

Are there any other frameworks that provide validation hooks but are not model-based?

5 Comments

Filed under Rails, Seaside