Building User Interfaces with the Information Bridge Framework

  • Article

 

Charles Maxson
OfficeZealot.com

May 2004

Applies to:
     Microsoft® Office Information Bridge Framework
     Microsoft Office Outlook® 2003
     Microsoft Office Word 2003
     Microsoft Office Excel 2003

Summary: The Microsoft Office Information Bridge Framework gives developers powerful programmatic control within the Office task pane. This article looks at customizing the Office task pane and other key aspects of building user interfaces for solutions with the Information Bridge Framework. (14 printed pages)

Note   This article assumes some familiarity with the concepts of the Information Bridge Framework.

Contents

Introduction
Programming the Task Pane the Information Bridge Framework Way
Creating an Information Bridge Framework Region
Designing a Region
Implementing IRegion
Wrapping It up
Conclusion

Introduction

Developers of solutions based on Microsoft® Office are often asked to retrieve data from back-end data sources and present it in a user friendly way inside of Office applications. The challenge for developers is how to present that data after you get it. You could insert it directly into an Office document, but what if the data is there to support the user in creating a document, not because it is a part of the document? How can you present this type of data to a user?

Since the Office task pane was introduced with Microsoft Office XP, it has shown the potential to be a canvas for presenting data to users. The task pane has become the natural accomplice to working with Office documents that appeals to all levels of users. Unlike a bulky custom dialog box that covers a portion of the active document, the task pane sits neatly docked to the side, awaiting a user's command. It provides the ideal dimensions for many data scenarios in which you are trying to give the users insight into information that will help them construct or better understand the document they are looking at. If you could program the task pane, you could create better solutions. It would be even better if it were as easy as making a Microsoft .NET-based Windows® Form!

Enter the Microsoft Office System and the Microsoft Office Information Bridge Framework. The Microsoft Office Information Bridge Framework is a solutions platform for Microsoft Office 2003 Editions, and one of its key aspects is that it enables developers to use the Office task pane for displaying data. Although the Information Bridge Framework is much more than just an enabler of task pane programming, the focus of this article is on building user interfaces for Information Bridge Framework solutions. For more information about the Information Bridge Framework, see Information Bridge Framework on the MSDN Office Developer Center.

Figure 1. The Information Bridge Framework implemented in Microsoft Word

Programming the Task Pane the Information Bridge Framework Way

Before getting into the details of how to use the Information Bridge Framework to program the Office task pane, this section looks at what makes up the core Information Bridge Framework UI and covers what the framework provides out of the box versus what you need to add to it.

The Anatomy of the Information Bridge Framework Task Pane

At first glance, the Information Bridge Framework task pane may look like a mini-application residing inside of an Office application, but it is not a single component. As you can see in Figure 2, the Information Bridge Framework task pane is made up of many elements that serve varying purposes. Many of these elements are automatically provided by the framework offering built-in functionality without any effort on your part. That said, as the developer of an Information Bridge Framework solution, you have some degree of programmatic control over nearly all of these elements, with the exception of the Back and Forward navigation buttons and the Footer section at the bottom of the task pane. The rest is in your hands.

Figure 2. The Elements of the Information Bridge Framework UI

Starting at the top, the Title bar tells users what they are looking at, very much like the caption of an application or a form. Typically, you will provide the type of item or "Entity" that the task pane refers to and the name of the instance of that entity. As shown in Figure 2, the content of the task pane refers to a customer account called "Trey Research". At the right end of the Title Bar, there is a triangular button that invokes the menu for the task pane, which hovers over the UI and appears and disappears like a right-click context-sensitive menu. This menu enables you to add custom menu items to your Information Bridge Framework solution that are displayed along with some of the menu items that are provided for you. The built-in menu items include insert Information Bridge Framework smart tag, insert or copy an Information Bridge Framework smart tag, refresh the task pane, and the obligatory About command. As shown in Figure 2, there is a custom menu that enables the user to view the details for the Account Executive who covers the Trey Research account.

Underneath the Title bar, Information Bridge Framework offers a set of navigation buttons similar to what you would expect to find in a browser application. If you are familiar with the Research Services feature in Office 2003, the Information Bridge Framework navigation buttons function very similarly. These are great for users who need to work their way through lots of data but also need to find their way back. The good news is that Information Bridge Framework manages these buttons for you so the feature is always there, working within your solution.

Underneath the navigation buttons is the focal area of the Information Bridge Framework user interface. It is here where you will present data to the users in what are referred to as Information Bridge Framework "Regions". The task pane can consist of one or multiple regions, and it can contain regions that you create and/or regions that are provided with Information Bridge Framework (which are described in a following section), in addition to regions provided by other developers or third parties. Regions are topped off by their own unique region title bar with both a caption and a plus/minus button so that the user can collapse or expand regions when screen space becomes scarce. Note that you can also control expanded and collapsed state programmatically.

The exciting thing about Information Bridge Framework Regions is that you probably already know how to create them, because the development approach that the Information Bridge Framework uses for regions is purely based on the .NET-based Windows forms programming model. More precisely, an Information Bridge Framework Region is nothing more than a .NET-based user control. So if you know how to create a Windows form, you know how to create an Information Bridge Framework Region. With Information Bridge Framework using .NET-based Windows forms, this means you also get all the benefits of .NET-based tools, such as using Microsoft Visual Studio® .NET as your editor, an abundance of controls to choose from, .NET-based security with managed code, ease of deployment, and so on. Figure 3 shows a before and after view of Information Bridge Framework Regions that display account detail data.

Figure 3. Information Bridge Framework Region in Design Time and Run Time

The remainder of this section describes the rest of the Information Bridge Framework UI. Figure 4 shows the Footer section of the Information Bridge Framework task pane, which serves two main purposes. The first purpose is to provide a navigational feature containing a set of tabs that enables a user to move between the available Information Bridge Framework pages within a solution. These include from left to right, the Search tab, the Reference tab, and the Solution tab.

Figure 4. Information Bridge Framework Task Pane Footer

The second purpose of the Information Bridge Framework Footer is to provide users with a visual indicator whenever Information Bridge Framework is processing a request. If Information Bridge Framework encounters any errors along the way, the Status Indicator turns into an Error icon. The Error icon becomes the launching point for the Information Bridge Framework Error Window (Figure 5), which is a passively populated list of any operational failures that occurred in rendering an Information Bridge Framework request. The Footer cannot be modified to developers, but it does provide a useful source of information in debugging Information Bridge Framework errors.

Figure 5. The Information Bridge Framework Error Window

Creating an Information Bridge Framework Region

Information Bridge Framework Regions are one of the core components that go into making an Information Bridge Framework solution, and serve as the basic building blocks of the user interface. When a user invokes Information Bridge Framework— whether it is through a smart tag, an attached-schema document, or an Information Bridge Framework Search— the result is that one or more regions are rendered in the task pane. Which regions are loaded with what data, and when, is determined from your Information Bridge Framework solution metadata. Metadata is a topic worthy of its own paper and is beyond the scope of this article. This section focuses on how to use Visual Studio .NET to create an Information Bridge Framework Region.

Getting Started

When you create a custom region for use with Information Bridge Framework, you can start by creating a new Visual Studio Windows Control Library project or you can use an existing project. Either way, you need to add project references to two Information Bridge Framework interfaces that will enable you to work with the Information Bridge Framework. The references are to Microsoft.InformationBridge.Framework.Interfaces.dll and Microsoft.InformationBridge.Framework.UI.Interop.dll, which are installed in the global assembly cache (GAC) during an Information Bridge Framework client installation, meaning that you will not need to ship them with your solution. After you have added these references to your project, you must make them accessible to your user control by adding their namespaces your code:

using Microsoft.InformationBridge.Framework.Interfaces;
using Microsoft.InformationBridge.Framework.UI.Interop;

Note   Both Microsoft.InformationBridge.Framework.Interfaces.dll and Microsoft.InformationBridge.Framework.UI.Interop.dll are installed in the global assembly cache (GAC) during the Information Bridge Framework client installation so you do not need to ship them with your solution.

Designing a Region

When you add controls and design the layout of your Information Bridge Framework-enabled user control, the basic rules of .NET-based Windows forms apply. That means you go about adding labels, text boxes, buttons, list boxes, and so on. from the .NET-based Toolbox just as you would in regular Windows form design. There are no technical limits imposed by the framework that you need to worry about. However, as the solution developer, you need to think about the aspects of your design that make logical sense and work "intelligently" within your solution.

Layout

For starters, you need to think about the layout of your control from a size and positioning perspective. Keep in mind that from inside the task pane, you do not have a lot of space to work with and you will want to optimize the way your data is viewed. Note that Information Bridge Framework will respect the height of your region in the task pane, so if you set it to be 240 pixels high, that is the size it will be in the task pane. One important thing to remember is that your region may not be alone in the task pane, so you will want to make sure that you do not command too much space with an overly tall region, leaving little room for others. Try to pick a height that seems practical for the data you need to display and consider using multiple regions if you have a lot of content.

On the other hand, Information Bridge Framework does not manage the width of the task pane— Office and the user do. For that reason, when your user control is rendered in the task pane, the width is essentially ignored. So if you create a region that is set to 400 pixels wide and your controls fill the entire region, you run the risk of having some data not displayed if the task pane is sized smaller within Office. Again, good design says stay conservative in choosing a form width and the layout of your controls. If you really want to make an impressionable region, you can programmatically size and position controls based upon catching the resize event of the user control. This requires a lot more work, but it guarantees that your form always displays its content in the best possible way. Use the Resize event on the user control to catch any task pane changes:

private void MyIBFRegionControl_Resize(object sender, System.EventArgs e)
{
   // Insert code here to manage control location and sizing
}

One more tip managing layout efficiently is to use the Anchor and Dock properties on controls to automatically fill regions. This allows spaces to be filled neatly with minimal effort on your part, although you will still have to manage the user control width.

Selecting Controls

Besides layout and size, you need to choose the types of controls you use. Again, the sky is the limit as far as choices go, but you need to make sure the selections make sense. For instance, if you are only displaying text, do you choose Labels or Text Boxes? Do you opt for rich text? Do you use separate controls for each data field or append multiple items into one larger control? The answers to these and other questions are very much dependent on your solution requirements. For example, if your solution requires the user to provide input, an enabled text box is necessary, but in a read-only case, using only labels would be acceptable. The controls you ultimately choose will have all of the inherent properties and events available to them that they do in any .NET-based Windows form, which gives you a lot of power and a lot of choices.

Implementing IRegion

After you have your user control designed the way you want it, the next step specific to making it an Information Bridge Framework region is to implement the IRegion interface, which is a member of Microsoft.InformationBridge.Framework.Interfaces. It is through IRegion that your user control will be able to get data, styles, and task pane frame information passed to it from Information Bridge Framework. The good news about developing user controls for Information Bridge Framework is that this is the only new information you need to learn, and there is very little to understand.

To begin implementing IRegion, you need to append the IRegion interface reference to the end of your user control class. For example, if your user control was named "MyIBFRegionControl", your class declaration would look like this:

public class MyIBFRegionControl : UserControl, IRegion

IRegion Members

After you add IRegion to your user control, the next step is to add the required property overrides for IRegion. There are four required properties:

  • Data
  • HostProxy
  • HostType
  • VisualStyle

Data Property

The Data property, so named because it is used to set the data returned by the Information Bridge Framework engine, is of an XmlNode data type. It is perhaps the most important of the IRegion members to understand, and it is also quite simple. The first time your control is loaded by the Information Bridge Framework, and each subsequent time Information Bridge Framework processes an operation that results in data being refreshed, the Data property is set with new results in the form of an XML document fragment. The following code represents the Data property:

public XmlNode Data
{
   set
   {
      XmlNode dataNode = value;
      //Call the LoadXmlData routine to insert data in UI controls
      LoadXmlData(dataNode);
   }
}

As the control developer, you need to process the XmlNode to extract the data being used and then place it in the corresponding controls. You could do this directly inside the property, but as shown in the preceding code example, the code passes the XmlNode to another routine called LoadXmlData. The following code example shows what LoadXmlData might look like:

private void LoadXmlData(XmlNode myData)
{
   textBoxCustomer.Text = (null == myData["CustomerName"])
      ? string.Empty : myData["CustomerName"].InnerText;
   textBoxAddress.Text = (null == myData["CustomerAddress"])
      ? string.Empty : myData["CustomerAddress"].InnerText;
   textBoxPhone.Text = (null == myData["CustomerPhone"]) ? string.Empty :
      myData["CustomerPhone"].InnerText;
}

The routine LoadXmlData extracts values from the XmlNode (passed in as myData) and sets them as the Text property on the appropriate text boxes. You can see that first the code checks to makes sure that the data node exists to avoid errors. Of course, this is normal Windows form development, so you would want to add your own error handling in real practice.

The contents and shape of the data in the XmlNode is set when you create your solution metadata. You can of course make changes or provide additional processing of the data inside the user control, but ideally your solution should only be handing off data that is ready to use. That means you should use the Information Bridge Framework engine to transform data so that your control receives only the exact data needed to be drawn. This will optimize performance and simplify user control development because you will not be paging through large amounts of unnecessary data and nodes. Another tip in region development is to clone the data and keep it in a class-level variable. That will make it possible to restore the original data or compare it with the existing values within your region at run time. This will enable you to deal with changes to Data that occur when your region is active.

The Other Members

The remaining members of IRegion, although still required like Data, may not actually be referenced in every region you create. They provide advanced features that can be ignored in simple regions. However, if you want to execute Information Bridge Framework commands, interoperate with the Office application or document, or change control styles based upon user settings, you will also need to interact with these members.

HostProxy enables you to get a reference to the object that serves as your regions parent; specifically the Information Bridge Framework task pane, which is an IRegionFrame object. You need access to the frame object if you want to perform any actions such as executing an Information Bridge Framework command or adding a region menu. The following code initializes HostProxy:

public IRegionFrameProxy HostProxy
{
   set
   {
      this._frameProxy = value;
   }
   get 
   {
      return this._frameProxy;
   }
}

When you have a HostProxy reference, you use its Host property to return its IRegionFrame object. IRegionFrame essentially acts like the "Application object" of the Information Bridge Framework solution, and it is the jumping off point for access to several other objects, including Mediator and RegionMenu. For example, if you wanted to add a region menu in your solution from code, you would do so by using HostProxy to get the Host in order to access the RegionMenu object:

MenuItem menuItemAbout = HostProxy.Host.RegionMenu.AddMenuItem ("About...", new EventHandler(DisplayAbout));

The Mediator is an important object that serves as a proxy between an Information Bridge Framework region and the rest of the environment, including both the Information Bridge Framework engine and the Office application that the solution is currently running in. With the Mediator object, you can execute Information Bridge Framework commands directly against the engine. For example, if you want to have a command button or a hyperlink control on your region that navigates to a different reference in your Information Bridge Framework solution, you would use a Mediator along with its CreateLocalCommand method to execute a command against the Information Bridge Framework engine. Another common use for the Mediator is to programmatically access the Word or Excel application object models. Whether your solution scenario calls for reading data from an Office document, writing data to an Office document, creating a new document, or starting some other Office-based process, you will need to go through the Mediator. For example, the following code returns access to the Word Application object from the region executing the code. In this instance, the Mediator is used to get an IApplicationService object, which is another member of the Information Bridge Framework interfaces. The IApplicationService returns a reference to the Office application that is currently hosting the Information Bridge Framework. However, in this sample, if the active application is not Microsoft Word, the code automatically creates a new version of Word to use. After you have the Word Application object, you can start programming against it just like you normally would, adding documents, inserting text, extracting data, and so on.

IMediator mediator = HostProxy.Host.Mediator;

Word.ApplicationClass wordApplication = null;
System.Type ias = typeof(IApplicationService);
IApplicationService iasApp = (IApplicationService)mediator.GetService(ias);
System.Object iasType = iasApp;

// Get the Word Application object if running in Word
if (iasType.ToString()== "[Microsoft.InformationBridge.Framework.Interop.Office.WordApplicationService]")
{
   wordApplication = (Word.ApplicationClass)iasApp.Application;
}
else
// Create a new Word Application if running in Outlook or Excel
{
   wordApplication = new Word.ApplicationClass();
}

HostType is a member of IRegion that has a relatively simple use. Its purpose is to inform you if your region is currently being hosted in the task pane or in a dialog box. This article has thus far only discussed regions being hosted in the task pane. Although that is the primary focus of Information Bridge Framework regions, Information Bridge Framework also allows regions to be shown in modal dialog boxes that are displayed on top of the Office applications, hosted in a regular Windows form with a border and Close button. This can be very useful, for example when your data is too large to neatly fit inside of a task pane region, or when you want to display a dialog box that demands a user complete a task that happens before the dialog can be dismissed.

Ultimately, regions have no control over how they are hosted; this is driven exclusively from the metadata. The solution developer can display a region with either a ShowRegion or ShowDialog operation from the metadata. After you, the region developer, create the region as described earlier in this article, it can be shown in either way without any special design considerations. You would use HostType to determine where the region is being hosted at run time, then you could conditionally control aspects of the region based on its hosted location. For example, if your region was being hosted in a dialog box, you might want to change the position of your controls so that it is laid out in a way that takes advantage of more abundant screen space. But, if the same control was being hosted in the task pane, you may want to lay out and size your controls to fit accordingly within the smaller confines. Here is a common implementation of HostType:

public FrameType HostType
{
   set
   {
      this._hostType = value;
   }
}

The final member of IRegion described here is VisualStyle. You should use VisualStyle if you are interested in creating a highly polished solution that adapts to a user's Windows style settings. This is not required, but it gives your region a personal, professional touch that some users will appreciate. When you set up VisualStyle, you should store the property in a class variable, in addition to on its Set. You should first set the styles for your region and introduce an event to capture style changes while your region is drawn, so it can be updated when changes are made. The following is an example of how to implement VisualStyle accompanied by a routine called SetStyles that demonstrates how you can update a region's control to reflect the current style settings.

public IVisualStyles VisualStyle
{
   set 
   {
      if (null != value) 
      {
         this._visualStyles = value;
         SetStyles(null, null);
         this._visualStyles.UserPreferencesChanged += new
            Microsoft.Win32.UserPreferenceChangedEventHandler
            (this.SetStyles);
      }
   }
   get
   {
      return this._visualStyles;
   }
}

private void SetStyles(object sender,
   Microsoft.Win32.UserPreferenceChangedEventArgs e) 
{
   if (null != this._visualStyles) 
   {
      //   Set back colors...
      Color newBackColor =
         this._visualStyles.GetColor(Colors.RegionBackColor);
      Color newForeColor =
         this._visualStyles.GetColor(Colors.RegionHeaderText);
      System.Drawing.Font newBoldFont =
         this._visualStyles.GetFont(Fonts.DefaultFontBold);
      System.Drawing.Font newFont =
         this._visualStyles.GetFont(Fonts.DefaultFont);
      this.BackColor = newBackColor;
      foreach (Control c in this.Controls) 
      {
         //   Set the back color...
         c.BackColor = newBackColor;
         c.ForeColor = newForeColor;

         if (c.GetType() == typeof(Label)) 
         {
            c.Font = newBoldFont;
         }
      }
   }
}

Wrapping It up

After your Information Bridge Framework-enabled region has been designed and the necessary controls and logic are in place, but the only thing left to do is compile your project as a .dll file and let your Information Bridge Framework solution know how and when to call it. That aspect is another feature of designing the Information Bridge Framework solution metadata, and the details of how to do this are not covered in this article. For more information about this, see the Microsoft Office Information Bridge Framework product documentation. If you do not want to wait to test your region using a live metadata solution, there is a test tool (IWBUITest.exe) that will soon be available to enable you to do this. (The exact details of this tool were not available at the time of this writing, but for more information, see Information Bridge Framework on the MSDN Office Developer Center.) Note also that the region developer is responsible for digitally signing your assembly and implementing the necessary .NET-based security trust policies.

Conclusion

The Microsoft Office Information Bridge Framework makes programming the Office task pane not only easy but also very powerful. The Information Bridge Framework task pane provides a rich user interface that you can extend by creating your own custom regions. Information Bridge Framework Regions, which are.NET-based user controls that implement the Information Bridge Framework IRegion interface, can contain common controls of many types, execute actions within or outside the context of an Information Bridge Framework solution, and enable solution developers to program the Office task pane through the familiar Windows form-based programming model. With Microsoft Office Information Bridge Framework, you can program the Office task pane with your data.

About the Author

Charles Maxson specializes in designing and developing smart client solutions featuring the Microsoft Office System. He is one of the resident zealots at OfficeZealot.com.