# 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: * IE 9+ * Chrome * Firefox * Opera * iOS Safari and Chrome * Android Chrome ## Getting Started ### Echo example ```css /* 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; } ``` ```html
``` ### Instantiating ```javascript $(div).jqconsole(welcomeString, promptLabel, continueLabel, disableAutoFocus); ``` * `div` is the div element or selector. Note that this element must be explicity sized and positioned `absolute` or `relative`. * `welcomeString` is the string to be shown when the terminal is first rendered. * `promptLabel` is the label to be shown before the input when using Prompt(). * `continueLabel` is the label to be shown before the continued lines of the input when using Prompt(). * `disableAutoFocus` is a boolean indicating whether we should disable the default auto-focus behavior. ## 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: * __(int|string)__ *keyCode*: The code of the key pressing which (when Ctrl is held) will trigger this shortcut. If a string is provided, the ASCII code of the first character is taken. * __function__ *callback*: A function called when the shortcut is pressed; "this" will point to the JQConsole object. Example: // Ctrl+R: resets the console. jqconsole.RegisterShortcut('R', function() { this.Reset(); }); ### jqconsole.SetIndentWidth Sets the number of spaces inserted when indenting and removed when unindenting. Takes one argument: * __int__ *width*: The number of spaces in each indentation level. Example: // Sets the indent width to 4 spaces. jqconsole.SetIndentWidth(4); ### 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: * __char__ *open*: The opening character of a "block". * __char__ *close*: The closing character of a "block". * __string__ *class*: The css class that is applied to the matched characters. Example: jqconsole.RegisterMatching('{', '}', 'brackets'); ## 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: * __function__ *input_callback*: A function called with the user's input when the user presses Enter and the input operation is complete. Example: // Echo the input. jqconsole.Input(function(input) { jqconsole.Write(input); }); ### 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 four arguments: * __bool__ *history_enabled*: Whether this input should use history. If true, the user can select the input from history, and their input will also be added as a new history item. * __function__ *result_callback*: A function called with the user's input when the user presses Enter and the prompt operation is complete. * __function__ *multiline_callback*: If specified, this function is called when the user presses Enter to check whether the input should continue to the next line. The function must return one of the following values: * `false`: the input operation is completed. * `0`: the input continues to the next line with the current indent. * `N` (int): the input continues to the next line, and the current indent is adjusted by `N`, e.g. `-2` to unindent two levels. * __bool__ *async_multiline*: Whether the multiline callback function should be treated as an asynchronous operation and be passed a continuation function that should be called with one of the return values mentioned above: `false`/`0`/`N`. Example: jqconsole.Prompt(true, function(input) { // Alert the user with the command. alert(input); }, function (input) { // Continue if the last character is a backslash. return /\\$/.test(input); }); ### 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 ``, with an optional class. If a prompt is currently being shown, the text is inserted before it. Takes two arguments: * __string__ *text*: The text to write. * __string__ *cls*: The class to give the span containing the text. Optional. * __bool__ *escape*: Whether the text to write should be html escaped. Optional, defaults to true. Examples: jqconsole.Write(output, 'my-output-class') jqconsole.Write(err.message, 'my-error-class') ### 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: * __(string|Element)__ *node*: The DOM Element or html string to append to the console just before the prompt. Example: // Add a div with the text 'hello' on a red background using jquery jqconsole.Append($('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 |
Code offset | Color |
---|---|
0 | Black |
1 | Red |
2 | Green |
3 | Yellow |
4 | Blue |
5 | Magenta |
6 | Cyan |
7 | White |