Getting Started

To use the Logger component, include the following source files in your web page with the script tag:

<!--CSS file (default YUI Sam Skin) --> <link type="text/css" rel="stylesheet" href="http://yui.yahooapis.com/2.5.1/build/logger/assets/skins/sam/logger.css"> <!-- Dependencies --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/yahoo-dom-event/yahoo-dom-event.js"></script> <!-- OPTIONAL: Drag and Drop (not required if not enabling drag and drop) --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/dragdrop/dragdrop-min.js"></script> <!-- Source file --> <script type="text/javascript" src="http://yui.yahooapis.com/2.5.1/build/logger/logger-min.js"></script>

Reading Log Messages

Instantiate a LogReader to display log messages on your web page:

<script type="text/javascript"> var myLogReader = new YAHOO.widget.LogReader(); </script>

Attach a LogReader to a specific HTML element by passing the element's ID to Logger's constructor:

<div id="myLogger"></div> <script type="text/javascript"> var myLogReader = new YAHOO.widget.LogReader("myLogger"); </script>

Attach a LogReader to a specific HTML element by passing an element reference to Logger's constructor:

<script type="text/javascript"> var myContainer = document.body.appendChild(document.createElement("div")); var myLogReader = new YAHOO.widget.LogReader(myContainer); </script>

Writing Log Messages

Use the YAHOO.log() function, part of the Yahoo Global Object, to write log messages from anywhere in your code:

<script type="text/javascript"> // Assigns default category "info" and default source "global" YAHOO.log("My log message"); </script>

Assign a category to your log message:

<script type="text/javascript"> // Assigns the category "source", which has a pre-defined style YAHOO.log("My log message", "warn"); </script>

Assign a custom category to your log message:

<style> .yui-log .mycategory {background-color:#7B0099;} /* customize a color */ </style> ... <script type="text/javascript"> // Assigns a custom, case-insensitive category "mycategory", which will // be styled by the custom CSS you define with the same string YAHOO.log("My log message", "mycategory"); </script>

Assign a category and a source to your log message:

<script type="text/javascript"> YAHOO.log("My log message", "error", "buggyscript.js"); </script>

Using Logger

This section describes in more detail the Logger, LogReader, and LogWriter classes, as well as some common configuration cases.

The Logger Class

YAHOO.widget.Logger is a singleton class that manages incoming log messages and makes them available for output to LogReader instances. By setting the Logger property maxStackEntries, you can cap the number of log messages the Logger will manage. Once the limit is reached, the oldest log message will be evicted to make room for the newer entry.

Some browsers have implemented a global console.log() method which can serve various functionalities. For instance, if you have the FireBug extension to Firefox installed, or the Safari JavaScript console enabled, logging messages to console.log() will output to browser-specific components. By default, the YUI Logger does not call this method, but you may wish enable this feature by calling YAHOO.widget.Logger.enableBrowserConsole(). Once enabled, calling YAHOO.widget.Logger.disableBrowserConsole() will disable this feature.

The Logger class also allows you to clear out all previous log messages:

<script type="text/javascript"> // Clears internal array of log message objects and clears all previous // log messages from any LogReaders. YAHOO.widget.Logger.reset(); </script>

The LogReader Class

YAHOO.widget.LogReader class creates a standalone UI control on a web page to easily display Logger messages included with debug builds of the YUI Library. LogReaders allow you to take full advantage of features like filtration by category and by source. The LogReader interface also allows you to pause and resume logging during script execution. Although LogReader has been pre-defined with a modestly configurable look and feel, advanced implementers may fully customize LogReader's CSS or subclass LogReader entirely for a customized experience.

Visibility of the LogReader UI is controlled using calls to show() and hide(). By default, the LogReader is visible.

// Hide the Log Reader UI (no loss of log messages) myLogReader.hide(); // Show the Log Reader UI myLogReader.show();

Common Configurations

The following properties are configurable using an object literal to set values in the constructor:

width

Width of console

height

Height of container

left/top/right/bottom

Position from edge of viewport

footerEnabled

If false, hides the footer

logReaderEnabled

If false, LogReader is paused

thresholdMax

Maximum number of messages to show in the console

thresholdMin

How many messages to keep displayed when thresholdMax is reached and console is cleared

draggable

If false, disables LogReader draggability, otherwise console is draggable (requires Drag and Drop Utility)

outputBuffer

Size of output buffer in milliseconds -- higher values will enhance performance

newestOnTop

If false, new entries will be added below previous entries

verboseOutput

If false, log entries will be printed in a more compact format

entryFormat

innerHTML template to customize the printed log entries

var myConfigs = { width: "20px", height: "30em", newestOnTop: false, footerEnabled: false }; var myContainer = null; // LogReader will create markup from scratch var myLogReader = new YAHOO.widget.LogReader(myContainer, myConfigs);

Customizing Output

The LogReader class allows you to customize the output format of log messages in three ways:

1. The config verboseOutput toggles between the default verbose and compact formats
2. The config entryFormat assigns a format template used to generate the entries' innerHTML strings
3. The LogReader's formatMsg method can be overridden with custom code

entryFormat Templates

// Customize the formatting of output to LogReader myLogReader.formatMsg = function(oLogMsg) { var category = oLogMsg.category; return '<p><span class="'+category+'">'+category+'</span> '+ oLogMsg.msg+'</p>'; };

entryFormat templates can contain markup as well as any of the following bracketed placeholders:

• category
• label
• sourceAndDetail
• message
• localTime
• elapsedTime
• totalTime

For example, the template used for verbose log entries (the default setting), is:

YAHOO.widget.LogReader.VERBOSE_TEMPLATE = "<span class='{category}'>{label}</span>{totalTime}ms (+{elapsedTime}) {localTime}:</p><p>{sourceAndDetail}</p><p>{message}</p>";

Customizing formatMsg

// Customize the formatting of output to LogReader myLogReader.formatMsg = function(oLogMsg) { var category = oLogMsg.category; return '<p><span class="'+category+'">'+category+'</span> '+ oLogMsg.msg+'</p>'; };

The LogWriter Class

The YAHOO.widget.LogWriter class provides a shortcut for implementers who are logging many messages from the same source. For instance, if you are debugging a class written in JavaScript, you may want to instantiate a single LogWriter to write logs for the entire class:

var MyClass = function(){ // Define a toString() for your class that can // identify the class and any instance information this.toString() = function() { return "MyClass instance data"; }; // Instantiate a LogWriter this.logger = new YAHOO.widget.LogWriter(this.toString()); // Now you can write log messages from your LogWriter this.logger.log("A new MyClass has been created","info"); }; // Every instance of your class can have its own LogWriter MyClass.prototype.logger = null; // This will log a message that is filterable by category and by source var myInstance = new MyClass();

Note that when you supply a space-delimited string to the LogWriter constructor, the first word of the string will be used to assign a source to the log message, and the rest of the string will be prepended to the log message for supplementary detail. LogReader will parse the string at the first empty space character. If there are no empty spaces in the string, the entire string will be used to assign a source to the log message.

Skinning Logger

The Logger comes with a default presentation or "skin," part of the "Sam Skin" visual treatment that accompanies most YUI controls. You can read more about the general approach to skinning YUI components in this in-depth article.

In the case of the Logger Control, there is no "core" CSS treatment — which is to say that there is no CSS that is considered essential to the functioning of the control. All of the CSS provided with Logger is part of the Sam Skin visual treatment.

To explore the CSS which controls the Logger's presentation, please review the Logger Skinning Example wherein the full CSS for the control is displayed.

YUI on Mobile: Using Logger Control with "A-Grade" Mobile Browsers

The Logger control has been tested on several high-end smart phones without any major known issues. It is meant primarily as a development tool, and therefore it is not recommended in production environments. Due to the inherent limitations found in mobile platforms, implementers should take into account the following preliminary list of known issues:

• The LogReader console may take up precious real estate.
• Output to the LogReader may experience delays due to the high-latency environment.
• Support for the native browser console.log() function may be unreliable at best or altogether non-existent.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUI SourceForge project site. Before filing new feature requests or bug reports, please review our reporting guidelines.

• Guidelines for YUI feature requests and bug reports.
• Review current bug list or file a new bug.
• Review current feature requests or file a new feature request.