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:

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' }

Person { name: 'Peter' }

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

Person.prototype.inspect = function inspect(depth) {
    return "Person named " + this.name;
};

peter;

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.

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;

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)

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

$$.svg(svgString)

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

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

$$.png(require("fs").readFileSync("image.png").toString("base64"));

$$.jpeg(base64String)

Similarly with JPEG files:

$$.jpeg(require("fs").readFileSync("image.jpg").toString("base64"));

$$.mime(mimeBundle)

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

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