Traps in Lotus Notes fields
Fields, seemingly simple things, places to put data elements. But, like much else in your notes, they are traps for the unwary. They are traps for the more experienced developers too, just when you are looking elsewhere.
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.
Input Enabled formula
While we’re on Computed for Display, there’s a recent (well, since 6.5) feature of editable fields called the Input Enabled formula. The Notes 6.5 help looks like it was re-edited in a hurry and not properly proofread afterwards. It says that there are three Notes field formulas, and then describes four – the traditional Default Value, Translation, Validation and the then new Input Enabled, and gets it wrong about what the formula should return.
Designer 8 help is at least more accurate, though actually less clear about what this formula does. So, briefly: The point of an input enabled formula is to allow you to determine if a field may be edited or not. Use a formula that results with one of @False or @True. This is pretty much as you would use a hide-when formula, except in reverse: Input Enabled @True means that the field is to be editable by this user, while an @True hide-when result hides the field.
These formulas allow you to bypass the old trick of having two fields, one editable and one Computed for Display using the value of the editable field, then displaying one or the other depending on whether the current user is able to edit the field. Note also that Input Enabled formulas originally – in 6.5 – required that the field was of Native OS type, but that restriction was removed in Notes 7 and they work with conventionally displayed Notes fields too.
Notes fields aren’t strictly typed
Another not uncommon trap with fields stems from the fact that Notes fields aren’t strictly typed. When you create a field with LotusScript or formula language, the field type is derived from the value that you assign. As the help for NotesDocument.ReplaceItemValue says: “The data type of the item depends upon the data type of the value, and does not need to match the data type of the old item.” and it goes on to explain how it is set.
Notes doesn’t care whether the same field on different documents is the same type either, because Notes doesn’t have a database schema. You can read about the lack of a schema in Notes in an article I wrote a few years ago, “Notes is not a relational database”.
This ability for Notes to store whatever values it has in a field without any reference to type is part of what makes Notes what it is. But when a field is displayed in a form, things do get a little more strict. Notes is happy enough to display any value in any field as the form is displayed, and still happy to do so when the form is in edit mode, but when it comes to save time, then the field value must match the field type as defined on the form, or the document won’t save.
There’s no silver bullet to this one, either – to get the document to save via its form on the front-end, the field values and types have to match. That goes for an error-free Compute with Form operation, too, by the way. So this is a good reason not to have any hidden editable fields on a form. Should the values get damaged, the document won’t then save, and because the fields aren’t editable, the user can’t correct them, and it will all be your fault – even if you’d had nothing to do with it.
You can also get some other strange effects from the lack or typing, too, and the fact that Notes displays on the screen whatever is in the underlying field, regardless of the data type. Imagine the frustration and the small amount of swearing that goes on when you see Notes proudly display 10.00 in a field where you have set the number format to have no decimal places – expecting to see the value 10. Just how long did it take to spot that the actual value in the field was text “10.00″, so that’s what Notes displayed.
Hide-whens and Rich Text fields
Then there’s the one about hide-whens and Rich Text fields. Never, ever, use a hide-when to hide or expose an editable Rich Text field, or, for that matter, a non-editable one. This is because, in a Rich Text field, unlike any other type of field, the value can itself contain hide-whens.
Worse, when you create the value of a Rich Text field by editing it via a form, the first paragraph (at least) of the field will inherit the hide-when from the form, and then carry it along with the the data. When the field is displayed, it will react to the hide-when with its own data, and not the hide-when on the form.
Worse, again, if your users copy and paste the Rich Text data, or you programmatically copy it from field to field, that copied value still contains the hide-when values from the source field, and which may well not be what you want at the target location.
Worse, even more, should you change the hide-when on the form, none of the Rich Text data will respond to that, because it will always respond to the hide-whens in its own data. So you then find that data that should be visible isn’t, and data that shouldn’t be, is visible, depending of course on the circumstances.
And you can’t programatically get to the stored hide-when data to fiddle with it either, unless you get very clever with the Notes API. For an application robustness and maintainability perspective, I don’t think you’ll want to go there.
If you need to work with hide-whens and Rich Text, you need instead to use a computed subform, and on that subform, you place the Rich Text field, and you don’t use any hide-whens to manage the Rich Text field. What you do instead is to include or not include the subform as appropriate on the form, and in this way the whole Rich Text field will either be visible and editable or not reachable at all.
The downside of this technique is that you need to close and reopen the document to change whether the Rich Text data is displayed or not, because that’s the only way to get the computed subform expression reevaluated.
Viewed 8282 times by 2716 viewers
