How to: Create your first task pane app by using "Napa" Office 365 Development Tools

apps for Office

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

Run button Run this sample now!

Last modified: June 30, 2014

Applies to: Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | Project 2013 | Project 2013 SP1 | Word 2013 | Word 2013 RT | Word 2013 SP1

   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 task pane app by using Visual Studio or a text editor. If you’re not sure which tool to use, read the Development basics.

In this article
Prerequisites
Overview
Create a basic app for Office
Change the properties of the app
Capture the text that users select in a document
Show images in the task pane app
Additional resources

You need the following components to complete this walkthrough:

  • An 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 task pane app by using the "Napa" Office 365 Development Tools app. The app that you’ll create shows a list of images. When users select text in the open document, a list of images that are tagged with the selected text are retrieved from Flickr and displayed in the task pane.

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

To create a basic app for Office

  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 Step 2.

    Figure 1. New project tile

    Add New Project tile
  2. Choose the Task Pane app for Office tile, name the project MyFirstTaskPaneApp, and then choose the Create button.

    Figure 2. task pane app tile

    The New Project dialog box in Napa

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

Run the sample app for Office

To run the code

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

    The task pane app is packaged, deployed, and installed on your Office 365 developer site.

    You may be prompted to log in to your Office 365 account.

    Your app appears in the task pane of Excel so that you can experiment with its features.

  2. When you are ready to move on, close Excel.

Note Note

By default, "Napa" Office 365 Development Tools projects are configured to open in Excel.

To change the properties of the app

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

    The properties of the app for Office appear.

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

    Figure 7. Properties dialog box

    The Properties dialog box

    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. The Start Page property points to the page that appears in the app for Office when you start the project. For this walkthrough, we are going to use the default page that comes with your project. However, you can add new pages to your project set the Start Page property to any of those pages. For an example, see How to: Create your first content app for Excel by using "Napa" Office 365 Development Tools.

  3. Choose the Run tab.

  4. Choose the Microsoft Word option button so that "Napa" Office 365 Development Tools opens Word when you run the project.

    Figure 8. The Run tab of the Properties dialog box

    The Run tab of the Properties dialog box.
  5. 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 an app for Office. It does not show all of the possible settings of an app for Office. If your scenario requires you to modify settings that do not appear in the Properties editor, you can open your project in Visual Studio and edit the manifest file directly.

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

Your task pane app can get the value of text that users select in the document.

To capture selected text

  1. On the side of the page, choose Home.html.

    Figure 7. The Home html file

    The default html page of the project

    The default webpage appears in the code editor.

  2. Add a section named Images beneath the Content section and change the get-data-from-selection button label to "Search Flickr". The code should now appear as follows.

    <body>
        <!-- Page content -->
        <div id="content-header">
            <div class="padding">
                <h1>Welcome</h1>
            </div>
        </div>
        <div id="content-main">
            <div class="padding">
                <p><strong>Add home screen content here.</strong></p>
                <p>For example:</p>
                <button id="get-data-from-selection">Search Flickr</button>
                
                <p style="margin-top: 50px;">
                    <a target="_blank" href="http://go.microsoft.com/fwlink/?LinkId=276812">
                        Find more samples online...
                    </a>
                </p>
            </div>
        <div>
            <div id="Images" style="height:800px; overflow:scroll">
        </div>
    
        </div>
    </body>
    
    
    
  3. On the side of the page, choose Home.js.

    The Home.js file appears in the code editor.

    Note Note

    You can use the Office.initialize method to define other actions that run when the app for Office starts. If you want your code to access the Office object model, this function is the best place to put that code. If you add that code to the Onload event of the default HTML file, that event might be raised before the Office object model is initialized, and an error might occur.

  4. In the Home.js file, modify the getDataFromSelection function by adding the following line of code: showImages(result.value);

    After you’ve added the code, your function will appear as follows.

        function getDataFromSelection() {
            Office.context.document.getSelectedDataAsync(Office.CoercionType.Text,
                function (result) {
                    if (result.status === Office.AsyncResultStatus.Succeeded) {
                        showImages(result.value);
                   } else {
                        app.showNotification('Error:', result.error.message);
                    }
                }
            );
        }
    

    This code gets the value of the text that the user selects and calls a method to display images for the selected text. You will define that method in the next procedure.

    NoteNote

    Like other methods in the JavaScript API for Office, this method is asynchronous in that it doesn’t prevent the app for Office from performing other operations while this method runs.

    The call to getSelectedDataAsync passes an anonymous function with a parameter, named result, as the callback argument. When the callback function runs, it uses the result parameter to access the value property of the AsyncResult object to display the data in the cell that the user chose.

In this procedure, you will use the Flickr API to search for images that were tagged with the text that is selected in the document.

To show images in the app

  • In the Home.js file, add the following code. This code adds a function that shows images that relate to the selected text.

    function showImages(selectedText) {
        
        $('#Images').empty();
    
        var parameters = {
            tags: selectedText,
            tagsmode: "any",
            format: "json"
        };
    
        $.getJSON("https://secure.flickr.com/services/feeds/photos_public.gne?jsoncallback=?",
                        parameters,
                        function (results) {
                            $.each(results.items, function (index, item) {
                                $('#Images').append($("<img />").attr("src", item.media.m));
                            });
                        }
        );
    }
    

Run it!

To run the code

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

    The task pane app is packaged, deployed, and installed on your Office 365 developer site.

  2. Choose the Launch your app in a Microsoft Word document link.

    Note Note

    You might have to log-in to your Office 365 account in the task pane.

  3. In the Launch App window, choose the Launch your app in a Microsoft Word document link.

  4. In Word, choose the Enable Editing button.

    Word opens and your app appears in the task pane. No data appears inside of the task pane because you haven't selected any text in the document yet.

  5. In open document, type any sentence that you want.

  6. Select any word in that sentence.

  7. In the task pane, choose the Search Flickr button.

    A list of images that are tagged with the selected word on Flickr appear in the task pane.

  8. Close Word.

Now that you’ve created a basic content app for Word, 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.

  • Create a content app for Excel by using "Napa" Office 365 Development Tools. Learn how to get information from a worksheet, put information into selected cells in a worksheet, and bind to cells in a worksheet. For more information, see How to: Create your first content app for Excel by using "Napa" Office 365 Development Tools.

  • 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 task pane app for Excel or Word by using Visual Studio. For more information, see How to: Create your first task pane or content app by using Visual Studio.

Show:
© 2014 Microsoft