hterm and Secure Shell

Embedding hterm

This is a quick overview describing how to use hterm in your own application. Please direct any questions to the chromium-hterm mailing list.

Get the code

The “libapps” git repository contains hterm and its dependencies. Clone this repo into a parent directory of your choice. In this example we'll create ~/src/libapps/:

$ mkdir ~/src
$ cd ~/src
$ git clone https://chromium.googlesource.com/apps/libapps

Build hterm

The build process bundles some resources as JavaScript source and concatenates the JavaScript into a single file (hterm_all.js).

$ cd ~/src/libapps
$ ./hterm/bin/mkdist.sh

The files are all written to ./hterm/dist/js/. Copy the hterm_all.js file into your project.

Include hterm in your app

Include the generated hterm_all.js file in your app in an appropriate manner. This step should be self evident.

Initialize hterm

Terminal node

You'll want a sacrificial DOM node which will become the terminal widget. It should be a div which is either position: relative or position: absolute.

In our example, we'll assume this DOM:

<!DOCTYPE html>
<html>
  <body>
    <div id="terminal"
         style="position:relative; width:100%; height:100%"></div>
  </body>
</html>

Runtime storage

You'll need to choose a storage implementation. This is the backing store that hterm will use to read and write preferences. This should be one of:

// If you are a cross-browser web app and want to use window.localStorage.
hterm.defaultStorage = new lib.Storage.Local();

// If you are a cross-browser web app and want in-memory storage only.
hterm.defaultStorage = new lib.Storage.Memory();

// If you are a Chrome app and want sync storage.
hterm.defaultStorage = new lib.Storage.Chrome(chrome.storage.sync);

// If you are a Chrome app and want local storage.
hterm.defaultStorage = new lib.Storage.Chrome(chrome.storage.local);

Terminal initialization

Create an instance of hterm.Terminal:

// opt_profileName is the name of the terminal profile to load, or "default" if
// not specified.  If you're using one of the persistent storage
// implementations then this will scope all preferences read/writes to this
// name.
const t = new hterm.Terminal(opt_profileName);

Now write an onTerminalReady handler. This will fire once, when the terminal is initialized and ready for use.

t.onTerminalReady = function() {
  // Create a new terminal IO object and give it the foreground.
  // (The default IO object just prints warning messages about unhandled
  // things to the the JS console.)
  const io = t.io.push();

  io.onVTKeystroke = (str) => {
    // Do something useful with str here.
    // For example, Secure Shell forwards the string onto the NaCl plugin.
  };

  io.sendString = (str) => {
    // Just like a keystroke, except str was generated by the terminal itself.
    // For example, when the user pastes a string.
    // Most likely you'll do the same thing as onVTKeystroke.
  };

  io.onTerminalResize = (columns, rows) => {
    // React to size changes here.
    // Secure Shell pokes at NaCl, which eventually results in
    // some ioctls on the host.
  };

  // You can call io.push() to foreground a fresh io context, which can
  // be uses to give control of the terminal to something else.  When that
  // thing is complete, should call io.pop() to restore control to the
  // previous io object.
};

After you've registered your onTerminalReady handler you can connect the terminal to the sacrificial DOM node.

t.decorate(document.querySelector('#terminal'));

Keyboard setup

After you call the decorate helper, you'll usually call installKeyboard to capture all keyboard input when the terminal is focused. This allows us to react to keyboard shortcuts and such.

t.installKeyboard();

Write to the terminal

Once onTerminalReady finishes, you're free to start writing content! This is the process or connection that wants to display content to the user (rather than the user sending content).

t.io.print('Print a string without a newline');
t.io.println('Print a string and add CRLF');

You usually want to go through the io object to display content rather than going directly through the terminal. It will take care of encoding UTF-16 to UTF-8 and then sending it via t.interpret (which processes escape sequences). If you use the t.print function directly, it won't do either of those things, which might be what you want.