# Terminal Riot Tag

A pretend commandline interface capable of displaying output from a "shell"
Javascript class. Multiple tags can be used on a page, each will work completely
independently.

## Dependencies

- [Riot](http://riotjs.com/) 2.3+

## Usage

    <terminal shell='myshellclass' welcome='text' prompt='text'></terminal>

    <script src='riot+compiler.min.js'></script>
    <script src='myshell.js'></script>
    <script src='terminal.tag' type='riot/tag'></script>
    <script>riot.mount('terminal')</script>

## Configuring

The terminal tag accepts 3 optional parameters:

- `shell` - Text specifying the shell class to interact with.
- `welcome` - Text/HTML displayed when a terminal is first mounted.
- `prompt` - Text/HTML before the command line input. Defaults to `'$ '`.

With no shell logic, the terminal tag will simply print commands entered.

Note: `welcome` and `prompt` can also be specified in the shell. Shell values
take priority over parameter values.

## Making A Shell Class

A shell class should be defined before the tag is mounted by riot. It should
expect a single parameter (the terminal tag itself) which will be an observable
object.

This observable will emit `'cmd_entered'` events containing input for
processing. Here is a minimal shell:

    // Contents of myshell.js
    function myshellclass(events) {
       this.prompt = ''
       this.welcome = ''
       events.on('cmd_entered', function(input) {
         // Do processing
       })
    }

### Events

The observable provides events to make things happen:

    events.trigger('disp_add', text)   // Append `text` to the display
    events.trigger('disp_set', text)   // Display only `text`
    events.trigger('disp_clear')       // Clear the display
    events.trigger('prompt_set', text) // Change the prompt to `text`
    events.trigger('prompt_hide')      // Hide the command prompt
    events.trigger('prompt_show')      // Show the command prompt
    events.trigger('cmd_add', text)    // Append `text` to the command line
    events.trigger('cmd_set', text)    // Set the command line to `text`
    events.trigger('cli_hide')         // Hide the command line and prompt
    events.trigger('cli_show')         // Show the command line and prompt

There is also an event to swap between sets of displays and prompts:

    events.trigger('context_swap', name)

The starting context name is `'default'`. Calling `'context_swap'` with:

- a new name - initialises a new, empty set.
- an existing name - loads that named set.
- no name - returns to the `'default'` set.

### Terminal ID

The observable also provides the id of the terminal tag via an `id` property.
This can be used, for example, for attaching handlers:

    document.getElementById(events.id).onkeypress = function() {}