Monday, December 1, 2008

Little known traps about Lotus Notes fields

PROGRAMMING POWER

By Mick Moignard

Fields would seem to be simple things, places to put data items. But like much else in Notes, they're traps for the unwary. They're traps for more experienced developers too, just when you're looking somewhere else.

Computed for Display

The first trap is Computed for Display fields. These are intended to enable you to calculate field values on the fly, using them to display on the screen or to drive underlying functionality, without saving that result to the document on disk. They've often been used, along with some hide-whens, in a mechanism to prevent certain users from editing fields.


"It will all be your fault - even if you'd had nothing to do with it."

The first trap is this: should the document actually contain a field of the same name as a Computed for Display field on the form, the Computed for Display field will display that document field value, rather than the expected calculated value. That one can lead to many hours of frustrated work and not a little swearing when it strikes you. It is most likely to happen when the design of an application has changed, where a field that used to be computed or editable becomes a computed for display, but the underlying data hasn't been changed.

So if you ever change a field from to Computed for Display, it's always worth an agent to skim through the data and delete all fields of that name from the documents.

There's another Computed for Display trap for the unwary, too. If the document isn't open in the UI, the field won't be present, as it's only calculated by the front-end as the document is displayed. While not many people will make that mistake in a background task such as an agent, it does mean that you need to be careful with client-side code.

From a LotusScript perspective, Computed for Display field aren't present until the form PostOpen event - you cannot get to them in the form QueryOpen. Actually, the field becomes "available" once the rendering process passes it. When Notes renders a document and form onto the screen, it processes the fields from top left to bottom right. Computed for Display fields don't exist until the order of processing passes over them - which means that the initialise event of a field cannot see a Computed for Display field that's below it, only those that are above it. Once you get to PostOpen, they're there, in the UI document and in the back-end NotesDocument that's referred to by the NotesUIDocument - but of course they aren't present in any NotesDocument that's opened from the NotesDatabase itself.