Accelerator Creation Guide


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:

  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 320×240 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 320×240:

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

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 “&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

Comments (37)

  1. Anonymous says:

    @accelerator proves address bar failure

    TOTAL BLOG TROLL FAILURE!

  2. Dan Ruehle says:

    Great article.  Is there any way to get accellerators to work in Outlook?  There are so many times I’d like to do a quick lookup of something in an email and find myself doing a copy/paste from there.  I know one workaround would be to just use OWA, but that’s cheating!

    Thanks!

  3. Jorge says:

    Great article! Nice to see content about the features of IE8 ๐Ÿ˜‰

    Keep up the great job with IE9 ๐Ÿ˜€

  4. Stefan says:

    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?

  5. Russ says:

    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.

  6. accelerator proves address bar failure says:

    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!

  7. WAF says:

    @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’…

  8. EricLaw [MSFT] says:

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

  9. accelerator proves address bar failure says:

    @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!

  10. Xepol says:

    This is one of those great features that every browser should support.

    Proper documentation could increase the chances of adoption – and increased adoption means increased penetration into the market and more people publishing accelerators.

    It’s all for the good.

  11. Keith Rowand says:

    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.

  12. Jon Seitel [MSFT] says:

    @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

  13. Rick says:

    @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?

  14. Hav says:

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

  15. hAl says:

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

  16. Phil says:

    @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 :-)

  17. Keith says:

    Bless you Hav.  

    So, hAL, who’s going to pay for ‘fixing’ the existing pages that work fine on other browsers?  

    Yes you can also ‘fix’ MS Pub 2003 pages by ungrouping & re-publishing, but then you loose the design functionality provided by grouping. Or you can upgrade to 2007(who pays for that?).  It seems to me that this ungrouping hack represents plausible deniability against the charge of extorting a fix via the upgrade.

    Asking detailed questions of the EMTs I support, it turns out their problems were small, and in some cases resolved by running in ‘compatibility’ mode.  When they tried Firefox the problems were non-existent and they didn’t have to muck ‘technical stuff.’  Which do you think they preferred?

    As people loose trust in Microsoft, they move to Firefox/Chrome/….

    I’m currently part of a team w an ASP.Net application; this lack of compatibility hurts MY credibility too.  PLEASE FIX THIS PROBLEM!

    One more observation is that to me, these ‘accelerators’ fit into the model of ’embrace, extend, extinguish’ that has gotten MS into trouble in the past.

  18. DT says:

    I’m interested to know what you think accelerators are embracing or extending.

  19. dlh2009 says:

    I love using Accelerators.  I hope this technology is improved or extended somehow in IE9.

    Keep up the good work!

  20. hAl says:

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

  21. Keith says:

    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>

  22. Keith says:

    and I never said didn’t display, I said "cannot _properly_ display"

  23. EricLaw says:

    Keith is sharing with you an instance where Publisher generated invalid VML markup which is hidden within conditional comments such that only IE is provided the invalid content. As you might imagine, this problem does not affect any major sites, and as noted in the KB article, an update is available for Publisher to correct this problem. A workaround is available for those that don’t want to update Publisher.

  24. @ 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

  25. SickOfPundits says:

    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.

  26. "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

  27. Learn-To-Read says:

    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.

  28. "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

  29. Hmmm says:

    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.

  30. hAl says:

    @Gerard Talbot.

    I looked at many of those testcase but most are obsure to say the least as they are often combining inheritence and boxmodel and less used css. Things not commenly found in most webpages as I have seen from experience that a lot of webdeveloper do not understand the css box model and inheritence either and thus avoid it.

    You won’t find many existing pages having those issues as is suggested by Keith who whoever is not providing any examples of those many existing pages that are not rendering with IE8. Kieth mistakenly showing a bug in MS Publisher to prove his point rather than provide those many existing pages show it all I would say.

  31. donald says:

    @hAl, @Keith, etc.

    Yes most pages run fine in IE8… but how many of them are running in a forced IE7-mode?

    This blog is one of them!

    Unfortunately by allowing back-compat in IE8, Microsoft has actually hurt progress in supporting web standards.

    IE9 should be a clean break (from IE7 rendering). IE9 should be CSS3 out of the box (with all the JS fixes) and have a compat switch to go back to IE8 CSS2.1 rendering **ONLY** (all standards mode)

  32. we want webkit says:

    Any word on IE using Webkit in the future?

  33. Trident says:

    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.

  34. michel says:

    IE is more interesting !!

    There are still some bugs but it is much better than before

  35. Chrisb78 says:

    As far as I know, IE won’t use Webkit in the near future.

  36. Sahoo says:

    I am looking for an accelarator which will allow me copy web content from IE to OneNote  2007. Is it available ?

  37. ieblog says:

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