Skip to main content

Getting Started

Introduction​

jQuery Terminal is a JavaScript library that requires jQuery to work properly. It's a library that allow you to create terminal based web apps. It's different from xterm.js, because you need to write your whole logic in client JavaScript code. In comparison, Xterm.js is a library to create a real terminal interface for a real Linux system on the backend. It allows running a real CLI/TUI applications like VI that run on the backend. To have the same in jQuery Terminal you will need to have a VI implemented in JavaScript. For this you can check jsvi.

To create an app using jQuery Terminal, first, you need to create an HTML page, and then include jQuery and both the JavaScript and CSS files from jQuery Terminal. You can also use webpack or other bundlers. In this tutorial, you will learn all the basics needed to create your own Terminal on a webpage.

jsDelivr CDN​

The best way to get jQuery Terminal is using jsDelivr, it's CDN (Content Delivery Network), that makes loading static assets (like JavaScript or CSS files) faster.

Those are main files that you need to include:

  • https://cdn.jsdelivr.net/npm/jquery.terminal@2.x.x/js/jquery.terminal.min.js
  • https://cdn.jsdelivr.net/npm/jquery.terminal@2.x.x/css/jquery.terminal.min.css

HTML Page​

Below is basic HTML code that you need:

<!DOCTYPE html>
<html>
<head>
<script src="https://cdn.jsdelivr.net/npm/jquery"></script>
<script src="https://cdn.jsdelivr.net/npm/jquery.terminal/js/jquery.terminal.min.js">
</script>
<link href="https://cdn.jsdelivr.net/npm/jquery.terminal/css/jquery.terminal.min.css"
      rel="stylesheet" />
</head>
<body>
<scrpt>/* your code here */</script>
</body>
</html>

The version @2.x.x is optional.

note

You can write your code inline like in the code above, or write separate file and use HTML like this:

<script src="your-file.js"></script>

Older Browsers​

If you need to support older browsers (like IE11) you can also include this JavaScript file:

<script src="https://cdn.jsdelivr.net/npm/js-polyfills/keyboard.js"></script>

It's a polyfill for key property on keyboard events. You can see the browser support for this feature.

Chinese and Japanese Character Support​

There are characters like Chinese and Japanese that are wider then 1 character. To display those characters properly on the terminal you can use wcwidth libary, which calculates the width of the characters.

note

wcwidth library needs to be included before the jQuery Terminal script file.

You can add this code to your HTML:

<script src="https://cdn.jsdelivr.net/gh/jcubic/static/js/wcwidth.js"></script>

Above file is a collection of libraries converted to UMD using browserify.

Terminal Initialization​

To initialize the terminal you need to use code like this:

$('body').terminal();

Above code is specific to jQuery. If you're not familar with it, it's basically dolar function that accept a CSS selector that points to element that will be transformed into your terminal. When you use body as the selector, it will create full screen terminal. But you can also use element that is part of your webpage, like a window that have a terminal inside.

Interpreter​

The first argument to the terminal is an interpreter, the simplest way to add multiple commands is using an object.

$('body').terminal({
    hello() {
        this.echo('hello, world!');
    },
    bye() {
        this.echo('goodby');
    }
});

This code will create two commands:

  • hello which prints on the terminal text "hello, world!",
  • bye which prints "goodby"
note

this inside methods is jQuery Terminal object, and echo is one of the methods supported by this object.

Read more about terminal instance and echo.

To create arguments to the commands you add them as function paramters:

const term = $('body').terminal({
    hello(what) {
        this.echo(`hello, this is ${what}!`);
    },
    bye() {
        this.echo('goodby');
    }
});

If you type hello Terminal it will print "hello, this is Terminal".

info

Note that terminal returns Terminal object with methods that allow you to interact with the terminal. It's the same object you can access with this. Terminal object is in fact jQuery object extended with additional methods.

Terminal Options​

Variable Number of Arguments​

If you want the argument to be optional you need to checkArity: false option (options is an object that is a second argumnet to the termianal). Variable number of arguments is so called Arity.

$('body').terminal({
    hello(what = 'world') {
        this.echo(`hello, this is ${what}!`);
    },
    bye() {
        this.echo('goodby');
    }
}, {
    checkArity: false
});

Greetings​

Another usefull option that you want to change is greetings, by default it display jQuery Terminal ASCII Art, but you can change it.

$('body').terminal({
    hello(what = 'world') {
        this.echo(`hello, this is ${what}!`);
    },
    bye() {
        this.echo('goodby');
    }
}, {
    greetings: 'My Terminal',
    checkArity: false
});

Prompt​

You can also change the prompt, which is the thing before the cursor, when there is no command typed yet. By default it's a string '> '. But you can change it and use different string:

$('body').terminal({
    hello(what = 'world') {
        this.echo(`hello, this is ${what}!`);
    },
    bye() {
        this.echo('goodby');
    }
}, {
    greetings: 'My Terminal',
    prompt: '$ ',
    checkArity: false
});

Completion​

By default, when you press <TAB> key, the terminal will insert a TAB key. You can make it complete the command, you're typing. When using object as an interpreter (like in above examples) all you have to do is to set an option: completion: true:

$('body').terminal({
    hello(what = 'world') {
        this.echo(`hello, this is ${what}!`);
    },
    bye() {
        this.echo('goodby');
    }
}, {
    greetings: 'My Terminal',
    prompt: '$ ',
    completion: true,
    checkArity: false
});

If you type h and press <TAB> it will complete the command and insert ello.

Default Commands​

When you use completion and press <TAB> twice, without typing anything, you will have list of commands. By default you will also have clear command that you can disable with clear: false option. There is also second default command which is exit, that appear only when you use authentication or nested interpreters.

Chaining​

Because jQuery Terminal use jQuery, you can use chaining of methods. Because most methods return terminal instance.

term.echo('This is').echo('jQuery Terminal');

There are more terminal methods that you can use, check Terminal Instance Guide, for more information.

Demo​

See the Pen Basic terminal by Jakub T. Jankiewicz (@jcubic) on CodePen.

See also​