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 Microsoft Advisory Services. For more information, visit these Microsoft Web sites:
Microsoft Certified Partners - https://partner.microsoft.com/global/30000104
Microsoft Advisory Services - http://support.microsoft.com/gp/advisoryservice
For more information about the support options that are available and about how to contact Microsoft, visit the following Microsoft Web site:http://support.microsoft.com/default.aspx?scid=fh;EN-US;CNTACTMS
This article assumes a general working knowledge of Outlook customforms. For information on getting started with customizing Outlook, referto the Microsoft Knowledge Base articles listed in the References sectionof this article.NOTE
: There is a distinction between the terms "items" and "forms." An itemrefers to a "record" of information (a group of fields) in a folder. A formis basically a "front end" for the item and does not typically contain anydata. Instead, it is published in a folder or forms library for use withitems in the folder.
When creating custom form solutions with Microsoft Outlook, it isimportant to be able to recognize how Outlook is using your custom form inrelation to the items in a folder.
A "Typical" Custom Forms Solution
If you want to create a custom contact form to replace the default Outlookcontact form, you would typically follow these steps:
- Start with a new, default Contact item to use as the basis for your custom form.
- Customize the form to suit your needs.
- Publish the form to the Contacts folder.
- Set the form as the default form for the Contacts folder by changing the folder properties.
Each Outlook item has a standard Message Class field to keep track of whichform should be used to display the item. The default message class for acontact is IPM.Contact, and when the form is published, the message classis changed to reflect the name of the published form. So in the previoussteps, if the form was called MyForm when it was published, it would have amessage class of IPM.Contact.MyForm. When you create a new item based onthe published form, the Message Class field of the item is set toIPM.Contact.MyForm.
For more information about working with message classes, please see thefollowing article in the Microsoft Knowledge Base:
OL98: How to Update Existing Items to Use a New Custom Form
In the typical scenario above, information about the form (the "formdefinition") is not saved with each item. The form is basically "linked"using the Message Class field. The size of a typical item may be 300 or 500bytes.NOTE
: For purposes of simplicity, this article will use the term "linkedform" to indicate a situation in which the form definition is not savedwithin an item and the Message Class field is set to use a custom form.However, it is possible to have the form definition saved with an item.Items that have a custom form definition stored within them are referred toas being "one-offed" or "a one-off."
When a form is one-offed, it will use the form definition that is storedwith the item instead of the published form. If a form definition is savedwith an item, the item's Message Class is changed back to the defaultmessage class for that form type, such as IPM.Contact.
Standard Ways Forms Become One-Offs
You can specify that a form is a one-off by selecting the "Send formdefinition with item" check box on the form's Properties page when indesign mode. You would typically do this when the form is not registered ina form library where the recipient has access to it. Selecting this optionensures that the person will see the custom form when the item is opened.NOTE
: In Outlook 97, this option was on by default for mail message forms,but in Outlook 98 the setting is off by default.
Items One-Offed Unexpectedly
Assume you have a linked forms scenario and you have 10 items alreadycreated that are using your published custom form. If you open one of theitems, and the form definition is somehow changed for that one particularitem, Outlook will automatically one-off the item (create a one-off form)and save the form definition with the item. The Message Class field willchange back to the default message class for that type of item, and thesize of the item will noticeably increase.
Following are known scenarios where items can be unexpectedly one-offed.
- You are in a typical linked forms scenario, open an existing item in a folder, make changes to the form in design mode, and save or send the item. If you want to change the form for all of the items in the folder, instead of opening an existing item, follow these steps:
All of the items in the folder will now use the updated custom form the next time the items are opened, because the Message Class still refers to the published form. The first time an item is opened after the form is changed, Outlook will briefly display a message indicating that the new form is being installed (copied to the forms cache).
- Open a new item based on your custom form.
- Make form design changes to that item.
- Using that item, republish the form with the same name.
- Close and do not save changes to the item.
- You used Microsoft Visual Basic Scripting Edition (VBScript) code in the custom form and used some methods or commands that are causing the item's form definition to change. The following methods most commonly cause this behavior: - ShowFormPage and HideFormPage - Methods that exist for the FormDescription object - Methods related to the properties of controls, usually for enabling/disabling controls or making them hidden/shown - The Delete method for the Action object
- You created a field for use in the folder, but the field did not actually exist in the item when the form was published. In this case, if you create a new item based on the custom form and use Outlook's in-cell editing feature to enter a value into an item in a table view, Outlook automatically adds the user-defined field to the item on-the-fly. This changes the form definition and therefore the item is one-offed.
- Assuming you published a message form so that it is available for everyone, if you open a new instance of the form, change any of the Message Options, and then send the form, the form will become a one-off form because Outlook updates the actions on the form.
Although solutions and situations vary greatly, there are some signs youshould be aware of that can indicate that items are becoming one-offed.
- A Macro virus warning is unexpectedly displayed when an item is opened. One-off forms are a common cause of the "Enable/disable" security warning Outlook displays if a form contains VBScript code. Because the code is not in a "registered" form, but actually in the item itself, Outlook will always display the warning. Ideally, you should try to avoid the scenario that is causing the item to be one-offed in the first place. For more information about the security warning, please see the following article in the Microsoft Knowledge Base:
OL97: Why Outlook Displays a Security Warning Opening an Item
- One-off forms are a common cause of the "Enable/disable" security warning Outlook displays if a form contains VBScript code. Because the code is not in a "registered" form, but actually in the item itself, Outlook will always display the warning. Ideally, you should try to avoid the scenario that is causing the item to be one-offed in the first place. For more information about the security warning, please see the following article in the Microsoft Knowledge Base:The size of an item increases unexpectedly.
- One-off forms are a common cause of the "Enable/disable" security warning Outlook displays if a form contains VBScript code. Because the code is not in a "registered" form, but actually in the item itself, Outlook will always display the warning. Ideally, you should try to avoid the scenario that is causing the item to be one-offed in the first place. For more information about the security warning, please see the following article in the Microsoft Knowledge Base:The icon for an item changes unexpectedly.
Identifying a One-Off Item
If an item is unexpectedly one-offed and then you notice that the "Sendform definition with item" check box is not selected, that does notnecessarily mean the form definition is not saved with the item.
An item is a one-off it its Message Class field is the default messageclass for that type of item, but when the item is opened, the form used todisplay the item is a custom form.
When developing a folder-based solution, you may want to display theMessage Class and Size fields in a table view so you can be sure that theitems in the folder are behaving as you expect. Also, a change in the iconfor an item oftentimes indicates a status change, but you should restartOutlook to be sure the proper icon is being displayed.
Steps to Reproduce the Problem
The following steps illustrate how the HideFormPage and ShowFormPagemethods can one-off an item.
- Create a new mail message.
- On the Tools menu, click Forms and then click Design This Form.
- Using the Control Toolbox, add a CommandButton to the P.2 page.
- On the Form menu, click View Code. Add the following VBScript codeinto the VBScript Editor and then close the editor:
Sub CommandButton1_click() ' This changes the form defintion Item.GetInspector.HideFormPage("P.2") ' Send the item Item.Send Msgbox Item.MessageClass End Sub Sub Item_Open() Msgbox Item.MessageClass End Sub Sub Item_Read() ' This changes the form definition Item.GetInspector.Hideformpage("P.2") Msgbox Item.MessageClass End Sub
- On the Tools menu, click Publish Form As and then publish the form in the Inbox as "Form1"
- On the Actions menu, click New Form1 to open an item based on the form.
- Address it to yourself.
- Use the Command Button on P.2 to send the message.
- When you receive the message, open it to read it.
Note that the macro warning message appears. Also, you will see the MessageClass changes to IPM.Note
because you have changed the form definition.
If you need to have a scenario where an item will become a one-off, you canwork around around the side effects of a one-off item by resetting themessage class field and then saving the item in code. As an example, usethe following code instead of the code given in the "Steps toReproduce the Problem" section, and the item will not disable the macrowarning message.
Dim sSaveMessageClass Sub CommandButton1_click() ' Save the MessageClass property sSaveMessageClass = Item.MessageClass ' This changes the form definition Item.GetInspector.HideFormPage("P.2") ' Restore the MessageClass property Item.MessageClass = sSaveMessageClass ' Save the changes to the form Item.Save ' Send the item Item.Send Msgbox Item.MessageClass End Sub Sub Item_Open() Msgbox Item.MessageClass End Sub Sub Item_Read() ' Save the MessageClass property sSaveMessageClass = Item.messageclass ' This changes the form definition Item.GetInspector.Hideformpage("P.2") ' Restore the MessageClass property Item.messageclass = sSaveMessageClass Msgbox Item.MessageClass End Sub
: If you programmatically change the message class of an item, the sizeof the item is not reduced. There is no way to truly remove the unwantedform definition from an item other than creating a new item without theform definition and copying the data from the old item to the new one.