Mail parts
To make sending mail easy and convenient for you, Domino Connection offers two non-visual parts: The Mail part and the Address Book part. If you run Notes Version 4.5 or later or Domino 4.5 or later, you should also review the section named Domino Connection Using mail. It contains information about how to create a mail applications that works in conjunction with version 4.5 and later mail databases.
Mail part (AbtNotesMailPart)
In principle, the mail part is a special kind of form part. The difference is, that it is connected to two databases, the mail file and the mail box. Depending on your system, you configure the mail part using the settings pages to connect to local or remote databases using the appropriate connection aliases. You also have to select a form definition for your mail document. In addition to that you might specify additional, user defined fields for the document to be created.
Address Book part (AbtNotesAddressBookPart)
The address book part is a convenient tool to find out valid recipients for your mail. It is not needed to have an address book part in every mail application, because if you are sure about mail addresses you do not have to double-check them with the address book contents. On the other hand it is a good practice to offer address book support for less experienced users.
Sending mail using the mail parts
Here is a step-by-step example showing how to create a simple mail application. For this example it is assumed that you have a Notes client workstation set up to server based mail (which is the common setting for a LAN based installation).
If you are using Domino Version 4.5 or later or Notes Version 4.5 or later, you should consider building the mail sample according to the description named Domino Connection Using Mail - additional version specific featured are added to ensure proper execution of that mail sample.
Depending on the settings in your Organizer you will be prompted with either the notebook style settings pages (like in the example) or with the generic property list style window when you edit the part's settings. You will achieve similar results with both methods of configuring the part. If you cannot open the notebook style settings, you have to load the AbtEditNotesSettingsPagesApp using the Application Manager or the Organizer.
1. Create a application and a new visual part using the Organizer.
2. Create a connection alias to your personal mail file and name it ConToSampleMail. (If you do not know how to create a connection alias, see
Domino Connection specification of this documentation). You will need a second connection alias to the mail server's mail.box file. Set up this connection as well and name it ServerMailBox.
3. Select the mail part from the parts palette and drop it on the free from surface. Now set up the mail part's properties. The first notebook settings page sets up the connection to a mail database. The mail database is needed not only to store a document as a reference when it is sent, but also to retrieve form definitions for the mail. Open the mail file's settings page. Select the newly created alias and set Memo as the form to use.
4. Now click the "Mail Settings" tab to continue configuring the mail part. On the second settings page, the connection alias for the mail.box file is specified. Use your newly created connection alias and set the other option on the settings page to your desire. The "Save in Mail File" option specifies whether a mail document produced with the mail part will be saved in the user's mail file when it is sent. Use the Add button to select those fields from the form which contain valid recipient names. On a normal Memo form select: SendTo, CopyTo, BlindCopyTo.
5. If you want to add other fields to your mail, you can use the "User Defined Fields" tab to do so.
6. Select the OK button to update the part and return to the Composition Editor.
7. Now connect the openendWidget event of your application window to the open action of the mail part. Also connect the openendWidget event of your application window to the newMail action of the mail part to create a new mail document each time the window is opened.
8. Now add two push buttons to your application window:
a. A Cancel button to close the window. Connect the button's clicked event with the closeWidget action of the window.
b. A Send button to send the mail document and close the window. Connect the clicked event of the button with the newMail action of the mail part and with the closeWidget action of the window. To take care of the Domino memory allocated by the mail part, connect the closedWidget event of the window to the close action of the mail part.
9. Then tear off the currentNote attribute from the mail part and drop it on the free-form surface. The current note represents the actual mail document to be processed. There is a quickform feature for the current note. As an alternative to selecting the self attribute for quick form, which would create entry fields for every field specified in the Memo form, use some of the fields presented in the pop-up window:
a. SendTo to set recipients
b. Subject to specify the mails topic
c. Body for the message text
Save the part and run the application. Send a mail to yourself an look into your personal mail file using the Notes client. You may notice that some of the elements of a regular memo are missing -- that is due to the fact that you have set up the mail part with a limited set of fields. When you use the mail part, you will also note that there is default behavior for some fields. For example, the From field is automatically set to the value returned from the class AbtLnEnvironment when you send the message currentUserName. You can override the default values. Send a mail to yourself and check the result with your Notes client.
In the next step you will expand the mail application and supply a list of valid recipients. To achieve this goal, you will add an address book (AbtAddressBookPart) to the free form surface.
The address book part is a special kind of view part. It must be connected to a names and address book database. Create a connection alias to your names and address book (or to the sample name and address book provided with the demo applications).
1. Add an address book part to the free form surface for your application.
2. Select the address book part and open the settings pages. On the General tab, you specify the connection for the address book and the view which provides the list of valid names. If you want to use the sample address book provided with Domino Connection, select the ConToAddressBook connection and the view named People.
Note:
Usually you can choose from a number of address books. You probably have a local name and address book on your workstation and one or more address databases on your mail server. Ask your system administrator which of the address books suites your needs.
3. Use the second tab named Address Book to select a column from the Name and Address book view. If you use the sample database provided with Domino Connection, select the $16 column. If you are not sure which column to select, use the Notes client or Domino Designer to find out about the column names or analyze the view structure with the Smalltalk methods provided with the Domino Connection. Close the settings pages.
4. Add an additional window to the free form surface of the composition editor. Drop a single list part into the new window and add a button labeled Close. Connect the clicked event of the button to the closeWidget action of the window and to the close action of the address book part. Connect the aboutToOpenWidget event of the window with the open action of the address book part.
5. Connect the names attribute of the address book part with the items attribute of the list in the new window.
6. Add a third button to the first window (which represents the memo form) and label it Find address. Connect the clicked event of that button with the openWidget action of the window containing the list.
7. Finally connect the selectedItem attribute of the list to the object attribute of the memo forms entry field with the SendTo label. Save the part.
When you test the part, you will be able to open up the second window using the Find address button. It will display a list for recipients you can select from. Double-click the selection and the SendTo field of your memo is set to the selected value.