Skip to main content
    Country/region select      Terms of use
     Home      Products      Services & solutions      Support & downloads      My account     

developerWorks  >  Lotus  >  Forums & community  >  Best Practice Makes Perfect

Best Practice Makes Perfect

A collaboration with Domino developers about how to do it and how to get it right in Domino

Here's my idea of probably the best we can do in the Notes client by way of user-friendly validation. I created a form to demonstrate this:

A Gentler Validation

The situation shown is just after trying to save. The yellow area at the top is a non-scrolling header, visible no matter where you are on the form. It's set to "fit to content," so it's not visible at all unless you have some validation errors (actually it's there but only about 15 pixels tall, and not yellow). When you save, Querysave code does a refresh (to trigger translation formulas and read rich text into the back end), scans the fields to build a list of validation messages, and if there are any messages, writes them into a hidden field, does another refresh to make them display, and displays the text of the first message in a messagebox. There are two reasons for the messagebox. First, the user needs to be alerted that the save they requested didn't happen, and second, visually impaired users will find it more difficult to use the error display area, so they will be grateful for something that screen readers will automatically read to them.

The focus is initially placed in the first field with an error. The user can click on any of the messages to navigate to the field that message is about. There's a limit of six messages we can display at once. If there are more than six, scrolling controls appear above and/or below the message list (depending on your current position in the list). I don't like having a limit, but I can't think of a way to accommodate an arbitrary number of messages.

This is done with six Computed for Display fields (I guess they could be computed text instead but this lets me use @ThisName in their formulas), six hotspots to set focus to a field, and eight or so different hide formulas. It doesn't seem to affect performance noticeably.

I thought about using passthru HTML to build the error list and links, but unfortunately this is only refreshed on open. Also, we do need some limit because if there are a lot of messages, we don't want to take up the whole screen with the error list, leaving no space at the bottom for the user to do the corrections.

This could be improved on if there were also some way to visually highlight the fields that were in error, and to highlight the message pertaining to the current field. I couldn't think of a way to do this that doesn't require you to add a lot of stuff all over the form and in field events. The way it is now, you can take that top bit and use it on any form -- just have to customize the Querysave code for the validations you want to do.

(Actually, it occurs to me now that the Querysave code could start a NotesTimer that periodically checks what field you're in, and updates the error message display to cause the relevant message to be highlighted somehow. I think I'll leave this for someone else to do. If you try it, warning about Native style fields: modifying the back-end document might make Notes forget where the cursor is or erase what you've typed since entering the field.)


  • If you have a non-scrolling header, the Notes client likes to start out with the focus in the header, so none of your editable fields has focus. You can correct for this by designating a field as having default focus (as I did for the Subject field in this case).
  • Since this is just a proof of concept, I didn't take the trouble to over-engineer the code as I normally do. In reality, we should modularize this more, put it on a subform, etcetera.
  • My first approach tried to do the validations using a formula in the computed field in the header. I found out these formulas are evaluated before the fields in the lower part of the form are updated in the formula engine's field list. LotusScript can read their current values; a formula in the header sees the old values from the last refresh.
  • A background color on the form seems to work OK, but a background image is visible only on the header. Any suggestions on how to make that strip vanish completely when not in use, and to get a graphic background on the main part of the form, would be appreciated.
Here's the sample database to play around with: Fancy

Andre Guirard | 21 February 2008 03:38:00 AM ET | Home, Plymouth, MN, USA | Comments (6)


1) A kinder, gentler validation
Nathan T. Freeman | 2/21/2008 5:52:42 AM

Instead of the non-scrolling header (which is a feature fraught with bugs anyway) this seems like a great scenario for a LAYER. :-)

2) re: A kinder, gentler validation
Andre Guirard | 2/21/2008 6:33:22 AM


That was my first thought, but I couldn't find a way to make the layer move around to stay visible, the way the header does (and as Lars suggested in another thread). If you know a way, please spill the beans -- or create your own sample.

Kevin suggested scattering layers all over the form, but I'd prefer an approach that doesn't require the developer to insert special code at multiple points on the form.

3) A kinder, gentler validation
Lars Berntrop-Bos | 2/21/2008 8:43:05 AM

Can you use javascript to move around layers?

also: pointers to Notes javascript exa,ples, howto's etc. They are way too scarce, and Domino Designer is VERY lacking on this subject.

4) A kinder, gentler validation
Charles Robinson | 2/21/2008 10:49:42 AM

"This could be improved on if there were also some way to visually highlight the fields that were in error."

What about the border color? { Link }

@3 - Unfortunately, no. The height of the layer can't be set. You can fake it, but it's not pretty and doesn't look good. Even if you could, it would take a lot of code in a lot of places to make it work since you can't hook the scroll events and you can't use On Event in a LS class to capture field events.

For some great examples of using JS in the Notes client, check Tommy Valand's blog: { Link } . In particular, his NotesFX toolkit is interesting to pull apart.

5) A kinder, gentler validation
Charles Robinson | 2/21/2008 10:50:45 AM

I meant the position of the layer can't be set programmatically. The height can be changed by setting it to autsize.

6) A kinder, gentler validation
Charles Robinson | 2/21/2008 10:53:43 AM

In reading through Nathan's explanation of $BorderColor more closely, it appears that it sets the color of everything on the form. Bummer. I thought I was onto something. :-)

7) A kinder, gentler validation
Kevin Pettitt | 2/21/2008 11:02:40 AM

I'd still like to try the right side "autoframe" approach for showing the validation error list, as that would probably be more stable and use screen real estate more efficiently. You could even use the same frame to display other data entry tips, and using that timer approach you might even be able to get them to update based on cursor position without field events.

As for really long lists of error messages, there has to be some sensible limit at which point you just tell the user to go back and fill out the form before saving because so much is blank/wrong. In fact, I believe there is a form size and/or complexity threshold above which this sort of "hands off" approach to the main part of the form just won't cut it. Of course, when you get to that level, it's probably time to consider wizards and other ways to break up the data entry task. And in those cases, you might avoid the need for scrolling altogether which would make layers more viable.

8) A kinder, gentler validation
Tony Palmer | 2/21/2008 6:11:05 PM

I think that the least intrusive example that I've seen was at { Link } I'm sure that this is possible in a Notes client. although would be slightly more work than simply adding a subform. In terms of screen real estate, you could have the message appear below rather that to the right. IMHO its up to us to make the user experience the best we can. If it means more effort on our part then that's what we should do. If we can make our users lives and our lives easier - then it's a bonus.

9) A kinder, gentler validation
Rob Goudvis | 2/22/2008 12:22:24 AM

I have made a quick alternative version of the form with a floating message window that shows all the validation errors.

Please note that the messagebox that I produce can be improved, but I took a sample that I already had available.

I sent it via mail to Andre, so he could publish it.

10) A kinder, gentler validation
Kevin Pettitt | 2/22/2008 10:57:24 AM

@8 - Tony, I'm not sure I'd call your example entirely "unintrusive" but its one the right track. One of the questions we haven't discussed yet is whether the form is used once by most people and never seen again (e.g. a registration form), or used frequently (e.g. by order takers or customer service reps).

In the first case, more handholding is acceptable and even desirable, but I would tweak your example site so "helper" text only pops up when absolutely necessary. For simple First/Last name fields, this is probably only at submit time if they are blank. For email and password matching fields, it is nice to have immediate feedback. In some cases it might be better to have the helper text show up blue when entering the field and red only if you tab out and validation fails. Having the red validation failure warning pop up onFocus seems overkill.

Many of these same techniques apply to the second case where the same users fill out the same form all day long. However the emphasis should be on speeding data entry using keyboard actions, auto-formatting of phone numbers, and being minimally "helpful" with instructions and error warnings. Another key issue in these cases, particularly on longer forms, is that users MUST be allowed to save the document in an "invalid" state if they simply don't have all the information. Maybe the caller had to hang up to change a diaper or answer the door - you never know. You simply flag the status as "draft" so that it goes into a holding pattern instead of being pushed to the next stage of processing. The WORST thing you can do with validation is force users to enter junk data in fields just to get the form to save.

 Add a Comment
Comment:  (No HTML - Links will be converted if prefixed http://)
Remember Me?     Cancel

Search this blog 


    About IBM Privacy Contact