How to: Insert data in the body when composing an appointment or message in Outlook

apps for Office

Learn how to insert data in the body of the appointment or message that the user is composing in Outlook.

Last modified: July 10, 2014

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

   Office.js: v1.1

   Apps for Office manifests schema: 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
Prerequisites for inserting data in the body of a compose form
To insert data at the current cursor position
To insert data at the beginning of the item body
Additional resources

The JavaScript API for Office provides asynchronous methods (getTypeAsync, prependAsync and setSelectedDataAsync of the Body object) to get the body type and insert data in the body of an appointment or message that the user is composing. These asynchronous methods are available to only compose apps. To use these methods, make sure you have set up the app manifest appropriately so that Outlook activates your mail app in compose forms, as described in the section Setting up mail apps for compose forms of Create mail apps for compose forms in Outlook.

In Outlook, a user can create a message in text, HTML, or Rich Text format. In a compose app, you can insert text or HTML data in the compose form for an appointment or message. While inserting text data into an HTML compose form is fine and Outlook would apply the appropriate formatting for the inserted text, you cannot insert HTML data into a compose form created in text format. So if the item being composed is a message, before you insert HTML data, you should first use getTypeAsync to verify the data type of the message. You can then specify the appropriate type of data to insert in prependAsync or setSelectedDataAsync, as the coercionType parameter. The coercionType parameter is optional; if you don’t specify an argument, prependAsync and setSelectedDataAsync assume the data to insert is in text format. On the other hand, attempting to insert HTML data in a text message body returns an error.

Because getTypeAsync is asynchronous, if your code relies on the result of getTypeAsync before calling prependAsync or setSelectedDataAsync, provide a callback method for getTypeAsync. In the callback method, check for the completion and success of getTypeAsync before calling prependAsync or setSelectedDataAsync. In general, the callback method for getTypeAsync is optional.

Note that as with most asynchronous methods in the JavaScript API for Office, getTypeAsync, prependAsync and setSelectedDataAsync take optional input parameters. For more information about specifying these optional input parameters, see passing optional parameters to asynchronous methods in Asynchronous programming in apps for Office.

This section shows a code sample that uses getTypeAsync to verify the body type of the item that is being composed, and then uses setSelectedDataAsync to insert data in the current cursor location.

You can pass a callback method and any of its parameters as optional input parameters to getTypeAsync, and get any status and results in the asyncResult output parameter. If the method succeeds, you can get the type of the item body in the AsyncResult.value property, which is a value in the Office.MailboxEnums.BodyType enumeration.

You must pass a data string as an input parameter to setSelectedDataAsync. Depending on the type of the item body, you can specify this data string in text or HTML format accordingly. As mentioned above, you can optionally specify the type of the data to be inserted in the coercionType parameter. In addition, you can provide a callback method and any of its parameters as optional input parameters.

If the user hasn’t placed the cursor in the item body, setSelectedDataAsync inserts the data at the top of the body. If the user has selected text in the item body, setSelectedDataAsync replaces the selected text by the data you specify. Note that setSelectedDataAsync can fail if the user is simultaneously changing the cursor position while composing the item. The maximum number of characters you can insert at one time is 1,000,000 characters.

This code sample assumes a rule in the app manifest that activates the mail app in a compose form for an appointment or message, as shown below.

<Rule xsi:type="RuleCollection" Mode="Or">
  <Rule xsi:type="ItemIs" ItemType="Appointment" FormType="Edit"/>
  <Rule xsi:type="ItemIs" ItemType="Message" FormType="Edit"/>
</Rule>

var item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Set data in the body of the composed item.
        setItemBody();
    });
}


// Get the body type of the composed item, and set data in 
// in the appropriate data type in the item body.
function setItemBody() {
    item.body.getTypeAsync(
        function (result) {
            if (result.status == Office.AsyncResultStatus.Failed){
                write(result.error.message);
            }
            else {
                // Successfully got the type of item body.
                // Set data of the appropriate type in body.
                if (result.value == Office.MailboxEnums.BodyType.Html) {
                    // Body is of HTML type.
                    // Specify HTML in the coercionType parameter
                    // of setSelectedDataAsync.
                    item.body.setSelectedDataAsync(
                        '<b> Kindly note we now open 7 days a week.</b>',
                        { coercionType: Office.CoercionType.Html, 
                        asyncContext: { var3: 1, var4: 2 } },
                        function (asyncResult) {
                            if (asyncResult.status == 
                                Office.AsyncResultStatus.Failed){
                                write(asyncResult.error.message);
                            }
                            else {
                                // Successfully set data in item body.
                                // Do whatever appropriate for your scenario,
                                // using the arguments var3 and var4 as applicable.
                            }
                        });
                }
                else {
                    // Body is of text type. 
                    item.body.setSelectedDataAsync(
                        ' Kindly note we now open 7 days a week.',
                        { coercionType: Office.CoercionType.Text, 
                            asyncContext: { var3: 1, var4: 2 } },
                        function (asyncResult) {
                            if (asyncResult.status == 
                                Office.AsyncResultStatus.Failed){
                                write(asyncResult.error.message);
                            }
                            else {
                                // Successfully set data in item body.
                                // Do whatever appropriate for your scenario,
                                // using the arguments var3 and var4 as applicable.
                            }
                         });
                }
            }
        });

}

// Writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Alternatively, you can use prependAsync to insert data at the beginning of the item body and disregard the current cursor location. Other than the point of insertion, prependAsync and setSelectedDataAsync behave in similar ways:

  • If you are prepending HTML data in a message body, you should first check for the type of the message body to avoid prepending HTML data to a message in text format.

  • Provide the following as input parameters to prependAsync: a data string in either text or HTML format, and optionally the format of the data to be inserted, a callback method and any of its parameters.

  • The maximum number of characters you can prepend at one time is 1,000,000 characters.

The following JavaScript code is part of a sample mail app that is activated in compose forms of appointments and messages. The sample calls getTypeAsync to verify the type of the item body, inserts HTML data to the top of the item body if the item is an appointment or HTML message, otherwise inserts the data in text format.

var item;

Office.initialize = function () {
    item = Office.context.mailbox.item;
    // Checks for the DOM to load using the jQuery ready function.
    $(document).ready(function () {
        // After the DOM is loaded, app-specific code can run.
        // Insert data in the top of the body of the composed 
        // item.
        prependItemBody();
    });
}

// Get the body type of the composed item, and prepend data  
// in the appropriate data type in the item body.
function prependItemBody() {
    item.body.getTypeAsync(
        function (result) {
            if (result.status == Office.AsyncResultStatus.Failed){
                write(asyncResult.error.message);
            }
            else {
                // Successfully got the type of item body.
                // Prepend data of the appropriate type in body.
                if (result.value == Office.MailboxEnums.BodyType.Html) {
                    // Body is of HTML type.
                    // Specify HTML in the coercionType parameter
                    // of prependAsync.
                    item.body.prependAsync(
                        '<b>Greetings!</b>',
                        { coercionType: Office.CoercionType.Html, 
                        asyncContext: { var3: 1, var4: 2 } },
                        function (asyncResult) {
                            if (asyncResult.status == 
                                Office.AsyncResultStatus.Failed){
                                write(asyncResult.error.message);
                            }
                            else {
                                // Successfully prepended data in item body.
                                // Do whatever appropriate for your scenario,
                                // using the arguments var3 and var4 as applicable.
                            }
                        });
                }
                else {
                    // Body is of text type. 
                    item.body.prependAsync(
                        'Greetings!',
                        { coercionType: Office.CoercionType.Text, 
                            asyncContext: { var3: 1, var4: 2 } },
                        function (asyncResult) {
                            if (asyncResult.status == 
                                Office.AsyncResultStatus.Failed){
                                write(asyncResult.error.message);
                            }
                            else {
                                // Successfully prepended data in item body.
                                // Do whatever appropriate for your scenario,
                                // using the arguments var3 and var4 as applicable.
                            }
                         });
                }
            }
        });

}

// Writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}
Show:
© 2014 Microsoft