OL2000: Working with the Message or Body of an Outlook Item (201105)

MORE INFORMATION

This article discusses using fields and controls with Outlook forms. It is important to understand the difference between the two. For additional information on the differences between fields and controls, click the article number below to view the article in the Microsoft Knowledge Base:

Working with the Message or Notes Field

The Message field is most commonly associated with a mail message form and is the main portion or "body" of the message. This is a unique field because it supports text in multiple formats, such as Rich Text Formatting (RTF), HTML, and Plain Text. You can also embed objects such as shortcuts or files into the message field.

This field also exists on other Outlook forms. On a Post form, it is called the Message field, but on all other forms, it is referred to as the Notes field. When you access this field through the Outlook object model, it is always referred to as the Body property of the appropriate item (ContactItem, PostItem, and such).

The following table summarizes the naming conventions:

   Item Type          Field Name    Property Name
   ---------          ----------    -------------
   Mail message       Message       Body
   Post               Message       Body
   Contact            Notes         Body
   Appointment        Notes         Body
   Meeting Request    Notes         Body
   Task               Notes         Body
   Task Request       Notes         Body
   Journal            Notes         Body
   Note*              N/A           Body

   * You cannot customize "Note" items.
				

NOTE: The remainder of this article will use the term "Message field" to refer to both Message and Notes.

Each Outlook item contains one Message field, and it is not possible to add an additional field of the same type as the Message field.

Working with the Message or Notes Control

When you design an Outlook form, you can use the Message control more than once on a form. However, when you insert a second Message control on a form, Outlook displays the following warning:
This warning may also appear when you use the form, such as when you switch to a form page that contains a second Message control.

Outlook controls are typically bound to MAPI fields to store the actual data. Each Outlook form or item has only one field that supports "rich text." Therefore, when you drag the Message field from the Field Chooser onto the form, it is automatically bound to the appropriate Outlook field. You cannot change this behavior. If there is more than one Message field on a form, they will all display the same data since there is only one field of this type permitted for each Outlook form. If you change data in one of the Message fields it does not automatically replicate to the other Message field unless you refresh the field by saving and reopening the form or setting the Body property via code.

The control used to display the Message field is built into the Outlook program and is not designed for use on non-Outlook forms. However, you can add the control to the Control Toolbox since it is a registered control on the system. Use your right mouse button to click a blank area of the Control Toolbox, and from the shortcut menu, click Custom Controls. "Outlook DocSite OLE Control" should be in the list of available controls. This is the control that is used to display the Message field.

Working with the Body Property with All Types of Message Formats

The Outlook user interface allows you to apply various formatting to mail messages, but when you use the Body property from Microsoft Visual Basic Scripting Edition (VBScript) or Microsoft Visual Basic for Applications, all of the text formatting is lost. This is because in the Outlook object model, the data type of the Body property is text, so it behaves no differently than other types of controls, such as a label or text box.

Microsoft provides programming examples for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. This article assumes that you are familiar with the programming language being demonstrated and the tools used to create and debug procedures. Microsoft support professionals can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific needs. If you have limited programming experience, you may want to contact a Microsoft Certified Partner or the Microsoft fee-based consulting line at (800) 936-5200. For more information about Microsoft Certified Partners, please visit the following Microsoft Web site: For more information about the support options that are available and about how to contact Microsoft, visit the following Microsoft Web site: When you use VBScript, you cannot programmatically insert information into the body of an Outlook item without completely replacing the body. The Body property enables you to programmatically create and delete the body text, but it does not enable you to insert or modify information that is within the body.

For example, you may have a mail item with the following text in the Message field:

   -------------------------------
   Thank you for using:



   We appreciate your business.
   -------------------------------
				

If you want to programmatically insert a product name between the lines, there is no method or property available that will not completely replace all of the body, as shown in the following examples.

' Completely replaces the existing text in the body. 
Item.Body = "This is new text" 

' Completely deletes the text in the Body. 
Item.Body = ""
				

The following VBScript example enables you to insert text within the Body property of the previous example. It does so by parsing the existing text and re-inserting new body text.

Sub Item_Open()
   ' Dimension X1, X2 to hold the return of the InStr function.
   Dim X1, X2
   
   ' Get the location of the first carriage return.
   X1 = Instr(1, Item.Body, Chr(13), 1)
   
   ' Get the location of the second carriage return.
   X2 = Instr(X1 + 1, Item.Body, Chr(13), 1)
   
   ' Get the text from the beginning of the body to the second carriage
   ' return.
   TempA = Left(Item.Body, X2)
   
   ' Get the rest of the text.
   TempB = Mid(Item.Body, X2 + 1, Len(Item.Body))
   
   ' Create new text.
   NewText = "Gadget Company" & Chr(13)

   ' Insert new Body which includes new text.
   Item.Body = TempA & NewText & TempB

End Sub
				

HTMLEditor

If you are using an HTML mail message, you can use the Outlook object model to access the HTML Document Object Model and use that object model to manipulate the embedded HTML. For more information, see the HTMLEditor property in the Microsoft Outlook Visual Basic Reference (Vbaoutl9.chm).

NOTE: For security reasons, you cannot use scripting code from within an HTML-based mail message to access the Outlook object model.

WordEditor

If you are using a WordMail message, you can use the WordEditor property to return the Microsoft Word object model and then use the object model to change the embedded Word document object. For more information, see the WordEditor property in the Microsoft Outlook Visual Basic Reference (Vbaoutl9.chm).