Gitiles
Code Review Sign In
gerrit.opencord.org / xos / 89f8a9e8c2468f09e52b05f12370940555185561 / . / xos / core / static / log4javascript-1.4.6 / docs / quickstart.html
blob: 3bffff5497fbc7af4b08f0edd3176689ab4f9f2a [file] [log] [blame]
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>log4javascript quick start tutorial</title>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<meta name="author" content="Tim Down - tim@log4javascript.org" />
<meta name="description" content="log4javascript, a logging framework for JavaScript based on log4j" />
<meta name="robots" content="all" />
<link rel="stylesheet" type="text/css" media="screen,print" href="../main.css" title="Default" />
</head>
<body>
<div id="container" class="nonav">
<div id="header">
<h1><a href="index.html">log4javascript</a></h1>
</div>
<div id="content">
<div id="nav">
<a class="navitem" href="../index.html">home</a>
| <a class="navitem" href="http://sourceforge.net/projects/log4javascript" target="_blank" title="Download (opens in new window)">download</a>
| <a class="navitem" href="index.html">docs</a>
| <span class="navitem">quick start</span>
| <a class="navitem" href="../demos/index.html">demos</a>
| <a class="navitem" href="http://log4javascript.org" target="_blank">website</a>
| <a class="navitem" href="http://www.timdown.co.uk" target="_blank">timdown.co.uk</a>
</div>
<h1>log4javascript quick start tutorial</h1>
<h2>Three step guide</h2>
<ol>
<li>
<h3>Download the code</h3>
<p>
Unzip the distribution and copy log4javascript.js into the desired
location. No other files are necessary.
</p>
</li>
<li>
<h3>Initialize log4javascript in your web page</h3>
<p>
Include log4javascript.js in your page using the code below. This
code assumes log4javascript is stored in the same directory as
your web page.
</p>
<pre class="code">
&lt;script type="text/javascript" src="log4javascript.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript"&gt;
var log = log4javascript.getDefaultLogger();
&lt;/script&gt;
</pre>
<p>
The default logger uses a <code><a href="manual.html#popupappender">PopUpAppender</a></code>
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.
</p>
</li>
<li>
<h3>Include logging statements in your code</h3>
<p>
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:
</p>
<ul>
<li><code>log.trace(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
<li><code>log.debug(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
<li><code>log.info(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
<li><code>log.warn(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
<li><code>log.error(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
<li><code>log.fatal(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>
</ul>
<p>
And that's it, log away. Below are some examples of common types of logging.
</p>
</li>
</ol>
<h2>Logging examples</h2>
<ol>
<li>
<h3>A simple logging message string</h3>
<pre class="code">
log.info("Hello world");
</pre>
displays
<pre class="console info">
19:52:03 INFO - Hello world
</pre>
</li>
<li>
<h3>Logging an error with a message</h3>
<pre class="code">
try {
throw new Error("Faking something going wrong!");
} catch (e) {
log.error("An error occurred", e);
}
</pre>
displays
<pre class="console error">
19:52:32 ERROR - An error occurred
Exception: Faking something going wrong! on line number 80 in file basic.html
</pre>
</li>
<li>
<h3>Logging multiple messages with one logging call</h3>
<pre class="code">
var a = "Hello";
var b = 3;
log.debug(a, b);
</pre>
displays
<pre class="console debug">
19:53:05 DEBUG - Hello 3
</pre>
</li>
<li>
<h3>Logging an object</h3>
<p>Logging an object:</p>
<pre class="code">
var obj = new Object();
obj.name = "Octopus";
obj.tentacles = 8;
log.info(obj);
</pre>
displays
<pre class="console info">
19:53:17 INFO - {
name: Octopus,
tentacles: 8
}
</pre>
</li>
</ol>
<h2>Tweaking the default logger</h2>
<p>
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)?
</p>
<p>
In this case, you will need to create a new logger, then create a
<code><a href="manual.html#popupappender">PopUpAppender</a></code>, set options
on it, and add it to the logger:
</p>
<pre class="code">
&lt;script type="text/javascript" src="log4javascript.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript"&gt;
// 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!");
&lt;/script&gt;
</pre>
<p>
<a href="../examples/example_quickstart_1.html" title="View example (opens in new window)"
target="_blank">See this example in action</a> (opens in new window)
</p>
<p>
Refer to the manual for more information about
<a href="manual.html#configuration">configuring appenders</a> and more
details about <code><a href="manual.html#popupappender">PopUpAppender</a></code>.
</p>
<h2>Sending log messages to the server</h2>
<p>
For this you will need to use an <code><a href="manual.html#ajaxappender">AjaxAppender</a></code>
as follows:
</p>
<pre class="code">
var ajaxAppender = new log4javascript.AjaxAppender(<em>URL</em>);
log.addAppender(ajaxAppender);
</pre>
<p>
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.
</p>
<p>
See <code><a href="manual.html#ajaxappender">AjaxAppender</a></code> for more details
on formatting log messages.
</p>
<h2>Changing the format of log messages</h2>
<p>
Using a <code><a href="manual.html#layouts">Layout</a></code>, you can
format log messages however you like. For example:
</p>
<pre class="code">
var log = log4javascript.getLogger("mylogger");
var popUpAppender = new log4javascript.PopUpAppender();
var layout = new log4javascript.PatternLayout("[%-5p] %m");
popUpAppender.setLayout(layout);
</pre>
<p>A call to</p>
<pre class="code">
log.debug("Hello world");
</pre>
<p>will now result in output in the pop-up window of </p>
<pre class="console debug">
[DEBUG] Hello world
</pre>
<p>
See <code><a href="manual.html#patternlayout">PatternLayout</a></code> for more details
on formatting log messages.
</p>
</div>
<div id="footer">
<span class="externallinkinfo">
<strong>NB.</strong> All external links open in a new window.
</span>
Written by Tim Down. <a href="mailto:tim@log4javascript.org">tim@log4javascript.org</a>
<br />
log4javascript is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html"
title="Apache License, Version 2.0 (opens in new window)" target="_blank">Apache License,
Version 2.0</a>
</div>
</div>
</body>
</html>