Walkthrough: Designing an Outlook Form Region

Custom form regions extend standard or custom Microsoft Office Outlook forms. In this walkthrough, you will design a custom form region that appears as a new page in the Inspector window of a contact item. This form region displays a map of each address that is listed for the contact, by sending the address information to the Windows Live Local Search Web site. For information about form regions, see Creating Outlook Form Regions.

Applies to: The information in this topic applies to application-level projects for Outlook 2007 and Outlook 2010. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

• Creating a new Outlook add-in project.

• Adding a form region to the add-in project.

• Designing the layout of the form region.

• Customizing the behavior of the form region.

• Testing the Outlook form region.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Working with Settings.

Prerequisites

You need the following components to complete this walkthrough:

-

An edition of Visual Studio 2010 that includes the Microsoft Office developer tools. For more information, see [Configuring a Computer to Develop Office Solutions](bb398242\(v=vs.100\).md).

• Microsoft Office Outlook 2007 or Outlook 2010.

For a video version of this topic, see Video How to: Designing an Outlook Form Region.

Creating a New Outlook Add-in Project

First create a basic add-in project.

To create a new Outlook add-in project

1. In Visual Studio, create an Outlook add-in project with the name MapItAddIn.

2. In the New Project dialog box, select Create directory for solution.

3. Save the project to any directory.

   For more information, see How to: Create Office Projects in Visual Studio.

Adding a Form Region to the Outlook Add-in Project

An Outlook add-in solution can contain one or more Outlook form region items. Add a form region item to your project by using the New Outlook Form Region wizard.

To add a form region to the Outlook add-in project

1. In Solution Explorer, select the MapItAddIn project.

2. On the Project menu, click Add New Item.

3. In the Add New Item dialog box, select Outlook Form Region, name the file MapIt, and then click Add.

   The New Outlook Form Region wizard starts.

4. On the Select how you want to create the form region page, click Design a new form region, and then click Next.

5. On the Select the type of form region you want to create page, click Separate, and then click Next.

   A separate form region adds a new page to an Outlook form. For more information about form region types, see Creating Outlook Form Regions.

6. On the Supply descriptive text and select your display preferences page, type Map It in the Name box.

   This name appears on the Ribbon of the Inspector window when the contact item is open.

7. Select Inspectors that are in compose mode and Inspectors that are in read mode, and then click Next.

8. On the Identify the message classes that will display this form region page, clear Mail Message, select Contact, and then click Finish.

   A MapIt.cs or MapIt.vb file is added to your project.

Designing the Layout of the Form Region

Develop form regions visually by using the form region designer. You can drag managed controls to the form region designer surface. Use the designer and the Properties window to adjust control layout and appearance.

To design the layout of the form region

1. In Solution Explorer, expand the MapItAddIn project, and then double-click MapIt.cs or MapIt.vb to open the Form Region Designer.

2. Right-click the designer, and then click Properties.

3. In the Properties window, set Size to 664, 469.

   This ensures that the form region will be large enough to display a map.

4. On the View menu, click Toolbox.

5. From the Common Controls tab of the Toolbox, add a WebBrowser to the form region.

   The WebBrowser will display a map of each address that is listed for the contact.

Customizing the Behavior of the Form Region

Add code to form region event handlers to customize the way a form region behaves at run time. For this form region, the code examines the properties of an Outlook item and determines whether to display the Map It form region. If it displays the form region, the code navigates to Windows Live Local Search and loads a map of each address listed in the Outlook contact item.

To customize the behavior of the form region

1. In Solution Explorer, right click MapIt.cs or MapIt.vb, and then click View Code.

   MapIt.cs or MapIt.vb opens in the Code Editor.

2. Expand the Form Region Factory code region.

   The form region factory class named MapItFactory is exposed.

3. Add the following code to the MapItFactory_FormRegionInitializing event handler. This event handler is called when the user opens a contact item. The following code determines whether the contact item contains an address. If the contact item does not contain an address, this code sets the Cancel property of the FormRegionInitializingEventArgs class to true and the form region is not displayed. Otherwise, the add-in raises the FormRegionShowing event and displays the form region.

   Private Sub MapItFactory_FormRegionInitializing(ByVal sender As Object, ByVal e As Microsoft.Office.Tools.Outlook.FormRegionInitializingEventArgs) Handles Me.FormRegionInitializing
   
       Dim myItem As Outlook.ContactItem = CType(e.OutlookItem, Outlook.ContactItem)
   
       If Not (myItem Is Nothing) Then
           If Not (myItem.BusinessAddress Is Nothing) AndAlso myItem.BusinessAddress.Trim().Length > 0 Or (Not (myItem.HomeAddress Is Nothing) AndAlso myItem.HomeAddress.Trim().Length > 0) Or (Not (myItem.OtherAddress Is Nothing) AndAlso myItem.OtherAddress.Trim().Length > 0) Then
               Return
           End If
       End If
   
       e.Cancel = True
   
   End Sub
   

   private void MapItFactory_FormRegionInitializing(object sender,
       Microsoft.Office.Tools.Outlook.FormRegionInitializingEventArgs e)
   {
       Outlook.ContactItem myItem = (Outlook.ContactItem)e.OutlookItem;
   
       if (myItem != null)
       {
           if ((myItem.BusinessAddress != null &&
                   myItem.BusinessAddress.Trim().Length > 0) ||
               (myItem.HomeAddress != null && 
                   myItem.HomeAddress.Trim().Length > 0) ||
               (myItem.OtherAddress != null && 
                   myItem.OtherAddress.Trim().Length > 0))
           {
               return;
           }
       }
   
       e.Cancel = true;
   }
   

4. Add the following code to the FormRegionShowing event handler. This code performs the following tasks:

   • Concatenates each address in the contact item and creates a URL string.

   • Calls the Navigate method of the WebBrowser object and passes the URL string as a parameter.

   The Local Search Web site appears in the Map It form region and presents each address in the scratch pad.

   Private Sub MapIt_FormRegionShowing(ByVal sender As System.Object, _
       ByVal e As System.EventArgs) Handles MyBase.FormRegionShowing
       Dim tempLoc As String = ""
       Dim defaultAddress As String = ""
       Dim scratchPadAddress As String = ""
   
       Dim myItem As Outlook.ContactItem = _
           CType(Me.OutlookItem, Outlook.ContactItem)
   
       If Not (myItem Is Nothing) Then
           If Not (myItem.HomeAddress Is Nothing) And _
               myItem.HomeAddress.Trim().Length > 0 Then
               tempLoc = myItem.HomeAddressStreet.Trim() + " " _
                   + myItem.HomeAddressCity + " " + myItem.HomeAddressState + _
                       " " + myItem.HomeAddressPostalCode
               If myItem.HomeAddress = myItem.MailingAddress Then
                   defaultAddress = tempLoc + "_Home"
               Else
                   scratchPadAddress += "adr." + tempLoc + "_Home~"
               End If
           End If
           If Not (myItem.BusinessAddress Is Nothing) And _
               myItem.BusinessAddress.Trim().Length > 0 Then
               tempLoc = myItem.BusinessAddressStreet.Trim() + " " _
                   + myItem.BusinessAddressCity + " " + _
                       myItem.BusinessAddressState + " " + _
                           myItem.BusinessAddressPostalCode
               If myItem.BusinessAddress = myItem.MailingAddress Then
                   defaultAddress = tempLoc + "_Business"
               Else
                   scratchPadAddress += "adr." + tempLoc + "_Business~"
               End If
           End If
           If Not (myItem.OtherAddress Is Nothing) And _
               myItem.OtherAddress.Trim().Length > 0 Then
               tempLoc = myItem.OtherAddressStreet.Trim() + " " + _
                   myItem.OtherAddressCity + " " + myItem.OtherAddressState + _
                       " " + myItem.OtherAddressPostalCode
               If myItem.OtherAddress = myItem.MailingAddress Then
                   defaultAddress = tempLoc + "_Other"
               Else
                   scratchPadAddress += "adr." + tempLoc + "_Other~"
               End If
           End If
       End If
   
       WebBrowser1.Navigate(("http://local.live.com/default.aspx?style=r&where1=" _
           + defaultAddress + "&sp=" + scratchPadAddress))
   
   End Sub
   

   private void MapIt_FormRegionShowing(object sender, EventArgs e)
   {
       string tempLoc = "";
       string defaultAddress = "";
       string scratchPadAddress = "";
   
       Outlook.ContactItem myItem = (Outlook.ContactItem)this.OutlookItem;
   
       if (myItem != null)
       {
           if (myItem.HomeAddress != null && 
                   myItem.HomeAddress.Trim().Length > 0)
           {
               tempLoc = myItem.HomeAddressStreet.Trim() + " " + 
                   myItem.HomeAddressCity + " " + myItem.HomeAddressState + 
                       " " + myItem.HomeAddressPostalCode;
               if (myItem.HomeAddress == myItem.MailingAddress)
               {
                   defaultAddress = tempLoc + "_Home";
               }
               else
               {
                   scratchPadAddress += "adr." + tempLoc + "_Home~";
               }
           }
           if (myItem.BusinessAddress != null && 
                   myItem.BusinessAddress.Trim().Length > 0)
           {
               tempLoc = myItem.BusinessAddressStreet.Trim() + 
                   " " + myItem.BusinessAddressCity + " " + 
                       myItem.BusinessAddressState + " " + 
                           myItem.BusinessAddressPostalCode;
               if (myItem.BusinessAddress == myItem.MailingAddress)
               {
                   defaultAddress = tempLoc + "_Business";
               }
               else
               {
                   scratchPadAddress += "adr." + tempLoc + "_Business~";
               }
           }
           if (myItem.OtherAddress != null && myItem.OtherAddress.Trim().Length > 0)
           {
               tempLoc = myItem.OtherAddressStreet.Trim() + " " + 
                   myItem.OtherAddressCity + " " + myItem.OtherAddressState + 
                       " " + myItem.OtherAddressPostalCode;
               if (myItem.OtherAddress == myItem.MailingAddress)
               {
                   defaultAddress = tempLoc + "_Other";
               }
               else
               {
                   scratchPadAddress += "adr." + tempLoc + "_Other~";
               }
           }
       }
   
       webBrowser1.Navigate("http://local.live.com/default.aspx?style=r&where1=" 
           + defaultAddress + "&sp=" + scratchPadAddress);
   
   }
   

Testing the Outlook Form Region

When you run the project, Visual Studio opens Outlook. Open a contact item to view the Map It form region. The Map It form region appears as a page in the form of any contact item that contains an address.

To test the Map It form region

1. Press F5 to run the project.

   Outlook opens.

2. In Outlook, create a contact by performing one of the following tasks:

   • In Outlook 2010, on the Home tab, click New Items, and then click Contact.

   • In Outlook 2007, on the File menu, point to New, and then click Contact.

3. In the contact form, type Ann Beebe as the contact name, and then specify the following three addresses.

   Address Type	Address
   Business	4567 Main St. Buffalo, NY
   Home	1234 North St. Buffalo, NY
   Other	3456 Main St. Seattle, WA

4. Save and close the contact item.

5. Re-open the Ann Beebe contact item.

6. In the Show group of the item's Ribbon, click Map It to open the Map It form region.

   The Map It form region appears, and displays the Local Search Web site. The Business, Home, and Other addresses appear in the scratch pad. In the scratch pad, select an address that you want to map.

Next Steps

You can learn more about how to customize the UI of an Outlook application from these topics:

• To learn about how to customize the Ribbon of an Outlook item, see Customizing a Ribbon for Outlook.

See Also

Tasks

Walkthrough: Importing a Form Region That Is Designed in Outlook

How to: Add a Form Region to an Outlook Add-in Project

How to: Prevent Outlook from Displaying a Form Region

How to: Access the Outlook Item that Displays the Form Region

Concepts

Accessing a Form Region at Run Time

Guidelines for Creating Outlook Form Regions

Associating a Form Region with an Outlook Message Class

Custom Actions in Outlook Form Regions

Other Resources

Creating Outlook Form Regions