Accelerator Creation Guide

Article
12/23/2009

IntroductionThere 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:

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>https://www.example.com</homepageUrl>
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>https://www.example.com/favicon.ico</icon>
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>
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.
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.
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="https://example.com/default.aspx?sel={selection}&src=IE8">
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="https://example.com/default.aspx?sel={selection}&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=”https://www.example.com/script.aspx?foo=bar”>

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

<execute action=”https://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="https://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:

Accelerator could not be installed dialog.

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 “&”, like this:

<execute action=”https://www.microsoft.com/testscript.aspx?foo=test&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

Comments

Anonymous
January 01, 2003
@accelerator proves address bar failure TOTAL BLOG TROLL FAILURE!
Anonymous
December 23, 2009
The comment has been removed
Anonymous
December 23, 2009
Great article! Nice to see content about the features of IE8 ;) Keep up the great job with IE9 :D
Anonymous
December 23, 2009
Great guide! Is there also a way to add a scrollbar into a accelerator? I want to build a YouTube Accelerator, which navigages to the mobile-site of YouTube. But the probelm is, that I can't scroll down inside of the accelerator, to see the other results. But also I don't know how I can "tell" the Accelerator to open the available links inside of the preview window in a new tab. Usually if I own the source code of the site, I can add 'target="_blank"'. But due to the fact, I don't own the source code of YouTube, I need to fix this with the Accelerator. Have you any ideas how I can do this?
Anonymous
December 24, 2009
I wish that accelerators worked better with Windows Speech Recognition - namely, that after selecting text on a webpage, there was some way of "clicking" the blue accelerator arrow by voice. There doesn't seem to be any way of doing this.
Anonymous
December 24, 2009
So one of the key parts of building an IE8 Accelerator is that you can include a favicon. This really helps users find the right action by the familiar icon from the website. Its just like how the address bar works in browsers. It shows you the favicon of the site you are visiting so that you can easily navigate to the site you want by the primary visual clue. Oh wait! that only works in all versions of Firefox, all versions of Chrome, all versions of Safari, all versions of Opera, and all versions of Internet Explorer EXCEPT IE8 Total Epic design Fail!
Anonymous
December 24, 2009
@accelerator proves address bar failure, I'm using IE8 right now.

There's a favicon in the main address bar
There's a favicon in each tab
There are favicons next to every link in my Favorites bar
There's a favicon next to each of my bookmarks the Favorites panel
Every site I visit that has an .ico to display is getting picked up. I've opened up Firefox and have the same tab set open. I can't see anywhere Firefox has favicons where IE does not and vice-versa. Just where else is this thing supposed to show up? You do realize that by posting inaccurate objections to things and bellowing about epic fails, you make yourself look very foolish. Just sayin'...

Anonymous
December 24, 2009
@WAF: I believe the prior author is trying to express his belief that the flyout list shown from the address bar should show FavIcons. As he correctly observes, it is designed not to do so.
Anonymous
December 24, 2009
@EricLaw [MSFT] - that is correct. I guess I wasn't fully clear on what part of the address bar was missing the favicons ;-) Since you used the key words "it is designed not to" in reference to the missing favicons - can you shed some light on why it was decided to remove this feature that AFAIK most people didn't want to lose? Otherwise, Merry Christmas and happy holidays!
Anonymous
December 26, 2009
The comment has been removed
Anonymous
December 29, 2009
Sorry to break topic here, but this seems to be the easiest way to relay dissatisfaction. Because IE8 cannot properly display many existing web pages, the emergency services providers in my county are going to endorse Firefox. You've had a year guys and blew it.
Anonymous
December 29, 2009
@Dan Ruehle: As a native application, Outlook won't give you access to your IE Accelerators. However, using the Accelerator Platform in Windows 7, it's quite possible to write an extension for Outlook that does. My article on the Accelerator Platform has some information on doing this. @Stefan: There's no way to add a real scrollbar to the preview window. However, it is possible to use script to simulate one. Links in the preview window should open in a new tab. @Russ: That's correct. I don't know of any way to do that. Thanks! Jon
Anonymous
December 29, 2009
@Keith: Venting one's spleen here is common, but that doesn't mean that it's useful at all. Rather than generic gripes, why not provide specific, reproducible steps (with URLs) to show what problem you're trying to describe?
Anonymous
December 29, 2009
@Rick - re examples I'm not sure what Keith's were, but here's mine: 1.) No SVG 2.) No CSS rounded corners, opacity 3.) No W3C event model 4.) No Canvas 5.) Broken innerHTML implementation 6.) Broken/missing DOM properties/methods Thus any site that tries to use the above will work fine in Firefox, Safari, Chrome, Opera, Camino (yikes I think even Arora! supports all that) - yet poor IE8 just can't keep up. Its a good thing they spent time creating accelerators instead of following the specs.
Anonymous
December 29, 2009
@Hav, Keith was talking about "MANY EXISTING" web pages. That seems a pure troll to me as there are hardly any webpages I can't view with IE8.
Anonymous
December 29, 2009
@hAl - I agree with you, but it's true a lot of intranets are coded for IE6 and break horribly if you use IE 7 or 8. I also realize most of the time it's down to the way the site is coded, but still... it does prevent uptake in some companies - the company where I work for example, won't support IE 7 if you choose to install it. You have IE 6 in the image for a reason :-)
Anonymous
December 30, 2009
The comment has been removed
Anonymous
December 30, 2009
I'm interested to know what you think accelerators are embracing or extending.
Anonymous
December 30, 2009
I love using Accelerators. I hope this technology is improved or extended somehow in IE9. Keep up the good work!
Anonymous
December 30, 2009
@Kieth You claim that MANY existing pages work in Firefox but not in IE8. I do not believe you. I have both and as far as I can see it seems that IE8 seems to render existing pages fine.
Anonymous
December 31, 2009
Here you go hal, don't take my word for it, take Microsoft's: http://support.microsoft.com/kb/969705 I will not, however, drag innocent webmasters into this discussion by outing their problems. My comment on embrace, extend, extinguish was a mistake in that I should not have opened the door to digression. </digression>
Anonymous
December 31, 2009
and I never said didn't display, I said "cannot properly display"
Anonymous
December 31, 2009
The comment has been removed
Anonymous
December 31, 2009
@ Rick and @ hAl > why not provide specific, reproducible steps (with URLs) to show what problem you're trying to describe? > there are hardly any webpages I can't view with IE8. We (James Hopkins, Zoffix Znet, Hilbrand Edskes, Bruno Fassino, Mark "Tarquin" Wilton-Jones, Dan, "mvdleij", Philip Taylor, Simon Pieters, Garrett Smith, Anton Prowse, Alan Gresley, John Russell, Chris Haig, Marc Pacheco, David Hammond, "the_dees", Colin Snover, Cory Duncan, Arnold Konrad and myself) already have provided URLs and webpages in the form of reduced testcases wrt to IE8 unable to meet/comply with CSS 2.1 spec or other mature, stable W3C web standards. That includes application crashes in IE8 and application hang (CPU maximized, unresponsive application) and other objectively serious bugs (with objective severity, gravity, importance criteria): all available, reproducible, accessible. Just yesterday, I loaded 18 tests on border-style: hidden to be eventually submitted to the CSS 2.1 test suite. All other browsers (Firefox 3.5.6, Opera 10.10, Safari 4.0.4, Konqueror 4.3.4) all pass those 18 tests: IE8 fails 16 of them. I'll most likely be able to submit 100 tests to CSS 2.1 test suite that fails in IE8. I'm probably already at around 75 now. Most tests, more proof, more URLs where IE8 fails are available at my site. season's greetings to all, Gérard Talbot
Anonymous
December 31, 2009
gerard: You do understand that your response doesn't address either of the remarks that you quoted, right? Either way, you should probably think more, and post less.
Anonymous
December 31, 2009
"We believe that IE8 has the first complete implementation of CSS 2.1 in the industry and it is fully compliant with the current CSS 2.1 test suite." Jason Upton [MSFT] Test Manager – Internet Explorer ie/archive/2009/03/20/more-web-standards-tests-submitted-to-the-w3c.aspx I am not dreaming this up, you know.. Microsoft words up there. Not mine. "Why Microsoft still haven’t removed statements claiming full CSS 2.1 support from their PR material, is beyond me. It’s astonishing to think that Microsoft thought that they could get away with publishing these blantant lies" James Hopkins jhop.me/browsers/ie8/update Gérard
Anonymous
December 31, 2009
The statement "it is fully compliant with the current CSS 2.1 test suite" was 100% accurate and suggesting otherwise is either deceitful or an indication of ignorance of the standards process and the role test suites play in that process.
Anonymous
December 31, 2009
"Internet Explorer 8 is fully compliant with the Cascading Style Sheets (CSS), Level 2 Revision 1 (CSS2.1) specification" en-us/library/cc304082(VS.85).aspx and the expressions "fully CSS 2.1 compliant" and "fully CSS 2.1-compliant support" are repeated several times in that webpage.

"To be compliant with HTML 4.01, the P tag must close before any non-inline element" Internet Explorer 8 Beta 1 Whitepapers March 5th 2008 ie8whitepapers/Release/ProjectReleases.aspx?ReleaseId=572 An unclosed <p> immediately preceding a form element should be implicitly closed by IE when parsing and building DOM tree Bug 338580 April 16th 2008 "This is an issue that we were aware of (...)" IE Team June 5th 2008 "At this time we do not plan on fixing this issue." IE Team September 17th 2008 "Automatically Closing P Elements As of Internet Explorer 8, unclosed P elements are automatically closed when followed by table, form, noFrames, or noscript elements." en-us/library/cc304133(VS.85).aspx#Closing and bug 338580 has been reactivated. The testcase for that issue has been submitted to CSS 2.1 test suite and approved. Gérard Talbot

Anonymous
December 31, 2009
gerard, if your goal is simply to spam this page with links to your site, at least have the courtesy of making your posts make sense. You gripe about CSS2.1 support and when challenged change the complaint to an obscure bug in HTML4.01 support? As for the CSS2.1 stuff, adding a testcase to the test suite AFTER compliance is claimed and then calling the person who claimed compliance is a bit dodgy in my book. If you're merely whining that MSDN documentation needs to be updated, then I think you're barking up the wrong tree.
Anonymous
January 01, 2010
The comment has been removed
Anonymous
January 02, 2010
The comment has been removed
Anonymous
January 04, 2010
Any word on IE using Webkit in the future?
Anonymous
January 04, 2010
The IE team already showed IE9 running an improved version of Trident at the PDC conference last year. They're not moving to WebKit and discussion on this topic is so tiresome I hope we don't bother to start it up again... it simply will not happen. They're not moving to Gecko either.
Anonymous
January 04, 2010
IE is more interesting !! There are still some bugs but it is much better than before
Anonymous
January 05, 2010
As far as I know, IE won't use Webkit in the near future.
Anonymous
January 06, 2010
I am looking for an accelarator which will allow me copy web content from IE to OneNote 2007. Is it available ?
Anonymous
January 06, 2010
@Sahoo: There's no accelerator for that, but OneNote does special work when you copy/paste from the browser, and they also install the "Send to OneNote" browser add-on.

Share via