GetFirstItem (NotesDocument - LotusScript®)

Given a name, returns the first item of the specified name belonging to the document.

Defined in

NotesDocument

Syntax

Set notesItem = notesDocument .GetFirstItem( name$ )

Parameters

name$

String. The name of the item you want to find.

Return value

notesItem

NotesItem or NotesRichTextItem. The first item with the specified name. Returns Nothing if the document does not contain an item with this name.

Usage

If multiple items in a document have the same name, programmatic access is limited to the first item. The remaining items yield invalid data. A work-around is to get the first item, process it, remove it, again get the first item (which was the second item), and so on until you process all the items with the same name. If you do not save the document, the items are not actually removed. However, the recommendation is that you avoid creating multiple items with the same name.

If the value of a field is computed for display, the value is not stored as an item. The value is inaccessible from a NotesDocument object, unless the object is accessed as the Document property of NotesUIDocument, and GetFirstItem returns Nothing. In some cases, you can use LotusScript® to access the field value another way. For example, if a document has a DateComposed field that's computed for display with a formula @Created, use the Created property in NotesDocument.

Using this method to get rich text items

You can use this method to get items declared as NotesRichTextItem as well as NotesItem.

Note: In earlier releases, you could not get an item declared as NotesRichTextItem. You had to declare it as Variant.

There's an extra step to get the contents of a rich text item from a document that's open in edit mode. Rich text items, unlike other item types, are not automatically copied from the NotesUIDocument to the NotesDocument that you obtained with NotesUIDocument.Document. In a new document, GetFirstItem will return Nothing when you look for rich text, and in an existing document that's being edited, you will see the value it had when the document was opened - not the value it has now. To force Notes® to update the back-end rich text from the data on the form, call NotesUIDocument.Refresh(True).

See also

NotesUIDocument.Refresh

Example