Creating an item and assigning values in LotusScript® classes

The New method of the NotesItem class creates a new item in a document and assigns a value to it. You can also use the ReplaceItemValue method or AppendItemValue method of the NotesDocument class to create a new item. The latter is not recommended because if another item exists with the same name, the new item does not replace that item but becomes an additional item with the same name.

To assign and reassign values to an item, you can:

• Write to the item name as though it were a property of the document. For example, if doc is the name of a document object and Subject is an item in the document, you can write to doc.Subject. The assigned value can be any LotusScript® data type, scalar or array, a reference to a NotesItem object, a reference to a NotesDateTime object, or a reference to a NotesDateRange object.
• Use the ReplaceItemValue method of NotesDocument. This is equivalent to the first technique.
• Access the item and write to its Values property.

Writing to the Values property affects only the current item object, while the other techniques replace all values of all items with the specified name.

After creating or replacing an item, you must call the Save method for the NotesDocument object containing the item or the update is lost when the program exits.

Computed fields are not recalculated when you save a document. If you change items that affect a computed field and want the new value to be available immediately (for example, if you want the user to see the new value in a view or you want to use the new value in a calculation), you must calculate the value in the script.

The user cannot see the new item as a field in the document unless you add the field to the form design. However, the item exists and can be accessed programmatically.

An item cannot appear in a view unless the IsSummary property is True. IsSummary is always False for rich text items, which cannot appear in views. IsSummary is initially False if the item is created with New or ReplaceItemValue.

You can replace the value of an item in every document of a document collection with the StampAll method of NotesDocumentCollection. This method writes immediately to the back-end document. Be sure to save all documents (Save method of NotesDocument) that you have modified in the script before using StampAll on them. You do not have to save after StampAll.