# Mojo.Log

## Namespace Detail

The framework provides a set of logging methods aimed at providing an efficient way to output interesting information from a running application but not have it slow down the application.

There are three levels of logging, in descending order, info, warn and error, with corresponding methods Mojo.Log.info(), Mojo.Log.warn() and Mojo.Log.error(). Only messages at or below the current logging level are printed.

The reason these logging APIs can keep an application from slowing down is that they don't end up constructing additional string objects unless the message is at a level where it will be printed. This isn't possible if you use console.log() and create the string to log by string addition. With these APIs, all the objects needed for logging are passed to the logging function, and only turned into strings if the message is actually going to be printed. This should make logging statements in an application pretty cheap, unless one is creating extra objects just for the purpose of logging.

### Using logging

The logging methods are designed to work like the ones in the Firebug Console API.

By default, all parameters passed to a logging function are concatenated together with a single space separating each parameter, using Array.join()

>     Mojo.Log.info("I have", 3, "eggs.");

would output

>     "I have 3 eggs."

You can also use a limited number of formatting characters, akin to those found in Java and C. For example:

>     var favoriteColor = 'blue';
>     Mojo.Log.info("My favorite color is %s.", favoriteColor);

would output

>     My favorite color is blue.

Right now you can use %s, %d, %f, %i, %o and %j. The first four are essentially the same, although we might eventually support more sophisticated number formatting. %o converts the parameter to a string using Prototype's Object.inspect(), while %j converts it using Object.toJSON().

In desktop browsers, these messages will frequently be adorned based on the level. For MojoSysMgr we've added some text to the message and some delimiters to try to get the messages to stand out a little more.

### Adding logging to your objects

If it feels inconvenient to have to type Mojo.Log.[info|warn|error] everywhere, you can add the logging methods to the prototype on your objects.

For example, the following line is used to add these logging methods to every scene controller:

>     Mojo.Log.addLoggingMethodsToPrototype(Mojo.Controller.SceneController);

So in your scene assistants, you can access the logging with

>     this.controller.info("Welcome to the dollhouse.");

If you find yourself doing even more logging than that, you could add the logging methods directly to your scene assistant using the technique used for the scene controller.

### Controlling logging

The current logging level is found in Mojo.Log.currentLogLevel, and defaults to 0. You can control the level of logging for your application by creating a file called `framework_config.json` in your application's directory that looks like

>     {
>       "logLevel": 99
>     }

The values are

>     Mojo.Log.LOG_LEVEL_ERROR = 0;
>     Mojo.Log.LOG_LEVEL_WARNING = 10;
>     Mojo.Log.LOG_LEVEL_INFO = 20;

## Summary

- Mojo.Log.LOG_LEVEL_ERROR
- Mojo.Log.LOG_LEVEL_INFO
- Mojo.Log.LOG_LEVEL_WARNING

## Method Summary

- Mojo.Log.addLoggingMethodsToPrototype(targetObject)
- Mojo.Log.error()
- Mojo.Log.info()
- Mojo.Log.logException(e, msg)
- Mojo.Log.logProperties(obj, name, includePrototype)
- Mojo.Log.propertiesAsString(targetObject, includePrototype)
- Mojo.Log.warn()

## Detail

### Mojo.Log.LOG_LEVEL_ERROR

Error Log Level. See Mojo.Log for more info.

### Mojo.Log.LOG_LEVEL_INFO

Info Log Level. See Mojo.Log for more info.

### Mojo.Log.LOG_LEVEL_WARNING

Warning Log Level. See Mojo.Log for more info.

## Method Detail

### Mojo.Log.addLoggingMethodsToPrototype(targetObject)

Call to add standard logging methods to an object's prototype.

#### Parameters

- {Object} targetObject - Object whose prototype should be extended with logging methods.

### Mojo.Log.error()

By default, all parameters passed to a logging function are concatenated together with a single space separating each parameter, using Array.join().

>     Mojo.Log.error("I have", 3, "eggs.");

would output

>     "I have 3 eggs."

See Mojo.Log for more info.

### Mojo.Log.info()

By default, all parameters passed to a logging function are concatenated together with a single space separating each parameter, using Array.join().

>     Mojo.Log.info("I have", 3, "eggs.");

would output

>     "I have 3 eggs."

See Mojo.Log for more info.

### Mojo.Log.logException(e, msg)

Log an exception.

#### Parameters

- {Object} e - The exception to log.
- {Object} msg - An optional message to prefix with exception log message.

### Mojo.Log.logProperties(obj, name, includePrototype)

Logs all the properties of an object. Handy for debugging. Each property has its own line in the log.

#### Parameters

- {Object} obj - object to dump
- {Object} name - name to show for object
- {Object} includePrototype - if true, also include properties inherited from a prototype

### Mojo.Log.propertiesAsString(targetObject, includePrototype)

Returns a string containing all the non-function properties of an object.

#### Parameters

- {Object} targetObject - object that is the source of the properties.
- {Object} includePrototype - true if you want properties from the object's prototype as well.

### Mojo.Log.warn()

By default, all parameters passed to a logging function are concatenated together with a single space separating each parameter, using Array.join().

>     Mojo.Log.warn("I have", 3, "eggs.");

would output

>     "I have 3 eggs."

See Mojo.Log for more info.