planetstack/core/static/log4javascript-1.4.6/docs/quickstart.html

   1 <?xml version="1.0"?>\r
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\r
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">\r
   4         <head>\r
   5                 <title>log4javascript quick start tutorial</title>\r
   6                 <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />\r
   7                 <meta name="author" content="Tim Down - tim@log4javascript.org" />\r
   8                 <meta name="description" content="log4javascript, a logging framework for JavaScript based on log4j" />\r
   9                 <meta name="robots" content="all" />\r
  10                 <link rel="stylesheet" type="text/css" media="screen,print" href="../main.css" title="Default" />\r
  11         </head>\r
  12         <body>\r
  13                 <div id="container" class="nonav">\r
  14                         <div id="header">\r
  15                                 <h1><a href="index.html">log4javascript</a></h1>\r
  16                         </div>\r
  17                         <div id="content">\r
  18                                 <div id="nav">\r
  19                                         <a class="navitem" href="../index.html">home</a>\r
  20                                         | <a class="navitem" href="http://sourceforge.net/projects/log4javascript" target="_blank" title="Download (opens in new window)">download</a>\r
  21                                         | <a class="navitem" href="index.html">docs</a>\r
  22                                         | <span class="navitem">quick start</span>\r
  23                                         | <a class="navitem" href="../demos/index.html">demos</a>\r
  24                                         | <a class="navitem" href="http://log4javascript.org" target="_blank">website</a>\r
  25                                         | <a class="navitem" href="http://www.timdown.co.uk" target="_blank">timdown.co.uk</a>\r
  26                                 </div>\r
  27                                 <h1>log4javascript quick start tutorial</h1>\r
  28                                 <h2>Three step guide</h2>\r
  29                                 <ol>\r
  30                                         <li>\r
  31                                                 <h3>Download the code</h3>\r
  32                                                 <p>\r
  33                                                         Unzip the distribution and copy log4javascript.js into the desired\r
  34                                                         location. No other files are necessary.\r
  35                                                 </p>\r
  36                                         </li>\r
  37                                         <li>\r
  38                                                 <h3>Initialize log4javascript in your web page</h3>\r
  39                                                 <p>\r
  40                                                         Include log4javascript.js in your page using the code below. This\r
  41                                                         code assumes log4javascript is stored in the same directory as\r
  42                                                         your web page.\r
  43                                                 </p>\r
  44                                                 <pre class="code">\r
  45 &lt;script type="text/javascript" src="log4javascript.js"&gt;&lt;/script&gt;\r
  46 &lt;script type="text/javascript"&gt;\r
  47         var log = log4javascript.getDefaultLogger();\r
  48 &lt;/script&gt;\r
  49 </pre>\r
  50                                                 <p>\r
  51                                                         The default logger uses a <code><a href="manual.html#popupappender">PopUpAppender</a></code>\r
  52                                                         which opens a pop-up window. By default, this window will open when the first\r
  53                                                         log message is written. For this to work, you will need to disable any pop-up blockers\r
  54                                                         you may have.\r
  55                                                 </p>\r
  56                                         </li>\r
  57                                         <li>\r
  58                                                 <h3>Include logging statements in your code</h3>\r
  59                                                 <p>\r
  60                                                         You have six logging methods at your disposal, depending on the severity\r
  61                                                         of the message you wish to log. By default, all messages are logged\r
  62                                                         in the pop-up window. The logging methods are:\r
  63                                                 </p>\r
  64                                                 <ul>\r
  65                                                         <li><code>log.trace(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>\r
  66                                                         <li><code>log.debug(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>\r
  67                                                         <li><code>log.info(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>\r
  68                                                         <li><code>log.warn(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>\r
  69                                                         <li><code>log.error(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>\r
  70                                                         <li><code>log.fatal(<em>message</em>[, <em>message2</em>, ... ][, <em>exception</em>])</code></li>\r
  71                                                 </ul>\r
  72                                                 <p>\r
  73                                                         And that's it, log away. Below are some examples of common types of logging.\r
  74                                                 </p>\r
  75                                         </li>\r
  76                                 </ol>\r
  77                                 <h2>Logging examples</h2>\r
  78                                 <ol>\r
  79                                         <li>\r
  80                                                 <h3>A simple logging message string</h3>\r
  81                                                 <pre class="code">\r
  82         log.info("Hello world");\r
  83 </pre>\r
  84 displays\r
  85                                                 <pre class="console info">\r
  86 19:52:03 INFO  - Hello world\r
  87 </pre>\r
  88                                         </li>\r
  89                                         <li>\r
  90                                                 <h3>Logging an error with a message</h3>\r
  91                                                 <pre class="code">\r
  92         try {\r
  93                 throw new Error("Faking something going wrong!");\r
  94         } catch (e) {\r
  95                 log.error("An error occurred", e);\r
  96         }\r
  97 </pre>\r
  98 displays\r
  99                                                 <pre class="console error">\r
 100 19:52:32 ERROR - An error occurred\r
 101 Exception: Faking something going wrong! on line number 80 in file basic.html\r
 102 </pre>\r
 103                                         </li>\r
 104                                         <li>\r
 105                                                 <h3>Logging multiple messages with one logging call</h3>\r
 106                                                 <pre class="code">\r
 107         var a = "Hello";\r
 108         var b = 3;\r
 109         log.debug(a, b);\r
 110 </pre>\r
 111 displays\r
 112                                                 <pre class="console debug">\r
 113 19:53:05 DEBUG  - Hello 3\r
 114 </pre>\r
 115                                         </li>\r
 116                                         <li>\r
 117                                                 <h3>Logging an object</h3>\r
 118                                                 <p>Logging an object:</p>\r
 119                                                 <pre class="code">\r
 120         var obj = new Object();\r
 121         obj.name = "Octopus";\r
 122         obj.tentacles = 8;\r
 123         log.info(obj);\r
 124 </pre>\r
 125 displays\r
 126                                                 <pre class="console info">\r
 127 19:53:17 INFO  - {\r
 128         name: Octopus,\r
 129         tentacles: 8\r
 130 }\r
 131 </pre>\r
 132                                         </li>\r
 133                                 </ol>\r
 134                                 <h2>Tweaking the default logger</h2>\r
 135                                 <p>\r
 136                                         The default logger is fine as a starting point, but what if you want the default logger\r
 137                                         with a few different options (say, bringing the pop-up to the front whenever a log message is\r
 138                                         logged, or having new log messages appear at the top of the pop-up rather than the bottom)?\r
 139                                 </p>\r
 140                                 <p>\r
 141                                         In this case, you will need to create a new logger, then create a\r
 142                                         <code><a href="manual.html#popupappender">PopUpAppender</a></code>, set options\r
 143                                         on it, and add it to the logger:\r
 144                                 </p>\r
 145                                 <pre class="code">\r
 146 &lt;script type="text/javascript" src="log4javascript.js"&gt;&lt;/script&gt;\r
 147 &lt;script type="text/javascript"&gt;\r
 148         // Create the logger\r
 149         var log = log4javascript.getLogger();\r
 150 \r
 151         // Create a PopUpAppender with default options\r
 152         var popUpAppender = new log4javascript.PopUpAppender();\r
 153 \r
 154         // Change the desired configuration options\r
 155         popUpAppender.setFocusPopUp(true);\r
 156         popUpAppender.setNewestMessageAtTop(true);\r
 157 \r
 158         // Add the appender to the logger\r
 159         log.addAppender(popUpAppender);\r
 160 \r
 161         // Test the logger\r
 162         log.debug("Hello world!");\r
 163 &lt;/script&gt;\r
 164 </pre>\r
 165                                 <p>\r
 166                                         <a href="../examples/example_quickstart_1.html" title="View example (opens in new window)"\r
 167                                                 target="_blank">See this example in action</a> (opens in new window)\r
 168                                 </p>\r
 169                                 <p>\r
 170                                         Refer to the manual for more information about\r
 171                                         <a href="manual.html#configuration">configuring appenders</a> and more\r
 172                                         details about <code><a href="manual.html#popupappender">PopUpAppender</a></code>.\r
 173                                 </p>\r
 174                                 <h2>Sending log messages to the server</h2>\r
 175                                 <p>\r
 176                                         For this you will need to use an <code><a href="manual.html#ajaxappender">AjaxAppender</a></code>\r
 177                                         as follows:\r
 178                                 </p>\r
 179                                 <pre class="code">\r
 180         var ajaxAppender = new log4javascript.AjaxAppender(<em>URL</em>);\r
 181         log.addAppender(ajaxAppender);\r
 182 </pre>\r
 183                                 <p>\r
 184                                         Now your log messages will appear in the pop-up window and be sent\r
 185                                         asynchronously to the URL you specify in the form of HTTP post parameters.\r
 186                                         No server-side code to process these requests is provided with log4javascript.\r
 187                                 </p>\r
 188                                 <p>\r
 189                                         See <code><a href="manual.html#ajaxappender">AjaxAppender</a></code> for more details\r
 190                                         on formatting log messages.\r
 191                                 </p>\r
 192                                 <h2>Changing the format of log messages</h2>\r
 193                                 <p>\r
 194                                         Using a <code><a href="manual.html#layouts">Layout</a></code>, you can\r
 195                                         format log messages however you like. For example:\r
 196                                 </p>\r
 197                                 <pre class="code">\r
 198         var log = log4javascript.getLogger("mylogger");\r
 199         var popUpAppender = new log4javascript.PopUpAppender();\r
 200         var layout = new log4javascript.PatternLayout("[%-5p] %m");\r
 201         popUpAppender.setLayout(layout);\r
 202 </pre>\r
 203                                 <p>A call to</p>\r
 204                                 <pre class="code">\r
 205         log.debug("Hello world");\r
 206 </pre>\r
 207                                 <p>will now result in output in the pop-up window of </p>\r
 208                                 <pre class="console debug">\r
 209 [DEBUG] Hello world\r
 210 </pre>\r
 211                                 <p>\r
 212                                         See <code><a href="manual.html#patternlayout">PatternLayout</a></code> for more details\r
 213                                         on formatting log messages.\r
 214                                 </p>\r
 215                         </div>\r
 216                         <div id="footer">\r
 217                                 <span class="externallinkinfo">\r
 218                                         <strong>NB.</strong> All external links open in a new window.\r
 219                                 </span>\r
 220                                 Written by Tim Down. <a href="mailto:tim@log4javascript.org">tim@log4javascript.org</a>\r
 221                                 <br />\r
 222                                 log4javascript is distributed under the <a href="http://www.apache.org/licenses/LICENSE-2.0.html"\r
 223                                         title="Apache License, Version 2.0 (opens in new window)" target="_blank">Apache License,\r
 224                                         Version 2.0</a>\r
 225 \r
 226                         </div>\r
 227                 </div>\r
 228 \r
 229         </body>\r
 230 </html>\r