Microsoft Developer Network

When an application needs to expose specific functionality to another source, it typically creates an interface. When a Web site exposes specific functionality to users, it also creates a standard way of accessing that service. In many cases, Web services can provide information based only on a few pieces of information from the browser (such as a word to define, or a street address to map) passed in the URL or as form parameters. In the absence of a standard way of doing this, users are required to copy and paste this information manually.

In Internet Explorer 8, "Activities" are contextual menu options that can quickly access a Web service from any Web page. Users can install Activities from the Internet Explorer 8 Activity Gallery  or through any Web site that advertises them. Activities make it easier to copy information from one Web page to another. This article describes how to define and deploy XML-based Activities.

• Introduction
• OpenService Activity Format
• Categories
• Variables
• Preview
• Localization
• Installation
• Related Topics

Introduction

Activities enable two types of scenarios: users can "preview" information without leaving a Web page, or they can "execute" (or send) content directly to a Web service or application.

The user can "preview" an address by selecting text and hovering over a map Activity. When a user reads an interesting article and wants to blog about it, the user selects a few lines of text and sends it to the blog Activity with a click. This action "executes" the desired Activity by navigating to the user's blog site with the selected portion of the article already available in the edit field.

Figure 1: Mapping an address with a "preview" Activity.

Activities are declarative. They use HTTP submission to communicate between the browser and the Web site. XML-based Activities are easy to create, test, and deploy to users.

OpenService Activity Format

An Activity is described through an XML file format called an OpenService Activity manifest. The XML file describes the format of the HTTP request to the Web server. This section explains the elements, attributes, and values of the OpenService Activity file format.

os:openServiceDescription

<os:openServiceDescription
    xmlns:os="http://www.microsoft.com/schemas/openservicedescription/1.0">

The root element of the OpenService Activity file is os:openServiceDescription. The xmlns attribute is required and must be http://www.microsoft.com/schemas/openservicedescription/1.0.

os:homepageUrl

<os:homepageUrl>http://maps.example.com</os:homepageUrl>

Required. The os:homepageUrl element defines the main URL of the Activity—where the user can access the service through browsing. All URLs declared in the OpenService Activity file must use the same domain as that of the os:homepageUrl.

os:display

<os:display> 

Required. The os:display element describes how the Activity is presented to the user. It contains both the os:name and os:icon elements.

os:name

<os:name>Map with MyMap</os:name>

Required. The os:name of the Activity that is displayed to the user on the context menu. Activity names should lead with a verb followed by the service provider. For example, "Map on Windows Live" or "Define with Encarta."

os:icon

<os:icon>http://www.example.com/favicon.ico</os:icon>

Optional. The os:icon element provides a URL to a 16 x 16 pixel icon for this Activity. The top-level domain must match the os:homepageUrl.

os:description

<os:description>Map addresses easily with MyMap.</os:description> 

Optional. The os:description element provides a longer description for the Activity.

os:activity

<os:activity category="map">

Required. The os:activity element contains all of the functionality of an Activity.

Each os:activity must specify a category attribute to describe the type of functionality that it offers. Activities are arranged by category in the browser's context menu so users can quickly access the type of operation that they want. Users can select the default Activity for a given category when the Activity is installed or by using the Manage Add-ons dialog box. Default Activities are presented on the browser's context menu, and all others are listed in a submenu. See the Categories section for more information.

os:activityAction

<os:activityAction context="selection">

Required. Each os:activityAction specifies the interaction with the service provider based on the selected data type. The optional context attribute specifies the data type. Default is "selection."

os:preview

<os:preview action="http://maps.example.com/preview.php?addr={selection}" />

Optional. The os:preview element defines the content of the HTML window displayed when the user hovers over the Activity. It shares the same attributes and child elements as the os:execute element. Read the Preview section for more details.

The URL of the action attribute can contain variable names that are replaced when the command is executed. For more information, see the section on Variables.

os:execute

<os:execute action="http://maps.example.com/" method="get"> 

Required. The os:execute element specifies the main action triggered when the user invokes the Activity. Like os:preview, it can contain replacement variables in the action attribute or as separate os:parameter elements.

The following attributes are defined for os:execute and os:preview:

os:parameter

<os:parameter name="addr" value="{selection}" type="text" /> 

Optional. The os:parameter element provides an alternative way to express the values to use. The required name and value attributes define string inputs that are specific to the service and typically refer to Activity variables. See the Variables section for a list.

The optional type attribute is used to transform the "{selection}" variable into HTML or plaintext. Default is "text."

Putting all these pieces together, the following Activity describes the interaction between the browser and a mapping service.

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="http://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.example.com</os:homepageUrl>
    <os:display>
        <os:name>Map with MyMap</os:name>
        <os:icon>http://www.example.com/favicon.ico</os:icon>
        <os:description>Map addresses easily with MyMap.</os:description>
    </os:display>
    <os:activity category="map">
        <os:activityAction context="selection">
            <os:preview action="http://maps.example.com/preview.php?addr={selection}" />
            <os:execute action="http://maps.example.com/" method="get">
                <os:parameter name="addr" value="{selection}" type="text" /> 
            </os:execute>
        </os:activityAction>
    </os:activity>
</os:openServiceDescription> 

Categories

Activities are grouped by type so that users can quickly access the task that they want. The user sets the default Activity for a given category at the time of installing the Activity or through the Manage Add-ons dialog box.

Examples of services that exist today:

• add: del.icio.us, Digg, Reddit
• blog: Windows Live Spaces, Windows Live Writer, Blogger
• define: Encarta, Wikipedia, Dictionary.com
• map: Windows Live Map, Google Maps, Yahoo! Maps, MapQuest
• send: Windows Live Mail, Gmail, Yahoo! Mail
• translate: Windows Live Translation, AltaVista's Babel Fish, Google Translation

If the Activity doesn't fit a recommended category, you can define your own.

<os:activity category="share">  

The category should be a verb that the user can recognize and that it is not tied to a specific brand or application so that other Activities of similar functionality can use the category.

Variables

Document properties and content are sent to the Activity service provider through HTTP GET and/or POST submission. These properties are expressed as replacement variables that can be passed as form fields or as URL parameters. Variables can be specified directly in the action attribute of os:execute and os:preview, or within os:parameter elements.

Cookies can be used to store state and user credentials.

The following variables are available:

Always enclose variable names in curly braces {}; for example {selection}.

Placing a "?" after the variable name indicates that it is optional; for example, {documentTitle?}. If the variable is optional and the value is empty, then the empty string is used as a replacement value. If the variable is not indicated as optional and the value is empty, the entire os:parameter element or action attribute is discarded.

URL Parameters

It is possible to describe the inputs to a service through the URL template.

<os:execute method="get"
    action="http://example.com/service.aspx?url={documentUrl}&title={documentTitle?}" />  

In this example, documentUrl is a required variable and documentTitle is optional. If the value of documentTitle is empty, then an empty string is used for the title parameter on the URL. However, if the value of documentUrl is empty, then the Activity returns an error.

Form-based Parameters

The os:parameter elements specifies the inputs to a service as name/value pairs. This is useful for making HTTP post requests or if the HTTP get request is longer than the URL character limit.

This following parameters pass the same values as the preceding example.

<os:execute method="post" action="http://example.com/service.aspx>
    <os:parameter name="url" value="{documentUrl}" />
    <os:parameter name="title" value="{documentTitle?}" />
</os:execute>  

If a required (non-optional) parameter is undefined in the current context, the parameter is ignored. For example, if {selection} were specified but not available, the entire parameter would be dropped from the request.

Selection Types

Selected text can be interpreted in two ways: as plain "text" (the default), or as "html" markup. The selection type is set on the os:parameter element.

Selected text is encoded as required by the selected HTTP request method. On the URL, this means that non-alphanumeric characters are percent-encoded and line breaks are passed as "CR LF" pairs (%0D%0A). If the user chooses to send multiple lines of text in a selection, the Web service must be able to handle the "CR LF" gracefully.

Preview

An Activity can provide an optional HTML preview that is displayed when the user hovers over an Activity on the menu. Previews are useful to quickly obtain a map, in-place definition or translation, content ratings, or links to related content.

The preview window should be used for lightweight interaction. It can contain links that send the user to a full Web page for more information. Preview does not prevent the user from clicking the Activity menu item.

Preview functionality is expressed in the OpenService Activity file by the os:preview element. When the user hovers over the menu item, Internet Explorer makes an HTTP request and displays the resulting HTML within the HTML preview window.

Size

The preview window is limited to 240 height and 320 width on a 96 dots per inch (dpi) display. All content outside of the region is cut off. It is not recommended to insert content that would display controls with scrollbars. The preview functionality is intended for the user to quickly view the information without too much interaction.

Content

The preview limits script resources to the same domain as the os:homepageUrl of the Activity. It also supports Microsoft ActiveX controls if they are already installed by the user for the domain.

Navigation

The user can navigate within the preview window using links. To send the user to a full Web page, set the link to open in a new window. This can be done in two ways:

1. Set the target attribute to be "_blank" as part of the hyperlink. When invoked by the user, the browser will open this as a new tab.
   <a href="gotosite.html" target="_blank">view full site</A>  

2. Use the open method and set the input URL to the site to which you would like the user to navigate.
   <FORM>
   <INPUT type="button" value="View Full Site" 
        />
   </FORM>  

Localization

A single OpenService Activity file maps to a single locale. If the service supports multiple locales, it will need to expose a separate XML file for each locale. The Web page that advertises Activities should use the browser's locale to display the correct XML file for the user to install. To allow multiple locales to be installed at one time, the value of the category element should also be localized.

English Example

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="http://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.yahoo.com</os:homepageUrl>
    <os:display>
        <os:name>Map with Yahoo!</os:name>
    </os:display>
    <os:activity category="map">
    ...
</os:openServiceDescription>  

Spanish Example

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="http://www.microsoft.com/schemas/openservicedescription/1.0">
    <os:homepageUrl>http://maps.yahoo.com</os:homepageUrl>
    <os:display>
        <os:name>Mapa con Yahoo!</os:name>
    </os:display>
    <os:activity category="map-es">
    ...
</os:openServiceDescription>  

If a user has Activities from multiple locales installed, each of them is displayed.

Installation

Internet Explorer 8 installs Activities through the Service Guide  Web page. Web sites can also promote their own Activities.

The first step is to publish the OpenService Activity XML file on a Web server. Installing an Activity XML file from the local system is not allowed; however, for testing purposes, you can use the Microsoft Internet Information Server (IIS) localhost or ASP.NET server of Microsoft Visual Studio.

Next, add an Install Activity button that calls AddService when clicked.

<button 
    >
    Install Activity</button> 

It is possible to verify whether the user currently has the Activity installed by calling IsServiceInstalled. In order to perform this check, the domain of the Web page must match the domain of the URLs specified in the OpenService Activity file.

window.external.IsServiceInstalled('http://www.example.com/Activity.xml');  

If the return value is false, the Activity is not installed.

Related Topics

• Internet Explorer 8 Activity Gallery