Custom Output

This tutorial describes the patterns available in IJavascript for customising output.

Types of output

The Jupyter messaging protocol defines three types of output resulting from an execution request:

  • the execution result, which the notebook shows preceeded by a numbered label (Out[n]:);

  • the standard output stream (stdout), which is usually shown above the execution result;

  • and the standard error stream (stderr), which is usually shown above the execution result in a pink background.

Whereas the standard streams are plain text, the execution result admits outputs in a number of MIME formats. The following sections describe how to customise the output of an execution result.

Customising the plain text output of a class

(MyClass.prototype.inspect)

IJavascript uses the Node.js function util.inspect() to generate the text/plain output of an execution result, as illustrated in the following example:

In [1]:
function Person(name) {
    this.name = name;
}

var peter = new Person("Peter");

var util = require("util");
console.log(util.inspect(peter));  // shown on stdout
peter;                             // shown as an execution result
Person { name: 'Peter' }
Out[1]:
Person { name: 'Peter' }

Node.js defines the following pattern to customise the output of util.inspect():

In [2]:
Person.prototype.inspect = function inspect(depth) {
    return "Person named " + this.name;
};

peter;
Out[2]:
Person named Peter

Customising the MIME output of a class

Similarly to the Node.js inspect pattern, IJavascript specifies the following conventions:

MyClass.prototype._toHtml()

If defined, IJavascript expects this method to return a string with the text/html representation of an instance of MyClass.

MyClass.prototype._toSvg()

If defined, IJavascript expects this method to return a string with the image/svg+xml representation of an instance of MyClass.

MyClass.prototype._toPng()

If defined, IJavascript expects this method to return a base64-encoded string with the image/png representation of an instance of MyClass.

MyClass.prototype._toJpeg()

If defined, IJavascript expects this method to return a base64-encoded string with the image/jpeg representation of an instance of MyClass.

MyClass.prototype._toMime()

If defined, IJavascript expects this method to return an object with the MIME representations of an instance of MyClass, i.e. { mimeType1: string1, mimeType2: string2, ...}.

Below is an example for text/html. See the next section, for an example that encodes a binary image into base64 string.

In [3]:
Person.prototype._toHtml = function _toHtml() {
    var style = (
        "display:inline-block;" +
        "padding:0.25em;" +
        "background:#ccc;" +
        "border: 1px solid #888;" +
        "border-radius:0.25em;" +
        "box-shadow: 0.8em 0.4em 0.4em black;"
    );
    return (
        "<div style='" + style + "'>" +
        this.inspect() +
        "</div>"
    );
};

peter;
Out[3]:
Person named Peter

Setting the output using the global object $$

IJavascript defines the global object $$ to help output results asynchronously. This functionality can also be used in synchronous execution.

$$.html(htmlString)

In [4]:
$$.html("<div style='background-color:olive;width:50px;height:50px'></div>");
Out[4]:

$$.svg(svgString)

In [5]:
$$.svg("<svg><rect width=80 height=80 style='fill: orange;'/></svg>");
Out[5]:

$$.png(base64String)

IJavascript can also output pictures in PNG and JPEG formats. However, this formats are binary and need to be encoded in base64. See below an example with a PNG file:

In [6]:
$$.png(require("fs").readFileSync("image.png").toString("base64"));
Out[6]:

$$.jpeg(base64String)

Similarly with JPEG files:

In [7]:
$$.jpeg(require("fs").readFileSync("image.jpg").toString("base64"));
Out[7]:

$$.mime(mimeBundle)

IJavascript also provides the global function $$.mime(mimeBundle) to display an output in any formats understood by the Jupyter frontend:

In [8]:
$$.mime({
    "text/html": "<div style='background-color:olive;width:50px;height:50px'></div>",
});
Out[8]: