Skip to main content

What You Can Echo?

echo is the most important method of jQuery Terminal. You use it to print stuff on the terminal.

String and other primitives​

You can echo strings and basic datatypes that can be converted to string.

This includes:

  • Numbers
  • Booleans
  • Regular Expressions
  • Null

Promises​

You can print a promise of the object that can be printed on the terminal. It can be any promise like object, same as with async/await. Which means that it can be real promise, jQuery Deferred, or even any object that have then then method.

ES6 Promise​

const promise = new Promise(resolve => {
    setTimeout(() => resolve('hello'), 100):
});

term.echo(promise);

Promise Like Object​

const promise = {
    then(fn) {
        fn('hello');
        return promise;
    }
};

term.echo(promise);

This object will work the same with async/await:

(async () => {
    term.echo(await promise);
})();

Array​

When you echo an array it will print it in columns.

const array = [
    "Lorem", "ipsum", "dolor", "sit", "amet", "consectetur", "adipiscing", "elit", "Huic",
    "mori", "optimum", "esse", "propter", "desperationem", "sapientiae", "illi",
    "propter", "spem", "vivere", "Duo", "Reges", "constructio", "interrete"
];

term.echo(array);

See the Pen Echo Array by Jakub T. Jankiewicz (@jcubic) on CodePen.

Function​

You can echo function that will be called on each render, that happen when you resize the terminal. With function you can create respnsive text that addapt to the size of the terminal. This is how default Greetings is created. It shows different ASCII Art based on the size of the terminal.

With function, you can print dynamic text using Figlet library, that renders ASCII text using different fonts.

term.echo(function() {
    const cols = this.cols();
    if (cols > 100) {
        return 'Large ASCII';
    } else if (cols > 50) {
        return 'Medium ASCII';
    } else (cols > 20) {
        return 'Small ASCII'
    }
});

Using Figlet​

First you need to include the figlet library:

<script src="https://cdn.jsdelivr.net/npm/figlet/lib/figlet.js"></script>

And jQuery Terminal figlet helper:

<script src="https://cdn.jsdelivr.net/gh/jcubic/jquery.terminal@devel/js/figlet.js"></script>

Then you can create a helper function that will display

const term = $('body').terminal({}, {
    greetings: false
});

(async () => {
    await $.terminal.figlet.load(['Slant']);
    term.echo($.terminal.figlet('Slant', 'jQuery Terminal'));
})();

$.terminal.figlet.load async function load all specified fonts, you can see the list of available fonts, on figlet demo website (type some text and click test all to see all fonts).

$.terminal.figlet returns a function that renders the text using figlet, because of this you have responsive text. See below demo how it works, you can resize the window, to see how the ASCII Art change.

See the Pen Terminal Figlet by Jakub T. Jankiewicz (@jcubic) on CodePen.

DOM Nodes and jQuery Objects​

jQuery Terminal don't allow to echo HTML directly, to prevent any misbehavior of your users, but you can echo DOM nodes (elements that represent HTML tags inside the browser):

const para = document.createElement('p');
para.innerText = 'hello, world!';
term.echo(para);

and jQuery object:

const $iframe = $('<iframe src="https://example.com"></iframe>');
term.echo($iframe);

Dolar function from jQuery also accepts HTML code and it create jQuery object from it, that object which wraps DOM node, can later be inserted into document.

See the Pen echo DOM node and jQuery object by Jakub T. Jankiewicz (@jcubic) on CodePen.

renderHandler​

When you have renderHandler you can print basciall anything, any kind of objects. Even React components. Below code use renderHandler to print object literals that by default are converted to string and display [object Object].

const term = $('body').terminal(/* your interpreter */, {
    renderHandler(value) {
        if ($.isPlainObject(value)) {
            this.echo(JSON.stringify(value, null, 2));
            return false;
        }
    }
});

term.echo({
    name: 'James Bond',
    code: '007'
});

See the Pen Echo Object by Jakub T. Jankiewicz (@jcubic) on CodePen.

Formatting The Text​

When working with normal text, the jQuery Terminal library allow for basic text formatting, with so called Terminal Formatting. It's a special syntax that you can use to change the style and color of the text.

Formatting syntax​

The formatting syntax looks like this:

[[bi;red;green]this is text]

This is basic example of the text "this is text" that will be bold and italic (b and i mnemonics). The text will have red color and green background.

List of Style Mnemonics​

Here is a list of all possible styles:

  • b — bold
  • i — italic
  • u — underline
  • o — overline
  • g — glow
  • s — strike

And there are two special characters:

  • ! — exclamation mark indicates that this is a link
  • @ — at sign indicates that this is an image

There are 2 required semicolons, which makes 3 arguments but they can be left blank.

This is valid formatting:

[[;;]this is text]

This will be converted as text wrapped in a span (generic inline element).

List of the Arguments​

  1. Style with any order of mneminics as a single string
  2. color, can be hex value, any CSS color name, or rgba color
  3. Background color that can be a vlue like color
  4. Class name or names separated by space
  5. Text of the formatting that will be included in data-text attribute, when you have long text and it wraps, the terminal will put the original text into data-text attribute so you can use it e.g. if you want to implement clicking on the link and do something with text that is clicked. The 5th argumnet is also where you put your URL for the images or links.
  6. The last argument is JSON object that contain attributes that will be added to a given element represented by the formatting. Because of security you're not allowed to put any argumnt. You can only add attributes that are listed on $.terminal.defaults.allowedAttributes array. The default list of attributes consist of: ['title', 'target', 'rel', /^aria-/, 'id', /^data-/].

Text inside formatting​

Inside formatting you can have normal text that will have the specified style. For the case of Images the text, will be alt attribute. Where you can describe what's on the image, for accessibility.

Here is full example of Terminal formatting:

[[!ub;#fff;#000;command;echo "hello";{"title": "this will execute echo command"}]echo "hello"]

With formatting like this you can add click event to the terminal and handle clicks:

term.on('click', '.command', function() {
    const command = $(this).data('text');
    this.exec(command);
    return false;
});
info

In above example we used exec terminal method, more about automation of the terminal in Automation Guide.

info

Terminal formatting is considered a low level way of formatting text. You can read about different ways in Formatters and Syntax Highlighting Guide.

See the Pen Terminal formatting by Jakub T. Jankiewicz (@jcubic) on CodePen.

Newline Ending​

By default, echo() method adds a newline at the end. But you can change this behavior by using an option: newline: false.

term.echo('hello, ', { newline: false }).echo('world!');

Text Wrapping​

The text wrapping in jQuery Terminal library is handled in JavaScript. It's not handled by CSS. By default,the Terminal use hard wrapping, which means that whole line if filled with characters and the word can break, where part of the word is in one line and the other in next line. You can change this behavior using keepWords option.

term.echo('Nobody expects the Spanish Inquisition!', { keepWords: true });

This of course is more important when text is long. Like in a demo below.

See the Pen echo + keepWords by Jakub T. Jankiewicz (@jcubic) on CodePen.

Buffering​

Terminal library use buffering for the printed stuff, but the buffer is flushed after each echo. You can change this behavior by using flush: false option and flushing manually.

import numberToWords from 'number-to-words';

for (let i = 0; i <= 100; ++i) {
    const num = numberToWords.toWords(i);
    term.echo(num, { flush: false });
}

term.flush();

You can also get the output buffer content as a string, similar to ob_get_contents() in PHP.

import numberToWords from 'number-to-words';

for (let i = 0; i <= 100; ++i) {
    const num = numberToWords.toWords(i);
    term.echo(num, { flush: false });
}

console.log(term.get_output_buffer());
term.flush();

See the Pen flush buffer by Jakub T. Jankiewicz (@jcubic) on CodePen.

info

The CodePen demo use importmap (inside HTML Tab) in order to use ESM modules inside the browser.