Ticker-log NPM

ticker-log

On-screen logging utility.

Monkey-patches and chains the browser's console object.

Functionality is driven by console statements, window.ticker, and keyboard chords starting with ` (back-tick).

This module facilitates an interactive-style of development/non-production logging.

demo

Play with ticker-log: http://jonbri.github.io/ticker-log/

Example Usage

Load node_modules/ticker-log/dist/ticker.min.js and press `-t to see a ticker log.

Press `-h to show the quick-help reference.

In your source code, execute:

console.log('`', 'hello ticker-log');

By default, console's log function accepts ticker-log invocations (passing in the ` character as the first argument).

Switch console "channel"

Rather than log you could listen to the warn channel.

Press `-<tab> a few times until you see "listening to warn..." and now only invocations of console.warn('`', '...') will be printed.

To show all output to the current channel press `-b, and to show all output from all channels use window.ticker.listenToEverything().

Execute ad-hoc testing code with keyboard "macros"

watch a variable:

var a = 0;
setInterval(function() {
    console.log('`', a);
}, 500);
// do complicated things with "a"...

Usage of ticker-log is best suited for one-off, quick debugging situations, with any api code remnants removed before pushing to production.

Motivation

Displaying on-screen logging output reduces browser debugger juggling (dev-tools, Firebug, etc) while you exercise your application.

It can also be valuable to target a specific sub-set of logs both statically (in your code) as well as at run-time using keyboard chords.

Typical use-cases:

a better approach to "throw an alert in there"
developing on non-desktop devices (difficult to access console)
debugging timing issues that involve user interaction
"special-event" emitting (listening and firing)

Features

Configurable via API and URL parameters
Swap log view with textarea for easy copy/pasting
Lightweight, no dependencies
Macro system for run-time, on-demand, static function execution
Regex log filtering

Installation

npm install ticker-log

Load script: node_modules/ticker-log/dist/ticker.min.js

Interface

To write to Ticker's "ticker tape" simply pass in a back-tick (`) as a first argument to console's logging functions (log, fatal, etc...).

For example:

console.log('`', 'lorum ipsum...');
console.fatal('`', 'something very bad just happened...');

All actions can be driven by keyboard shortcut chords. Every key-combination starts with the back-tick key (`).

On-screen

Increase and decrease the speed of the ticker with `-<up> and `-<down>.

Move the horizontal position of the logs with `-<left> and `-<right>.

Change the vertical starting position with `-<pageUp> and `-<pageDown>.

Pause movement with `-p (or on-click) and remove all with `-k.

Show the current ticker log in a textarea (useful for copy/pasting) with `-o. Show all the accrued log output with `-l. Reverse contents with `-f (flip).

Embed the current configuration settings in the browser-window's url with `-<enter>.

For the full list of actions, show the help screen with `-h.

Configuration

A configuration object is maintained, of which most properties (if they differ from their default) can be expressed as a JSON object url parameter.

Property examples:

whether to show line numbers (default=true) (showLineNumbers)
speed logs travel up the screen (interval)
starting position of logs (logStartTop)
flush to left or right of screen (align)
console channel to listen to (channel)
don't trail previous log (default=true) (trailPreviousLog)

Return a copy of the current config settings by invoking the config API with no arguments:

var alignment = window.ticker.config().align;

Set a configuration property by passing an object into config:

window.ticker.config({
    align: 'right'
});

Configuration settings take this format when embedded as a url parameter:

http://localhost/index.html?ticker-log={"interval":275,"channel":"debug"}

API

Most on-screen actions can be scripted by using the global ticker object:

window.ticker.help();          # show help screen
window.ticker.config();        # return config object clone
window.ticker.config(o);       # o overlays configuration object
window.ticker.increaseSpeed(); # increase speed
window.ticker.decreaseSpeed(); # decrease speed
window.ticker.moveUp();        # make starting position a little higher
window.ticker.moveDown();      # make starting position a little lower
window.ticker.moveLeft();      # move logs to the left of the screen (the default)
window.ticker.moveRight();     # move logs to the right of the screen
window.ticker.pause();         # pause ticker log movement
window.ticker.kill();          # remove all ticker logs from screen
window.ticker.output();        # show current on-screen logs in textarea
window.ticker.outputAll();     # show _all_ accrued logging in textarea
window.ticker.flip();          # reverse order of textarea text
window.ticker.dump();          # show all configuration

Additional API is covered in the following sections.

Channels

Channels allow you to control which logs are printed to the screen:

log (default)
debug
warn
error
trace

By default, within the current channel, console invocations that are given ` as the first argument are printed.

To print all calls to the current channel set the requireBacktick configuration property to false (`-b).

To show all console logging (regardless of channel) using the listenToEverything api function.

Macros

Macros are bits of code you want to run at ad-hoc times. There are 10 "slots" stored in keys 0-9.

Macros 0-8 are reserved for api-driven macros:

var variableToTrack;
window.ticker.registerMacro(0, function() {
    // output values of variables in closure scope
    console.log('`', 'variableToTrack: ' + variableToTrack);
});
// code exercises "variableToTrack"...
// invoke macro by pressing `-0

Macro 9 is reserved for an on-screen editing option. Press `-m and a textarea will appear. Enter JavaScript code to be evaled and press `-m again to "register" the macro.

Filtering

Filter all log output by string:

window.ticker.filter('string subset match');

regex:

window.ticker.filter(/^startsWith/);

function:

window.ticker.filter(function(s) {
    // do something with log text
});

Pair filtering with listenToEverything to broadly filter:

window.ticker.listenToEverything();
window.ticker.filter(someErrorCode);

Custom action key

Use a custom key rather than the default ` key for keyboard chords:

// additionally use the 'z' key as a modifier
window.ticker.config({
    defaultBacktickKeys: [192, 90] // `, Z
});

Global-state Impact

window.history.pushState and window.location.replace
- "save" action (`-<enter>)
window.ticker
- api namespace
console functions (log, debug, etc)
- console overrides are reverted when applicable (such as when changing channels)

Reset to default state:

window.ticker.reset();

Build

npm install
npm test        # run test suite (qunit, phantomjs)
npm run lint    # eslint
npm run serve   # http://localhost:9000/index.html
npm run package # build and populate dist