YUI recommends YUI3.

YUI 2 has been deprecated since 2011. This site acts as an archive for files and documentation.

This documentation is no longer maintained.

YUI 2: Logger

YUI 2: Logger

Image: The Logger's optional UI.The Logger Control provides a simple way to read or write log messages with a single line of code. With this control, you can tap into the rich event-driven messages included with the YUI Library's debug files; This messaging allows you to get a fuller picture of the inner workings of any YUI Library component. The Logger Control provides a simple messaging interface that allows you to filter, pause, resume, and clear log messages on your screen. Whether or not you invoke this UI, you can monitor log output via the FireBug extension for Firefox or via the Safari JavaScript console. The Logger Control supports logging messages with customizable categories and sources. Adventurous developers can extend Logger to build their own implementations to suit any requirement.

Getting Started

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

  1. <!--CSS file (default YUI Sam Skin) -->
  2. <link type="text/css" rel="stylesheet" href="http://yui.yahooapis.com/2.9.0/build/logger/assets/skins/sam/logger.css">
  3.  
  4. <!-- Dependencies -->
  5. <script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
  6.  
  7. <!-- OPTIONAL: Drag and Drop (not required if not enabling drag and drop) -->
  8. <script src="http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop-min.js"></script>
  9.  
  10. <!-- Source file -->
  11. <script src="http://yui.yahooapis.com/2.9.0/build/logger/logger-min.js"></script>
  12.  
<!--CSS file (default YUI Sam Skin) -->
<link type="text/css" rel="stylesheet" href="http://yui.yahooapis.com/2.9.0/build/logger/assets/skins/sam/logger.css">
 
<!-- Dependencies -->
<script src="http://yui.yahooapis.com/2.9.0/build/yahoo-dom-event/yahoo-dom-event.js"></script>
 
<!-- OPTIONAL: Drag and Drop (not required if not enabling drag and drop) -->
<script src="http://yui.yahooapis.com/2.9.0/build/dragdrop/dragdrop-min.js"></script>
 
<!-- Source file -->
<script src="http://yui.yahooapis.com/2.9.0/build/logger/logger-min.js"></script>
 
Next, apply the yui-skin-sam class name to an element that is a parent of the element in which the Logger Control lives. You can usually accomplish this simply by putting the class on the <body> tag:

  1. <body class="yui-skin-sam">
  2.  
<body class="yui-skin-sam">
 

For more information on skinning YUI components and making use of default skins, see our Understanding YUI Skins article here on the website.

YUI dependency configurator.

YUI Dependency Configurator:

Instead of copying and pasting the filepaths above, try letting the YUI dependency Configurator determine the optimal file list for your desired components; the Configurator uses YUI Loader to write out the full HTML for including the precise files you need for your implementation.

Note: If you wish to include this component via the YUI Loader, its module name is logger. (Click here for the full list of module names for YUI Loader.)

Where these files come from: The files included using the text above will be served from Yahoo! servers. JavaScript files are minified, meaning that comments and white space have been removed to make them more efficient to download. To use the full, commented versions or the -debug versions of YUI JavaScript files, please download the library distribution and host the files on your own server.

Order matters: As is the case generally with JavaScript and CSS, order matters; these files should be included in the order specified above. If you include files in the wrong order, errors may result.

Reading Log Messages

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

  1. var myLogReader = new YAHOO.widget.LogReader();
  2.  
var myLogReader = new YAHOO.widget.LogReader();
 

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

  1. <div id="myLogger"></div>
  2.  
<div id="myLogger"></div>
 
  1. var myLogReader = new YAHOO.widget.LogReader("myLogger");
  2.  
var myLogReader = new YAHOO.widget.LogReader("myLogger");
 

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

  1. var myContainer = document.body.appendChild(document.createElement("div"));
  2. var myLogReader = new YAHOO.widget.LogReader(myContainer);
  3.  
var myContainer = document.body.appendChild(document.createElement("div"));
var myLogReader = new YAHOO.widget.LogReader(myContainer);
 

Writing Log Messages

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

  1. // Assigns default category "info" and default source "global"
  2. YAHOO.log("My log message");
  3.  
// Assigns default category "info" and default source "global"
YAHOO.log("My log message");
 

Assign a category to your log message:

  1. // Assigns the category "source", which has a pre-defined style
  2. YAHOO.log("My log message", "warn");
  3.  
// Assigns the category "source", which has a pre-defined style
YAHOO.log("My log message", "warn");
 

Assign a custom category to your log message:

  1. /* customize a color */
  2. .yui-log .mycategory {
  3.     background-color: #7B0099;
  4. }
  5.  
/* customize a color */
.yui-log .mycategory {
    background-color: #7B0099;
}
 
  1. // Assigns a custom, case-insensitive category "mycategory", which will
  2. // be styled by the custom CSS you define with the same string
  3. YAHOO.log("My log message", "mycategory");
  4.  
// 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");
 

Assign a category and a source to your log message:

  1. YAHOO.log("My log message", "error", "buggyscript.js");
  2.  
YAHOO.log("My log message", "error", "buggyscript.js");
 

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:

  1. // Clears internal array of log message objects and clears all previous
  2. // log messages from any LogReaders.
  3. YAHOO.widget.Logger.reset();
  4.  
// Clears internal array of log message objects and clears all previous
// log messages from any LogReaders.
YAHOO.widget.Logger.reset();
 

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.

  1. // Hide the Log Reader UI (no loss of log messages)
  2. myLogReader.hide();
  3.  
  4. // Show the Log Reader UI
  5. myLogReader.show();
  6.  
// 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
  1. var myConfigs = {
  2.     width: "20px",
  3.     height: "30em",
  4.     newestOnTop: false,
  5.     footerEnabled: false
  6. };
  7. var myContainer = null; // LogReader will create markup from scratch
  8. var myLogReader = new YAHOO.widget.LogReader(myContainer, myConfigs);
  9.  
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
  1. // Customize the formatting of output to LogReader
  2. myLogReader.formatMsg = function(oLogMsg) {
  3.    var category = oLogMsg.category;
  4.    return '<p><span class="'+category+'">'+category+'</span> '+ oLogMsg.msg+'</p>';
  5. };
  6.  
// 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:

  1. YAHOO.widget.LogReader.VERBOSE_TEMPLATE =
  2.     "<span class='{category}'>{label}</span>{totalTime}ms (+{elapsedTime}) {localTime}:</p><p>{sourceAndDetail}</p><p>{message}</p>";
  3.  
YAHOO.widget.LogReader.VERBOSE_TEMPLATE =
    "<span class='{category}'>{label}</span>{totalTime}ms (+{elapsedTime}) {localTime}:</p><p>{sourceAndDetail}</p><p>{message}</p>";
 
Customizing formatMsg
  1. // Customize the formatting of output to LogReader
  2. myLogReader.formatMsg = function(oLogMsg) {
  3.    var category = oLogMsg.category;
  4.    return '<p><span class="'+category+'">'+category+'</span> '+ oLogMsg.msg+'</p>';
  5. };
  6.  
// 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:

  1. var MyClass = function(){
  2.     // Define a toString() for your class that can
  3.     // identify the class and any instance information
  4.     this.toString() = function() {
  5.         return "MyClass instance data";
  6.     };
  7.  
  8.     // Instantiate a LogWriter
  9.     this.logger = new YAHOO.widget.LogWriter(this.toString());
  10.  
  11.     // Now you can write log messages from your LogWriter
  12.     this.logger.log("A new MyClass has been created","info");
  13. };
  14.  
  15. // Every instance of your class can have its own LogWriter
  16. MyClass.prototype.logger = null;
  17.  
  18. // This will log a message that is filterable by category and by source
  19. var myInstance = new MyClass();
  20.  
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.

The Logger Control

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

About this Section: YUI generally works well with mobile browsers that are based on A-Grade browser foundations. For example, Nokia's N-series phones, including the N95, use a browser based on Webkit — the same foundation shared by Apple's Safari browser, which is found on the iPhone. The fundamental challenges in developing for this emerging class of full, A-Grade-derived browsers on handheld devices are:

  • Screen size: You have a much smaller canvas;
  • Input devices: Mobile devices generally do not have mouse input, and therefore are missing some or all mouse events (like mouseover);
  • Processor power: Mobile devices have slower processors that can more easily be saturated by JavaScript and DOM interactions — and processor usage affects things like battery life in ways that don't have analogues in desktop browsers;
  • Latency: Most mobile devices have a much higher latency on the network than do terrestrially networked PCs; this can make pages with many script, css or other types of external files load much more slowly.

There are other considerations, many of them device/browser specific (for example, current versions of the iPhone's Safari browser do not support Flash). The goal of these sections on YUI User's Guides is to provide you some preliminary insights about how specific components perform on this emerging class of mobile devices. Although we have not done exhaustive testing, and although these browsers are revving quickly and present a moving target, our goal is to provide some early, provisional advice to help you get started as you contemplate how your YUI-based application will render in the mobile world.

More Information:

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 YUILibrary.com forums.

Also be sure to check out 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 YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Logger Control Cheat Sheet:

Cheat Sheet for the Logger Control.

Download full set of cheat sheets.

Logger Control Examples:

Other YUI Examples That Make Use of the Logger Control:

More Reading about the YUI Logger Control:

YUI Logger on del.icio.us:

Copyright © 2013 Yahoo! Inc. All rights reserved.

Privacy Policy - Copyright Policy - Job Openings