Updated Outlook Topics for the Visual Studio Code Name "Orcas" January CTP
Today the VSTO user education team is presenting 4 more topics from the VSTO documentation included with the January 2007 CTP of Microsoft Visual Studio Code Name “Orcas” (for more information, see Monday's post). Today's topics are all about Outlook Form Regions: "Walkthrough: Creating an Outlook Form Region", "Custom Actions in Outlook Form Regions", "How to: Add a Custom Action to a Form Region" and "Associating a Form Region with an Outlook Message Class". If you have any feedback regarding these topics, please leave us a comment.
*************************************************
Walkthrough: Creating an Outlook Form Region
Introduction
Custom form regions extend standard or custom Microsoft Office Outlook 2007 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 Live Local Web site.
For information about form regions, see "Creating Outlook Form Regions".
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 The dialog boxes and menu commands you see might differ from those described in Help depending on your active settings or edition. To change your settings, select Import and Export Settings on the Tools menu. For more information, see "Visual Studio Settings".
Creating a New Outlook Add-in Project
First create a basic add-in project, and then later add a form region item.
To create a new Outlook add-in project |
1. In Visual Studio, create an Outlook 2007 add-in project with the name MapItAddIn. 2. In the New Project dialog box, select Create directory for solution. 3. Save the project to %USERPROFILE% \My Documents\Visual Studio 2005\Projects\. For more information, see "How to: Create Visual Studio Tools for Office Projects". |
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, right-click the MapItAddIn project, click Add, and then click New Item. 2. In the Add New Item dialog box, select Outlook Form Region, name the file MapIt, and click Add. The New Outlook Form Region wizard starts. 3. In the Create a New Outlook Form Region 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". 4. In the Supply descriptive text and select your display preferences page, type Map It in the Name box. This name identifies the form region in the Ribbon of the Inspector window when the contact item is open. 5. Select Inspectors that are in compose mode and Inspectors that are in read mode, and then click Next. 6. In 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. 4. On the View menu, click Toolbox. 5. From the Common Controls tab of the Toolbox, add a WebBrowser to the form region. |
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 the Live Local Web site 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. Add the following code to the Microsoft.Office.Tools.Outlook.FormRegionControl.BeforeStartup event handler. The add-in raises the Microsoft.Office.Tools.Outlook.FormRegionControl.BeforeStartup event 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 Microsoft.Office.Tools.Outlook.FormRegionBeforeStartupEventArgs.Cancel property of the Microsoft.Office.Tools.Outlook.FormRegionBeforeStartupEventArgs class to true and the form region is not displayed. Otherwise, the add-in raises the Microsoft.Office.Tools.Outlook.FormRegionControl.Startup event and displays the form region. [Visual Basic]Private Sub MapIt_BeforeStartup(ByVal sender As System.Object, ByVal e As Microsoft.Office.Tools.Outlook.FormRegionBeforeStartupEventArgs) Handles MyBase.BeforeStartup Dim myItem As Outlook.ContactItem = CType(e.OutlookItem, Outlook.ContactItem) If Not (myItem Is Nothing) Then If Not (myItem.BusinessAddress Is Nothing) And myItem.BusinessAddress.Trim().Length > 0 Or (Not (myItem.HomeAddress Is Nothing) And myItem.HomeAddress.Trim().Length > 0) Or (Not (myItem.OtherAddress Is Nothing) And myItem.OtherAddress.Trim().Length > 0) Then Return End If End If e.Cancel = True End Sub
[C#] private static void MapIt_BeforeStartup(object sender, Microsoft.Office.Tools.Outlook.FormRegionBeforeStartupEventArgs 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; } 3. Add the following code to the Microsoft.Office.Tools.Outlook.FormRegionControl event handler. This code performs the following tasks: · Concatenates each address in the contact item and creates a URL string. · Calls the System.Windows.Forms.WebBrowser.Navigate method of the System.Windows.Forms.WebBrowser object and passes the URL string as a parameter. The Live Local Web site appears in the Map It form region and presents each address in the Live Local Scratch pad. [Visual Basic] Private Sub MapIt_Startup(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Startup 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(("https://local.live.com/default.aspx?style=r&where1=" + defaultAddress + "&sp=" + scratchPadAddress)) End Sub
[C#] private void MapIt_Startup(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("https://local.live.com/default.aspx?style=r&where1=" + defaultAddress + "&sp=" + scratchPadAddress); } |
Testing the Outlook Form Region
When you run the project, Visual Studio Tools for Office Code Name "Orcas" runs the add-in and opens Outlook 2007. 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 CTRL+F5 to run the project. Outlook 2007 opens. 2. In Outlook, 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.
4. Save and close the contact item. 5. Re-open the Ann Beebe contact item in Outlook 2007. 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 Live Local Web site. The Business, Home, and Other addresses appear in the Live Local Scratch pad pane. In the Live Local Scratch pad pane, 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 2007".
"c***********************************************
Custom Actions in Outlook Form Regions
Introduction
Actions display buttons that enable users to respond to a Microsoft Office Outlook item. For example, to respond to a mail item, users click the Reply, Reply to All, or Forward action buttons. Each of these actions creates a new mail item and populates the item's fields by using information from the original item.
You can create a custom action that opens any kind of Outlook item. For example, you can add a custom action that opens a new appointment or task item. Set the properties of a custom action or use custom code to populate the fields of the new item. Custom actions appear in the Custom Actions menu of an item that is open in an Outlook inspector window.
Adding Custom Actions to a Form Region
To add a custom action to a form region, use the Custom Actions dialog box. For more information, see "How to: Add a Custom Action to an Outlook Form Region.
You can use the Custom Actions dialog box to specify a target form. A target form is the form that appears when the user executes the custom action.
You can also use the Custom Actions dialog box to specify how you want information from the original item to appear in the target form.
The following table describes the properties that are available in the Custom Actions dialog box. For more information about the values that you can select for each property, see the Action Settings section of the article Developing Custom Forms Using Microsoft Outlook 2002 (Part 2 of 2).
Property |
Description |
AddressLike |
Specifies how the target form will be addressed. |
Body |
Specifies how the body of the original item is appended to the target form. |
Enabled |
Indicates whether the custom action is enabled. If this property is set to false, the custom action does not appear in the Ribbon. |
Method |
Specifies the type of response available when the custom action is executed. The custom action can send the form, open the form, or prompt the user whether they want to send or open the form. |
Name |
Specifies the internal name that you can use to reference this custom action in code. |
ShowOnRibbon |
Indicates whether to display the custom action on the Ribbon of the original item. |
SubjectPrefix |
Specifies text that is inserted at the start of the subject line of the target form. |
TargetForm |
Specifies the message class name of the target form. For example, type IPM.Task to open a task form. |
Title |
Specifies the label of the custom action button. |
Customizing a Custom Action at Run Time
You can also add behavior to the custom action using code. For example, you can add code that takes the names of e-mail recipients and adds those names as attendees in a new appointment item. To do this, handle the CustomAction event of the Actions object. For more information, see the Microsoft Office Outlook 2003 Visual Basic Reference.
***********
How to: Add a Custom Action to an Outlook Form Region
Introduction
Add one or more custom actions to a Microsoft Office Outlook form region by using the Custom Actions dialog box. For more information, see "Custom Actions in Outlook Form Regions".
Procedures
To add a custom action to a form region |
1. In Visual Studio, open an Outlook 2007 add-in project that contains a form region item. 2. In Solution Explorer, expand the project node, right-click the form region item, and then click View Designer. The form region designer appears. 3. Right-click the form region designer, and then click Properties. 4. In the Properties window, expand the Manifest node, select the CustomActions property, and then click the ellipsis button. The Custom Actions dialog box appears. 5. Click Add to add a new custom action. 6. Set the properties of the custom action, and then click OK to close the Custom Actions dialog box. For information about what each property means, see "Custom Actions in Outlook Form Regions". |
************
Associating a Form Region with an Outlook Message Class
Introduction
When you create a form region for Microsoft Office Outlook, you must identify the message class names of the Microsoft Office Outlook forms you want to extend. Outlook generates a message class to identify each form in its collection. To associate the form region with the message class, specify these names in the New Form Region wizard or apply attributes to the form region class.
Identifying Message Class Names
Use a form region to extend any of eight standard forms. The following table lists these eight standard forms and their message class names.
Form |
Message Class Name |
Appointment |
IPM.Appointment |
Contact |
IPM.Contact |
Journal |
IPM.Activity |
IPM.Note |
|
Meeting Request / Response |
IPM.Schedule |
Post |
IPM.Post |
RSS |
IPM.Post.RSS |
Task |
IPM.Task |
You can also extend any custom form that you define in Outlook. Identify a custom form just as you identify a standard form, by using its message class name.
Associating a Form Region with an Outlook Message Class Using
the New Form Region Wizard
The final page of the New Form Region wizard lets you to select a standard message class or type the name of a custom message class.
The list of standard message classes is disabled if the form region is designed to replace the whole form or the default page of a form. You can only specify standard message class names for forms that add a new page to a form or append to the bottom of a form. For more information, see "How to: Add a Form Region to an Outlook Project".
You can use the Which custom message classes will display this form region? text box to type the name of one or more custom message classes.
The name(s) that you type must comply with the following guidelines:
· Use the fully qualified message class name (for example: "IPM.Note.Contoso").
· Use semi-colons to separate multiple message class names.
· Do not include standard Outlook message classes, such as "IPM.Note" or "IPM.Contact".
· Do not specify the base message class by itself (for example: "IPM").
· Do not exceed 256 characters for each message class name.
The New Outlook Form Region Wizard validates your input when you click Finish. You will receive an error if the text violates one or more of these guidelines.
Note The New Outlook Form Region Wizard only validates the format of your input. It does not verify that the message class names that you provide are located in Outlook. Therefore, make sure that the message class names that you specify in this text box match valid message class names in Outlook. If they do not match, the form region will not display.
When you complete the wizard, the New Outlook Form Region wizard applies attributes to the form region class that contain the specified message class names. You can also apply these attributes manually.
Associating a Form Region with a Message Class Using Class
Attributes
You can associate a form region with an Outlook message class after you complete the New Form Region wizard. To do this, apply attributes to the form region class.
The following example applies two Microsoft.Office.Tools.Office.MessageClassAttribute attributes to a form region class named myFormRegion. The first attribute associates the form region with a standard message class. The second attribute associates the form region with a custom message class named IPM.Task.Contoso.
[Visual Basic]
<Microsoft.Office.Tools.Outlook.MessageClassAttribute(Microsoft.Office.Tools.Outlook.MessageClassAttribute.Note)> _
<Microsoft.Office.Tools.Outlook.MessageClassAttribute("IPM.Task.Contoso")> _
<Microsoft.Office.Tools.Outlook.FormRegionNameAttribute("Trin_Outlook_FR_Attributes.myFormRegion")> _
Public Class myFormRegion
End Class
[C#]
[Microsoft.Office.Tools.Outlook.MessageClassAttribute(Microsoft.Office.Tools.Outlook.MessageClassAttribute.Note)]
[Microsoft.Office.Tools.Outlook.MessageClassAttribute("IPM.Task.Contoso")]
[Microsoft.Office.Tools.Outlook.FormRegionNameAttribute("Trin_Outlook_FR_Attributes.myFormRegion")]
partial class myFormRegion : Microsoft.Office.Tools.Outlook.FormRegionControl
{
public myFormRegion()
{
InitializeComponent();
}
}
Attributes must comply with the following guidelines:
· For custom message classes, use the fully qualified message class name (for example: "IPM.Note.Contoso").
· Do not specify the base message class by itself (for example: "IPM").
· Do not exceed 256 characters for each message class name.
· Do not include the names of standard message classes if the form region replaces the whole form or the default page of a form. You can only specify standard message class names for forms that add a new page to a form or append to the bottom of a form. For more information, see "How to: Add a Form Region to an Outlook Project".
If attributes violate one or more of these guidelines, you will receive an error when you build the project.
Note Visual Studio Tools for Office Code Name "Orcas" only validates the format of your input. Visual Studio Tools for Office Code Name "Orcas" does not verify that the message class names that you provide are located in Outlook. Therefore, make sure that the message class names that you specify in this text box match valid message class names in Outlook. If they do not match, the form region will not display.