Chapter 5: Introducing Form Regions

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This article is an excerpt from Microsoft Outlook 2007 Programming: Jumpstart for Power Users and Administrators by Sue Mosher from Elsevier (ISBN 978-1-55558-346-0, copyright Elsevier 2008, all rights reserved). No part of these chapters may be reproduced, stored in a retrieval system, or transmitted in any form or by any means—electronic, electrostatic, mechanical, photocopying, recording, or otherwise—without the prior written permission of the publisher, except in the case of brief quotations embodied in critical articles or reviews.

Form regions arrive in Microsoft Office Outlook 2007 as a new way to change the appearance of Outlook items and give them additional features. Most of the time, professional developers will combine form regions with Outlook add-ins to integrate their applications with the Outlook platform. However, form regions can also add functionality even when an add-in is not involved.

The highlights of this chapter include discussions of the following:

• The difference between adjoining and separate regions

• What new controls Outlook provides for custom form regions

• How to tell Outlook when to use a custom form region

• How to design a custom form region to display a contact’s birth date and age in the reading pane

Contents

• 5.1 Understanding form regions

• 5.2 Controls for form regions

• 5.3 Creating your first form region

• 5.4 Registering and deploying form regions

• 5.5 Limitations of form regions

• 5.6 Other ideas for form regions

• 5.7 Summary

5.1 Understanding form regions

A form region can add a collapsible pane to an Outlook item’s layout (hence the name form “region”), add a new page to a form, or replace all the pages on a form. You design custom form regions in the same Outlook forms designer that you saw in Chapter 4.

Form regions come in two flavors: adjoining and separate. Either can appear when composing a new item, reading an existing item, previewing an existing item, or all of the above, depending on the settings for the region.

An adjoining region appears at the bottom of the item’s window or at the bottom of the reading pane. Multiple adjoining regions for the same type of item stack on top of each other. Each one is collapsible. Figure 5.1 shows an example of an adjoining form region to display a contact’s age and the date you first made contact with this person. We will see how to build this region later in the chapter.

Figure 5.1. An adjoining form region displays as a collapsible pane at the bottom of an open or previewed item

A separate form region displays as a stand-alone page when the user opens the item. A separate form region can add a new page, replace the first page of a standard form, or replace all the built-in pages. However, a form region can replace existing pages only for Outlook items whose MessageClass property is not one of the default classes—IPM.Note, IPM.Contact, and so on. In other words, you can implement a replacement form region for a custom message class named IPM.Note.MyForm, but for the default message class for mail messages, IPM.Note, Outlook will display only separate form regions that add new pages.

Note
Remember that an item’s MessageClass property determines what form that item will display. Look back at Figure 4.22, which shows the message class of a newly published form at the bottom of the Publish Form As dialog.

Implementing a custom form region requires three steps:

1. Design the region in the Outlook forms designer (yes, the same one we saw in Chapter 4). The design process is the same regardless of whether it’s a separate region or an adjoining region.

2. Create an .xml file (i.e., a text file using XML syntax) to tell Outlook where to find the form region and when to display it. This file is known as the manifest for the form region.

3. Add an entry to the Windows registry telling Outlook which message class to apply the region to and where to find the manifest file with the other instructions.

After a review of the new controls that Outlook 2007 provides for form regions, we will walk through the creation of a form region and then see how to save and register it.

5.2 Controls for form regions

Outlook 2007 gives form regions a new set of controls that support Windows themes so that they have the same color scheme and other settings as most Windows dialogs. These controls make it possible to almost completely duplicate the look of Outlook’s built-in form pages that are not customizable, such as the main page of the appointment form. Also available are Outlook-aware controls such as the “info bar” that displays information about the last time the user replied to or forwarded a message.

Before you can use these controls, you must add them to the Control Toolbox in the form designer. Right-click the Toolbox, and choose Custom Controls. In the Custom Controls dialog (see Figure 5.2), the custom form region controls all have names that begin with “Microsoft Office Outlook.” Table 5.1 lists the controls designed specifically for custom form regions and whether they can be bound to an Outlook field.

Figure 5.2. You must select form region controls in the Control Toolbox before you can add them to a region

Bound controls display and set the data stored in the bound field. In other words, when you want to enter data into a control and have that data saved with the Outlook item that the form is displaying, you need to use a bound control. The table also lists the name that each control shows when you hover the mouse over the Control Toolbox to display the control’s screen tip. This is also the control’s object class name in the Outlook object model. The _DocSiteControl and _RecipientControl objects are hidden; you can see them, though, if you right-click in the VBA Object Browser and choose Show Hidden Members.

Even with this rich set of controls, perfectly duplicating the look and functionality of a page from a standard form may not be possible, but you should be able to come very close.

Table 5.1. Microsoft Office Outlook Controls for Custom Form Regions  

Control	Screen Tip and Object Name	Description	Can Be Bound?
Microsoft Office Outlook Body Control	_DocSiteControl	Display the message or notes (Body property)	No; already bound to the Body property
Microsoft Office Outlook Business Card Control	OlkBusinessCardControl	Display the electronic business card for a contact item	No; already bound to the BusinessCardLayoutXml property
Microsoft Office Outlook Category Control	OlkCategory	Displays the names of the categories that the user selects by clicking the Categorize button	No; already bound to the Categories property
Microsoft Office Outlook Check Box Control	OlkCheckBox	Displays a check box and caption	Yes, to any yes/no (Boolean) property
Microsoft Office Outlook Combo Box Control	OlkComboBox	Displays a drop-down list of items for the user to choose from	Yes
Microsoft Office Outlook Command Button Control	OlkCommandButton	Displays a clickable button	Yes
Microsoft Office Outlook Contact Photo Control	OlkContactPhoto	Displays the photo for a contact item	No; used only for the contact photo
Microsoft Office Outlook Date Control	OlkDateControl	Displays a drop-down calendar where the user can select a date	Yes, to any date/time property
Microsoft Office Outlook Frame Header Control	OlkFrameHeader	Displays the top line and caption of a frame	Yes
Microsoft Office Outlook Info Bar Control	OlkInfoBar	Displays information about the current item in a yellow “info bar”	No
Microsoft Office Outlook Label Control	OlkLabel	Displays non-editable text	Yes
Microsoft Office Outlook List Box Control	OlkListBox	Displays a list of items for the user to choose from	Yes
Microsoft Office Outlook Option Button Control	OlkOptionButton	Used in a set of two or more option buttons to allow the user to make one choice	Yes
Microsoft Office Outlook Page Control	OlkPageControl	Displays scheduling controls in appointment forms or, in message forms, a tracking grid	No
Microsoft Office Outlook Recipient Control	_RecipientControl	Displays a list of recipients or linked contacts	Only to fields related to email addresses: Assigned To, Bcc, Cc, Contacts, From, Have Replies Sent To, Optional Attendees, Required Attendees, Resources, and To fields, plus the three email fields on a contact
Microsoft Office Outlook Sender Photo Control	OlkSenderPhoto	Displays the sender photo in a mail message	No; used only for the sender’s photo on messages
Microsoft Office Outlook Text Box Control	OlkTextBox	Displays editable or non-editable text	Yes
Microsoft Office Outlook Time Control	OlkTimeControl	Displays a drop-down list for choosing a time	Yes, to any date/time property
Microsoft Office Outlook Time Zone Control	OlkTimeZoneControl	Displays a drop-down list for choosing a time zone	No

Warning

Do not attempt to use any of the new Olk* controls in a legacy custom form. If you do, the form may become corrupted and lose all the VBScript code behind it.

5.3 Creating your first form region

To create a custom form region, you use the same form designer as we saw in Chapter 4. Let’s look at a practical example. On the Outlook contact form, users must go to the Details page to enter a person’s date of birth. In this example, you’ll see how to add the Birthday field to the first page of the Contact form and to even add a field to calculate and display the person’s current age on that page. Then, you’ll add a second date/time field—this one with a dropdown calendar—to track the date of your first contact with each person.

Start by using the Tools | Forms | Design a Form command to open a contact form in design mode. Then choose Form Region | New Form Region. You should see a new tab with the name (Form Region) and a plain, blank gray page.

This form region will use the new-style label, text box, and date controls. If you haven’t already added these, display the Control Toolbox, right-click it, choose Custom Controls, and add those controls.

Next, we’ll put the controls on the region, starting with a text box for entering the birth date.

Tip
You don’t really need a date picker control for the birth date, since you wouldn’t normally want to scroll back through a few decades to find the original birth date in the drop-down calendar.

Since Birthday is an existing Outlook contact property, you can drag it from the Field Chooser to the form page. This adds an old-style text box and label control, not the new controls, but that’s OK. When the form region displays at runtime, Outlook will automatically show the newer controls.

Outlook contains no property that automatically calculates a person’s age, but you can add one by creating a new field that computes the value of a formula. In the Field Chooser, click New. Give the new field the name Age, set the Type to Formula, and type in this formula:

IIf([Birthday]<>"None", DateDiff("yyyy",[Birthday],Date())-IIf(DateDiff("d", CDate(Month([Birthday]) & "/" & Day([Birthday]) & "/" & Year(Date())),Date())<0,1,0),"")

Click OK to save the new field definition. Drag the Age field from the Field Chooser to place it to the right of the controls for the birthday.

Note
You’ll learn more about formula fields and other kinds of Outlook custom properties in Chapter 6.

Tip
When designing an adjoining form region, arrange your controls so that they take up as little vertical space as possible, since an adjoining region stacks at the bottom of the reading pane or item window.

The next step is to create a new date field to hold the date of your first contact with an individual, along with a date picker control for that field. First, add a label control and a date control in line with the controls for the Birthday and Age fields. Change the caption for the label control to First contact: using the control’s Properties dialog. Use the Align and Size commands to change the height and arrangement of the controls so that the form region looks like Figure 5.3.

The drop-down date picker in Figure 5.3 looks odd doesn’t it? It shows a date of 12/30/1899. This is because it has not yet been bound to an Outlook field. We need to create a new field to hold that date and then tell the date picker to display the data from that field. This process is called binding the control.

Figure 5.3. Form region controls added to the Toolbox (bottom row) have a different look from the older form controls

Figure 5.4. Use a bound control to display data from an Outlook property

To create the date field, return to the Field Chooser, click New again, and this time create a field with the name First Contact and the type Date/Time. From the Format drop-down list, choose any format that displays just the date, such as “Wed 7/5/06.” Click OK.

Right-click the date picker, choose Properties, and switch to the Value tab. Click the Choose Field button, and from the User-defined fields in folder list, select First Contact, as shown in Figure 5.4. Also, under Initial Value, check the box for Set the initial value of this field to and type Date() into the blank box. Leave selected the default option for Calculate this formula when I compose a new form. Those Initial Value settings mean that whenever you create a new contact, Outlook will automatically set today’s date as the default value for the First Contact field. You will need to change it only if you met the person on some day other than today. Click OK to save the changes to this control. You should see the date displayed in the date picker change from 12/30/1899 to None.

Tip
The Properties dialog for each form region control includes a Layout tab where you can set the control’s automatic alignment and resizing properties.

You’ve finished the form region design! Save your new form region by choosing Form Region | Save Form Region. Make a note of the location that you choose to save the region. Outlook saves form regions with an .ofs file extension. After you save the form region, click the close (x) button at upper-left to end the form design session, and choose No when you’re asked to save changes.

Tip
To help organize your form region files, you may want to create a Regions folder on your hard drive and use a different subfolder to store the files for each region.

As described earlier, creating the region is just the first of three steps in implementing a custom form region. Before Outlook can use the form region, you must create a special text file to tell Outlook where to find the .ofs file and how to use it, and you must add some information to the Windows registry.

5.4 Registering and deploying form regions

After you have designed and saved an .ofs form region file, you next need to create an .xml manifest file with information about your form and also add information to the Windows registry to tell Outlook where to find the .xml file. You can create the file in any text editor, such as Notepad, and save it as a file with an .xml extension. Specialized XML editor tools also exist, but Notepad should be sufficient for the simple .xml files used by form regions. XML is case-sensitive, so if you are not using an XML editor, you need to take special care to use the correct case for any element names.

Note

XML stands for Extensible Markup Language. XML turns up in many places in Office 2007, from the storage of electronic business card details in Outlook to the hidden structure of Word, Excel, and PowerPoint documents. Superficially, it looks a little like the HTML source code for a Web page in that it contains tags enclosed in angle brackets like <this>. However, where HTML code is often concerned with formatting, XML concentrates on structure. It provides an organized way to describe complex structures using plain-text syntax. Because the syntax is in plain text, rather than some proprietary binary format, it is portable and readable both by human eyeballs and by applications like Outlook. Because the syntax is quite strict, it is possible to validate an XML document against a standard specification, called a schema, to determine whether that document contains “good” XML, as defined for that schema.

Let’s start with a simple example. Listing 5.1 shows a manifest to display your new form region in the individual windows for new and existing contacts.

Listing 5.1. XML manifest to display an adjoining form region

<?xml version="1.0" encoding="utf-8"?>
<FormRegion xmlns="http://schemas.microsoft.com/office/outlook/12/formregion.xsd">
  <name>FirstContactRegion</name>
  <title>Key Dates</title>
  <formRegionType>adjoining</formRegionType>
  <layoutFile>firstcontact.ofs</layoutFile>
  <showCompose>true</showCompose>
  <showRead>true</showRead>
  <showPreview>false</showPreview>
  <version>1.0</version>
</FormRegion>

Note
Individual item windows in Outlook are Inspector windows. The windows that display folders are Explorer windows.

The first line of the manifest (<?xml ... ?>) is a declaration that indicates this is an XML document and that it supports 8-bit Unicode character encoding. The rest of the document consists of elements that begin with an open tag consisting of the element name in angle brackets (e.g., <FormRegion ...>) and end with a matching close tag e.g., (</FormRegion>). XML documents typically include nested elements; in this example, you see the elements to describe an adjoining form region nested inside the <FormRegion> element. What looks like a Web page URL inside the <FormRegion ...> open tag is a reference to the XML schema (available as a reference from Microsoft) that defines form regions. When Outlook tries to load the form region, it validates the information in the manifest against this schema to determine whether all required elements are present, all values are appropriate, and so on. Only if the manifest is valid will Outlook load the form.

The first region element, <name>, is required. Outlook add-ins use this name for various standard coding tasks, but if you’re loading a form region directly from an .ofs file rather than building an add-in, it doesn’t serve any particular purpose. The <title> element determines the title displayed for an adjoining region and the tab caption for a separate region.

Table 5.2 Values for the <formRegionType> Element

Value	Description
adjoining	An adjoining form region appears as a stacked, collapsible pane at the bottom of the reading pane or at the bottom of the main page of an item viewed in an Inspector window.
separate	A separate form region appears as a new form tab. (See below for information on the <displayAfter> element that determines the tab order.)
replace	A replacement form region replaces the first tab on a form. (Does not apply to standard message classes such as IPM.Note.)
replaceAll	A replace-all form region replaces the first tab on a form and hides all other standard tabs. (Does not apply to standard message classes such as IPM.Note.)

Tip
Do not use an ampersand (&) character for the <title> element of separate form regions. Separate regions appear as separate pages, and Outlook ignores any ampersand in a form page name.

Use the <formRegionType> element to specify whether the region should load as an adjoining region, a separate page, or a replacement page. This element is required. Table 5.2 lists the supported values.

The <layoutFile> element tells Outlook where to find the saved .ofs form region file. It can take three kinds of string values:

• A path relative to the location of the manifest file. If the .ofs file is stored in the same folder as the manifest, specify just the name of the file, as in Listing 5.1.

• A complete file path, such as C:\Data\Form Regions\firstcontact.ofs

• A file path with environment variables, such as %ProgramFiles%\Microsoft Office\Office12\Addins\firstcontact.ofs

Note
An Outlook add-in that provides the storage for a form region would use the <addin> element to supply the ProgID value for the add-in, instead of using the <layoutFile> element to point to a file storage location. Either one or the other of these two elements must be present in the manifest, but not both.

The <showCompose>, <showRead>, and <showPreview> elements determine whether the form region is visible in the window for a new item, the window displaying an existing item, or in the Outlook reading pane, respectively. Each can take the Boolean value true or 1 to show the region and false or 0 to not show it. All three elements are optional and have a default value of true. In other words, if you do not include these elements, the form will appear in all three locations. I find it helpful to include all three even if each value is true, to make it absolutely clear in the manifest how Outlook will display the region.

The <version> element is an optional element that allows you to provide a string value to indicate the form version. For replacement and replace-all form regions, this version number will appear on the Tools | Forms | Choose Form dialog.

How does Outlook know when to use a form region and which one to use? The third step in deploying a form region is to modify the Windows registry to tell Outlook that the form region is available and where to find its settings. Run the Regedit.exe application and navigate to this registry key:

HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\FormRegions

To deploy the First Contact form region created earlier in this chapter so that it is visible on all Outlook contacts, create a new key named IPM.Contact (the message class for the standard contact form). Under the IPM.Contact key, add a string value that refers to this particular region (e.g., “First Contact”) and set its value to the full path to the manifest (e.g., C:\Form Regions\First Contact\firstcontact.xml). Figure 5.5 shows you what the registry should look like.

The IPM.Note.* regions shown in Figure 5.5 are installed automatically with Outlook to provide support for Exchange 2007 Unified Messaging features.

Figure 5.5. A registry value points Outlook to the form region manifest, which in turn contains all the information Outlook needs to load the form

Figure 5.6. Adjoining form regions stack and can be collapsed

Restart Outlook, then open an existing or new contact to see the form region in action. Since the manifest specifies it as an adjoining region, it appears at the bottom, as shown in Figure 5.1.

Tip
To collapse the ribbon and leave more screen room for the contact information, as shown in Figure 5.6, double-click any of the tabs on the ribbon.

Once you register a form region in the registry, if you need to make subsequent changes to the region, you do not need to restart Outlook or make any changes to the manifest file. Just save the changes as a new .ofs file with the same file name, the name referred to in the manifest’s <layoutFile> element.

5.4.1 Other form region manifest settings

In the previous section, you saw some of the settings for the <FormRegion> elements that define how Outlook uses a form region. Only four are required: <name>, <title>, <formRegionType>, and either <layoutFile> or <addin>. Listing 5.2 shows another example of a manifest for a form region, this time for a separate form region to replace the first page on a custom task form, but only for Inspector windows, not in the reading pane.

Listing 5.2. XML manifest to display a separate form region

<?xml version="1.0" encoding="utf-8"?>
<FormRegion xmlns="http://schemas.microsoft.com/office/outlook/12/formregion.xsd">
  <name>TaskWorkRegion</name>
  <title>Task</title>
  <formRegionType>replace</formRegionType>
  <layoutFile>taskwork.ofs</layoutFile>
  <showCompose>true</showCompose>
  <showRead>true</showRead>
  <showPreview>false</showPreview>
  <contact>Sue Mosher (sue@turtleflock.com)</contact>
  <icons>
     <default>taskwork_default.ico</default>
     <window>taskwork_window.ico</window>
  </icons>
  <version>1.0</version>
</FormRegion>

An optional element related to form region display is <hidden>, which applies only to replacement and replace-all form regions. It controls whether such regions will appear on the Actions menu for the appropriate folders and on the Choose Form dialog for creating a new item. It also takes Boolean values. If you do not include this element, the default value of false will apply, which means that the custom form will appear on the Actions menu for all folders of the appropriate item type (e.g., all contact folders) and in the Tools | Forms | Choose Form dialog. Use true instead if you do not want the form to appear on the Actions menu or Choose Form dialog.

The optional <contact> element provides contact information for the form region.

The optional <displayAfter> element contains the internal name of the form region that the current region should follow. Remember that the <name> element sets that internal name. This element is relevant for separate and replace-all regions.

The optional <icons> element can contain elements for defining the icons associated with various states of the form. As with the <layoutFile> element, the paths can be relative or exact and support environment variables. Table 5.3 lists the available icon elements.

Table 5.3. Form Region Manifest Elements That Control Icons

Element Name	Description
<default>	Default icon
<window>	Icon used for the window displaying the form region
<page>	Icon displayed for the region in the ribbon
<unread>	Icon used when the form’s item is unread
<read>	Icon used when the form’s item is read
<replied>	Icon used when the form’s item has been replied to
<forwarded>	Icon used when the form’s item has been forwarded
<unsent>	Icon used when the form’s item is unsent
<signed>	Icon used when the form’s item has been digitally signed
<encrypted>	Icon used when the form’s item has been digitally encrypted
<submitted>	Icon used when the form’s item has been submitted but not sent
<recurring>	Icon used to identify that the item is recurring

Microsoft’s official documentation for form region manifests can be found in Help, starting with Help topic HV10204449, “Using the Form Region XML Manifest to Define a Form Region.” This topic includes information on other optional elements such as <customActions> to add custom actions and <stringOverride> to localize the display names of controls and other strings.

The <formRegionName> element is used by separate, replacement, and replace-all regions to set the name of the page shown in the Show group on the ribbon; if not present, the <title> element is used. The <loadLegacyForm> element applies only to replacement and replace-all regions and has a default value of false, which tells Outlook not to look for a legacy custom form of the same message class as the region. If <loadLegacyForm> is set to true, Outlook will both load the region and try to locate a legacy form, which could slow down performance.

5.4.2 Other considerations for deploying form regions

As you’ve seen in this section, the components related to a form region consist of .ofs and .xml files and a registry key and values. This simple architecture means that you can create a form region on one machine and deploy it to one or many other machines, using the same tools that you would use to deploy other files and registry changes, such as login scripts or the Office Customization Tool included in the Office 2007 Resource Kit.

The example earlier in this chapter showed deployment of the necessary registry key to the HKEY_CURRENT_USER hive of the registry. Alternatively, you could use the same key, only in the HKEY_LOCAL_MACHINE hive, to deploy a form region to a machine and make it available to all users of that computer.

The keys in the FormRegions key work in an additive fashion, each level inheriting the regions from the lower levels. A form region for the IPM.Contact.Sales.Manager message class would display form regions registered for IPM.Contact and also for IPM.Contact.Sales as well as any regions for IPM.Contact.Sales.Manager.

5.5 Limitations of form regions

Custom form regions have two limitations when compared with traditional custom forms:

• They do not support VBScript code behind them. Instead, all business logic is handled with code in an Outlook add-in.

• A form region must be registered on every machine that needs to use it. There is no concept of a centralized registry of form regions analogous to the Organizational Forms library for legacy custom forms.

Creating an Outlook add-in requires an additional developer tool, such as Microsoft Visual Studio Tools for Office, and is not covered in this book.

Caution

All controls for form regions that display in the reading pane should be set for read-only access. If you leave a control editable, and the user presses the Delete key with the focus in a form region control in the reading pane, Outlook will delete the entire item, instead of deleting text in the control. This means that you may need two versions of a particular region—one with read-only controls deployed with a manifest containing the element <showPreview>true</showPreview> and a second version with editable controls and the element <showPreview>false</showPreview>.

One final limitation; Microsoft does not support designing Outlook form regions in any screen resolution other than 96 dots per inch (dpi). Outlook automatically scales the appearance of text on the screen at runtime if the machine is using a different resolution. But for the scaling to work properly, the form region must be designed at 96 dpi.

5.6 Other ideas for form regions

Even with the above limitations, form regions open up some opportunities for building Outlook enhancements. One particularly interesting possibility is consolidating information in the preview pane that formerly required the user to open an item to see it. For example, you could show the tracking tab for messages using the Microsoft Office Outlook Page Control in an adjoining form region. Use the Advanced Properties dialog to change the value of the Page property for this control from the default value, 0-Planner, to the other possible value, 1-Tracker.

Another kind of enhancement is adding simple data entry. Do you prefer to type in the names of categories, rather than use the Categorize button? If so, you can create an adjoining form region with a text box control bound to the Categories field. Compare Figure 5.6, which shows the Key Dates region collapsed above a second region, Categories, with Figure 5.1.

5.7 Summary

The new form regions feature in Outlook 2007 overcomes many past custom form limitations, such as forms cache corruption and no reading pane layout, and provides a rich control environment. The new controls that can help you duplicate the look of almost any standard form page include date and time pickers, an info bar, a control to display tracking information, and controls to show contact pictures and electronic business cards. Although adding business logic to form regions requires building an Outlook add-in, there are still many codeless form region applications that can help you display data in the reading pane and provide the user with new data entry controls.

Additional Resources

• Chapter 17: Working with Item Bodies

• Chapter 24: Generating Reports on Outlook Data

• Outlook Developer Portal

• Microsoft Office Developer Center