-->![Broadsoft Outlook Toolbar Picture Broadsoft Outlook Toolbar Picture](https://www.add-in-express.com/images/outlook-toolbar-controls/custom-control-outlook-toolbar.gif)
This tutorial teaches you how to build an Outlook add-in that can be used in message compose mode to insert content into the body of a message.
In this tutorial, you will:
Microsoft Outlook Work smarter with tools that help you communicate, manage your schedule, and find what you need—simply and fast. BroadSoft is the leader in cloud PBX, unified communications, team collaboration and contact center solutions for business.
- Create an Outlook add-in project
- Define buttons that will render in the compose message window
- Implement a first-run experience that collects information from the user and fetches data from an external service
- Implement a UI-less button that invokes a function
- Implement a task pane that inserts content into the body of a message
Prerequisites
- Node.js (version 8.0.0 or later)
- The latest version of Yeoman and the Yeoman generator for Office Add-ins. To install these tools globally, run the following command via the command prompt:NoteEven if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.
- Outlook 2016 or later on Windows (connected to an Office 365 account) or Outlook on the web
- A GitHub account
Setup
The add-in that you'll create in this tutorial will read gists from the user's GitHub account and add the selected gist to the body of a message. Complete the following steps to create two new gists that you can use to test the add-in you're going to build.
- Login to GitHub.
- Create a new gist.
- In the Gist description.. field, enter Hello World Markdown.
- In the Filename including extension.. field, enter test.md.
- Add the following markdown to the multiline textbox:
- Select the Create public gist button.
- Create another new gist.
- In the Gist description.. field, enter Hello World Html.
- In the Filename including extension.. field, enter test.html.
- Add the following markdown to the multiline textbox:
- Select the Create public gist button.
Create an Outlook add-in project
Important
Spaces are not currently permitted in the add-in project name or anywhere in the folder path where you create your add-in project. If your add-in's project name or folder path contains spaces, the local web server won't start when you run
npm start
or npm run start:web
. This limitation is temporary and will be eliminated when the underlying issue is resolved in the Yeoman generator for Office Add-ins.Use the Yeoman generator to create an Outlook add-in project.
- Run the following command from the command prompt and then answer the prompts as follows:
- Choose a project type -
Office Add-in Task Pane project
- Choose a script type -
Javascript
- What do you want to name your add-in? -
git-the-gist
- Which Office client application would you like to support? -
Outlook
After you complete the wizard, the generator will create the project and install supporting Node components. - Navigate to the root directory of the project.
- This add-in will use the following libraries:
- Showdown library to convert Markdown to HTML
- URI.js library to build relative URLs.
- jquery library to simplify DOM interactions.
To install these tools for your project, run the following command in the root directory of the project:
Update the manifest
The manifest for an add-in controls how it appears in Outlook. It defines the way the add-in appears in the add-in list and the buttons that appear on the ribbon, and it sets the URLs for the HTML and JavaScript files used by the add-in.
Specify a support page
The manifest that the generator creates contains a placeholder value for the
SupportUrl
element that's not a valid URL. To prevent the file from failing validation, complete the following steps:- In the root directory of the project, create a new file named support.html and add the following markup.
- Open the manifest.xml file and update the
SupportUrl
element to point to the support.html file that you created.
Specify basic information
Next, make the following updates in the manifest.xml file to specify some basic information about the add-in:
- Locate the
ProviderName
element and replace the default value with your company name. - Locate the
Description
element, replace the default value with a description of the add-in, and save the file.
Test the generated add-in
Before going any further, let's test the basic add-in that the generator created to confirm that the project is set up correctly.
Note
Office Add-ins should use HTTPS, not HTTP, even when you are developing. If you are prompted to install a certificate after you run one of the following commands, accept the prompt to install the certificate that the Yeoman generator provides.
Tip
If you're testing your add-in on Mac, run the following command before proceeding. When you run this command, the local web server will start.
- Run the following command in the root directory of your project. When you run this command, the local web server will start (if it's not already running).
- Follow the instructions in Sideload Outlook add-ins for testing to sideload the manifest.xml file that's located in the root directory of the project.
- In Outlook, open an existing message and select the Show Taskpane button. If everything's been set up correctly, the task pane will open and render the add-in's welcome page.
Define buttons
Now that you've verified the base add-in works, you can customize it to add more functionality. By default, the manifest only defines buttons for the read message window. Let's update the manifest to remove the buttons from the read message window and define two new buttons for the compose message window:
- Insert gist: a button that opens a task pane
- Insert default gist: a button that invokes a function
Remove the MessageReadCommandSurface extension point
Open the manifest.xml file and locate the
ExtensionPoint
element with type MessageReadCommandSurface
. Delete this ExtensionPoint
element (including its closing tag) to remove the buttons from the read message window.Add the MessageComposeCommandSurface extension point
Locate the line in the manifest that reads
</DesktopFormFactor>
. Immediately before this line, insert the following XML markup. Note the following about this markup:- The
ExtensionPoint
withxsi:type='MessageComposeCommandSurface'
indicates that you're defining buttons to add to the compose message window. - By using an
OfficeTab
element withid='TabDefault'
, you're indicating you want to add the buttons to the default tab on the ribbon. - The
Group
element defines the grouping for the new buttons, with a label set by thegroupLabel
resource. - The first
Control
element contains anAction
element withxsi:type='ShowTaskPane'
, so this button opens a task pane. - The second
Control
element contains anAction
element withxsi:type='ExecuteFunction'
, so this button invokes a JavaScript function contained in the function file.
Update resources in the manifest
The previous code references labels, tooltips, and URLs that you need to define before the manifest will be valid. You'll specify this information in the
Resources
section of the manifest.- Locate the
Resources
element in the manifest file and delete the entire element (including its closing tag). - In that same location, add the following markup to replace the
Resources
element you just removed: - Save your changes to the manifest.
Reinstall the add-in
Since you previously installed the add-in from a file, you must reinstall it in order for the manifest changes to take effect.
- Follow the instructions in Sideload Outlook add-ins for testing to locate the Custom add-ins section at the bottom of the My add-ins dialog box.
- Select the .. button next to the Git the gist entry and then choose Remove.
- Close the My add-ins window.
- The custom button should disappear from the ribbon momentarily.
- Follow the instructions in Sideload Outlook add-ins for testing to reinstall the add-in using the updated manifest.xml file.
After you've reinstalled the add-in, you can verify that it installed successfully by checking for the commands Insert gist and Insert default gist in a compose message window. Note that nothing will happen if you select either of these items, because you haven't yet finished building this add-in.
- If you're running this add-in in Outlook 2016 or later on Windows, you should see two new buttons in the ribbon of the compose message window: Insert gist and Insert default gist.
- If you're running this add-in in Outlook on the web, you should see a new button at the bottom of the compose message window. Select that button to see the options Insert gist and Insert default gist.
Implement a first-run experience
This add-in needs to be able to read gists from the user's GitHub account and identify which one the user has chosen as the default gist. In order to achieve these goals, the add-in must prompt the user to provide their GitHub username and choose a default gist from their collection of existing gists. Complete the steps in this section to implement a first-run experience that will display a dialog to collect this information from the user.
Collect data from the user
Let's start by creating the UI for the dialog itself. Within the ./src folder, create a new subfolder named settings. In the ./src/settings folder, create a file named dialog.html, and add the following markup to define a very basic form with a text input for a GitHub username and an empty list for gists that'll be populated via JavaScript.
Next, create a file in the ./src/settings folder named dialog.css, and add the following code to specify the styles that are used by dialog.html.
Now that you've defined the dialog UI, you can write the code that makes it actually do something. Create a file in the ./src/settings folder named dialog.js and add the following code. Note that this code uses jQuery to register events and uses the
messageParent
function to send the user's choices back to the caller.Update webpack config settings
Finally, open the file webpack.config.js file in the root directory of the project and complete the following steps.
- Locate the
entry
object within theconfig
object and add a new entry fordialog
.After you've done this, the newentry
object will look like this: - Locate the
plugins
array within theconfig
object and add these two new objects to the end of that array.After you've done this, the newplugins
array will look like this: - If the web server is running, close the node command window.
- Run the following command to rebuild the project.
- Run the following command to start the web server.
Fetch data from GitHub
The dialog.js file you just created specifies that the add-in should load gists when the
change
event fires for the GitHub username field. To retrieve the user's gists from GitHub, you'll use the GitHub Gists API.Within the ./src folder, create a new subfolder named helpers. In the ./src/helpers folder, create a file named gist-api.js, and add the following code to retrieve the user's gists from GitHub and build the list of gists.
Note
You may have noticed that there's no button to invoke the settings dialog. Instead, the add-in will check whether it has been configured when the user selects either the Insert default gist button or the Insert gist button. If the add-in has not yet been configured, the settings dialog will prompt the user to configure before proceeding.
Implement a UI-less button
This add-in's Insert default gist button is a UI-less button that will invoke a JavaScript function, rather than open a task pane like many add-in buttons do. When the user selects the Insert default gist button, the corresponding JavaScript function will check whether the add-in has been configured.
- If the add-in has already been configured, the function will load the content of the gist that the user has selected as the default and insert it into the body of the message.
- If the add-in hasn't yet been configured, then the settings dialog will prompt the user to provide the required information.
Update the function file (HTML)
A function that's invoked by a UI-less button must be defined in the file that's specified by the
FunctionFile
element in the manifest for the corresponding form factor. This add-in's manifest specifies https://localhost:3000/commands.html
as the function file.Open the file ./src/commands/commands.html and replace the entire contents with the following markup.
Update the function file (JavaScript)
Open the file ./src/commands/commands.js and replace the entire contents with the following code. Note that if the
insertDefaultGist
function determines the add-in has not yet been configured, it adds the ?warn=1
parameter to the dialog URL. Doing so makes the settings dialog render the message bar that's defined in ./settings/dialog.html, to tell the user why they're seeing the dialog.Create a file to manage configuration settings
The HTML function file references a file named addin-config.js, which doesn't yet exist. Create a file named addin-config.js in the ./src/helpers folder and add the following code. This code uses the RoamingSettings object to get and set configuration values.
Create new functions to process gists
Next, open the ./src/helpers/gist-api.js file and add the following functions. Note the following:
- If the gist contains HTML, the add-in will insert the HTML as-is into the body of the message.
- If the gist contains Markdown, the add-in will use the Showdown library to convert the Markdown to HTML, and will then insert the resulting HTML into the body of the message.
- If the gist contains anything other than HTML or Markdown, the add-in will insert it into the body of the message as a code snippet.
Test the button
Save all of your changes and run
npm start
from the command prompt, if the server isn't already running. Then complete the following steps to test the Insert default gist button.- Open Outlook and compose a new message.
- In the compose message window, select the Insert default gist button. You should be prompted to configure the add-in.
- In the settings dialog, enter your GitHub username and then either Tab or click elsewhere in the dialog to invoke the
change
event, which should load your list of gists. Select a gist to be the default, and select Done. - Select the Insert default gist button again. This time, you should see the contents of the gist inserted into the body of the email.NoteOutlook on Windows: To pick up the latest settings, you may need to close and reopen the compose message window.
Implement a task pane
This add-in's Insert gist button will open a task pane and display the user's gists. The user can then select one of the gists to insert into the body of the message. If the user has not yet configured the add-in, they will be prompted to do so.
Specify the HTML for the task pane
In the project that you've created, the task pane HTML is specified in the file ./src/taskpane/taskpane.html. Open that file and replace the entire contents with the following markup.
Specify the CSS for the task pane
In the project that you've created, the task pane CSS is specified in the file ./src/taskpane/taskpane.css. Open that file and replace the entire contents with the following code.
Specify the JavaScript for the task pane
In the project that you've created, the task pane JavaScript is specified in the file ./src/taskpane/taskpane.js. Open that file and replace the entire contents with the following code.
Test the button
Save all of your changes and run
npm start
from the command prompt, if the server isn't already running. Then complete the following steps to test the Insert gist button.- Open Outlook and compose a new message.
- In the compose message window, select the Insert gist button. You should see a task pane open to the right of the compose form.
- In the task pane, select the Hello World Html gist and select Insert to insert that gist into the body of the message.
Next steps
In this tutorial, you've created an Outlook add-in that can be used in message compose mode to insert content into the body of a message. To learn more about developing Outlook add-ins, continue to the following article:
Outlook comes with two types of built-in command bar objects, the Menu Bar and toolbars. Only one Menu Bar is allowed, but you can customize both it and the built-in toolbars. In addition, you can add custom toolbars to automate specialized or repetitive tasks. Fortunately, command bars are easy to configure and create in any Office application, including Outlook. Here are some of the various ways you can tailor Outlook to suit your working style.
Note: This information is also available as a PDF download.
#1: Rearrange existing commands
Most of us use a few commands a lot, and seldom, if ever, use the rest. You can rearrange the commands on the Menu Bar or a toolbar, making selection a bit more efficient. To do so, choose Tools | Customize, click the Commands tab, and click Rearrange Commands. In the Rearrange Commands dialog box, select either the Menu Bar or Toolbar option. Then, choose the appropriate menu (if you selected the Menu Bar option) or toolbar (if you selected Toolbar) from the drop-down list at the top of the dialog box. The Controls list box will display the commands, including submenus, as they appear from top to bottom on the menu (or left to right on the selected toolbar).
You can add, delete, or move a command up or down (or left and right). Clicking Add will position the new item above or to the left of the selected command. You can also modify the selection by changing its caption and other attributes. Select Begin A Group if you want to add a separator above or beside the selected command. Clicking Reset removes all the customization in case you need to start over.
#2: Move commands the easy way
You don't have to use the Customize dialog box to move commands on a toolbar. Hold down the Alt key, click on a button, and drag it to an alternate position or off the toolbar completely. To restore the tool, reset the toolbar or use the Customize dialog box to put it back.
If you remove a custom command, you'll have to rebuild it if you ever need it again. Consider removing custom commands to a custom toolbar created for the purpose of storing custom commands you think you no longer need. Someday, you may want that command and you can simply restore it from the custom toolbar instead of rebuilding it.
#3: Disable personalized menus
The personalized menu feature displays only the commands you use the most often. You might find this feature more irritating than helpful, especially when you're looking for a seldom-used command and can't find it simply because Outlook isn't displaying it. To disable this feature, choose Customize | Tools. In the Options tab, check the Always Show Full Menus option and click Close. This option will affect the entire Office suite, not just Outlook.
![Broadsoft Outlook Toolbar Picture Broadsoft Outlook Toolbar Picture](https://www.add-in-express.com/images/outlook-toolbar-controls/custom-control-outlook-toolbar.gif)
Developers can find the details for personalized menus in a file named msout11.pip in the C:Documents and SettingsApplication DataMicrosoftOffice folder.
#4: Store your customization
Outlook stores the changes you make to command bars in a file named outcmd.dat. If you want to reset all of your command bars to their default settings, simply delete this file. But be careful. Deleting this file will wipe out all of your custom command bars.
If you've spent a lot of time customizing Outlook, store a backup of outcmd.dat in a safe place. Then, if you have to reinstall Outlook, restore your customized command bars by replacing outcmd.dat with your stored copy. You can also use outcmd.dat to copy your customizations to other systems. Simply save it over the exiting file.
#5: Create custom toolbars
To create a custom toolbar, open the Customize dialog box by choosing Customize | Tools. Everything you need is in one spot. Click the Toolbars tab and then click New. In the New Toolbar dialog box, enter a name and click OK. Outlook will create a new, empty toolbar. Just switch to the Commands tab to add built-in commands to the new toolbar by dragging them from the Commands list.
You can create commands for any folder or form, except for Note forms. Outlook displays custom toolbars in all views, but it's smart enough to enable only those commands that apply to the current view.
# 6: Create hyperlinks for quick access
All of us have a folder we use more than the others. It might contain e-mail from family and friends or store critical information about your current project. Instead of wading through the folders hierarchy to access it, add a hyperlink command to a command bar.
First, display the Web toolbar (right-click any toolbar and select Web). Then, navigate to the folder in question so you can see its path displayed in the Web toolbar's address box. For instance, if you selected the Inbox, the Web toolbar would display the path Outlook:Inbox.
Microsoft Outlook Toolbar Download
Next, choose Tools | Customize, click the Commands tab, and choose Web from the Categories list. Scroll to the bottom of the Commands list box and drag the Folder command to a toolbar. Right-click the Folder command, choose Assign Hyperlink, and then select Open from the resulting submenu to open the Assign Hyperlink: Open dialog box. Enter the folder's path in the Address field and click OK. Now, anytime you want to access that folder, just click the new hyperlink command. This shortcut also works for Web addresses and local files.
#7: Create a Mail To hyperlink
If you send the same e-mail message to the same list on a regular basis, you can create a hyperlink command to reduce some of your work. For instance, let's suppose your group has a weekly meeting and before that meeting, you e-mail an agenda to everyone in the group. Now, there's more than one way you could automate this task, but a hyperlink command is the simplest.
Begin by choosing Tools | Customize and clicking the Commands tab. With File selected in the Categories list box, drag Mail Message from the Commands list box to a toolbar. Right-click the Mail Message command to display its properties. Since Outlook uses the New Mail Message icon, choose Text Only or select Change Button Image to pick a different icon for the command.
Next, click the Assign Hyperlink option and choose Open from the resulting submenu. In the Edit Hyperlink: Open dialog box, click E-mail Address in the Link To section (bottom left). Then, enter the name of your group's distribution list or enter each individual's e-mail address separately in the E-mail Address field. Add a descriptive subject and then click OK.
Each week, when you're ready to send the meeting's agenda, click the hyperlink command and Outlook will display a new e-mail form, pre-filled with the appropriate e-mail addresses and subject text.
#8: Use command bar shortcuts
Not everyone uses the mouse for everything. If you're more at home using the keyboard, you probably appreciate keyboard shortcuts. There are a number for working with command bars. First, activate the menu bar by pressing F10. Then you can use any of these shortcuts:
Action | Result |
Ctrl+Tab | Select next toolbar |
Ctrl+Shift+Tab | Select previous toolbar |
Tab | Select next button or menu |
Shift+Tab | Select previous button or menu |
Up or Down arrow+Enter | Select an option from a menu or drop-down list |
#9: Create a button image
Use the Office Button Editor to create custom icons for your custom commands. It's a bit limited, but it will get the job done most of the time. With the Customize dialog box open (Tools | Customize), right-click the command and choose Edit Button Image to launch Button Editor. Choose a color and then click a square or selection of squares in the Picture grid. You can also paste in a bitmap file that's 32 x 32 pixels or smaller.
Broadsoft Outlook Toolbar Pictures
#10: Beware of the Reset option
If you add a custom tool to the Menu Bar or to one of Outlook's built-in toolbars, you need to be careful about the Reset option. In fact, you might be better off creating a custom toolbar instead of altering the built-in Menu Bar or toolbars. It's just too easy to reset them without realizing that you're wiping out a custom tool — until later when you need it and it's no longer there. To reset the Menu Bar or a built-in toolbar, all you do is choose Tools | Customize, click the Toolbars tab, select the object you want to reset, and click Reset. This will remove all customization from the selected command bar, so make sure that's what you really want to do.