JSChannel Documentation

Verifying the correctness of the code on this page...

All the code on this page is correct.

Some code on this page doesn't work.

Introduction

JSChannel is a small JavaScript abstraction layer on top of HTML5 cross-document messaging. It builds rich messaging semantics out of window.postMessage().

About The Code Examples

This page uses the doctestjs library by Ian Bicking. The code examples are actually run on your browser to verify their correctness.

All the code examples in this documentation assume communication between a parent page and a child frame. Example code executed in the child frame looks like this:

/* Here's a comment in the child frame. */

The examples also assume that a few global functions exist in the parent page:

emit() simply prints out its arguments, like so:
```
$ emit("hi", "there");
out("hi", "there")
```

Page Setup

JSChannel has no dependencies, so there's very little setup involved. You can get started by making a simple HTML page that includes the JSChannel script:

<script src="jschannel.js"></script>

And a trivial child frame:

<iframe id="childId" src="child.html"></iframe>

The contents of the child frame don't matter, so long as it includes the JSChannel script (so that it can communicate with its parent).

Note that we're just using a child frame for the sake of example; as a rule, JSChannel can be used anywhere that window.postMessage() can.

Creating a Channel

Let's create a channel in our child frame:

var chan = Channel.build({window: window.parent,
                          origin: "*",
                          scope: "testScope"});

And now we'll build one in our parent page to communicate with it:

$ chan = Channel.build({
>   window: document.getElementById("childId").contentWindow,
>   origin: "*",
>   scope: "testScope",
>   onReady: function() {
>     emit("channel is ready!");
>   }
> });
> wait();
out("channel is ready!")

Note that the onReady callback is called once actual communication has been established between the parent page and child frame. If the child frame hadn't set up its end of the channel, for instance, onReady would never get called.

Learn more about channel creation »

If you pass a bogus first parameter to Channel.build(), a friendly exception is thrown.

$ Channel.build();
Error: Channel build invoked without a proper object argument
$ Channel.build({});
Error: Channel.build() called without a valid window argument
$ Channel.build({window: document.getElementById("fakeChildId")});
Error: Channel.build() called without a valid window argument

The origin parameter is used for security purposes, just as in window.postMessage(), and it can take many different forms:

$ tgtwin = document.getElementById("fakeChildId").contentWindow;
> Channel.build({window: tgtwin, origin: "http://trickyco.de"}).destroy();
> Channel.build({window: tgtwin,
>                origin: "http://trickyco.de:8080"}).destroy();
> Channel.build({window: tgtwin,
>                origin: "http://trickyco.de:8080/"}).destroy();
> Channel.build({window: tgtwin, origin: "http://localhost"}).destroy();
> Channel.build({window: tgtwin, origin: "http://localhost:1234"}).destroy();
> Channel.build({window: tgtwin, origin: "http://10.0.1.104:1234"}).destroy();
> var tricky_caps = Channel.build({window: tgtwin,
>                                    origin: "http://TrIcKyCaPiTaLiZaTiOn.CoM"});
> var overlaps_tricky_caps = Channel.build({window: tgtwin,
>                                           origin: "http://trickycapitalization.com"});
Error: A channel is already bound to the same window which overlaps with origin 'http://trickycapitalization.com' and has scope ''
$ tricky_caps.destroy();
>

...except for obvious exceptions.

$ Channel.build({window: tgtwin, origin: "this isn't a valid origin!"});
Error: Channel.build() called with an invalid origin

And the scope parameter can include almost any characters to automatically namespace the channel so it doesn't conflict with other channels:

$ var tgtwin = document.getElementById("fakeChildId").contentWindow;
> Channel.build({window: tgtwin,
>                origin: "http://trickyco.de",
>                scope: "goodScope"}).destroy();
> Channel.build({window: tgtwin,
>                origin: "http://trickyco.de",
>                scope: "speshulScope!@#%^@**(#(%*<>';][,.';'"}).destroy();
> Channel.build({window: tgtwin,
>                origin: "http://trickyco.de",
>                scope: "closeTo:BadScope"}).destroy();
> Channel.build({window: tgtwin,
>                origin: "http://trickyco.de",
>                scope: "closer:T:o:B:a:dScope"}).destroy();

But a channel's scope can't include double colons.

$ Channel.build({window: tgtwin,
>                origin: "http://trickyco.de",
>                scope: "veryBad::Scope"});
Error: scope may not contain double colons: '::'

Remote Methods

Now we'll define a simple function in our child frame:

chan.bind("reverse", function(trans, s) {
  return s.split("").reverse().join("");
});

And call it in our parent frame.

$ chan.call({method: "reverse",
>            params: "hello world!",
>            success: function(v) { emit(v.toString()); }});
> wait();
out("!dlrow olleh")

Learn more about return types »

Of course, more than just strings can be returned from a remote call. Assume we have a trivial echo function like this:

chan.bind("echo", function(trans, a) { return a });

It's possible for a remote method to return any native JavaScript types, like numbers:

$ chan.call({method: "echo",
>            params: 0,
>            success: emit,
>            error: emit});
> wait();
out(0)

null works, too:

$ chan.call({method: "echo",
>            params: null,
>            success: emit,
>            error: emit});
> wait();
out(null)

As do booleans:

$ chan.call({method: "echo",
>            params: false,
>            success: emit,
>            error: emit});
> wait();
out(false)

Remote methods can throw errors, too. Here's one in our child frame:

chan.bind("throwObject", function(trans, s) {
  throw {error: "object_error_code", message: 'object error message'};
});

Calling that produces this:

$ chan.call({method: "throwObject",
>            error: emit,
>            success: emit});
> wait();
out("object_error_code", "object error message")

Learn more about exceptions »

But objects with keys other than error and message...

chan.bind("throwSmushedObject", function(trans, s) {
  throw {dont:"smush",me:"no!!"};
});

...get smushed into strings by attempting to serialize them to JSON.

$ chan.call({method: "throwSmushedObject",
>            error: emit,
>            success: emit});
> wait();
out("runtime_error", "{\"dont\":\"smush\",\"me\":\"no!!\"...}")

But objects that can't be serialized to JSON just get coerced to strings:

chan.bind("throwToStringedObject", function(trans, s) {
  throw window;
});

$ chan.call({method: "throwToStringedObject",
>            error: emit,
>            success: emit});
> wait();
out("runtime_error", "[object...]")

You can throw arrays, too:

chan.bind("throwArray", function(trans, s) {
  throw [ "array_error_code", 'array error message'];
});

$ chan.call({method: "throwArray",
>            error: emit,
>            success: emit});
> wait();
out("array_error_code", "array error message")

And strings...

chan.bind("throwString", function(trans, s) {
  throw "this is a string";
});

$ chan.call({method: "throwString",
>            error: emit,
>            success: emit});
> wait();
out("runtime_error", "this is a string")

Totally unintentional exceptions get propagated, too:

chan.bind("accidentalThrow", function(trans, s) {
  window.nonExistentMethod();
});

$ chan.call({method: "accidentalThrow",
>            error: emit,
>            success: emit});
> // Note that the exception content varies by browser.
> wait();
out("runtime_error", ...)

Transactions

If your method's implementation is asychronous, you'll have to use the transaction object that's automatically passed as the first argument to a remote method, like so:

chan.bind("twiddleThumbs", function(trans) {
  setTimeout(function() { trans.complete("thumbs twiddled!"); }, 50);
  trans.delayReturn(true);
});

The caller doesn't do anything differently, since it's always calling the remote method asynchronously:

$ chan.call({method: "twiddleThumbs", success: emit});
> wait();
out("thumbs twiddled!")

You can use a transaction's error() method to propagate errors, too.

chan.bind("getStuff", function(trans) {
  setTimeout(function() {
    trans.error("mega_fail", "i could not get your stuff.");
  }, 50);
  trans.delayReturn(true);
});

$ chan.call({method: "getStuff",
>            error: emit,
>            success: emit});
> wait();
out("mega_fail", "i could not get your stuff.")

Callbacks

Clients can pass functions as parameters to remote methods, and they can be called by the implementer. Here's a trivial example:

chan.bind("simple_cb", function(trans, params) {
  params.cb("you called?");
  trans.complete("complete");
});

$ chan.call({method: "simple_cb", params: { cb: emit }, success: emit});
> wait();
out("you called?")
out("complete")

Learn more about callbacks »

Callback parameters can be nested, too, and they arrive in the order in which they were originally called:

chan.bind("caller_backer", function(trans, params) {
  params.cb("you called?");
  params.cb2("you called again!?");
  params.nested.cb("STOP CALLING ME!");
  trans.complete("complete");
});

$ chan.call({method: "caller_backer",
>            params: { cb: emit, cb2: emit, nested: { cb: emit } },
>            error: emit,
>            success: emit});
> wait();
out("you called?")
out("you called again!?")
out("STOP CALLING ME!")
out("complete")

Timeouts

Clients can also be notified if a remote method invocation takes too long to complete by passing a timeout parameter to a channel's call() method.

For instance, we can try calling a nonexistent method with a timeout:

$ chan.call({method: "nonexistent",
>            timeout: 50,
>            error: emit,
>            success: emit});
> wait();
out("timeout_error", "timeout (50ms) exceeded on method 'testScope::nonexistent'")

Learn more about timeouts »

Of course, the timeout doesn't get triggered if the method call actually completes...

$ var x = [];
> chan.call({ method: "echo",
>             params: "echo called",
>             timeout: 100,
>             error: function(e, m) { x.push(e); },
>             success: function(m) { x.push(m); }});
> setTimeout(function() { emit.apply(null, x); }, 250);
> wait();
out("echo called")

Notifications

Notifications are similar to method calls, but are "fire-and-forget", lacking any concept of an error or return value. For example:

chan.bind("ping", function(context, params) {
  // context.origin contains the origin also for notifications.
  if (!context.origin) throw "where's your origin?";
  chan.notify({method: "pong", params: params});
});

$ chan.bind("pong", function(context, params) { emit(params); });
> chan.notify({method: "ping", params: "hai2u"});
> wait();
out("hai2u")