Show TOC

How to Create a Custom Task PaneLocate this document in the navigation structure

Designing the UI for Custom Task Pane.

Designing the UI for Custom Task Pane

Context

In this section, we will create a custom task pane to EPM Accounts.

Example To illustrate this procedure, let us use the ContactCollection available in the Contact service.

Procedure

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

    The first step is to design the UI for the task pane.

  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 EPMAccounts End of the navigation path.
  3. Right click on EPM Accounts and selectStart of the navigation path  Add  Next navigation step New Item End of the navigation path.
    Note Template folder has the name of the Template provided during the project generation in the wizard.
    The Add New Item window appears. The Outlook Form Region item is added.
  4. Select the new item, and enter the Name as EPMAccountDetailsUserControl.cs.
  5. Click Add to proceed.
    The Microsoft Visual Studio will create an empty UI and the associated designer and the code behind the class for the user control, and will open up the class in the designer mode.
  6. Click on the Toolbox and the Properties buttons from the toolbar to display the toolbox and properties region.
  7. Do the following in the Properties view:
    1. Set the Margin of the user control to 0,0,0,0
    2. Set the Size of the control to 300,500
  8. From Toolbox, expand Containers.
  9. Select TableLayoutPanel, drag and drop it onto the user control.
  10. Do the following customizations for the TableLayoutPanel in the Properties view:
    1. Set the Name of the panel to pnlMain.
    2. Set the Margin to 0;0;0;0.
    3. Set Dock to Fill.
  11. In the Properties view, navigate to Start of the navigation path Collection Next navigation step Rows End of the navigation pathset the columns and rows for the TableLayoutPanel.
  12. Click on drop-down button located in the row adjacent to Rows.
    The Column and Rows Styles window appears.
  13. Do the following in the Column and Rows Styles window:
    1. Click Add to add three more rows to the TableLayoutPanel.
      Three rows now added to the existing two rows.
    2. Select the rows 1, 2 and 3 individually and under Size Type choose the Absolute radio button and set the value to 30.
    3. Select the rows 4 and 5 individually and under Size Type choose the Percent radio button, and set the value to 50%.
    4. Clilck OK to confirm.Column and Row Styles
  14. From the Toolbox, expand Common Controls.
  15. Select Label under Common Controls, drag and drop it to the first row of the panel.
  16. Set the following properties for the label:
    1. Set the Text to lblContactName
    2. Set the Cell to 0;0
    3. Set the Margin to 0;0;0;0
    4. Set the Columnspan to 2
    5. Set the Dock to Fill
    6. Set the Font to Microsoft Sans Serif; 18pt
    7. Set the AutoEllipsis to True
  17. From the Toolbox, expand Common Controls.
  18. Select Label under Common Controls again, drag and drop it to the second row of the first column in the cell.
  19. Set the following properties for the label:
    1. Set the Name to Customer ID.
    2. Set the Cell to 0;1.
    3. Set the Margin to 12;12;0;0.
    4. Set the Font to Microsoft Sans Serif; 9pt.
  20. Copy and paste the row created in the step 18 to the third row of the first column
    1. Set the Cell to 0;2.
    2. Set the Name to Country.

Now let us add the labels to hold the values of the above defined properties.

  1. Copy the label Customer ID that was created in the step 18 to the second row of the second column.
    1. Set the Name to lblCustomerID.
    2. Set the Cell to 1;1.
    3. Set the Margin to 12;12;12;0.
    4. Set the Font to Microsoft Sans Serif; 9pt.
    5. Set the AutoEllipsis to True
    6. Set the Dock to Fill
    7. Leave the Text field empty.
  2. Repeat the step 20 to add the label for setting the country code and change the following properties:
    1. Set the Name to lblCountryName.
    2. Set the Cell to 1;2.
      The basic design for the contact custom task pane is done.

      CustomTaskPane

Binding the UI with SAP Data

Context

In the previous section we created a UI to hold the Custom Tabs. In this section let us bind this UI with SAP Data.

Procedure

  1. Open the Solution Explorer and expand Start of the navigation path EPM Accounts  Next navigation step Outlook Next navigation step Contacts Next navigation step EPM Accounts Next navigation step EPMAccountDetailsUserControl.cs End of the navigation path.
    Note The folder name EPM Accounts may vary depending on the application name provided during GWM Outlook project creation.
  2. Right click EPMAccountDetailsUserControl.cs and select View Code in the shortcut menu, or double click on the class to open it in the designer.
  3. Insert the below mentioned method to set the property text for customer id and countryname set in the previous section.
    /// <summary>
            /// this method will set the country text, customer id and the contact name fields of the ui
            /// </summary>
            /// <param name="contactname">selected contact name</param>
            /// <param name="customerid">selected contact id</param>
            /// <param name="countrytext">selected contact country</param>
            internal void SetOIDRegion(string contactname, string customerid, string countrytext)
            {
                this.lblContactName.Text = contactname;
                this.lblCustomerID.Text = customerid;
                this.lblCountryName.Text = countrytext;
            }
    

Adding the User Control to the Contacts Task Pane

Procedure
  1. Open the Solution Explorer and expand Start of the navigation path EPM Accounts  Next navigation step Outlook Next navigation step Contacts Next navigation step EPM Accounts Next navigation step ContactInspectorWrapper.cs End of the navigation path.
    Note The folder name EPM Accounts may vary depending on the application name provided during GWM Outlook project creation.
  2. In the ContactInspectorWrapper class, first declare the taskpane variable required to initialize the custom taskpane using the below mentioned code:
    private Microsoft.Office.Tools.CustomTaskPane taskPane;
  3. Add the method “Initialize” in the ContactInspectorWrapper class as shown below.
    /// <summary>
    /// Method is called when the wrapper has been initialized.
    /// </summary>
    protected void initialize()
    {
    
    }
  4. Initialize the task pane in the Initialize method with the UI control created in section Designing the UI for Custom Task Pane and then bind it to the contact inspector view. The following code can be used:
            /// <summary>
            /// Method is called when the wrapper has been initialized.
            /// </summary>
            protected void Initialize()
            {
                Microsoft.Office.Interop.Outlook.UserProperties userProperties = null;
                try
                {
                    Logger.Log(Severity.Verbose, Categories.Outlook_StarterKit, "Entering Initialize");
    
                    outlookItem = (ContactItem)Inspector.CurrentItem;
                    outlookItem.Write += new ItemEvents_10_WriteEventHandler(ItemWrite);
                    taskPane = Globals.ThisAddIn.CustomTaskPanes.Add(new EPM_Accounts.Outlook.Contact.EPMAccounts.EPMAccountDetailsUserControl(), "EPM Accounts", this.Inspector);
                    taskPane.Width = 350;
    
                    userProperties = outlookItem.UserProperties;
                    string businessApplicationName = OutlookUtilities.GetApplicationName(userProperties);
                    BusinessApplicationFactory.GetBusinessApplication(businessApplicationName).SetTaskPane(taskPane, outlookItem);
                }
                catch (System.Exception ex)
                {
                    Logger.Log(Severity.Verbose, Categories.Outlook_StarterKit, "Failed to set the task pane");
                }
                finally
                {
                    Logger.Log(Severity.Verbose, Categories.Outlook_StarterKit, "Leaving Initialize");
                    OutlookUtilities.CleanUpResources(userProperties);
                }
            }
    
  5. Add the call Initialize method created above in the ContactInspectorWrapper constructor method.
    /// <summary>
            /// Constructor for ContactItemWrapper class
            /// </summary>
            /// <param name="inspector">The Outlook Inspector instance that is to be handled.</param>
            public ContactInspectorWrapper(Inspector inspector): base(inspector)
            {
                Initialize();
    			outlookItem = (ContactItem)Inspector.CurrentItem;
    			string businessApplicationName = OutlookUtilities.GetApplicationName(outlookItem.UserProperties);
    			if (OutlookUtilities.GetOutlookButton(businessApplicationName) != "selected")
                {
    				outlookItem.Write += new ItemEvents_10_WriteEventHandler(ItemWrite);
    			}
    			else
    			{
    			   MessageBox.Show(ResourceManager.GetLocalizedText("Update_GetAll_InProgress", Constants.ErrorMessages), ResourceManager.GetLocalizedText("MessageBoxTitleInformation", Constants.UIDialog), MessageBoxButtons.OK, MessageBoxIcon.Information);
    			}
            }
    

The task pane created should be closed during the closing of the inspector view.

  1. Search for the method protected override void Close and then use the following code to remove the task pane during inspector close.
    if (taskPane != null)
                {
                    Globals.ThisAddIn.CustomTaskPanes.Remove(taskPane);
                }
                taskPane = null;
    

Populating the CustomTask Pane with Contacts Data

Procedure

  1. Open the Solution Explorer and expand Start of the navigation path EPM Accounts  Next navigation step Outlook Next navigation step Contacts Next navigation step EPM Accounts Next navigation step EPMAccountsBusinessApplication.cs End of the navigation path.
    Note The folder name EPM Accounts may vary depending on the application name provided during GWM Outlook project creation.
  2. Search for the method SetTaskPane.
  3. The SetTaskPane method we will read the values for the contact name from the standard contact item fields and the values for the customerid and country from the custom properties using the code provided below:
    /// <summary>
            /// This method can be implemented to provide the display outlook data or business application data in the custom task pane for BusinessPartner
            /// </summary>
            /// <param name="taskPane">Custom Task Pane</param>
            /// <param name="outlookItem">current selected item (ContactItem/TaskItem/AppointmentItem)</param>
            internal override void SetTaskPane(Microsoft.Office.Tools.CustomTaskPane taskPane, object selectOutlookItem)
            {
                UserProperties userProperties = null;
                UserProperty userProperty = null;
                try
                {
                    Logger.Log(Severity.Error, Categories.Outlook_Update, "Entering Set Task Pane");
                    EPMAccountDetailsUserControl accountTaskPane = taskPane.Control as EPMAccountDetailsUserControl;
                    if (accountTaskPane != null)
                    {
                        ContactItem outlookItem = selectOutlookItem as ContactItem;
                        userProperties = outlookItem.UserProperties;
    
                        string countryName = "";
                        string customerid = "";
    
                        userProperty = userProperties[OutlookUtilities.GetUserPropertyName("Address.CountryText")];
                        if (userProperty != null)
                        {
                            if (!string.IsNullOrEmpty(userProperty.Value))
                            {
                                countryName = userProperty.Value;
                            }
                            OutlookUtilities.CleanUpResources(userProperty);
                        }
                        userProperty = userProperties[OutlookUtilities.GetUserPropertyName("BusinessPartnerID")];
                        if (userProperty != null)
                        {
                            if (!string.IsNullOrEmpty(userProperty.Value))
                            {
                                customerid = userProperty.Value;
                            }
                            OutlookUtilities.CleanUpResources(userProperty);
                        }
                        accountTaskPane.SetOIDRegion(outlookItem.FullName, customerid, countryName);
                        taskPane.Visible = true;
    
                    }
    
                }
                catch (System.Exception ex)
                {
                    Logger.Log(Severity.Error, Categories.Outlook_Update, "An exception occured while performing operation in SetTaskPane");
                }
                finally
                {
                    Logger.Log(Severity.Error, Categories.Outlook_Update, "Leaving Set Task Pane");
                    OutlookUtilities.CleanUpResources(userProperties);
                    OutlookUtilities.CleanUpResources(userProperty);
                }
    
            }
    

Verifying in Outlook

Context

Note Perform this step on a system where Microsoft Office Outlook Professional edition is installed.

Procedure

  1. Build and run the Microsoft Outlook project to launch the Microsoft Outlook.
  2. Navigate to the Contacts folder and select any existing EPM Accounts, and the contact will be loaded with the custom task pane
  3. Double click on the EPM Accounts to open the contact.
    The contact will be loaded with the Custom Task Pane.