View on GitHub

Jq-console

Feature complete web terminal

Download this project as a .zip file Download this project as a tar.gz file

jq-console

A jQuery terminal plugin written in CoffeeScript.

This project was spawned because of our need for a simple web terminal plugin
for the repl.it project. It tries to simulate a low level terminal by providing (almost)
raw input/output streams as well as input and output states.

Version 2.0 adds baked-in support for rich multi-line prompting and operation
queueing.

Tested Browsers

The plugin has been tested on the following browsers:

Getting Started

Echo example

    /* The console container element */
    #console {
      position: absolute;
      width: 400px;
      height: 500px;
      background-color:black;
    }
    /* The inner console element. */
    .jqconsole {
        padding: 10px;
    }
    /* The cursor. */
    .jqconsole-cursor {
        background-color: gray;
    }
    /* The cursor color when the console looses focus. */
    .jqconsole-blurred .jqconsole-cursor {
        background-color: #666;
    }
    /* The current prompt text color */
    .jqconsole-prompt {
        color: #0d0;
    }
    /* The command history */
    .jqconsole-old-prompt {
        color: #0b0;
        font-weight: normal;
    }
    /* The text color when in input mode. */
    .jqconsole-input {
        color: #dd0;
    }
    /* Previously entered input. */
    .jqconsole-old-input {
        color: #bb0;
        font-weight: normal;
    }
    /* The text color of the output. */
    .jqconsole-output {
        color: white;
    }
    <div id="console"></div>
    <script src="jquery.js" type="text/javascript" charset="utf-8"></script>
    <script src="jqconsole.js" type="text/javascript" charset="utf-8"></script>
    <script>
      $(function () {
        var jqconsole = $('#console').jqconsole('Hi\n', '>>>');
        var startPrompt = function () {
          // Start the prompt with history enabled.
          jqconsole.Prompt(true, function (input) {
            // Output input with the class jqconsole-output.
            jqconsole.Write(input + '\n', 'jqconsole-output');
            // Restart the prompt.
            startPrompt();
          });
        };
        startPrompt();
      });
    </script>

Instantiating

    $(div).jqconsole(welcomeString, promptLabel, continueLabel);

Configuration

There isn't much initial configuration needed, because the user must supply
options and callbacks with each state change. There are a few config methods
provided to create custom shortcuts and change indentation width:

jqconsole.RegisterShortcut

Registers a callback for a keyboard shortcut. Takes two arguments:

jqconsole.SetIndentWidth

Sets the number of spaces inserted when indenting and removed when unindenting.
Takes one argument:

jqconsole.RegisterMatching

Registers an opening and closing characters to match and wraps each of the
opening and closing characters with a span with the specified class.
Takes one parameters:

Usage

Unlike most terminal plugins, jq-console gives you complete low-level control
over the execution; you have to call the appropriate methods to start input
or output:

jqconsole.Input:

Asks user for input. If another input or prompt operation is currently underway,
the new input operation is enqueued and will be called when the current
operation and all previously enqueued operations finish. Takes one argument:

jqconsole.Prompt

Asks user for input. If another input or prompt operation is currently underway
the new prompt operation is enqueued and will be called when the current
peration and all previously enqueued operations finish. Takes three arguments:

jqconsole.AbortPrompt

Aborts the current prompt operation and returns to output mode or the next
queued input/prompt operation. Takes no arguments.

Example:

    jqconsole.Prompt(true, function(input) {  
      alert(input);  
    });  
    // Give the user 2 seconds to enter the command.  
    setTimeout(function() {  
      jqconsole.AbortPrompt();  
    }, 2000);  

jqconsole.Write

Writes the given text to the console in a <span>, with an
optional class. If a prompt is currently being shown, the text is inserted
before it. Takes two arguments:

jqconsole.Append

Append the given node to the DOM. If a prompt is currently being shown, the text is inserted before it. Takes a single argument:

jqconsole.SetPromptText

Sets the text currently in the input prompt. Takes one parameter:

jqconsole.SetPromptLabel

Replaces the main prompt label. Takes two parameters:

jqconsole.ClearPromptText

Clears all the text currently in the input prompt. Takes one parameter:

jqconsole.GetPromptText

Returns the contents of the prompt. Takes one parameter:

jqconsole.Reset

Resets the console to its initial state, cancelling all current and pending
operations. Takes no parameters.

Example:

    jqconsole.Reset()  

jqconsole.GetColumn

Returns the 0-based number of the column on which the cursor currently is.
Takes no parameters.

Example:

    // Show the current line and column in a status area.  
    $('#status').text(jqconsole.GetLine() + ', ' + jqconsole.GetColumn())  

jqconsole.GetLine

Returns the 0-based number of the line on which the cursor currently is.
Takes no parameters.

Example:

    // Show the current line and column in a status area.  
    $('#status').text(jqconsole.GetLine() + ', ' + jqconsole.GetColumn())  

jqconsole.Focus

Forces the focus onto the console so events can be captured.
Takes no parameters.

Example:

    // Redirect focus to the console whenever the user clicks anywhere.  
    $(window).click(function() {  
      jqconsole.Focus();  
    })  

jqconsole.GetIndentWidth

Returns the number of spaces inserted when indenting. Takes no parameters.

Example:

    jqconsole.SetIndentWidth(4);  
    console.assert(jqconsole.GetIndentWidth() == 4);  

jqconsole.UnRegisterMatching

Deletes a certain matching settings set by jqconsole.RegisterMatching.
Takes two paramaters:

jqconsole.Dump

Returns the text content of the console.

jqconsole.GetState

Returns the current state of the console. Could be one of the following:

jqconsole.MoveToStart

Moves the cursor to the start of the current line.
Takes one parameter:

jqconsole.MoveToEnd

Moves the cursor to the end of the current line.
Takes one parameter:

jqconsole.Disable

Disables input and focus on the console.

jqconsole.Enable

Enables input and focus on the console.

jqconsole.IsDisabled

Returns true if the console is disabled.

jqconsole.GetHistory

Returns the contents of the history buffer.

jqconsole.SetHistory

Set the history buffer to the given array.

Takes one parameter:

jqconsole.ResetHistory

Resets the console history.

jqconsole.ResetMatchings

Resets the character matching configuration.

jqconsole.ResetShortcuts

Resets the shortcut configuration.

Default Key Config

The console responds to the followind keys and key combinations by default:

ANSI escape code SGR support

jq-console implements a large subset of the ANSI escape code graphics.
Using the .Write method you could add style to the console using
the following syntax:

ASCII 27 (decimal) or 0x1b (hex) [ SGR code m

Example:

jqconsole.Write('\033[31mRed Text');

Note that the third parameter escape must be true which defaults to it.

You'll need to include the ansi.css file for default effects or create your
own using the css classes from the table below.

SGR

Reference.

Code Effect Class
0 Reset / Normal
1 Bold `jqconsole-ansi-bold`
2 Faint `jqconsole-ansi-lighter`
3 Italic `jqconsole-ansi-italic`
4 Line below text `jqconsole-ansi-underline`
5 Blink: 1s delay `jqconsole-ansi-blink`
6 Blink: 0.5s delay `jqconsole-ansi-blink-rapid`
8 Hide text `jqconsole-ansi-hidden`
9 Line through text `jqconsole-ansi-line-through`
10 Remove all fonts
11-19 Add custom font `jqconsole-ansi-fonts-{N}` where N is code - 10
20 Add Fraktur font (not implemented in ansi.css) `jqconsole-ansi-fraktur`
21 Remove Bold and Faint effects
22 Same as 21
23 Remove italic and fraktur effects
24 Remove underline effect
25 Remove blinking effect(s).
28 Reveal text
29 Remove line-through effect
30-37 Set foreground color to color from the color table below jqconsole-ansi-color-{COLOR} where {COLOR} is the color name
39 Restore default foreground color
40-47 Set background color to color from the color table below `jqconsole-ansi-background-color-{COLOR}` where {COLOR} is the color name
49 Restore default background color
51 Adds a frame around the text `jqconsole-ansi-framed`
53 Line above text jqconsole-ansi-overline
54 Remove frame effect
55 Remove over-line effect

Colors

Reference.

Code offset Color
0 Black
1 Red
2 Green
3 Yellow
4 Blue
5 Magenta
6 Cyan
7 White

CSS Classes

Several CSS classes are provided to help stylize the console:

Of course, custom classes may be specified when using jqconsole.Write() for
further customization.

Contributors

Max Shawabkeh
Amjad Masad

License

MIT