Share via

OpenService Accelerators Developer Guide

  • Article

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

This article contains the following sections:

  • Key Points
  • Introduction
  • Categories
  • Variables
    • URL Template Parameters
    • Form-based Parameters
    • Selection Types
    • Security Implications of Document Variables
  • Preview
    • Size
    • Content
    • Navigation
  • Localization
    • English Example
    • Spanish Example
  • Installation
  • OpenService Accelerator Format
  • Related topics

Key Points

  • Accelerators appear on the right-click shortcut menu of the Web page in Internet Explorer 8. They are grouped by function so that users can quickly access the task that they want.
  • Accelerators enable two types of scenarios: users can "preview" information without leaving a Web page or "execute" to send content directly to an application or Web service.
  • An XML-based Accelerator uses XML file to describe the format of HTTP requests to the Web server. Data from the target context (selection, link, or document) is passed as variables in URL parameters and/or form data.
  • To install XML-based Accelerators from a Web site, use the window.external.AddService method to prompt the user.

Introduction

Accelerators let you act on data in a Web page. You can select a few lines of text and send it to a blog or email it with a click. Using a previously installed Accelerator, this action "executes" the desired activity by navigating to the desired Web site with the selected portion of the article already available in the edit field. You can also act on data without going to another Web site using "preview" Accelerators; for example, you can translate a word or map an address. Hover over an Accelerator with your mouse to view the preview window, as shown in the following screen shot.

Figure 1: Mapping an address with a preview Accelerator.

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

Categories

Accelerators are grouped by function so that users can quickly access the task that they want. You can set the default Accelerator for a given category when you install the Accelerator 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, Google Mail, Yahoo! Mail
  • Translate: Windows Live Translation, AltaVista's Babel Fish, Google Translation

If the Accelerator 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 is not tied to a specific brand or application so other Accelerators of similar functionality can use the category. Additionally, because the value of the category attribute is used by Manage Add-ons to organize Accelerators in groups, it should be human-readable and capitalized appropriately.

Variables

Document properties and content are sent to the Accelerator service provider through HTTP GET and/or POST submissions. 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 (called a "URL template"), or within os:parameter elements.

Note  You can use cookies to store state and user credentials.

 

The following variables are available:

Variable Context Description
{documentUrl} All† The href of the document.
{documentTitle} All The title of the document, if available.
{documentDomain} All Effective second-level domain from the document's href.
{documentHost} All Fully qualified domain from the document's href.
{selection} selection Currently selected text.
{link} link The href of the selected link.
{linkText} link The innerText of the selected link.
{linkRel} link The rel of the selected link, if available.
{linkType} link The type of the selected link, if available.
{linkDomain} link Effective second-level domain from the link's href.
{linkHost} link Fully qualified domain from the link's href.

 

† Not available during preview outside of document context.

A few things to remember about variables:

  • Always enclose variable names in curly braces {}; for example {selection}. To specify a literal curly brace character in the request, escape it with a backslash, such as \{{selection}\}.
  • Placing a "?" after the variable name indicates that it is optional; for example, {documentTitle?}.
  • If any required (non-optional) variable in the URL template is not available (for example, trying to execute an Accelerator that includes {linkRel} in the action attribute against a link with no rel attribute) the Accelerator cannot be executed and its entry in the shortcut menu is dimmed.
  • If any os:parameter element has an empty value for any reason, it will not appear in the request.

URL Template Parameters

URL parameters convey information from the Web page to the service. In a get request, all parameters are passed on the URL whether you specify them as os:parameter elements or add variables directly to the URL template.

Note  If you specify os:parameter elements, the URL parameters following the question mark (?) in the URL template will not be used.

 

Make sure to correctly identify optional variables in the URL template. Consider the following template:

<os:execute method="get"
    action="http://example.com/service.aspx?url={documentUrl}&amp;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 required value of documentUrl is empty, then the Accelerator will be unavailable (grayed out) on the Accelerator shortcut menu.

Form-based Parameters

In a post request, the os:parameter elements specify the name/value pairs of the form input. This following example passes the same values as the preceding one.

<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, the parameter is ignored. For example, if {selection} were specified but not available, the 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.

Security Warning: Web services that accept HTML as input must be correctly configured to handle arbitrary HTML input. Web services that allow arbitrary input without filtering or encoding are susceptible to HTML/script injection attacks.

If you create an Accelerator that uses a {selection} parameter of type html, make sure the Web service is set up to correctly interpret it. Consider the following service that naively accepts text from the query string of the URL and places it directly in the value attribute of a text input by using Active Server Pages (ASP):

<input name="txtQueryString" size="60" maxlength="65000" value="<%=Request.QueryString("q")%>" />

In this case, if the service were to accept HTML from the Accelerator, it is possible that the incoming text could prematurely close the input tag and rewrite portions of the Web page. Even worse, malicious script or SQL statements injected in this fashion would be allowed to run in the context of the domain that hosts the Web site. To read more about how to validate input to protect your application from injection attacks, see How To: Protect From Injection Attacks in ASP.NET. See also the discussion of client-side script injection using innerHTML.

Security Implications of Document Variables

Because document variables could be used to track users without their knowledge, these variables cannot be used in certain contexts.

  • Document variables cannot be used by a preview Accelerator except in the document context.
  • The transmission of document variables is prohibited between HTTP and Secure Hypertext Transfer Protocol (HTTPS), and from a security zone of lesser restriction to a higher one, such as from a page in the intranet zone to a server on the Internet.

If a required document variable is unavailable for any reason, the Accelerator entry in the shortcut menu will be dimmed.

Preview

An Accelerator can provide an optional HTML preview that is displayed when the user hovers over an Accelerator 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 Accelerator menu item.

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

Size

The preview window is limited to 320 width and 240 height 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 Accelerator. It also supports Microsoft ActiveX controls if they are already installed by the user for the domain.

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" 
    onClick="window.open(gotosite.html')" />
</FORM>

Localization

An OpenService Accelerator file can only support a single locale. If the service supports multiple locales, it will need a separate XML file for each language. In addition to using locale-appropriate text for os:name and os:description, the value of the category attribute must also be localized into the user's language. The Web page that advertises these Accelerators should use the accept-language header of the request to determine and display the correct XML file for the user to install.

English Example

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://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="https://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="Mapa">
    ...
</os:openServiceDescription>

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

Installation

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

The first step is to publish the OpenService Accelerator XML file on a Web server. Installing an Accelerator 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 Accelerator button that calls AddService when clicked.

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

If the return value is 0, the Accelerator is not installed.

OpenService Accelerator Format

This section explains the elements, attributes, and values of the OpenService Accelerator file format.

Example

The following XML-based Accelerator describes the interaction between the browser and a mapping service.

<?xml version="1.0" encoding="UTF-8"?>
<os:openServiceDescription
    xmlns:os="https://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>

os:openServiceDescription

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

The root element of the OpenService Accelerator file is os:openServiceDescription. The xmlns attribute is required and must be https://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 Accelerator—where the user can access the service through browsing. All URLs declared in the OpenService Accelerator file must use the same domain as that of the os:homepageUrl.

os:display

<os:display>

Required. The os:display element describes how the Accelerator 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 Accelerator that is displayed to the user on the context menu. Accelerator 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 Accelerator. The domain name used 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 Accelerator that is displayed in the Manage Add-ons dialog box.

os:activity

<os:activity category="Map">

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

Each os:activity must specify a category attribute to describe the type of functionality that it offers. Accelerators 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 Accelerator for a given category when the Accelerator is installed or by using the Manage Add-ons dialog box. Default Accelerators 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 target of the Accelerator. The optional context attribute specifies the target. Default is selection.

Context Description
document The current document. Always available.
selection Default. The selected text. The Accelerator is only available when clicking a selected region.
link A hyperlink. The Accelerator is available for links only.

 

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 Accelerator. 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 Accelerator. 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:

Attribute Required? Description
action Yes The URL template to use for HTTP submission.
method No The type of HTTP method to use (get, post). Default is get.
enctype No The type of content that is submitted to the server. Default is application/x-www-form-urlencoded.
accept-charset No The charset used for submission. Default is utf-8.

 

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 Accelerator 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.

Add Accelerator Providers to Internet Explorer 8