Tutorial

In this tutorial, a Microsoft Outlook Add-in is created that introduces a new Ribbon tab and a custom task pane in the explorer window.

The entire code of the example Add-in can be found here.

The tutorial is based on the current version which is mentioned at Home.

The class name for the Add-in used here is JoaAddin1 and it is placed in the package addin1.

Required previous step: Create a New Eclipse Workspace

Create Add-in Project

• Create a New Add-in project

Create Add-in Class

• Create a New Add-in class

Create Launch Configurations

• Create a New Debug Configuration

Create Globals Class

Create the class Globals with static methods to easily access the Add-in object from everywhere.

public class Globals {

    private static JoaAddin1 addin;

    protected static void setThisAddin(JoaAddin1 addin) {
         Globals.addin = addin;
    }

    public static JoaAddin1 getThisAddin() {
         return addin;
    }
}

Add a constructor to the Add-in class which sets the global reference to the Add-in:

public JoaAddin1() {
	Globals.setThisAddin(this);
}

Define a Ribbon Tab

The custom Ribbon extensions have to be provided in XML format. Microsoft Outlook queries for this data by calling the function GetCustomUI of the Add-in. Please try an internet search for GetCustomUI, you will find several hits and maybe you meet the page Extending the User Interface in Outlook 2010 with many useful information. Most of the topics there can be transformed to be used with JOA.

In the class hierarchy of JoaAddin1, the class OfficeAddin already defines GetCustomUI (hint: press F3 on a symbol to open its definition). The function tries to find an XML file in the classpath that fits to the Ribbon ID passed as argument. The file must reside in the same package than the Add-in class and its name has to start with "Ribbon.".

In order to separate resource data from code, create a new source folder in the project:

• In "Project Explorer", right-click on the project folder and select "New" - "Source Folder".
• Enter "res" as folder name.
• Click "Finish"
• Create the same package as for the Add-in class:
• In "Project Explorer", right-click on folder "res" (not project) and select "New" - "Package".
• Enter "addin1" as package name.

Create the XML file for the Ribbon definition:

• Right-click on the new package folder "addin1" and select "New" - "File".
• Enter "Ribbon.Microsoft.Outlook.Explorer.xml" as file name.
• Copy the following code into the file:

Ribbon.Microsoft.Outlook.Explorer.xml:

<?xml version="1.0" encoding="utf-8"?>
<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui">
	<ribbon>
		<tabs>
 			<tab id="ExplorerTab" label="JOA Tutorial">
				<group id="Group1" label="Happy Group">
					<button id="SmileButton" imageMso="HappyFace" size="large"
						label="Smile" onAction="onSmileButtonClicked" />
				</group>
			</tab>
		</tabs>
	</ribbon>
</customUI>

Register and Start the Add-in

• Close Microsoft Outlook if it is running.
• Terminate all processes in the debug view of Eclipse.
• Register the Add-in: Eclipse toolbar, drop-down list next to "bug" button, "Addin1 Register". This step is usually necessary only once. It might be also useful, if Outlook has disabled the Add-in, because it removes the state information that Outlook tracks about it.
• Run the Add-in: start "Addin1" in the drop-down list.

Hint: At this moment, the "Addin1" process has started a system wide "COM Class Factory" for creating instances of our Add-in class. When Outlook is started in the next step, it uses this factory to instantiate the Add-in. Hence, the Add-in will run in the address space of the "Addin1" process and can be debugged in Eclipse.

• Start Outlook
• A new Ribbon tab should be displayed named "JOA Tutorial".
• This tab contains a button with a smiling face.

• Close Outlook

Hint: Thereby you can watch in the Eclipse debugger window, that the "Addin1" process is terminated too. This happens some seconds after the Outlook window has disappeared. Outlook calls OutlookAddin.onQuit on termination and this function calls Platform.exit().

• Start Outlook again. Do not start the "Addin1".
• Since Outlook (resp. Windows) does not find a running "COM Class Factory" for the Add-in's GUID, it starts a new process from the location found in the registry data of the Add-in. In the Task Manager, an additional "javaw.exe32" process is visible.

Hint: this additional process is a common reason, that breakpoints are not hit. Outlook is connected to this process and not to the one that is running under the debugger.

• Close Outlook. (The additional "javaw.exe" disappears in the Task Manager)

Add a Button Click Handler

There is already a handler function specified in the Ribbon XML code: ... onAction="onSmileButtonClicked".... Now, a corresponding Java function is defined to react on the click. In this example, a note item is created, when the button is pressed.

• Open class JoaAddin1 in the editor.
• Add the following code to the class

... JoadAddin1.java:

public void onSmileButtonClicked(Dispatch ribbonControl) {
    
    // Event handlers triggered from Outlook should not immediately call
    // Outlook functions during processing. This can cause a deadlock.
    // Thus: execute the code in a background thread.
    BackgTask.run(() -> {
        
            // Obtain Outlook application interface
            com.wilutions.mslib.outlook.Application app = Globals.getThisAddin().getApplication();

            // Create a new NoteItem object and "cast" it to NoteItem.class
            NoteItem noteItem = app.CreateItem(OlItemType.olNoteItem).as(NoteItem.class);

            // Assign some text and display the note
            noteItem.setBody("Hello Note");
            noteItem.Display(true);

    });
}

• Save the changes
• Stop Outlook if it is running
• Start debug configuration "Addin1"
• Start Outlook
• Click the button with the happy face icon.

A new note should be displayed as shown in this screenshot:

Hint: If a breakpoint is hit the fist time in Eclipse, a dialog asks for switching to the debug perspective. If you are not familiar with Eclipse, you should decline this question with "No" (check "Remember my decision"). If you accept, the workbench window gets completely disarranged.

Debugging the Code

In the following, a breakpoint is set in the button handler.

Hint: If a breakpoint is hit the fist time in Eclipse, a dialog asks for switching to the debug perspective. If you are not familiar with Eclipse, you should decline this question with "No" (check "Remember my decision"). If you accept, you might feel that the workbench window gets completely disarranged.

Double-click in the left border of the editor window in order to set a breakpoint:

• Click the button and verify that the program stops a the breakpoint. If not, Outlook might have created the Add-in in another process than the one currently being debugged.
• Press F5 to step into a function call, F6 to step over a call, F7 to step out of the call, F8 to continue program execution.

Some minor code changes can be made without restarting the Add-in and Outlook. This can be very handy during debugging.

• Add the line noteItem.Delete(); after the note is displayed.
• Save the changes
• Verify that the Java runtime applies the modifications without a restart.

Develop a Custom Task Pane

A task pane integrates with an explorer or inspector window and is usually docked to one side of the window. It displays a JavaFX scene and can contain controls like buttons, text boxes, etc.

• Create a new Java class named ExplorerTaskPane in the package addin1
• Specify com.wilutions.joa.TaskPaneFX as superclass
• Implement the function createScene which is abstract in the superclass, e.g. create a scene with a single button. The class might look as follows:

ExplorerTaskPane.java:

package addin1;

import javafx.scene.Scene;
import javafx.scene.control.Button;
import javafx.scene.layout.GridPane;

import com.wilutions.com.ComException;
import com.wilutions.joa.fx.TaskPaneFX;

public class ExplorerTaskPane extends TaskPaneFX {

    @Override
    protected Scene createScene() throws ComException {
        GridPane grid = new GridPane();
        Button clear = new Button("Klickme!");
        GridPane.setConstraints(clear, 0, 0);
        grid.getChildren().add(clear);
        Scene scene = new Scene(grid);
        return scene;
    }

}

• Define a new member in JoaAddin1 of type ExplorerTaskPane and initialize it with a new object.

JoaAddin1.java:

    final ExplorerTaskPane taskPane = new ExplorerTaskPane();

• Extend the Ribbon definition by a new element of type toggleButton. This button will show or hide the task pane.

Ribbon.Microsoft.Outlook.Explorer.xml:

<group>
...
	<toggleButton id="JoaTaskPane" imageMso="HappyFace"
		size="large" label="Show/Hide"
		onAction="onJoaTaskPaneClicked" />
</group>

• In the JoaAddin1 class, write the button click handler that creates the task pane's window or changes it's visibility.

JoaAddin1.java:

public void onJoaTaskPaneClicked(Dispatch control, Boolean pressed) {
    BackgTask.run(() -> {
        if (taskPane.hasWindow()) {
            taskPane.setVisible(pressed);
        } else {
            Object parentWindow = getApplication().ActiveExplorer();
            createTaskPaneWindowAsync(taskPane, "JOA TaskPane", parentWindow, (taskPane, ex) -> {
                if (ex == null) {
                    taskPane.setVisible(true);
                }
                if (ex != null) {
                    ex.printStackTrace();
                }
            });
        }
    });
}

Hint: the onAction handler of a toggleButton has an extra argument that specifies the button's state.

• Save all changes and start the Add-in and Outlook.