Export (0) Print
Expand All

Loading the DOM and runtime environment

apps for Office

The first thing an app must do before running its own custom logic is to make sure both the DOM and the apps for Office runtime environment have been loaded.

Last modified: July 18, 2014

Applies to: Access app for SharePoint | Excel 2013 | Excel 2013 RT | Excel 2013 SP1 | Excel Online | Exchange Online | Exchange Server 2013 | Exchange Server 2013 SP1 | Outlook 2013 | Outlook 2013 RT | Outlook 2013 SP1 | Outlook Web App | OWA for Devices | PowerPoint 2013 | PowerPoint 2013 RT | PowerPoint 2013 SP1 | PowerPoint Online | Project 2013 SP1 | Project Professional 2013 | 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

"Outlook" in this article refers to the Outlook rich client, Outlook RT, Outlook Web App, and OWA for Devices.

In this article
Startup of a content or task pane app
Startup of a mail app
Checking the load status
Additional resources

Figure 1. The flow of events involved in starting a content or task pane app in Excel, PowerPoint, Project, or Word

Flow of events when starting content/task pane app

   

The following summarizes the events involved in starting and initializing a content or task pane app:

  1. The user opens a document that already contains an app or inserts an app in the document.

  2. The Office host application reads the app's XML manifest from the Office Store, app catalog on SharePoint, or shared folder catalog it originates from.

  3. The Office host application opens the app's HTML page in a browser control.

    The next two steps, steps 4 and 5, occur asynchronously and in parallel. For this reason, your app's code must make sure that both the DOM and the app runtime environment have finished loading before proceeding.

  4. The browser control loads the DOM and HTML body, and calls the event handler for the window.onload event.

  5. The Office host application loads the runtime environment, which downloads and caches the JavaScript API for JavaScript library files from the content distribution network (CDN) server, and then calls the app's event handler for the initialize event of the Office object.

  6. When the DOM and HTML body finish loading and the app finishes initializing, the main function of the app can proceed.

Figure 2. The flow of events involved in starting a mail app in the Outlook rich client, Outlook Web App or OWA for Devices running on the desktop, tablet, or smartphone

Flow of events when starting Outlook mail app

   

The following summarizes the events involved in starting a mail app in Outlook:

  1. When Outlook starts, Outlook reads the XML manifests for mail apps that have been installed for the user’s email account.

  2. The user selects an item in Outlook.

  3. If the selected item satisfies the activation conditions of a mail app, Outlook activates the app and makes its button visible in the user interface.

  4. If the user clicks the button to start the mail app, Outlook opens the HTML page in a browser control. The next two steps, steps 5 and 6, occur in parallel.

  5. The browser control loads the DOM and HTML body, and calls the event handler for the onload event.

  6. Outlook calls the event handler for the initialize event of the Office object of the app.

  7. When the DOM and HTML body finish loading and the app finishes initializing, the main function of the app can proceed.

One way to check that both the DOM and the runtime environment have finished loading is to use the jQuery .ready() function: $(document).ready(). For example, the following initialize event handler function makes sure the DOM is first loaded before the code specific to initializing the app runs. Subsequently, the initialize event handler proceeds to use the Mailbox.item property to obtain the currently selected item in Outlook, and calls the main function of the app, initDialer.

Office.initialize = function () {
    // Checks for the DOM to load.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        var mailbox = Office.context.mailbox;
        _Item = mailbox.item;
        initDialer();
    });
}

This same technique can be used in the initialize handler of any app for Office.

The phone dialer sample mail app shows a slightly different approach using only JavaScript to check these same conditions. For a description of the code, see the JavaScript implementation section of Sample: Create a mail app for Voice Over IP dialing in Outlook.

Important: Even if your app has no initialization tasks to perform, you must include at least a minimal Office.initialize event handler function like the following example.

Office.initialize = function () {
};

If you fail to include an Office.initialize event handler, your app may raise an error when it starts. Also, if a user attempts to use your app with an Office Online web client, such as Excel Online, PowerPoint Online, or Outlook Web App, it will fail to run.

If your app includes more than one page, whenever it loads a new page that page must include or call an Office.initialize event handler.

Show:
© 2014 Microsoft