Allows for defining custom JavaScript powered kinos.

example

Example

Here's how we could define a minimal kino that embeds the given HTML directly into the page.

defmodule KinoDocs.HTML do
  use Kino.JS

  def new(html) do
    Kino.JS.new(__MODULE__, html)
  end

  asset "main.js" do
    """
    export function init(ctx, html) {
      ctx.root.innerHTML = html;
    }
    """
  end
end

Let's break down the API.

To define a custom kino we need to create a new module. In this case we go with KinoDocs.HTML.

We start by adding use Kino.JS, which makes our module asset-aware. In particular, it allows us to use the asset/2 macro to define arbitrary files directly in the module source.

All kinos require a main.js file that defines a JavaScript module and becomes the entrypoint on the client side. The JavaScript module is expected to export the init(ctx, data) function, where ctx is a special object (discussed in detail later) and data is the kino data passed from the Elixir side. In our example the init function accesses the root element with ctx.root and overrides its content with the given HTML string.

Finally, we define the new(html) function that creates kinos with the given HTML. Underneath we call Kino.JS.new/2 specifying our module as the kino type and passing the data (available in the JavaScript init function later). Again, it's a convention for each kino module to define a new function to provide uniform experience for the end user.

assets

Assets

We already saw how to define a JavaScript (or any other) file using the asset/2 macro, however in most cases it's preferable to put assets in a dedicated directory to benefit from syntax highlighting and other editor features. To do that, we just need to specify where the corresponding directory is located:

use Kino.JS, assets_path: "lib/assets/html"

stylesheets

Stylesheets

The ctx.importCSS(url) function allows us to load CSS from the given URL into the page. The stylesheet can be an external resource, such as a font from Google Fonts or a custom asset (as outlined above). Here's an example of both:

defmodule KinoDocs.HTML do
  use Kino.JS

  def new(html) do
    Kino.JS.new(__MODULE__, html)
  end

  asset "main.js" do
    """
    export function init(ctx, html) {
      ctx.importCSS("https://fonts.googleapis.com/css?family=Sofia")
      ctx.importCSS("main.css")

      ctx.root.innerHTML = html;
    }
    """
  end

  asset "main.css" do
    """
    body {
      font-family: "Sofia", sans-serif;
    }
    """
  end
end

urls

URLs

When using multiple asset files, make sure to use relative URLs. For example, when adding an image to the page, instead of:

<img src="/images/cat.jpeg" />

Do:

<img src="./images/cat.jpeg" />

This will correctly point to the images/cat.jpeg file in your assets.

security

Security

Note that all assets are assumed public and Livebook doesn't enforce authentication when loading them. Therefore, never include any sensitive credentials in the assets source, instead pass them as arguments from your Elixir code.

javascript-api

JavaScript API

In the example we briefly introduced the ctx (context) object that is made available in the init(ctx, data) function. This object encapsulates all of the Livebook-specific API that we can call on the JavaScript side.

properties

Properties

• ctx.root - the root element controlled by the kino

functions

Functions

• ctx.importCSS(url) - loads CSS from the given URL into the page. Returns a Promise that resolves once the CSS is loaded

• ctx.importJS(url) - loads JS from the given URL into the page using a regular <script> tag. Returns a Promise that resolves once the JS is loaded

• ctx.handleEvent(event, callback) - registers an event handler. Once event is broadcasted, callback is executed with the event payload. This applies to Kino.JS.Live kinos

• ctx.pushEvent(event, payload) - sends an event to the kino server, where it is handled with Kino.JS.Live.handle_event/3. This applies to Kino.JS.Live kinos

• ctx.handleSync(callback) - registers a synchronization handler, it should flush any deferred UI changes to the server. This applies to Kino.SmartCell cells

• ctx.selectSecret(callback, preselectName) - asks the user to select a Livebook secret. Suggests preselectName as the default choice. When the user selects a secret, callback is called with the secret name

cdn

CDN

It is possible to use a regular JavaScript bundler for generating the assets, however in many cases a simpler and preferred approach is to import the necessary dependencies directly from a CDN.

To give a concrete example, here's how we could use the mermaid JavaScript package for rendering diagrams:

defmodule KinoDocs.Mermaid do
  use Kino.JS

  def new(graph) do
    Kino.JS.new(__MODULE__, graph)
  end

  asset "main.js" do
    """
    import "https://cdn.jsdelivr.net/npm/mermaid@9.1.3/dist/mermaid.min.js";

    mermaid.initialize({ startOnLoad: false });

    export function init(ctx, graph) {
      mermaid.render("graph1", graph, (svgSource, bindListeners) => {
        ctx.root.innerHTML = svgSource;
        bindListeners && bindListeners(ctx.root);
      });
    }
    """
  end
end

And we would use it like so:

KinoDocs.Mermaid.new("""
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
""")

live-kinos

Live kinos

So far we covered the API for defining static kinos, where the JavaScript side only receives the initial data and there is no further interaction with the Elixir side. To introduce such interaction, see Kino.JS.Live as a next step in our discussion.