Accelerator Creation Guide

Introduction

There are a lot of really cool services out there, and I think a lot of them would fit in really well with Accelerators. But even though there’s a lot of value to be had in creating Accelerators, I don’t think we’ve ever had a blog post explaining a step-by-step process for how to do it. I’m hoping this post will help with that.

I’ve been working on the feature for a while, so I’ve come up with some tips and best practices that have helped me become more efficient in building Accelerators. There are also a few mistakes I’ve seen (and made!) over and over again, so I’ll talk about those in the hope of making the development process a bit easier for everyone else out there.

Building an Accelerator

Accelerators streamline the common copy-navigate-paste operation by enabling users to send selected content from the current webpage to one of their favorite services. Fortunately, even though the feature is quite powerful, it’s actually quite easy to write code that uses it. Here’s a step-by-step guide for creating a simple Accelerator.

First, I’ve put up an Accelerator template, with sample information pre-loaded. All you need to do is swap out the sample information for yours. Note that you don’t need to be the service provider to build an accelerator that interacts with a service. If you can find the following information, then you can build an accelerator for virtually any service you want.

Here are the steps:

1. First, choose a <homepageUrl> for your Accelerator. This is an important field—all the other URLs in the manifest need to match its domain. Generally speaking, the top-level domain for your service is a good choice.

   Example:  <homepageUrl>http://www.example.com</homepageUrl>

2. Fill in the absolute path to your favicon into the <icon> field. One trick for doing so: right-click on the service page, view the source, and then search for an .ico file.

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

3. Under the <display> node, choose a <name> that’s descriptive of your service, while under 50 characters. We recommend that the name include the Accelerator category followed by the name of the service provider.

   <display>
   <name>Act with Example.com</name>
   </display>

4. Choose a “category” attribute for the <activity> field. I have another post on categories, but here are the ones we recommend:
   • Blog - A blog service that creates a new blog post based on a link or user-selection
   • Bookmark - A service adds a link to the user's personal bookmarks on the web
   • Define - A service that provides definitions based on a selection
   • Email - A service that provides email communication that can create a new email message
   • Find - service that finds related content within the scope of the site
   • Map - A service that provides map locations based on user-selection
   • Send - A service that converts web data into application data
   • Share – A service that shares a link (with optional comments) with the site community or network
   • Translate - A service that translates the current webpage or user-selection from one language to another

   Choosing a descriptive category is important for how Accelerators are grouped in the accelerator menu, and enables users to understand what your Accelerator will do before even experimenting with it.

5. Choose which contexts you want your Accelerator operate on—“selection”, “link”, and/or “document”—and then add them as attributes to one or more <ActivityAction> elements. For example:

   <activityAction context="selection"> … </activityAction>

   The link and document contexts could probably use a little extra explanation. The link context is activated when a user right-clicks on a link and then executes an accelerator from the resulting context menu. Similarly, the document context is activated when the user right-clicks on the page itself and uses the context menu, or goes to the Page menu and executes something under the “All Accelerators” submenu.

6. Next, fill in the “action” attribute of the <execute> element with the URL of the service you want to use. See the section below regarding variables to find out how to pass data into your service.

   Example:  <execute action="http://example.com/default.aspx?sel={selection}&amp;src=IE8">

7. Preview windows are a great way of delivering the output of a service to users as part of a more inline browsing experience—it’s also a great way of enticing them to visit a service’s home page.

   You can add a preview window via the <preview> element. I’ve written a section about preview below.

   Example:  <preview action="http://example.com/default.aspx?sel={selection}&amp;src=IE8">

The sections that follow provide some more in-depth specifics about the steps above.

Variables

IE exposes a number of variables for use with Accelerators. Here’s a list of the most commonly used variables:

• {selection} - the user selection within the webpage. Only available in selection context.
• {documentUrl} - the URL of the webpage where the Accelerator is invoked.
• {documentTitle} - represents the title of the webpage where the Accelerator is invoked.
• {link} - the URL of the user selected URL.
• {linkText} - the text of the user selected URL.

A full list of variables is available here.

There are two methods of passing these variables to a service through an Accelerator. The first is through the query string:

<execute action=”http://www.example.com/script.aspx?foo=bar”>

The second is through one or more <parameter> tags:

<execute action=”http://www.example.com/script.aspx”>

<parameter name=”foo” value=”bar” />

</execute>

Note that using a <parameter> element is the only way to insert data into the body of the HTTP request. You can use POST with a parameterized query string, as well, but any parameters you pass will show up in the URL. You can specify a GET or POST request via the “method��� attribute of the <activityAction> element.

Adding Preview

Preview is probably the most visible feature of Accelerators, and one of the most useful when implemented effectively.

Accelerator previews occupy a window of size 320x240 pixels. Given this, most Accelerators that use it create a special preview page for displaying it.

The key to an effective preview is returning the most relevant information possible based on the information sent by the user, then making sure it fits in the space provided by the preview window.

The Bing Maps Accelerator, for example, maps the location of a selected address using its own UI, scaled down to 320x240:

<preview method="get" action="http://www.bing.com/maps/geotager.aspx">
<parameter name="b" value="{selection}" />
<parameter name="clean" value="true" />
<parameter name="w" value="320" />
<parameter name="h" value="240" />
<parameter name="client" value="ie" />
<parameter name="format" value="full" />
</preview>

Note that you can pass variables to the preview window the same way you can for execution. For example, the Accelerator above uses {selection}.

Another handy rule of thumb is load time—if it takes your preview window takes more than half a second to load, you probably have too much in it, from a user experience perspective.

One trick that you might find useful involves using the mobile version of a service for a preview window. We deliberately sized the preview window to be compatible with mobile services.

Testing your Accelerator

Once you’re done building your Accelerator, it’s time to test it out. We have a Javascript API for installation. Some code like the following will create a link that brings up the Accelerator installation dialog:

<a href=”javascript:window.external.addService(‘myAccelerator.xml’)”>Install me</a>

In order for this to work, you’ll need a live web server—trying to open the link from a page on your local hard drive will result in an error. Any kind of local server will work fine, though—you can use Visual Studio’s ASP.NET server without issue, for example.

If everything goes well, you’ll see the normal Accelerator installation dialog. If it doesn’t, you’ll see something like this:

Whenever I see this dialog, there are a couple of mistakes that very frequently turn out to be the culprits.

Encoded Characters

The first has to do with XML itself. When dealing with query strings, it’s very common to pass in multiple arguments using the ampersand character. Unfortunately, this is a reserved character in XML, so using it as a literal in a query string will raise an error. Instead, you’ll need to escape it with “&amp;”, like this:

<execute action=”http://www.microsoft.com/testscript.aspx?foo=test&amp;bar=test”>

Matching Domain Requirement

The second has to do with the <homepageUrl> tag. To properly identify a service, we require that the URLs specified in <homepageUrl>, the action attribute of <execute>, and the action attribute of <preview> all share the same domain. If this isn’t the case, an error is raised.

Test Cases

Once you can install your Accelerator, there are a few scenarios you should definitely test, since they tend to break for a lot of the Accelerators already out there:

• Blank content – what happens when blank content is sent to your service? Do you have a graceful error message in place?
• Multi-line content – does your service handle line-breaks the way you think it will? You may want to make sure you parse for the carriage return-line feed sequence (“%0d%0a” in URL encoding) and replace it with something appropriate, like a space.
• Script – Some user selection may have JavaScript associated with it. If you specify HTML selection, then your service should be filtering this script on the server for security reasons.
• Large selections – Accelerators truncate GET requests at 2048 characters. If you’d like your accelerator to be able to handle more data, you might consider using POST.

Next Steps and Conclusion

Once you have a cool Accelerator built, feel free to upload it to the IE Gallery. It’s a great way to gain more exposure for your Accelerator and your service.

I hope this post was helpful in creating Accelerators. If you have any feedback on this post, any thoughts on Accelerators in general, or any cool creations you’d like to share, feel free to leave a comment.

Thanks!
Jon Seitel
Program Manager