Access to the fields or to the field contents of a document (AbtLnNote) is provided by two simple methods which reflect the dictionary-style character of a document: at: and at:put:.
Fields in a document can be easily accessed using the at: method. All fields in a note have a unique name which is a String (except some special cases to be discussed later). To support the dictionary-like protocol of an AbtLnNote, there is an at:ifAbsent: method as well.
Note: | Some names are reserved for Domino internal use. See your Domino documentation for reserved and internal field names. If you need to look at field names using the Notes client, use the "Document Property" context window. |
All fields are typed. There is a set of data types defined in Domino which maps to corresponding Smalltalk classes. In addition to that, these Smalltalk classes feature implicit conversion routines to Smalltalk base classes. The following example shows how to read all fields within a document retrieved from the sample database provided with Domino Connection.
| sampleDatabase note | "Initialize runtime system" AbtLnEnvironment startUp. "Open the local mailfile" sampleDatabase := AbtLnConnection local openDatabase: 'VASAMPLE\VAMAIL'. "Read the first note from the query results and load the contents" note := (sampleDatabase allNotesFromQuery: 'SELECT Form="Memo"') first fill. "Iterate through the fields in the document and print information to the Transcript" note allItems do: [ :item | Transcript nextPutAll: 'Fields class: '; nextPutAll: item class printString; cr; nextPutAll: 'Field Name: '; nextPutAll: item name; cr; nextPutAll: 'Field contents: '; nextPutAll: item contents printString; cr; cr. ]. "Close the sample database" sampleDatabase close. "Shutdown runtime system" AbtLnEnvironment shutDown.
It is equally easy to set document contents. Just use the at:put: protocol of your AbtLnNote instance. If you are not sure about the existence of a particular field, you can send the hasItem: message to the document.
As stated before, the fields in a document are typed. So if you put data into fields, be sure that you supply the proper data types. The at: method takes care of most of the necessary conversions.
Use the following classes to set the corresponding items:
Smalltalk Class | AbtLnItem |
String | AbtLnItemText |
Float | AbtLnItemNumber |
String | AbtLnItemComposite |
If you want to set an AbtLnItemTimeDate, the following parameters can be passed:
Array with: aDate and: aTime
AbtLnTimeDate
If you want to set any of the multiple value fields use the corresponding
formats:
OrderedCollection of | AbtLnItem |
String | AbtLnItemTextList |
Float | AbtLnItemNumberRange |
Time or Date | AbtLnTimeRange |
Note: | Changes to field values become persistent only when a document is stored. Use the store method with your AbtLnNote instance to save the changes. |
Note: | Domino Connection supports some additional field properties. Readersand Authorsfields are maintained during read and write operations with the Smalltalk classes. |
One of the great advantages of Domino over relational databases is its variable document structure. As stated before, a document can contain (almost) any number of fields. The user is always free to add or remove fields to/from a document. This feature allows the implementation of very dynamic information exchange applications.
To support this flexibility VisualAge Smalltalk Domino Connection implements a number of methods to change document structure. Use the deleteItem: method to remove not only the contents of an item but also its actual existence in the document. To append fields to a document you can choose from the following messages:
Note: | Changes to the document structure become persistent only when a document is stored. Use the store method with your AbtLnNote instance to save the changes. |
All prior described methods were operating on preexisting documents. The following section describes how to create a new document using the structure of a form definition.
Creating a "blank" document is very easy. Send the newNote message to an open instance of AbtLnDatabase and you will receive an empty document. Using the addItemNamed: protocols introduced in the last chapter, you can fill in items for your purpose. There is a more convenient way to create documents which are preinitialized according to a form definition. Use the newNoteFromForm: message to create a new document containing all field definitions that are available in the referenced form. When you create a document using newNoteFromForm:, form formulas will be executed: the default value formula on creation of the document, the input translation and input validation formulas on storing the document. An exception is signaled if one of the formulas fails to evaluate properly.
The example below copies a document from the sample discussion database to the sample mail database and adds some fields necessary to show up in the mail database's views.
| localConnection note sampleDatabase sampleMailDatabase newNote | "Initialize runtime system" AbtLnEnvironment startUp. "Build a local connection" localConnection := AbtLnConnection local. "Open the sample mail database" sampleMailDatabase := localConnection openDatabase: 'VASAMPLE\VAMAIL'. "Open the sample discussion database" sampleDatabase := localConnection openDatabase: 'VASAMPLE\VASAMPLE'. "Get the first MainTopic document from the discussion database" note := (sampleDatabase allNotesFromQuery: 'SELECT Form="MainTopic" ') first fill. "Create a new Note using the sample mail databases form definition for MEMO" newNote := sampleMailDatabase newNoteFromForm: 'Memo'. "Add information to MEMO specific fields - copy the body contents from the discussion document into the MEMO style document" newNote at: 'SendTo' put: 'Your Name'. newNote at: 'Subject' put: 'A copy from the discussion database'. newNote at: 'Body' put: (note at: 'Body'). "Add new fields to the MEMO note" newNote addTimeDateNamed: 'PostedDate'. newNote at: 'PostedDate' put: Time now. "Add a field that will not be displayed, because there is no such field definition in the MEMO form." newNote addCompositeNamed: 'SecretMessage'. newNote at: 'SecretMessage' put: 'You can only read this using the Notes client if you use the document property context window'. "Store the new note" newNote store. "Close both databases" sampleDatabase close. sampleMailDatabase close. "Shutdown runtime system" AbtLnEnvironment shutDown.
With Domino Connection you receive another sample database called abtlncl.nsf. It is a database designed to hold information about Smalltalk methods. There is a very simple form called Method which displays some of the relevant information about a Smalltalk method: the name of the class the method is implemented in, the name of the application the class is defined in, and the actual method selector. You can easily add more fields to this form to expand the database into a "class reference", or even to enhance it in a way that you can share code with other remote users. Here is a piece of code to show you how you can initially fill the database with all method information for the AbtLnBaseApp application.
Note: | This code will take some time to run. It generates a Domino document for each method in the selected application. |
| db application | "Start runtime system" AbtLnEnvironment startUp. "Open the method notes & comments db" db := AbtLnConnection local openDatabase: 'VASAMPLE\ABTLNCL.NSF'. "Collect the information about the AbtLnBaseApp" application := AbtNotesBaseApp. application defined do: [ :definedClass | definedClass methodsDo: [:method | | note | note := db newNoteFromForm: 'Method'. note at: 'Selector' put: method printString. note at: 'Class' put: definedClass printString . note at: 'Application' put: application printString. note store. ] ]. "Close the database" db close. "Shutdown runtime system" AbtLnEnvironment shutDown.