Export (0) Print
Expand All

How to: Create your first mail app for Outlook by using "Napa" Office 365 Development Tools

apps for Office

Learn how to create a mail app for Outlook by using "Napa" Office 365 Development Tools.

Run button Run this sample now!

Last modified: June 30, 2014

Applies to: Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices

   Office.js: v1.0, v1.1

   Apps for Office manifests schema: v1.0, v1.1

Note Note

We can also show you how to build a mail app by using Visual Studio or a text editor. If you are not sure which tool to use, read the Development basics.

In this article
Prerequisites
Overview
Create a basic mail app for Outlook
Change the properties of the app
Extract addresses from Outlook items
Show the history of property values for a selected address
Debug your mail app in Windows Internet Explorer
Additional resources

You need the following components to complete this walkthrough:

  • Office 365 account

  • The "Napa" Office 365 Development Tools app

For more information, see Sign up for an Office 365 Developer Site, set up your tools and environment, and start deploying apps.

By reviewing this walkthrough, you can learn how to create a simple mail app for Outlook by using "Napa" Office 365 Development Tools. The app that you will create enables users to view the history of property values for all of the addresses that appear in the body of the currently open email message.

This example shows how to get information from an open item. In your app, you might use an address to get information from a service such as a map or more information about the value of a property, sales history, or real estate taxes.

For more information about "Napa" Office 365 Development Tools, see Create apps for Office and SharePoint by using "Napa" Office 365 Development Tools.

After you have created your first mail app using "Napa" Office 365 Development Tools, learn more about mail apps, and the fundamentals for developing mail apps in Outlook.

In this procedure, you will create a basic mail app for Outlook.

To create a basic mail app for Outlook

  1. Choose the Add New Project button.

    Note Note

    The Add New Project button appears only if you have created other projects. If this is your first project, skip to the next step.

    Figure 1. New project tile

    Add New Project tile
  2. Choose the Mail app for Office tile, name the project MyFirstMailApp, and then choose the Create button.

    Figure 2. Mail app project tile

    Mail app project tile

    The code editor opens and shows the default webpage (named Home.html), which already contains some sample code that you can run without doing anything else.

  3. In the Home.html file, replace the opening and closing <body> tags with the following code.

    <body>
    <!-- Page content -->
    <div id="content-main">
    <div class="padding">
    <p><strong>Select an address to view the property value history:</strong></p>
      <form name= "addressForm"" id="addresses">
                        <table>
    <tr>
                                <td>
                                    <table id="addressOptions"></table>
                                </td>
        </tr>
                         </table>
                     </form>
     <div id="valueWidget"></div>
    </div>
    </div>
    <div id="content-footer">
    <div class="padding">
    </div>
    </div>
    </body>
    

    This code adds a table that will contain a list of addresses and a section that will contain the history of property values.

In this procedure, you will specify a name and description for your app. Then, you will apply activation rules to the app so that your mail app appears only next to mail items that have addresses in them.

To change the properties of the app

  1. At the side of the page, choose the properties (Properties button) button.

    The properties of the mail app appear.

  2. Set the Name, and Description properties to the values shown in Figure 3.

    Figure 3. General tab of the Properties page

    General tab of the properties page

    The Name and Description properties help users understand the purpose of the app for Office when it appears in a list of available apps for an Office application.

  3. Choose the Activation Rules tab.

  4. Select the Subject or body of the item contains a known entity check box.

  5. In the Subject or body of the item contains a known entity list, choose Address.

    These rules ensure that your app appears only next to mail items that have addresses in them.

    Figure 4. Activation rules that ensure that your mail app appears only next to mails that contain addresses

    Activation rules of the mail app
    Note Note

    This example only works with addresses in the United States. However, you can work around this limitation by using well-known entities. For more information, see Matching strings in an Outlook item as well-known entities.

  6. Choose the Apply button at the bottom of the Properties dialog box.

    The property values are saved.

    Note Note

    The Properties editor shows the most common settings of a mail app. It does not show all of the possible settings of a mail app. If your scenario requires you to modify settings that do not appear in the Properties editor, you can create your app by using Visual Studio or a text editor.

  7. Choose the Explore button (Explore button) on the left side of the page to return to the project view.

Your mail app can identify and obtain certain strings in the subject and body of the current Outlook item, including addresses, contacts, email addresses, meeting suggestions, phone numbers, task suggestions, and URLs. In this procedure, you will get an array of addresses from the body of the current Outlook item and show those addresses in the mail app.

To view examples of obtaining other types of strings, see Sample: Extract entity strings from an Outlook item.

To extract addresses from Outlook items

  1. Go to the Home.js file.

  2. In the code editor, open the Home.js file, and replace the contents of this file with the following code.

    /// <reference path="../App.js" />
    /*global app*/
    
    (function () {
    'use strict';
    
    // The Office initialize function must be run each time a new page is loaded
    Office.initialize = function (reason) {
    $(document).ready(function () {
    app.initialize();
           $('#addresses').click(getSelectedAddress);
       getAddresses();
       
    });
    };
    })();
    
    function getAddresses() {
        var item = Office.context.mailbox.item;
        var entities = item.getEntities();
        var addressesArray = entities.addresses;
        
        for (var i = 0; i < addressesArray.length; i++) {
        var src = "<tr><td><Input type='radio' name='address' value='" + addressesArray[i] +
                      "'></td><td>" + addressesArray[i] + "</td></tr>";
      
            $('#addressOptions').append($(src));
    
          }
    }
    
    

In this procedure, you’ll add code that runs when the user chooses an address in the app. The code will use the address that the user chose to show a line chart of property values over the past year.

To show the history of property values for the selected address

  1. Go to the Home.js file.

  2. In the code editor, open the Home.js file, and add the following functions.

    function ShowPropertyValues(address) {
    
        var encodedAddress = encodeURIComponent(address);
    
        var src = "<iframe height='300' width='300' " +
                  "src='https://www.zillow.com/widgets/zestimate/ZestimateLargeWidget.htm?" +
                  "did=zillow-shv-large-iframe-widget&type=iframe&address=" +
                   encodedAddress + "&searchbox=no&skinnyWidget=true&tc=566276&bgc=e2e7eb'></iframe>";
    
        $('#valueWidget').empty();
        $('#valueWidget').append($(src));
    }
    
    function getSelectedAddress() {
    
        var selectedItem = "";
    
        for (i = 0; i < document.addressForm.address.length; i++) {
    
            if (document.addressForm.address[i].checked) {
                selectedItem = document.addressForm.address[i].value;
            }
        }
        if (selectedItem === "") {
            selectedItem = document.addressForm.address.defaultValue;
        }
    ShowPropertyValues(selectedItem);
    }
    
    

Run it!

Now you can run the app.

To run the app

  1. On the side of the page, choose the run (Run button) button.

    A dialog box appears that prompts you to provide your email address and password.

  2. Provide the email address and password for a server that is running Exchange Server 2013, and then choose Continue.

  3. In Outlook, send yourself an email message that contains one or more addresses.

  4. After the message appears in the Inbox folder, open the message.

  5. At the top of the message, choose MyFirstMailApp.

    The MyFirstMailApp app opens. The addresses appear as options in the app.

  6. Choose an address from the list.

    The history of property values associated with that address appears in a chart.

  7. Close Outlook.

If you use Windows Internet Explorer (IE) 9 and up, you can use F12 developer tools to debug the JavaScript, HTML, and Cascading Style Sheets (CSS) of your mail app.

The following procedure shows you how to open F12 tools, start the debugger, and cause execution to stop on a line of code in your Home.js file.

To get started debugging your mail app in Windows Internet Explorer

  1. At the bottom of the page, choose the run (Run button) button.

    A dialog box appears that prompts you to provide your email address and password.

  2. Provide the email address and password for a server that is running Exchange Server 2013, and then choose Continue.

  3. Open the message that contains the address.

  4. At the top of the message, choose MyFirstMailApp.

    The MyFirstMailApp app opens.

  5. In Outlook, select the mail app so that the app is in focus when you start the debugging tools.

  6. Press the F12 key on your keyboard.

    The F12 tools open in a separate window.

  7. In the F12 tools window, choose the Script tab, and then choose the Start debugging button.

  8. From the View Sources drop-down list under the Stop debugging button, select Home.js.

    The content of the MyAppPage file appears in the left pane of the window.

  9. Set a breakpoint next to the getSelectedAddress method.

    For more information about how to set a breakpoint in the F12 tool window, see Breaking Code Execution.

  10. On the shortcut menu for the mail app, choose Refresh.

  11. Choose an address from the list.

    In the F12 tools window, execution stops on the getSelectedAddress method.

    For more information, see any of the following topics.

    If you use a browser other than Windows Internet Explorer, consult the documentation for that browser.

Now that you have created a basic mail app, consider exploring the following paths:

  • Share your project with someone by choosing the Share Project (The Share Project button). "Napa" Office 365 Development Tools creates a copy of your project and provides you with a public link that you can give to anyone.

  • Publish your app by choosing the Publish button (Publish button).

    For more information, see How to: Publish an app for Office.

  • Learn more about mail apps for Outlook and the fundamentals for developing mail apps in Outlook.

  • Open your project in Visual Studio by choosing the Open in Visual Studio (Open in Visual Studio button) button. "Napa" Office 365 Development Tools automatically installs the necessary tools and opens your project in Visual Studio.

    You can also download and install these tools directly by visiting the Downloads page of the Apps for Office and SharePoint Dev Center. For more information, see Downloads.

  • Create a mail app by using Visual Studio. For more information, see How to: Create your first mail app for Outlook by using Visual Studio.

Show:
© 2014 Microsoft