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 (4)


1) Really?
Andrew Brew | 6/23/2010 9:42:37 PM


Your first point above says that if you call NotesDocument.Save from a NotesDocument derived from a NotesUIDocument you risk a save conflict. Is this really correct? I do this all the time (and have for about fourteen years!)), but do not get conflicts. What does cause conflicts is to get a handle to that same document by other means. So, in my experience, the following will be fine:

dim ws as new NotesUIWorkspace

set uidoc = ws.CurrentDocument

set doc = uidoc.Document

call doc.Save(false, false)

call uidoc.Save

Something like this, though, will cause a conflict:

dim session as new NotesSession

dim ws as new NotesUIWorkspace

dim db as NotesDatabase

set db = session.CurrentDatabase

set uidoc = ws.CurrentDocument

set doc = db.GetDocumentByUNID (uidoc.Document.UniversalID)

call doc.Save(false, false)

call uidoc.Save

The advantage of doing the back-end save is that it does NOT trigger QuerySave and PostSave events, which you may not want to fire in certain circumstances.

Or am I quite wrong, and need to change my practice?? : (


2) More could be said...
Scott Leis | 6/30/2010 11:35:27 PM

Good post, but more could be said about front-end / back-end differences.

We have one developer who took a while to get his head around the idea that creating a back-end document, setting the form, then saving the document does *not* automatically create all the other fields on the form.

3) NotesUIDocument.Document and NotesDocument difference?
Ajay B Mali | 10/12/2010 6:02:34 AM

Hi Andrew,

I read your article and looking for kind of article. Thank you for written such article.

Could you please elaborate in tabular format, what is the extact diffrence NotesUIDocument.Document and NotesDocument.

Once again thanks !!


Ajay B Mali

4) Lawyer Reviews and Law Tips
Brian Law | 1/28/2011 5:11:51 AM

Lawyer Reviews: { Link } and Law Tips.

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

Search this blog 


    About IBM Privacy Contact