[Cordova Wiki] Update of "LoggingPlugin" by PatrickMueller

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "LoggingPlugin" page has been changed by PatrickMueller:
http://wiki.apache.org/cordova/LoggingPlugin

New page:
= Logging Plugin =

As of Cordova 1.8, a new Logging plugin is available.  This plugin is not yet ready for public API status, but can be used by plugin developers.  It is available as a "built-in" plugin.

Currently, there is only a native implementation for iOS.  The default story for the Logging plugin is to use `window.console` methods to log the messages if a native implementation is not available.

The logger is installed as an object on the `cordova.logger` property and implemented in cordova-js as `lib/common/plugin/logger.js`.  

The logger has a notion of "levels" at which messages can be logged.  Levels are, in "increasing" order:

 * `LOG` - messages are always logged, but without a prefix
 * `ERROR` - messages are logged with an "ERROR" prefix
 * `WARN` - messages are logged with a "WARN" prefix
 * `INFO` - messages are logged with an "INFO" prefix
 * `DEBUG` - messages are logged with a "DEBUG" prefix

Those levels are also available as properties on the logger object.  eg, `logger.LOG == "LOG"`

== cordova.logger methods ==

'''`logger.level()`'''

Returns the current logging level.  Only messages at the returned level or lower will be displayed. Default: WARN

'''`logger.level(aString)`'''

Set and returns a new logging level.  Only messages at the returned level or lower will be displayed.

'''`logger.useConsole()`'''

Returns whether messages are logged via the `window.console` methods or not. Default: true

'''`logger.useConsole(aBoolean)`'''

Sets and returns whether messages are logged via the `window.console` methods or not.

'''`logger.log(aString, ...)`'''

Log a message at the LOG level, formatting the message via `utils.format()`

'''`logger.error(aString, ...)`'''

Log a message at the ERROR level, formatting the message via `utils.format()`

'''`logger.warn(aString, ...)`'''

Log a message at the WARN level, formatting the message via `utils.format()`

'''`logger.info(aString, ...)`'''

Log a message at the INFO level, formatting the message via `utils.format()`

'''`logger.debug(aString, ...)`'''

Log a message at the DEBUG level, formatting the message via `utils.format()`

'''`logger.logLevel(aLevelString, aString, ...)`'''

Log a message at the specified level, formatting the message via `utils.format()`

== Native Implementation ==

The native implementation currently supports one service/action: "Logger" / "logLevel", which corresponds to the `logger.logLevel()` method.  All of the setting/checking of the log level is done in !JavaScript.

To use the native implementation, a platform should arrange to call `logger.useConsole(false)` during startup.  

Messages logged BEFORE `deviceready` will be queued UNTIL `deviceready`, then logged.

It may be that some platforms may want to support a native logging level (eg, using Log4J or whatever), in which case we should add some additional native functions to query and set the log level.