HTML5 custom protocol and content handlers

By Mike Taylor

Introduction

Since the Opera 11.60 snapshot release, we have had support for the HTML5 custom scheme and content handlers. Their purpose is pretty simple. Your site can offer to handle certain MIME types or schemes (aka “protocols”) and the user has the option of opting in. One obvious use case is webmail, for example a service like Fastmail.fm or Gmail could tell your browser to open its "Compose" page if you click on a mailto: link, rather than opening a native desktop mail application.

Of course, there are reasons why you wouldn’t want to pass off every type of content to a web app! We want JavaScript and CSS to be handled by the browser, for example, so a blacklist exists to reconcile potential issues that may arise there. For security reasons, there's also a whitelist for schemes, with the option to create a custom “web+” scheme).

Not yet supported are the isProtocolHandlerRegistered, isContentHandlerRegistered, unregisterContentHandler, unregisterProtocolHandler methods which were added to the spec recently.

Protocol Registration

Note: before you read through this section, load up the telephone demo application: all the code discussed below comes from there.

To start with, we need to register new protocols we want to use: this is done using the navigator.registerProtocolHandler object. This takes three arguments: the protocol, a URL pointing to the custom handler application with a placeholder “%s”, and a title.

navigator.registerProtocolHandler (
  "tel", //protocol
  "/protocolhandler.html?%s", //handler
  "Telephony" //title
);

In a user-agent that supports this, the user will be prompted to allow this registration to happen. Figure 1 shows how this currently looks in Opera 11.60 alpha:

Figure 1: The protocol registration prompt dialog, in Opera 11.60 alpha.

Once that’s taken care of, the browser will then give users the option to handle “tel:” links with this “Telephony” app. For example: clicking on tel: 555-1234 brings up a dialog asking if you would like to open the link with the just-registered application, or the default, as shown in Figure 2.

Figure 2: Once the registration has been allowed, the user is now given the choice of handling the custom protocol with the custom handler application.

When the custom handler application is chosen, the browser then navigates to ../html5-custom-protocol-and-content-handlers/index.html/?tel%3A5551234 — you can see how the placeholder is filled in. A custom script can then parse this custom URL and operate on the “tel%3A5551234” content (in this case, just put the phone number in the phone’s LED on the application).

Content Registration

The next part of the puzzle is getting custom content registered: this is done with the navigator.registerContentHandler object, which takes three arguments: the content-type, a URL pointing to the custom content handler with a placeholder “%s”, and a title. In this example we'll be investigating how to handle a very important new web content type: .cheeseburger.

navigator.registerContentHandler (
  "text/x-cheeseburger", //content-type
  "cb.html?cb=%s", //handler
  "Cheeseburger Parser" //title
);

Just like with custom protocols and the registerProtocolHandler object, when the browser comes across custom content it will prompt the user to allow the content-type registration to happen, as shown in Figure 3.

Figure 3: The content registration prompt dialog, in Opera 11.60 alpha.

In this example, we have a custom text/x-cheeseburger content-type parser (defined in the cheeseburger syntax diagram) to operate on our .cheeseburger files. When we download a resource with the text/x-cheeseburger content-type, our browser will ask us if we wish to open it with our custom handler, as shown in Figure 4.

Figure 4: Once the content registration has been allowed, the user is now given the choice of handling the content with our custom cheeseburger handler.

Again, just like with registerProtocolHandler, the handler is opened with the “%s” placeholder replaced by the URL of content to be handled, in this case, cb.html?cb=http%3A%2F%2Fmiketaylr.com%2Fpres%2Fcapjs%2Fdemo%2Fsingle.cheeseburger. Now our cheeseburger script can fetch the contents and present it in a colorful way, as shown in Figure 5.

Figure 5: The output of our cheeseburger content handler - that is one mighty fine cheeseburger!

Play with our cheeseburger content handler live.

This article is licensed under a Creative Commons Attribution 3.0 Unported license.