Developing Microsoft Office extension on RO Chrome.
Create custom toolbars, ribbons, task panes.
Add-in Express™
|
|
Outlook 2000+
|
FrontPage 2000+
|
Getting started
This page presumes that you installed Visual Studio 2005 and Chrome 1.5 for Visual Studio using the default General Development settings. So, when we refer to Chrome and Add-in Express, we are referring to Chrome 1.5.5 and Add-in Express 3.4. We run Visual Studio 2005 and Office 2007 with all latest updates installed on Windows Vista Business. However, you can use Windows 2000 and Windows XP as well as Visual Studio 2003, Office 2000 – 2003 and any higher versions of RO Chrome and Add-in Express.
Below you will find a step-by-step instruction on developing an Outlook COM add-in using Chrome and Add-in Express. It illustrates the important concepts of using RO Chrome together with Add-in Express. Please note, you will not find much of Chrome code here, but rather a lot of screenshots; the main goal of this page is to highlight all Add-in Express RAD capabilities and its concepts. Remember, we assume that you have some experience in Office development and the Office object model.
Starting a new solution
To start a new solution, run the Visual Studio IDE, select File\New\Project, and click on the Other Project Types\Extensibility\ADX COM Add-ins project template. This runs the New COM Add-in wizard that creates a new solution based on Add-in Express.
The first window of the wizard asks you to select the programming language, the isolation and setup project.
Select Chrome Project and click Next. The second window prompts you to select target applications and Office interop assemblies for your extension. Select the application and interop assemblies you need and click Finish. A new solution is created.
The concept of compatibility, version-neutrality and Office interop assemblies
The Add-in Express core is designed to be compatible with all Office applications, versions and suites. You can develop one solution for one, several or all Office applications installed on your development PC by checking corresponding check boxes.
For .NET, Add-in Express provides access to Office objects via Office interop assemblies, the imported Office type libraries provided by Microsoft (primary interop assemblies, PIAs) or custom type libraries offered by Add-in Express. Note, the primary interop assemblies from Microsoft are not version-neutral and support Office 2002, 2003 and 2007 separately.
If you have to develop a solution compatible with several Office versions, you can use the version-neutral interop assemblies delivered by Add-in Express. Just check the Use Version-neutral Office PIAs check box. It gives you access to Office objects via the Office 2000 object model but you can stay with version-specific features through the late binding. It is a very effective technique to support several Office versions. In any case, remember that the Add-in Express core is version-neutral, so you may or may not use version-neutral interop assemblies.
The inside of your Office solution
By default, every Office solution based on Add-in Express includes two projects: the main extension project and a setup project. The first project is your extension itself, the second one you use to deploy the extension. Both projects include all necessary references and dependencies.
Security and deployment
Every solution based on Add-in Express templates is secure and deployable. Firstly, Add-in Express isolates your solution in its own AppDomain by a custom shim, the Loader, included in the setup project. The loader gives you the capability to update your solution on the fly which makes deployment and redeployment very comfortable for your administrators. Secondly, the loader supports the strict Office security model, so your Office add-ins run under the High Security setting. See also Deploying Office solutions.
RAD modules
Each of your solutions includes a special RAD module (AddinModule.pas in this example), the "heart" of your project. It is an analog of the Data Module in CodeGear Delphi that has its own visual designer. You concentrate your development around this module since it is a container for all Office-specific components and it provides "access points" for handling Office objects. Thus, the RAD module is the place where your write your applied code.
In this example, the AddinModule class uses all necessary namespaces including AddinExpress.MSO; it is a descendant of ADXAddinModule; it implements several methods and properties (see the listing below; some insignificant code pieces are skipped).
namespace MyFirstOutlookAddin;
interface
uses
AddinExpress.MSO;
type
[GuidAttribute( _
'6B9D2084-1414-4054-ADBD-26840BCE3DD6'), _
ProgId('MyFirstOutlookAddin.AddinModule')]
AddinModule = public class(AddinExpress.MSO.ADXAddinModule)
public
constructor;
[ComRegisterFunctionAttribute]
class procedure AddinRegister(t: System.Type);
[ComUnregisterFunctionAttribute]
class procedure AddinUnregister(t: System.Type);
method UninstallControls(); override;
property OutlookApp: outlook._Application _
read self.HostApplication as outlook._Application;
end;
implementation
constructor AddinModule;
begin
InitializeComponent();
end;
{$REGION Component Designer generated code}
/// Required by designer support - do not modify the following method
method AddinModule.InitializeComponent;
begin
self.AddinName := 'MyFirstOutlookAddin';
self.SupportedApps := (AddinExpress.MSO.ADXOfficeHostApp.ohaOutlook);
end;
{$ENDREGION}
end.The concept of designers
Open the Solution Explorer windows and click AddinModule. The Add-in Designer will appear. As described above, it is a container of any components including Office-specific components delivered with Add-in Express. You can add to the module any components from the Toolbox, however Office-specific ones can be added only by the designer commands available by the right click of the mouse. You can add the following Office-specific components (see the picture below or right click on the Add-in Designer):
- Command bar – it allows you to add a new or customize any existing toolbars of any Office applications.
- Outlook Explorer and Inspector command bar – they are used to create new or change any existing toolbars on the Outlook Explorer and Inspector windows.
- Built-in control connector – using this component you can intercept any ID-based control built in Office applications; for example, you can handle the Save menu item in Word or the Send button in Outlook.
- Keyboard shortcut – it provides the application-level keyboard shortcut; e.g. pressing Ctrl-Alt-S in Excel or Ctrl-F in PowerPoint.
- Outlook Bar shortcut manager – use it to create your own set of shortcuts on the Navigation Pane of Outlook.
- Ribbon tab – it allows creating a new or customizing an existing tab on the ribbon context you specify. More about Ribbon tab designer.
- Ribbon Quick Access Toolbar – you can create your own Quick Access Toolbar.
- Ribbon Office menu – this component provides you with customization for the Office Menu in Office 2007 applications.
- Outlook forms manager – you add it to your project to customize Outlook views and forms using Advanced Outlook Regions.
- Event helpers – these components are used to handle all important events of all Office applications such as Outlook NewMail, Word DocumentBeforeSave, Excel WorkbookBeforeOpen, etc.
- Host Configuration item is used to configure Office applications for a specified .NET Framework version.
Since AddinModule in this example is the central module of the project, it implements all COM-interfaces required by the COM Add-in technology; it has the base properties and events of COM add-ins (see the picture below). You can use the Properties window to name your add-in, to specify images for your toolbar and ribbon controls, to register your add-in for the current user or for all users, to collect and register your custom task panes and custom Outlook property pages, to define the namespace for your ribbon customization. Finally, using the SupportedApps property of your AddinModule you can enable / disable your extensions for certain Office applications. The events of your AddinModule include events for add-in initialization, finalization, error trapping, ribbon loading, task pane creation, etc.
Customizing Office
The Microsoft Office extensibility and Add-in Express components allow you to customize the Office UI including toolbars, menus, sub-menus, ribbons, task panes and property pages. This example shows the main features of Add-in Express, so it is very simple. However, here we describe three most important fields of Office customization - extending the Office UI, accessing Office objects and handling their events.
Creating your own toolbars for traditional Office 2000 – 2007 UI
With the command bar components you can add your own or customize any existing toolbars and menus in your host applications. For example, to add a new toolbar to the Outlook Explorer window, open and right click on the Add-in Designer, and then select the Add Explorer CommandBar item. This adds an adxOlExplorerCommandBar component. Next, select the added component and customize it through the Properties window using the CommandBarName, Position, Protection, UseForRibbon properties. The FolderNames and ItemTypes properties are Outlook-specific; you can use them to bind your toolbar to certain Outlook folders or specified content. For example, select Mail in the ItemTypes property to show your toolbar for mail folders only:
All command bar components have the Controls collection, a container for controls of you toolbar. Using its designer you can add to your toolbar standard Office toolbar controls such as button, edit and combo boxes, pop-ups, etc. To add a button to the toolbar, select the Controls collection on the Properties window and open its designer. Then, click the Add button, select ADXCommandBarButton and customize it.
Then, create an event handler for the button click:
method AddinModule.adxCommandBarButton1_Click(sender: System.Object);
var
MailItem: outlook.MailItem;
begin
if OutlookApp.ActiveExplorer.Selection.Count > 0 then begin
MailItem := OutlookApp.ActiveExplorer.Selection.Item(1) as MailItem;
MessageBox.Show(MailItem.Subject);
end;
end;
Finally, register your project as an Office add-in. To do this, select the Register ADX Project item on the Build menu of your Visual Studio, run Outlook and click your button.
Third-party controls on Office toolbars
For Outlook, Excel, Word and PowerPoint, you can use any third-party controls on Office toolbars. For example, let's add a label that shows the subject of the selected mail.
First, you add to the add-in module a special component that supports third-party controls on Outlook toolbars. It is adxOutlookControlAdapter that you can find on the Toolbox; add it to the Add-in Designer. Next, add a label to the Add-in Designer and customize it through the Properties window.
Then, select your toolbar, open the Controls collection designer, click the Add button, select ADXCommandBarAdvancedControl and select the added label in the Control property.
To show the subject of the selected mail we need to handle the SelectionChange event. To do this, right click on the Add-in Designer, select Add Events, click Outlook Events on the opened window and click OK. This adds the Outlook events component to the Add-in Designer.
Using the Properties window, create an event handler for the ExplorerSelectionChange event:
method AddinModule.adxOutlookEvents_ExplorerSelectionChange
(sender: System.Object; explorer: System.Object);
var
MailItem: outlook.MailItem;
begin
if OutlookApp.ActiveExplorer.Selection.Count > 0 then begin
MailItem := OutlookApp.ActiveExplorer.Selection.Item(1) as MailItem;
(Self.adxCommandBarAdvancedControl1.ActiveInstance as Label).Text _
:= MailItem.Subject;
end;
end;
Finally, rebuild your project, run Outlook and select any mail. If you reproduce the steps above correctly, your label will show the subject of the selected mail item. Please note that you needn't register your project for the second time. More about customizing Outlook toolbar with any controls.
Customizing Ribbon UI in Office 2007
Add-in Express includes special components for the Office Ribbon UI customization. To create your own ribbon tab, right click on the Add-in Designer and select Add Ribbon Tab. This adds an adxRibbonTab component to the Add-in Designer. Next, name your tab via the Caption property and specify its ribbons via the Ribbons property (for example, select OutlookMailCompose).
Then, add a group and button to the tab through the Ribbon tab designer of the Controls collection.
Next, handle the click of the button:
method AddinModule.adxRibbonButton1_OnClick(sender: System.Object;
control: AddinExpress.MSO.IRibbonControl; pressed: System.Boolean);
var
MailItem: outlook.MailItem;
begin
MailItem := OutlookApp.ActiveInspector.CurrentItem as MailItem;
if Assigned(MailItem) then
MailItem.Subject := 'Test';
end;
Finally, rebuild your project, run Outlook, create a new mail and click your button.
Adding application-level keyboard shortcuts
With Add-in Express you can easily create application-level keyboard shortcuts. To do this, click on the Add-in Designer, set its HandleShortcuts property to true, right click on the Add-in Designer and select Add Keyboard Shortcut. An adxKeyboardShortcut will be added to the Add-in Designer. Next, set the shortcut text to the ShortcutText property of the add-in component (Ctrl-Shift-R for this example).
Then, handle your shortcut action. In this example we reply to the currently selected mail and initialize its text:
method AddinModule.adxKeyboardShortcut1_Action(sender: System.Object);
var
MailItem: outlook.MailItem;
begin
if OutlookApp.ActiveExplorer.Selection.Count > 0 then begin
MailItem := OutlookApp.ActiveExplorer.Selection.Item(1) as MailItem;
MailItem := MailItem.Reply;
MailItem.Body := 'Test';
MailItem.Display(false);
end;
end;
Finally, rebuild your project, run Outlook and press Ctrl-Shift-R.
