Exercise 3: Outlook Form Regions

In this exercise you will use an Outlook Form Region to extend the Task form in Outlook. The extensions will allow tracking of billable tasks within Outlook’s storage location.

Task 1 – Creating a Form Region

In this first task, you will create a new Outlook Form Region attached to the existing Task forms in Outlook.

1. Create new Outlook 2010 add-in project
   1. Open VisualStudio 2010 and select File -> New -> Project
   2. In the New Project dialog select the Visual C#(in case of C#)/ Visual Basic(in case of VB) -> Office -> 2010 templates
   3. Choose an Outlook 2010 Add-in template
   4. Set the Name of the project to OutlookFormRegion and set the location to %Office2010DeveloperTrainingKitPath%\Labs\OfficeUI\Source\[language]\Starter
   5. Verify Create directory for solution is unchecked and click OK to create the new project

      

      Figure 7(a)-In case of C#

      

      Figure 7(b)- In case of VB

      New Outlook 2010 Addin Project

2. Add a new form region named BillableTaskRegion to the Task form
   1. Right click on OutlookFormRegion in the Solution Explorer and click Add -> New Item
   2. In the Add New Item dialog choose the Visual C#(in case of C#)/ Visual Basic(in case of VB) -> Office templates
   3. Choose OutlookFormRegion and name it BillableTaskRegion.vb(in case of VB) & BillableTaskRegion.cs(in case of C#)
   4. Click Add to create the new item
   5. In the first page of the New Outlook Form Region wizard, choose Design a new form region and click Next
   6. In the next page, select Adjoining and click Next

      

      Figure 8

      Choose Form Region Type

   7. Change the name to Billable Task and click Next
   8. Choose the Task option and clear all other check boxes then click Finish

      

      Figure 9

      Choose Form Region Class

      Note:

      The message classes chosen determine which types of items receive the new form region. In this case you will be extending the IPM.Task message class only

Task 2 – Implement the Form Region

1. In this second task, you will add controls to the form and implement the code behind necessary to make the form region functional.
2. Add the controls to the form region to create the Billable Task extensions

   

   Figure 10

   Completed Custom Form Region

   1. Open the designer for BillableTaskRegion.vb(in case of VB) & BillableTaskRegion.cs(in case of C#) by right clicking it in the Solution Explorer and clicking View Designer
   2. Right click the design surface and click Properties
   3. In the Properties window, set the size of the canvas to 486, 150
   4. Using the toolbox, drag the following controls onto the canvas
      1. 1 CheckBox
      2. 1 ComboBox
      3. 1 NumericUpDown
      4. 1 TextBox
      5. 2 Labels
   5. Set the following properties on the CheckBox controls
      1. (Name) & Text – chkBillable & Billable
      2. Location & Size – 6, 6 & 59, 17
   6. Set the following properties on one of the Label controls
      1. Text –Customer
      2. Location & Size – 87, 7 & 51, 13
   7. Set the following properties on the ComboBox control
      1. (Name) – lstCustomer
      2. Location & Size – 143, 4 & 167, 21
      3. Items – Fabrikam Inc., Adventure Works
         Note:

         Enter each company on its own line

   8. Set the following properties on the remaining Label control
      1. Text –Hours
      2. Location & Size – 347, 7 & 35, 13
   9. Set the following properties on the NumericUpDown control
      1. (Name) – numHours
      2. Location & Size – 386, 4 & 95, 20
   10. Set the following properties on the TextBox control
       1. (Name) - txtDetails
       2. Multiline - true
       3. Location & Size – 5, 31 & 476, 116
       4. Anchor – Top, Bottom, Left, Right
3. Add the code behind that will implement the functionality of the form
   1. Open the code behind for BillableTaskRegion.vb(in case of VB) & BillableTaskRegion.cs(in case of C#) by right clicking it in the Solution Explorer and clicking View Code
   2. Add the following properties to the BillableTaskRegion class

      C#

      private Outlook.TaskItem m_taskItem;
      private Outlook.ItemProperty m_isBillable;
      private Outlook.ItemProperty m_customer;
      private Outlook.ItemProperty m_hours;
      private Outlook.ItemProperty m_details;

      Visual Basic

      Private m_taskItem As Outlook.TaskItem
      Private m_isBillable As Outlook.ItemProperty
      Private m_customer As Outlook.ItemProperty
      Private m_hours As Outlook.ItemProperty
      Private m_details As Outlook.ItemProperty

   3. Add the EnsureItemProperty method to aid in creating custom properties on the task

      C#

      private void EnsureItemProperty(
          ref Outlook.ItemProperty property, string name,     
          Outlook.OlUserPropertyType propertyType)
      {
          if (property == null)
          {
              property = m_taskItem.ItemProperties[name];
              if (property == null)
                  property = 
                      m_taskItem.ItemProperties.Add(name, propertyType);
          }
      }

      Visual Basic

      Private Sub EnsureItemProperty(ByRef [property] As Outlook.ItemProperty, ByVal name As String, ByVal propertyType As Outlook.OlUserPropertyType)
      If [property] Is Nothing Then
      [property] = m_taskItem.ItemProperties(name)
      If [property] Is Nothing Then
      [property] = m_taskItem.ItemProperties.Add(name, propertyType)
      End If
      End If
      End Sub

   4. Add the EnsureProperties method to verify all of the custom task properties exists

      C#

      private void EnsureProperties()
      {
          EnsureItemProperty(ref m_isBillable, "Billable", 
              Outlook.OlUserPropertyType.olYesNo);
          EnsureItemProperty(ref m_customer, "Billable Customer", 
              Outlook.OlUserPropertyType.olText);
          EnsureItemProperty(ref m_hours, "Billable Hours", 
              Outlook.OlUserPropertyType.olNumber);
          EnsureItemProperty(ref m_details, "Billing Details", 
              Outlook.OlUserPropertyType.olText);
      }

      Visual Basic

      Private Sub EnsureProperties()
      EnsureItemProperty(m_isBillable, "Billable", Outlook.OlUserPropertyType.olYesNo)
      EnsureItemProperty(m_customer, "Billable Customer", Outlook.OlUserPropertyType.olText)
      EnsureItemProperty(m_hours, "Billable Hours", Outlook.OlUserPropertyType.olNumber)
      EnsureItemProperty(m_details, "Billing Details", Outlook.OlUserPropertyType.olText)
      End Sub

   5. Add UpdateEnableState to update the state of the controls based on the state of the Billable checkbox

      C#

      public void UpdateEnableState()
      {
          lstCustomer.Enabled = chkBillable.Checked;
          numHours.Enabled = chkBillable.Checked;
          txtDetails.Enabled = chkBillable.Checked;
      }

      Visual Basic

      Public Sub UpdateEnableState()
      lstCustomer.Enabled = chkBillable.Checked
      numHours.Enabled = chkBillable.Checked
      txtDetails.Enabled = chkBillable.Checked
      End Sub

   6. Implement FormRegionShowing to load the current property values into the controls and setup the initial state of the form region

      C#

      m_taskItem = this.OutlookItem as Outlook.TaskItem;
      
      EnsureProperties();
      chkBillable.Checked = m_isBillable.Value;
      UpdateEnableState();
      
      lstCustomer.SelectedText = m_customer.Value;
      numHours.Value = (decimal)m_hours.Value;
      txtDetails.Text = m_details.Value;

      Visual Basic

      m_taskItem = TryCast(Me.OutlookItem, Outlook.TaskItem)
      
      EnsureProperties()
      chkBillable.Checked = m_isBillable.Value
      UpdateEnableState()
      
      lstCustomer.SelectedText = m_customer.Value
      numHours.Value = CDec(m_hours.Value)
      txtDetails.Text = m_details.Value

4. Add code behind that will write the contents of the controls as they change
   1. Create a method named chkBillable_CheckedChanged to handle the Billable check box’s checked event

      C#

      private void chkBillable_CheckedChanged(object sender, EventArgs e)
      {
          m_isBillable.Value = chkBillable.Checked;
          UpdateEnableState();
      }     

      Visual Basic

      Private Sub chkBillable_CheckedChanged(ByVal sender As Object, ByVal e As EventArgs)
      m_isBillable.Value = chkBillable.Checked
      UpdateEnableState()
      End Sub

   2. Create a method named lstCustomer_TextChanged to handle the Customer drop down control’s changed event

      C#

      private void lstCustomer_TextChanged(object sender, EventArgs e)
      {
          m_customer.Value = lstCustomer.Text;
      }     

      Visual Basic

      Private Sub lstCustomer_TextChanged(ByVal sender As Object, ByVal e As EventArgs)
      m_customer.Value = lstCustomer.Text
      End Sub

   3. Create a method named numHours_ValueChanged to handle changes in the Hours control

      C#

      private void numHours_ValueChanged(object sender, EventArgs e)
      {
          m_hours.Value = (double)numHours.Value;
      }

      Visual Basic

      Private Sub numHours_ValueChanged(ByVal sender As Object, ByVal e As EventArgs)
      m_hours.Value = CDbl(numHours.Value)
      End Sub

   4. Create a method named txtDetails_TextChanged to handle changes to the Details control

      C#

      private void txtDetails_TextChanged(object sender, EventArgs e)
      {
          m_details.Value = txtDetails.Text;
      }

      Visual Basic

      Private Sub txtDetails_TextChanged(ByVal sender As Object, ByVal e As EventArgs)
      m_details.Value = txtDetails.Text
      End Sub

5. Connect the code behind to the controls using the designer
   1. Open the designer for BillableTaskRegion.vb(in case of VB) & BillableTaskRegion.cs(in case of C#) by right clicking it in the Solution Explorer and clicking View Designer
   2. Right click the Billable check box control and click Properties
   3. In the Properties window, click the Event icon (the lightning bolt)
   4. Set the CheckedChanged event to chkBillable_CheckedChanged using the drop down list

      

      Figure 11

      Control Events

   5. Repeat the above process to attach the Customer control’s TextChanged event to the lstCustomer_TextChanged method
   6. Repeat the above process to attach the Hours control’s ValueChanged event to the numHours_ValueChanged method
   7. Repeat the above process to attach the Details control’s TextChanged event to the txtDetails_TextChanged method

Exercise 3 Verification

In order to verify that you have correctly performed all steps in the above exercise, proceed as follows:

Test the Add-in

Test your add-in to confirm that the export ribbon and backstage buttons work as expected.

1. Run the add-in and verify the enable checkboxes work
   1. In the Debug menu, click Start Without Debugging
   2. Once Outlook 2010 loads, switch to the Home ribbon tab
   3. Click the New Items -> Task option to create a new task
   4. Verify the Billable Task form region is visible

      

      Figure 12

      Custom Task Form Region

   5. Enter some data into the new task and save it
   6. Switch to the Tasks section using the buttons in the lower left and open the task you just created.
   7. Verify the information in the Billable Task region is loading correctly
2. When you are done cleanup and remove the add-in
   1. Close Word 2010
   2. In the Solution Explorer, right click OutlookFormRegion and click Clean