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

I don't expect this will be news for most of my regular readers, but it's a good topic for novice developers (and gives me something to link them to in the forums).

Using NotesUIDocument and NotesDocument together

NotesUIDocument is a "front end" object, concerned with what the user sees on screen. The NotesUIDocument.Document property returns the corresponding "back end" NotesDocument object, which shows what is stored on disk when the document is saved. If you make changes to fields in this NotesDocument object -- this special NotesDocument that has a relationship with the NotesUIDocument -- those changes are mostly immediately reflected on screen. That makes this NotesDocument very useful for writing buttons and actions that work on the document being edited. If you do this, however, bear the following in mind:

  • It's usually a bad idea to call NotesDocument.Save on a document you got from a NotesUIDocument. That's because the UI doesn't realize the document has been saved, and if the user then saves the document in the front-end also (for instance, by using menu File > Save), Notes detects that as a save conflict. Someone saved changes to the document while you were editing it. That someone was you, but because you snuck around behind the back of the UI with a back-end save, Notes doesn't realize that's what happened.
  • If you must do a back-end save, it's best to then immediately close the NotesUIDocument to prevent the user causing a save conflict. If the document is in edit mode, you might need to set the field SaveOptions = "0" to be able to close the document without the user being prompted whether to save.
  • The NotesUIDocument only knows about text in a field. If a field is a number or date-time type, the NotesUIDocument.FieldGetText method will just return the characters that are visible on screen. If you ask for the value from the NotesDocument, however (e.g. using GetItemValue) you'll get the number or date/time value, if the field contains a valid value of this type.
  • The NotesDocument is especially useful for multi-valued fields, because it lets you get the field value as an array instead of a delimited string. This lets you write code that won't break if the form design changes and different delimiter characters are being used than before.
  • If keyword fields have synonym values ("Yes | 1", "No | 0"), the NotesUIDocument works with the user-display values ("Yes" or "No") while the NotesDocument knows only about the stored values ("1" or "0"). This is useful because it lets you write code to operate on the stored values via the back end, and that code will not break if someone changes the user-display values corresponding to those stored values (or if there are multiple versions of the user strings, e.g. in a multilingual application).
  • Rich text fields are special and difficult. The contents of a NotesRichTextItem are not up to date with what's on the screen unless you call NotesUIDocument.Refresh(True). If you use the methods of NotesRichTextItem to make changes to rich text, there is no way to get those changes to appear on screen short of closing and reopening the document.
  • If you do use NotesRichTextItem to change some rich text, though the changes do not appear on the screen, they will still be saved when the user saves the document through the UI. This works unless the user also makes manual changes to the same rich text field; such changes would override your back-end changes. So, this technique is most often useful with "computed" rich text fields which the user cannot edit, or in cases where it's practical to immediately close the document (and maybe reopen it to show the updated rich text).
  • If you do need to redisplay some rich text, or if while in edit mode you need to refresh other information that normally only shows on open, it's possible to do this by closing and reopening the document without saving it. How to reload rich text by closing and reopening a document without saving it.

Andre Guirard | 23 June 2010 01:50:11 PM ET | Home, Plymouth, MN, USA | Comments (3)

Search this blog 


    About IBM Privacy Contact