Show TOC

How to Add Custom Tabs to Display User PropertiesLocate this document in the navigation structure

Adding Custom tabs to Outlook application.


In this section let us design the UI to display the phone details of a contact person. This Custom Tab will contain read-only fields.

Example To illustrate this procedure, we use the ContactCollection available in the Contact service and a project called CRMContacts.

In addition, it shows the following:

  • Creating a New Form Region

  • UI Design of the Custom Tab
  • Populating the DataGridView for Phone Details of a Contact
  • Disabling Code for the Form
  • Verifying the Custom Tab

Creating a New Form Region


  1. Create a GWM Outlook Add-in for a Contacts project and generate it as detailed in the Creating and Working with Contact Templatesection.

    The first step is to design the UI to show the phone details of a contact person.

  2. Open the generated project and in the Solution Explorer region, navigate to Start of the navigation path Project Next navigation step Outlook Next navigation step Template End of the navigation path.
  3. Right click on the Template folder and select Start of the navigation path Add New Item End of the navigation path.
    Note The Template folder has the name of the template created when you generated the project.
    The Add New Item window appears. The Outlook Form Region item is added.
  4. Select the new item, and enter the Name as PhoneDetailstab.cs.CustomTabs
  5. Click Add to proceed.
    The New Outlook Form Region window appears.
  6. Ensure the Design a new form region radio button is selected by default.
  7. Choose Next to continue.
    The Select the type of form region you want to create page displays.
  8. Choose Separate.
  9. Click Next.
    The Supply descriptive text and select your display preferences page appears.
  10. Ensure that the Name field remains as PhoneDetailstab.
  11. Choose Next.
    The Identify the message classes that will display this form region page displays.
  12. Select only the Contact(IPM.Contact) checkbox.
  13. Click Finish.
    The PhoneDetailsTab is added to the project. CustomTabsAdded

UI Design of the Custom Tab


  1. Open the Toolbox.
  2. Drag and drop the DataGridView from the Toolbox to the FormRegion.
  3. Right click on the DataGridView and choose Properties to display the Properties region.
  4. Set the following properties for the DataGridview:
    1. Name: <dgvPhoneDetails>
    2. BackgroundColor: <ControlLightLight>
    3. Dock: <Fill>
  5. Right click on the DataGridView and select Add Column.
    The Add Column window appears.
  6. Add two colums with the following names:
    Columns Entries
    Column 1 Name : <FieldName>
      Header text: <FieldName>
    Column 2 Name: <Value>
      Header text: <Value>
    Now, the DataGridView will have two columns added.
  7. Right click on the DataGrid and select Edit Columns.
    The Edit Columns window appears.
  8. Set the AutoSizeMode property of the fields to <Fill> under the Unbound Column Properties region for both columns.
    The UI design for the Custom tab is completed. The next step is to add code to populate DataGridView for PhoneDetails of a Contact

Populating the DataGridView for Phone Details of a Contact


  1. In the Solution Explorer region, navigate to Start of the navigation path Project Next navigation step Outlook Next navigation step Template Next navigation step PhoneDetailsTab.cs End of the navigation path.
  2. Open the PhoneDetailsTab.cs to view the code.
  3. Add the following assembly references at the top:
    using System.Linq;
    using System.Text;
    using Office = Microsoft.Office.Core;
    using Outlook = Microsoft.Office.Interop.Outlook;
    using Microsoft.Office.Interop.Outlook;
    using CRMContacts.Outlook.Common;
    using CRMContacts.Outlook.Common.ExceptionUtility;
    using CRMContacts.Outlook.Common.UIResources;
    using System.Windows.Forms;
    using System.Drawing;
  4. Add the following code in PhoneDetailsTabFactory_FormRegionInitializing method:
    // Occurs before the form region is initialized.
    // To prevent the form region from appearing, set e.Cancel to true.
    // Use e.OutlookItem to get a reference to the current Outlook item.
    private void PhoneDetailsTabFactory_FormRegionInitializing(object sender, Microsoft.Office.Tools.Outlook.FormRegionInitializingEventArgs e)
    Logger.Log(Severity.Verbose, Categories.Outlook_CustomTab,  "PhoneDetailsTabFactory::PhoneDetailsTabFactory_FormRegionInitializing()");
    ContactItem outlookItem = e.OutlookItem as ContactItem;
       UserProperties userProperties = outlookItem.UserProperties;
       string projectName =        (System.IO.Path.GetFileName(System.Reflection.Assembly.GetExecutingAssembly().Location));
       projectName = projectName.Remove(projectName.IndexOf("."));
       if (!OutlookUtilities.IsSAPItem(userProperties) ||         OutlookUtilities.GetApplicationName(userProperties) != "Template1" || OutlookUtilities.EscapeFileName(projectName) != userProperties[Constants.PROJECTNAME].Value)
         e.Cancel = true;
    Logger.Log(Severity.Info, Categories.Outlook_CustomTab, "Enabling Custom Properties  Tab for business application Template1 for outlook item entry Id {0}", outlookItem.EntryID);
    Note The Template1 used in the above code is the name of the add-in specified when creating the project using the GWM Wizard.
  5. Add the LoadCustomFieldsDataGrid method to load the properties required to the DataGridView:
    /// <summary>
    /// This method will load the UserPropertiesTab Region with the custom properties of the item selected
    /// </summary>
    private void LoadCustomFieldsDataGrid()
     Logger.Log(Severity.Verbose, Categories.Outlook_CustomTab,   "PhoneDetailsTabFactory::LoadCustomFieldsDataGrid()");
       UserProperties userProperties = null;
       ContactItem outlookItem = null;
         outlookItem = this.OutlookItem as ContactItem;
         userProperties = outlookItem.UserProperties;
         bool itemCreate = string.IsNullOrEmpty(outlookItem.EntryID);
         this.AddPropertyToDataGrid("MobileCallerNumber", userProperties, itemCreate);
         this.AddPropertyToDataGrid("MobileCountryCode", userProperties, itemCreate);
         this.AddPropertyToDataGrid("MobileNumber", userProperties, itemCreate);
         this.AddPropertyToDataGrid("MobileSequenceNumber", userProperties, itemCreate);
         this.AddPropertyToDataGrid("TelephoneCountryCode", userProperties, itemCreate);
         this.AddPropertyToDataGrid("TelephoneExtension", userProperties, itemCreate);
         this.AddPropertyToDataGrid("TelephoneNumberWithExtension", userProperties, itemCreate);
         this.AddPropertyToDataGrid("TelephoneSequenceNumber", userProperties, itemCreate);
        catch (System.Exception ex)
         if (ExceptionHandler.IsFatalException(ex))
                          ExceptionHandler.ShowMessage(ResourceManager.GetLocalizedText("UserProperties_LoadGrid", Constants.ErrorMessages));
        Logger.Log(Severity.Error, Categories.Outlook_CustomTab, "Error while Loading the grid on the PhoneDetailsTab region");
          Logger.LogException(Severity.Error, Categories.Outlook_CustomTab, ex);
  6. Add the SetDataGridStyleToReadOnly to set the datagrid row to read-only and AddPropertyToDataGrid to populate the datagrid with the properties.
    /// <summary>
    /// This method will set the data grid row style to read only
    /// </summary>
    /// <param name="dataGridCell">datagrid cell whose value is to be set</param>
    /// <param name="dataGridRow">datagrid row being set</param>
    private static void SetDataGridStyleToReadOnly(DataGridViewTextBoxCell dataGridCell, DataGridViewRow dataGridRow)
        dataGridCell.ReadOnly = true;
        dataGridRow.DefaultCellStyle.BackColor = SystemColors.Control;
     /// <summary>
     /// This method will add the property to the data grid
     /// </summary>
     /// <param name="propertyName">property name</param>
     /// <param name="userProperties">user properties name</param>
     /// <param name="isItemCreate">is item create</param>
     private void AddPropertyToDataGrid(string propertyName, UserProperties userProperties,  bool isItemCreate)
    Logger.Log(Severity.Verbose, Categories.Outlook_CustomTab, "PhoneDetailsTabFactory::AddPropertyToDataGrid(propertyName:{0},isItemCreate:{1})", propertyName, isItemCreate);
       DataGridViewRow dataGridRow = null;
       DataGridViewTextBoxCell dataGridCell = null;
       PropertyMetadata propertyMetadata = null;
       UserProperty userProperty = null;
       dataGridRow = new DataGridViewRow();
       dataGridCell = new DataGridViewTextBoxCell();
       if (
          propertyMetadata =[propertyName];
    dataGridCell.Value = (propertyMetadata == null ||   string.IsNullOrEmpty(propertyMetadata.Label)) ? propertyName : propertyMetadata.Label;
        dataGridCell.Tag = propertyName;
        if (propertyMetadata != null && propertyMetadata.Mandatory)
          dataGridCell.Value += "*";
        dataGridCell = new DataGridViewTextBoxCell();
        userProperty = userProperties[OutlookUtilities.GetUserPropertyName(propertyName)];
        if (userProperty != null && userProperty.Value != null)
                    dataGridCell.Value = userProperty.Value;
           SetDataGridStyleToReadOnly(dataGridCell, dataGridRow);

Disabling Code for the Form


  1. In the Solution Explorer region, navigate to Start of the navigation path Project Next navigation step Outlook Next navigation step Template Next navigation step PhoneDetailsTab.Designer.cs End of the navigation path.
  2. In the PhoneDetailsTab.Designer.cs comment the following lines:CustomTabsComment

Verifying the Custom Tab


  1. From the Solution Explorer, navigate to Start of the navigation path Project folder Next navigation step BusinessEntity Next navigation step BusinessConnectivityHelper.cs End of the navigation pathDouble click on the ‘ ’ class which is under the ‘ ’ folder of the project.
  2. Double click the BusinessConnectivityHelper.cs.
  3. Go to HandleSAPConnectivity method and provide the credentials.BusinessConnectivityHelper.cs
  4. Build and Run the project.
  5. In the Outlook ribbon, click on your project name, for example, CRMContacts, tab GetAll button to fetch the Contacts.
    The CRM Contacts should be fetched.
  6. Double click on one of the contacts. and then click on PhoneDetailsTab on the toolbar.
    The Phone related properties will be displayed.