Domino Connection


Database design information -- working with design documents

The object model of Domino is very concise. The definitions of forms, views and other design database elements like replication formulas are stored in documents like all other information. These documents do not differ structurally from "normal" data documents. They simply contain a flag in the document's header, which identifies them as so-called "special documents" or design documents. With VisualAge Smalltalk Domino Connection you can access these special documents with a simple protocol. The following section gives you an overview over design documents and their usage.

Note:The internal structure of a design document is complex. Some of the important design information is usually stored in an RTF field called $BODY. To understand what is in the $BODY field, you have to parse the RTF data stream. There is only limited support to do this within the Domino Connection, but if you want to fully exploit the information available in a design note, refer to the Domino API documentation.

There is a set of classes which model the properties of design documents. The design document classes are subclasses of AbtLnNote because all their basic properties can be derived from "regular" documents. In addition to the AbtLnNote protocol the design documents offer a number of specialized methods according to their function in a database

Form documents

An AbtLnFormNote describes the properties of a Domino form. The fields in a form note do not directly correspond to the entry fields in the form. The fields in the form note are used to describe how a form works, how it looks, and what fields are defined in the form. There are convenient methods in the class AbtLnFormNote to retrieve relevant data from forms.

A typical form definition (like the "Server Connection" of your names and address book) contains some 50 fields. Helping you understand the meaning of each field is beyond the scope of this document. See your Domino documentation or API toolkit documentation for more information on fields in form documents.

A form is composed of typed entry fields. Those entry fields are used to display and enter data into documents. When building a form with the Domino designer, you can specify the name of an entry field, its data type (for example Text, Number, RTF) and some other properties like access control settings and field formulas.

Use the methods formNoteByName: or allFormNotes implemented in AbtLnDatabase to retrieve form documents.

Domino Connection support two levels of access to the field information of a form:

Simple form properties

The class AbtLnFormNote supplies a protocol to find out about some of the important form properties. Because a form can have one or more names/alias names, you can use the name or allFormNames methods of AbtLnFormNote to retrieve the name(s) as String or if alias names are present as an OrderedCollection of Strings. In addition you can gather structural information about a form using the allFieldNamesAndTypes selector. This method returns an OrderedCollection of Associations containing the name of the field as key and the type definition (that is the AbtLnItem subclass) as value.

Full form field information -- AbtLnFormField

To retrieve a full functional description of a form's field definition you must use the allFormFields method. The result will be an OrderedCollection of instances of subclasses of AbtLnFormField. The class AbtLnFormField models the properties of a field definition in a form. There is a subclass for each type of entry field. For example the AbtLnFormFieldKeywords class offers methods to find out about the predefined keyword list (method keywords) and about the set of formulas associated with the field: the default value formula, the input translation formula, the input validation formula and, if any, the keyword list creation formula.

Working with fields

You can access the properties of any form field in a form. The field information is read only and can be used to configure entry fields and input validation formulas in windows that represent forms in a Smalltalk application.

Smalltalk classes

There are 10 subclasses of AbtLnFormField which model the behavior of all possible fields in a form. There are methods to ask for most of the fields functional properties. Most important are the field formulas common to all classes. Depending on some field property (field is editable or computed) you will find one or more of the following formula types associated with each field: Value Formula (computed fields), Default Value Formula (editable fields), Input Translation Formula (editable fields), Input Validation Formula (editable fields). You can execute those formulas on demand. See chapter 2.6.6. for information about formula handling.

Keyword fields (AbtLnFormFieldKeywords)

Additional methods are available for keyword fields. You can find out about the keyword list and its visual representation on the corresponding Domino form. The protocol includes methods like: isInterfaceCheckBox, isFrame3D and of course keywords. Here is a piece of sample code how to access the field information for a keyword field. Use the sample database called vaforms.nsf provided with Domino Connection.

| localConnection sampleDatabase sampleForm sampleKeywordField |
"Initialize runtime system"
AbtLnEnvironment startUp.
 
"Create a local connection"
localConnection := AbtLnConnection local.
 
"Open the test database"
sampleDatabase := localConnection openDatabase:'VASAMPLE\VAFORMS.NSF'.
 
"Get the sampleDatabases form named 'FormulaTest'"
sampleForm := sampleDatabase formNoteByName: 'FormulaTest'.
 
"Get the first (and only) keyword field of the sample form"
sampleKeywordField := sampleForm allFormFields detect: 
   [ :field | field isKeywordField ].
 
"Write keywords of the field to the transcript"
Transcript cr; nextPutAll: 'Keywords : '; cr.
sampleKeywordField keywords do: [ :keyword | 
   Transcript nextPutAll: keyword; cr ].
 
"These keywords are computed by a formula. Read the formula"
Transcript nextPutAll: 'Choices formula : '.
sampleKeywordField usesFormulaForChoices
ifTrue: [ Transcript nextPutAll:  
    sampleKeywordField choicesFormula text ; cr ].
 
"Read the user interface settings"
Transcript nextPutAll: 'User interface : '.
Transcript nextPutAll:  sampleKeywordField interface; cr.
 
"Close database and runtime environment"
sampleDatabase close.
AbtLnEnvironment shutDown.

Number fields (AbtLnFormFieldNumbers)

Number fields can be queried for the number format which was set up during form design. You can find out about decimal places, parentheses on negative numbers etc.

Time and date fields (AbtLnFormFieldTime)

Time and Date fields offer a variety of additional methods to learn about the time and date format that was specified in the form field. You can find out if the field was configured to display the time or the date component of the underlying AbtLnItemTimeDate. You can also retrieve the time zone settings and the time display formats.

Names fields, Authors, Readers

In Names fields, you can access the information which of the following data sources is allowed to specify the names list: ACL, Address Dialog or View Dialog.

Associating forms and documents

When using the Notes client, the difference between a form and a document is not always obvious. Working with Domino Connection the distinction becomes very clear.

If you do not want to emulate the behavior of a form regarding its program logic (which is contained in the field formulas), you can easily use the newNoteFromForm: method in the class AbtLnDatabase to create a document containing the basic field names and type information defined in a certain form note. If you use this protocol you will get an empty AbtLnNote that is preinitialized with a set of AbtLnItems according to the field definitions in the form (see example in the next section). All the fields within the new document will be uninitialized and must be filled by your program. Storing such a document does not invoke input translation or input validation formulas.

If you want to execute all formulas contained in a form's definition, you must use the newNoteFromComputedForm: method. This method executes the default value formulas for each field definition contained in the form you specified and consequently initializes the new documents fields with their default values. Using this method, you associate the given form with the new document. You can subsequently use the other formulas to translate and validate the document's fields. Use the translate and store methods of the class AbtLnNote to perform the corresponding operations.

Note:The store method invokes the input validation formulas of a form only when a document was created via newNoteFromComputedForm:. If there is no form associated to a document, no formula will be executed automatically.

Using newNoteFromComputedForm: might be time consuming depending on the number and quality of formulas to be executed. Be aware that some formulas (for example @DBLookUp()) might need a long time for evaluation. Make sure that you really need to use the default value formulas in your application or consider using newNoteFromForm: and perform some of the necessary initializations using Smalltalk.

Here is a sample which demonstrates the two possibilities of creating documents using form information:

Before you look at the Smalltalk code, understand how the used form is set up. What follows is a subset of the information generated by the Domino design synopsis function for the form named: 'FormulaTest' :

Form Information:
Form:                              FormulaTest
Field:                             NoFormula
Datatype:                          Text
Field Type:                        Editable
 
Field:                             DefaultFormulaField
Datatype:                          Text
Default Value Formula:             "This is a default value"
 
Field:                             TranslationFormulaField
Datatype:                          Text
Default Value Formula:             "lower case default value"
Input Translation Formula:         @UpperCase(TranslationFormulaField)
                                   + " NOW TRANSLATED TO UPPERCASE";
 
Field:                             ValidationFormulaField
Datatype:                          Text
Default Value Formula:             "Short default value text"
Input Validation Formula:          @If((@Length(ValidationFormulaField)
                                   <30);@Failure("Input string is
                                   too short in ValidationFormulaField -
                                   must be 30 characters or longer"); 
                                   @Success);
 
Field:                             KeywordField
Datatype:                          Keywords
Field Type:                        Editable
Keyword User Interface:            Standard
Allow Values Not In List:          No
Allowable Keywords Formula:        @Explode(@Text(@Today) + "
                                   " + @Text(@Yesterday));

Here is Smalltalk code that operates on the form:

| connection database formNote noteWithForm simpleNote errorReporter |
"Start runtime system"
AbtLnEnvironment startUp.
 
"Create a connection to local databases"
connection := AbtLnConnection local.
 
"Open one of the sample databases provided with the feature"
database := connection openDatabase: 'VASAMPLE\VAFORMS'.
 
"Display the results of the 'newNoteFromForm:' method on the
Transcript window"
Transcript nextPutAll: 'New document - no forms formula executed'; cr.
Transcript nextPutAll:
(simpleNote := database newNoteFromForm: 'FormulaTest')
printString; cr; cr.
 
"Display the results of the 'newNoteFromComputedForm:' method on the
Transcript window"
Transcript nextPutAll: 'New document - default value formulas executed';cr.
Transcript nextPutAll:
(noteWithForm := database newNoteFromComputedForm:
'FormulaTest') printString; cr.
 
"Display the results of the 'translate:' method on the Transcript
window"
Transcript nextPutAll: 'Translation Formula executed for the
initialized document ';cr.
 
"provoke an exception due to length underflow on field
VALIDATIONFORMULAFIELD"
[ noteWithForm store ] when:  AbtLnErrorReporter errorSignal do: [ :e |
System message: e argument, 'Note can not be stored'.
e exitWith: nil ].
 
"Put a value to the field that is long enough to pass the input
validation formula"
noteWithForm at: 'VALIDATIONFORMULAFIELD' put: 'This is a very long
String that definitely can be stored in the document'.
 
"Store the note"
noteWithForm store.
 
Transcript nextPutAll: 'Validation Formula executed successfully -
document stored ';cr.
 
"Close the database"
database close.
 
"Shutdown runtime system"
AbtLnEnvironment shutDown.

When you look at your Transcript window, you will notice the difference between the two documents created: the first document is empty, the second document contains some fields that were initialized by the default value formula.

Note:There is a field named FORM which is initialized in the new document. This is done by Domino Connection and is not the result of a default value formula.

After the execution of the default value formula, the document that was associated with a form is used to demonstrate the effects of input translation formulas. When you send the translate message, all defined input translation formulas (if any) will be executed. Remember that the formulas will be executed in an order defined by the forms layout (from top left to bottom right).

The document will not be stored automatically, you will have to send the store message to the AbtLnNote. As you see in the sample, the document raises an exception when at least one of the input validation formulas can not be passed. The sample code catches the exception and displays a message box. After setting the contents of the VALIDATIONFORMULAFIELD to a String that is long enough (see input validation formula), the document can be stored.

View documents

An AbtLnViewNote describes the properties of a Domino view. The fields in a view document hold information about the views layout, the view formulas (for example selection formula, forms formula, column formula) access rights and other view details. View documents can be used to retrieve information to build a view equivalent window in Smalltalk and to program part of the functionality provided by the view.

Note:Most of the fields in a view document have a $-sign prefix, which means those are reserved names. You can learn about the meaning of each entry by consulting your Domino documentation.

Use the methods viewNoteByName: or allViewNotes implemented in the class AbtLnDatabase to retrieve view documents defined in a particular database.

Note:A view document does not contain data displayed in a view. A view document is kind of meta description of how a view looks and how it operates. If you want to access data in a view, use the AbtLnDatabaseView class.

To learn more about handling formulas in Domino Connection, see Advanced topics.

View formatting -- AbtLnColumnFormat

AbtLnViewNote supplies a protocol for easy access to information about the view's columns. Each column is treated as a separate entity and is described by an instance of a class called AbtLnColumnFormat. You can ask for an OrderedCollection of AbtLnColumnFormats from your view note using the columnFormats method. The collection contains the column descriptions ordered from left to right. The first element in the collection represents formatting and functional information for the leftmost column in the view.

The class AbtLnColumnFormat offers a rich set of methods which help you find out every detail about a view column. You can read every property of the view that is accessible through the Notes client software. The following step-by-step sample shows you how to build a tool to display view definitions that works somewhat like the Domino database synopsis.

| connection database viewNote |
"Startup runtime system"
AbtLnEnvironment startUp.
 
"Create a connection to local databases"
connection := AbtLnConnection local.
 
"Open one of the sample databases provided with the feature"
database := connection openDatabase: 'VASAMPLE\VAFORMS'.
 
"Get the first view note from the database"
viewNote := database allViewNotes first.
 
"Print view information on the Transcript"
Transcript nextPutAll: 'View Name is: ', (viewNote title); cr.
Transcript nextPutAll: 'Analyzing the view Columns :'; cr;cr.
 
"Iterate through all columns in the selected view and print column
format information on the Transcript window"
viewNote columnFormats do: [ :columnFormat |
Transcript nextPutAll: 'Column Title: ', columnFormat title; cr.
Transcript nextPutAll: 'Column Item: ',
columnFormat itemName; cr.
Transcript nextPutAll: 'Column Formula: ',
columnFormat formula text; cr.
Transcript nextPutAll: 'Column Width: ',
columnFormat displayWidth; cr.
Transcript nextPutAll: 'Column isHidden: ',
columnFormat isHidden printString; cr.
Transcript nextPutAll: 'Column isSortAscending: ',
columnFormat isSortAscending printString;
cr;cr.
].
 
"Close the database"
database close.
 
"Shutdown runtime system"
AbtLnEnvironment shutDown.

Using this information you can tailor specialized windows for Domino views or even create your own generic database view display widget.

Replication -- replication documents

Replication document are the third type of design documents supported by Domino Connection. Domino uses replication documents to store information about how and what elements of a particular database should be replicated with other Domino servers or Notes workstations. VisualAge Smalltalk Domino Connection grants you access to information in replication documents and lets you specify replication settings from your Smalltalk application.

Note:Replication is a very powerful tool and configuration can be complicated. Wrong replication settings can cause undesired data deletion and security violations. Be sure to fully understand replication settings before you try out changing replication documents.

As operations on replication setting are relatively complicated from an API perspective, Domino Connection condenses the functions into a convenient to use class called AbtLnReplicationSettings. An instance of this class can be retrieved from AbtLnDatabase using the replicationSettings method.

Basic replication -- AbtLnReplicationSettings

Basic settings can be accessed through an AbtLnReplicationSettings instance with simple methods like isHighPriority or excludeDeletedNotes. If you change replication settings, be aware that you have to execute the store method to make the changes persistent.

Selective replication settings -- AbtLnSelectiveReplicationSettings

Replication documents are projected onto a class named AbtLnSelectiveReplicationSettings. This class offers the necessary protocol to read and write settings for each replication peer. Thorough understanding of selective replication and the underlying mechanism is required to operate AbtLnSelectiveReplicationSettings instances.

Initiating replication

Limited by the capabilities of the API, VisualAge Smalltalk Domino Connection can only initiate replication for a local database with a server database. It is simple to start replication for a database by sending the message replicateWithServer: to the AbtLnDatabase instance. Using this protocol, default replication options are used. If you need to specify special options, use replicateWithServer:options: and an AbtLnReplicationSettings object. With AbtLnReplicationSettings you can fine-tune the replication as you would do it using the "replicate with options" feature of the client software.


[ Top of Page | Previous Page | Next Page | Table of Contents ]