Basic screen logger

This tutorial is a community contribution by Christoph Ziegler working at “ARD Programmdirektion”, the programming directorate coordinating the joint TV programme “Das Erste” and the joint video-on-demand service “ARD Mediathek” of the regional public-service broadcasters in Germany.

HbbTV terminals have no console object to print messages for debugging. However, during development, you may want to be able to visualise state information of your HbbTV app; for example to see if everything works as expected or to find the cause for unexpected behaviour. This tutorial explains a basic logging utility contained in the GitHub repository that accompanies this series of tutorials. The utility prints log messages to the graphical user interface of your app. It achieves this by appending log messages to a <div> container, which it appends to the <body> element of the app’s document. There are plenty of other ways to implement screen loggers. This utility may help you debug your HbbTV app right away and may be a starting point and inspiration for you to develop your own more elaborate logging solution.

Full source code is available here: https://github.com/HbbTV-Association/Tutorials/tree/main/screen-logger

Create loggers and write log messages

All features you need to instantiate loggers, write log messages and to set global logging configurations are exposed by the global Logger element.

Example 1: Instantiate logger and write log message

Create instances of Logger with the new operator.

var logger = new Logger(); logger.log(“A simple log message”); // Will print: // 1. This is a simple log message

Example 2: Arguments of the log methods

Logging methods can handle arguments of type string or number. You can pass as many arguments as you like. Logger will concatenate them with a single space delimiter.

var product = “apple”; var quantity = 1; logger.log(“Customer bought”, quantity, product); // Will print: // 1. Customer bought 1 apple

Example 3: Add a tag name to your logger

You can pass an optional tag name to the constructor that, if set, will prefix all log messages of that logger instance. You could, for example, create instances of Logger per class or per module, which may help keeping track of where in your code the log line has been invoked.

var logger = new Logger(“basic-logger”); logger.log(“A simple log message”); // Will print: // 1. [basic-logger]: A simple log message

Example 4: Use multiple instances of Logger

All instances of logger print to the same log container in your app’s document.

var CarFactory = (function () {
 var factoryLogger = new Logger("factory-logger");
 var carLogger = new Logger("car-logger"); 
 var Car = function (numDoors) {
 this.numDoors = numDoors;
 carLogger.log("Car has", numDoors, "doors");
 }; 
 return {
 createCar: function (numDoors) {
 factoryLogger.log("Creating new car");
 return new Car(numDoors);
 },
 };
})(); 
CarFactory.createCar(4); 
// Will print:
// 1. [factory-logger]: Creating new car
// 2. [car-logger]: Car has 4 doors

Example 5: Make use of different log levels

Instances of Logger provide logging methods for different levels of importance of log messages. Log messages are prefixed with the respective log level. Following log levels are supported (sorted from low to high importance): VERBOSE, DEBUG, INFO, WARN, ERROR.

var logger = new Logger("log-level-demo");
logger.log("A log message");
logger.verbose("A verbose log message");
logger.debug("A debug message");
logger.info("An info message");
logger.warn("A warning");
logger.error("An error message"); 
// Will print:
// 1. [log-level-demo]: A log message
// 2. [log-level-demo]: VERBOSE: A verbose log message
// 3. [log-level-demo]: DEBUG: A debug message
// 4. [log-level-demo]: INFO: An info message
// 5. [log-level-demo]: WARN: A warning
// 6. [log-level-demo]: ERROR: An error message

Example 6: Styling of log messages

For different log levels, logger adds different classes to elements in the document that represent log messages. By default, the font color of log and debug messages is black. Verbose messages appear in gray, info messages in green, warnings in orange and error messages in red. You can change the appearance of log messages by changing the default style definition in the logger.css stylesheet:

/* safe area as recommended by standard */
div.safe_area
{
    position: absolute;
    left: 128px; top: 36px; width: 1024px; height: 648px;
    /** set background color and alpha */
    background-color: rgba(0, 0, 0, .5);
}

Example 7: Clear log

To clear the log run:

Logger.clear();

Visibility of the logs

By default, all log messages that reach the default verbosity level DEBUG will be appended to the container element for log messages. By default, this container will only be visible in the UI if a log message is written that reaches the default trigger level ERROR. Section Configuration explains how you can change the trigger and verbosity levels.

Logs written with logger.log() trigger the logger’s visibility at trigger level DEBUG. They are captured in the log container at verbosity level DEBUG or lower.

You can also programmatically show and hide the logger:

Logger.show(); // This will show the logger Logger.hide(); // This will hide the logger Logger.toggle(); // This will change the current visibility state

These methods could for example be invoked by key event handlers. This allows you, for example, to toggle the log container’s visibility with the press of a button on the remote.

Configuration

The global Logger object exposes the Config object which you can use to configure the logger. Values in the below example are the default values:

// If set true all log messages are prefixed with a line number.
Logger.Config.lineCountActive = true; 
// To prevent screen overflow, Logger removes older log messages
// from the log container if the maximum number of log lines
// is exceeded.
Logger.Config.maxLines = 15; 
// The log level that triggers visibility of the logger
Logger.Config.triggerLevel = Logger.Level.ERROR; 
// Threshold that a log message’s log level needs reach in order
// to appear in the log container
Logger.Config.verbosityLevel = Logger.Level.DEBUG;