NotesItem (LotusScript®)

Represents a specific piece of data in a document.

In the user interface, Notes® displays items in a document through fields on a form. When a field on a form and an item in a document have the same name, the field displays the item (for example, the Subject field displays the Subject item).

All of the items in a document are accessible through LotusScript®, regardless of what form is used to display the document in the user interface.

Derived Classes

NotesRichTextItem inherits from NotesItem class.

Containment

Contained by: NotesDocument

Contains: NotesDateRange, NotesDateTime, NotesMIMEEntity

Properties

Methods

GetValueCustomDataBytes

GetValueDateTimeArray

GetMIMEEntity

Remove

SetValueCustomDataBytes

Creation

There are two ways to create a new NotesItem object:

To create one from scratch, use New, or ReplaceItemValue in NotesDocument.

Note: The New method is not supported in COM.

To create a new NotesItem object from one that already exists, use CopyItemToDocument, or CopyItem, or ReplaceItemValue in NotesDocument.

Given a document, New creates an item on the document with a name and value that you specify. The data type of the item depends on the value you give it.

You must call Save on the document if you want the modified document to be saved to disk. The document won't display the new item in the user interface unless there is a field of the same name on the form used to display the document.

Syntax

Dim variableName As New NotesItem( notesDocument , name$ , value [, specialType% ] )

Set notesItem = New NotesItem( notesDocument , name$ , value [, specialType% ] )

Parameters

notesDocument

The document on which to create the item.

name$

String. The name of the new item.

value

The value to assign to the new item. The data type of value determines the type of item that Notes® creates:


	Data type of value	Resulting notesItem
	String	Text item containing the value (if specialType% is used, may be Names, Readers, or Authors)
	Array of String	Text item containing each element of the value (if specialType% is used, may be Names, Readers, or Authors)
	Long, Integer, Double, Single, or Currency	Number item containing the value
	Array of Long, Integer, Double, Single, or Currency	Number item containing each element of the value
	Variant of type DATE or NotesDateTime	Date-time item containing the value
	Array of Variant of type DATE or array of NotesDateTime	Date-time item containing each element of the value
	NotesItem	Item whose data type matches the NotesItem type and whose value(s) match the NotesItem value(s)

Type conversion occurs as necessary. For example, floating-point numeric items are double precision so a value of type Single is converted to Double prior to storage.

specialType%

Optional. Constant of type integer. Indicates if a text item should be of type Names, Readers, or Authors. Must be one of the following constants: NAMES, READERS, or AUTHORS. To use specialType%, the value parameter must be a string or array of strings.

Usage

When you create a NotesItem using New, the IsSummary property of the item defaults to False, which means that the item value cannot be displayed in a view or folder.

Access

There are several ways to access an existing NotesItem object.

To access an item when you know its name, use GetFirstItem in NotesDocument.
To access all the items in a document, use Items in NotesDocument.

Accessing items directly from a document

For convenience, NotesDocument has methods you can use to access items without declaring a NotesItem object. All you need to know is the name of the item:

To get an item's value, use GetItemValue.
To set an item's value, use ReplaceItemValue.
To check for the existence of a particular item in a document, use HasItem.
To delete an item from a document, use RemoveItem.

In addition, you can treat an item name as a property of a NotesDocument object. For example, the following line of script sets the value of the Subject item in a document to "Hello":

doc.Subject = "Hello"

Rich text fields

NotesRichTextItem, which inherits the properties and methods of NotesItem, has additional properties and methods you can use to manipulate a rich text item.

Saving Changes

After you create or modify an item, you must save the changes by calling the parent document's Save method.

If you don't call Save before the script finishes, all of your changes to a NotesItem object are lost.

Example