Explore JavaScript API for Office: Messaging applications

This article is an in-depth discussion of part Fourth of the JavaScript API for Office, focusing on the available API portions of mail applications supported by Outlook and Outlook Web applications. Let's say you have a basic understanding of Office applications. If you have questions, read the "Application Overview for Office" (BIT.LY/12NBWHG) on the Developer Center documentation page for more information. The first part of this series, "Exploring the new JavaScript API for Office" (msdn.microsoft.com/m agazine/jj891051), provides an overview of the object model with Office objects as the root object. The Mailbox object in Office.context provides a portal to the vast majority of messaging application-specific features in the object model, which I'll start with.

The topic of this article is to introduce developers to the application of JavaScript API for Office in messaging applications. I also provided an online sister article in the following address, which dissected a sample mail application and provided source code: msdn.microsoft.com/m agazine/dn205107. Now I'm going to discuss the various features of the JavaScript API for Office, starting with more basic common techniques and then introducing more advanced concepts.

JavaScript API for Office basic functionality

The Mailbox object provides access to user profiles, the items currently selected by the user, forms that display items, and an Exchange Web Services (EWS) subset that manipulates items and folders in an e-mail mailbox. The Item object represents the selected message or appointment item. This object allows you to further access the built-in properties, custom properties, and attachments to the item.

Depending on the item type control activation can define rules in the manifest to determine when the mail application is activated. The item currently selected by the user and specified by Mailbox.item can be a "mail" (including meeting request, response, and cancellation) object or an Appointment object. Depending on your scenario, you can restrict the mail application to activate only certain types of items. The following XML example shows a itemis activation rule that restricts the mail application to activate only the message class items:

<rule xsi:type= "Itemis" itemtype= "message" 

/>

Using the JavaScript API for Office, you can use the ItemType property to confirm the type of the selected item:

Office.context.mailbox.item.itemType

An essential feature provided by the item access and property mail application is to access the currently selected item and its built-in properties.

The following JavaScript example shows how to access the selected item and its built-in properties subject:

       

   The Initialize function is required to all apps.
          Office.initialize = function () {
  //Check for the DOM to load.
          $ (document). Ready (function () {
    var item = Office.context.mailbox.item;
    var subject = Item.Subject;
    Continue processing the subject.
          });

Known entities Exchange Server recognizes some of the available entities, whether or not you use an entity-activated messaging application. If the entities exist within the subject or body of the selected item, Outlook and Outlook Web App extracts them and makes them available through the following JavaScript API methods:

Getentities method Getentitiesbytype (EntityType) method Getfilteredentitiesbyname (name) method

The supported entities include addresses, contacts, e-mail addresses, and so on.

Note that Outlook and Outlook Web Apps can extract only English strings, regardless of the default locale specified in the application manifest. They cannot extract the entities in the Sent Items folder. They can extract meeting suggestions for message types and cannot extract recommendations for appointment types.

Gets a match that can generate context activation to specify an activation rule that relies on regular expression matching (Itemhasregularexpressionmatch rules) or entity matching (itemhasknownentity rules) in selected items. You can get regular expression matches in the following ways: These methods are available in the parent Item object, which can be either a message type or an appointment type:

Getregexmatches method Getregexmatchesbyname (name) method

You can use the methods listed in the "Known entities" section to get specific entity matches. Note that no matter what type of activation rules the messaging application uses, these methods can always be used to get any entity matches.

The following example is an example of a itemhasregularexpressionmatch rule named Videourl that activates the mail application if the selected item is a message and the message body contains the URL of a video on YouTube:

          <rule xsi:type= "rulecollection" 

mode= "and" > <rule xsi:type= "itemis" itemtype=
  "message"/>
  <rule xsi:type= "Itemhasregularexpressionmatch" regexname= videourl "regexvalue=" http://www\.youtube\
    . com/watch\?v=[a-za-z0-9_-]

{one} "
    propertyname=" Body "/>
</Rule>

The following JavaScript code example shows how to use the Item.getregexmatches method to get a match for the preceding videourl regular expression:

          Office.initialize = function () {
  //Check for the DOM to load.
          $ (document). Ready (function () {
    //Get a array of string matches for the regular expression 

Videourl,
    //As S Pecified in the manifest.
          var matches = Office.context.mailbox.item.getRegExMatches

(). Videourl;
    Continue processing the matches for the regular expression.
          });