Listeners

Listeners allow you to add your own commands to the terminal.

Structure

A listener is an associative map with following fields:

{
    commands: *associative map*,
    complete: *function(args [, async])*,
    execute: *function(args [, async])*
}

commands

command is an associative map, with commands the listener provides as keys and their help information as values. These information are arrays of strings, and the first element is used to display command list by executing help.

complete and execute

complete is called when the user presses TAB. execute is called when a command is executed.

They take a list of arguments as parameter, for convenience the first element (at index 0) is the command.

If the listener doesn't handle the plugin, they have to return no value (at least, a false value). Otherwise, they must return an array of strings, which are the outputs of the command.

Alternatively, they may give output asynchronously. In this case, they must return true. The functions receives as second parameter an async function, which must be called with an array of string as parameter to return values. This comes in handy when dealing with AJAX requests.

For convenience to complete a command, the plugin provides a function to select suggestions which fit an argument: $.terminal.among(argument, suggestions).

Example

var helloListener = {
    commands : {
        'hello' : [
            'Gives greetings',
            '',
            'Usage: \tbhello\tb [\tuwho\tu]',
            '',
            'If \tuwho\tu is not given, greets the world.'
        ],
    },
    complete: function(args) {
        switch (args[0]) {
            case 'hello':
                if (args.length > 2) {
                    return;
                }
                return $.terminal.among(args[1], [ 'me', 'world', 'you' ]);
        }
    },
    execute: function(args) {
        switch (args[0]) {
            case 'hello':
                return [ 'Hello ' + (args.length > 1 ? args[1] : 'world') + '!' ];
        }
    }
};

Using custom listeners

Give a listeners option when constructing the terminal:

$('div').terminal({
    listeners : [ ... ]
});

The order is important: when executing or completing a command, the first listener is be called, if it doesn't handle the command the second one is called, etc.

Add or remove listeners

$().terminal('addListeners', ...) or $().terminal('addListeners', array listeners) with listeners as parameters.

$().terminal('removeListeners', ...) or $().terminal('removeListeners', array listeners) with listeners as parameters.

$('#term').terminal('addListeners', myListener);

You can directly edit the listeners variable in the options as well:

var options = $('#term').terminal('options');
options.listeners = ...
$('#term').terminal('options', options);

Note that the listener used to provided the base commands is the last element of the array at the initialization, and you may remove it like any other listeners.

Built-in listeners

$.terminal.listeners contains some listeners:

Easily create single commands: $.terminal.listeners.command(name, help, execute [, complete])

If you just need to add a single command, this listener is for you! Give it a name (string), an help message (array of string), an execute function, and a complete function (this latter is optional), and it will return a listener structure handling this command.

The functions will only be called on the given command, that way you don't need to check it anymore. The arguments for both functions stay the same (see above). Warning: v2.5 lacks the async function, I spotted the error as I wrote these lines :)

Communicate with the server: $.terminal.listeners.jsonrpc(endpoint [, namespace] , commands)

Only available if jQuery JSON RPC plugin is included.

This listener allows to communicate with the server using JSON RPC protocol. You can easily write listeners for other protocols.

commands is an object containing command declarations: its name as key and its help message as value. AJAX requests will only be made on execution or completion.

On the server side, you must provide an execute function, and you may provide a complete function as well. Both receive only the list of arguments: there is no async function!

Debug with Firebug: $.terminal.listeners.firebug

This plugin shows the executed command with its arguments in Firebug, a plugin for Firefox. It works for completion too.

You may use it with other browser as well if they have the console.log function. Otherwise it's easy to build your own debug listener.

It should be the first listeners you specify in the listener list.