Skip to content
A JavaScript Terminal "simulator" for creating websites with a command line interface.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
dist
src
test
.gitattributes
.gitignore
README.md
gulpfile.js
package.json

README.md

terminator.js

terminator.js is a tiny dependency-free library for building text terminal like interfaces for the browser. See it in action on the Information & Systems Security Society website, also on GitHub.

Usage

Drop the JS + CSS into your website to access terminator.js. The latest build can always be found in the dist/ folder of the GitHub repository.

<link rel="stylesheet" type="text/css" href="terminator.css">
<script src="terminator.js"></script>

The script exposes a Terminator constructor with which takes two parameters: a DOM element (such as a div) and a configuration Object. Example:

var config = {
        alwaysFocus: true, 	//Prevents the user from blurring the terminal input.
        autoScroll: true, 	//Automatically scrolls to the bottom when typing or executing commands.
        prefix: '~$', 		//The prefix character in front of the prompt.
        caret: '_'			//The caret symbol in the input field.
};
var targetNode = document.getElementById('some-dom-id');
var theTerminator = new Terminator(targetNode, config);

Register some functions:

//Print everything that comes after 'echo'
main.register(function(term, command) {
    term.writeLine(command.split(' ').slice(1).join(' '));
    term.prompt();
}, 'echo');

Then, whenever you're ready to accept commands, call

theTerminator.prompt();

Build Process

Clone the repsitory. With NodeJS (4+) and NPM (3+), first install the dependencies from command line:

npm install
npm install -g gulp-cli

The source code for the terminator.js library is located in the src directory. To build terminator.js, run

gulp

in the command line. This will build ready-to-use files into the dist directory.

Testing

terminator.js uses QUnit for browser based testing. All test code is located in the test folder. To run tests, first have a build ready in the dist directory (read "Build Process" above), and then open the test/index.html file in your browser.

API

.register(callback, name)

Registers a standard JS function under the command name. An array of multiple names can be provided to serve as aliases.

When the user types in the provided name into the prompt and presses the enter key, the callback is executed. The callback function will be called with two arguments: the terminal object, and the entire command string. The following example is a basic echo function:

//Print everything that comes after 'echo'
main.register(function(term, command) {
    term.writeLine(command.split(' ').slice(1).join(' '));
    term.prompt();
}, 'echo');

The first argument (terminal) provides access to the rest of the API within the function itself. In the above case, term === main.

The second argument (command) contains the entire string that the user typed into the prompt. If the user types echo bananas in the prompt and presses enter, command === 'echo bananas'.

.prompt([prefix=''], [callback=undefined])

Prompts the user for input. When the user presses enter, the terminal finds the function registered with the corresponding name to the first argument typed and executes that function. See above for details on how to register functions.

An optional prefix string can be provided as the first argument to override the default prefix defined in the configuration options. An optional callback second argument can be provided to override the function executed after the user presses the enter key.

.autoType(command, [delay=0])

Automatically types a string command into the prompt, letter by letter, to simulate human typing. When auto-typing finishes, the command executes. An optional delay parameter can be provided to delay (in ms) the insertion of the first character.

When .autoType is called, the prompt input is cleared and user input is ignored. Make sure a prompt is available (call .prompt) before calling .autoType, or else nothing will get actually typed.

.writeLine(text)

Inserts text (will be escaped) in a span and a newline (br) into the terminal.

.writeHTML(content)

Inserts a div with the innerHTML set to content to the terminal.

.lineBreak()

Inserts a newline (br) into the terminal.

License: MIT

You can’t perform that action at this time.