log4javascript quick start tutorial
Author: Tim Down - tim@log4javascript.org
Description: log4javascript, a logging framework for JavaScript based on log4j

# log4javascript

# log4javascript quick start tutorial

## Three step guide

1. ### Download the code

   Unzip the distribution and copy log4javascript.js into the desired location. No other files are necessary.

2. ### Initialize log4javascript in your web page

   Include log4javascript.js in your page using the code below. This code assumes log4javascript is stored in the same directory as your web page.

       <script type="text/javascript" src="log4javascript.js"></script>
       <script type="text/javascript">
       	var log = log4javascript.getDefaultLogger();
       </script>

   The default logger uses a `PopUpAppender` which opens a pop-up window. By default, this window will open when the first log message is written. For this to work, you will need to disable any pop-up blockers you may have.

3. ### Include logging statements in your code

   You have six logging methods at your disposal, depending on the severity of the message you wish to log. By default, all messages are logged in the pop-up window. The logging methods are:

   - `log.trace(message[, message2, ... ][, exception])`
   - `log.debug(message[, message2, ... ][, exception])`
   - `log.info(message[, message2, ... ][, exception])`
   - `log.warn(message[, message2, ... ][, exception])`
   - `log.error(message[, message2, ... ][, exception])`
   - `log.fatal(message[, message2, ... ][, exception])`

   And that's it, log away. Below are some examples of common types of logging.

## Logging examples

1. ### A simple logging message string

       	log.info("Hello world");

   displays

       19:52:03 INFO  - Hello world

2. ### Logging an error with a message

       	try {
       		throw new Error("Faking something going wrong!");
       	} catch (e) {
       		log.error("An error occurred", e);
       	}

   displays

       19:52:32 ERROR - An error occurred
       Exception: Faking something going wrong! on line number 80 in file basic.html

3. ### Logging multiple messages with one logging call

       	var a = "Hello";
       	var b = 3;
       	log.debug(a, b);

   displays

       19:53:05 DEBUG  - Hello 3

4. ### Logging an object

   Logging an object:

       	var obj = new Object();
       	obj.name = "Octopus";
       	obj.tentacles = 8;
       	log.info(obj);

   displays

       19:53:17 INFO  - {
       	name: Octopus,
       	tentacles: 8
       }

## Tweaking the default logger

The default logger is fine as a starting point, but what if you want the default logger with a few different options (say, bringing the pop-up to the front whenever a log message is logged, or having new log messages appear at the top of the pop-up rather than the bottom)?

In this case, you will need to create a new logger, then create a `PopUpAppender`, set options on it, and add it to the logger:

    <script type="text/javascript" src="log4javascript.js"></script>
    <script type="text/javascript">
    	// Create the logger
    	var log = log4javascript.getLogger();

    	// Create a PopUpAppender with default options
    	var popUpAppender = new log4javascript.PopUpAppender();

    	// Change the desired configuration options
    	popUpAppender.setFocusPopUp(true);
    	popUpAppender.setNewestMessageAtTop(true);

    	// Add the appender to the logger
    	log.addAppender(popUpAppender);

    	// Test the logger
    	log.debug("Hello world!");
    </script>

See this example in action (opens in new window)

Refer to the manual for more information about configuring appenders and more details about `PopUpAppender`.

## Sending log messages to the server

For this you will need to use an `AjaxAppender` as follows:

    	var ajaxAppender = new log4javascript.AjaxAppender(URL);
    	log.addAppender(ajaxAppender);

Now your log messages will appear in the pop-up window and be sent asynchronously to the URL you specify in the form of HTTP post parameters. No server-side code to process these requests is provided with log4javascript.

See `AjaxAppender` for more details on formatting log messages.

## Changing the format of log messages

Using a `Layout`, you can format log messages however you like. For example:

    	var log = log4javascript.getLogger("mylogger");
    	var popUpAppender = new log4javascript.PopUpAppender();
    	var layout = new log4javascript.PatternLayout("[%-5p] %m");
    	popUpAppender.setLayout(layout);

A call to

    	log.debug("Hello world");

will now result in output in the pop-up window of

    [DEBUG] Hello world

See `PatternLayout` for more details on formatting log messages.