In order to create a simple data CFC, just create a CFC with one required method on it called configure where you will define the logging configuration data:

**
* A LogBox configuration data object
*/
component{

    function configure(){
        logBox={

        };
    }
}

Base Config

Once you have this shell, you will create a logBox variable in the variables scope that must be a structure with the following keys:

Appenders

To define an appender you must define a struct with a key value which is the internal name of the appender. Each appender name must be unique. You configure each appender with the following keys:

Root Logger

To configure the root logger use the following keys:

Categories

To define categories you must define a struct with a key value which is the internal name of the category. Each category name must be unique. You configure each category with the following keys:

As you might notice the name of the keys on all the structures match 100% to the programmatic methods you can also use to configure logBox. So when in doubt, refer back to the argument names.

Example Configuration

logBox = {
    // Appenders
    appenders = {
        appenderName = {
            class="class.to.appender",
            layout="class.to.layout",
            levelMin=0,
            levelMax=4,
            properties={
                name  = value,
                prop2 = value 2
            }
    },
    // Root Logger
    root = { levelMin="FATAL", levelMax="DEBUG", appenders="*" },
    // Granualr Categories
    categories={
        "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*" },
        "model.security" = { levelMax="DEBUG", appenders="console" }
    }
    // Implicit categories
    debug = [ "coldbox.system.interceptors"  ],
    info  = [ "model.class", "model2.class2" ],
    warn  = [ "model.class", "model2.class2" ],
    error = [ "model.class", "model2.class2" ],
    fatal = [ "model.class", "model2.class2" ],
    off   = [ "model.class", "model2.class2" ]
};

Instantiation

Once you have defined the configuration data in this object you can now use the same LogBox Config object to either instantiate it for you or you can pass a reference of it by using the init() method of the LogBoxConfig object:

init([CFCConfig,CFCConfigPath])

• CFCConfig : The object instance that has the logbox configuration data

• CFCConfigPath : The instantiation path of the object that has the logbox configuration data

// Using config path
config = createObject( "component", "logbox.system.logging.config.LogBoxConfig" )
    .init( CFCConfigPath="my.path.LogBoxConfig" );
logBox = createObject( "component", "logbox.system.logging.LogBox" ).init( config );

// Using config object
data = createObject( "component", "my.data.CFC" );
config = createObject( "component", "logbox.system.logging.config.LogBoxConfig" ).init( data );
logBox = createObject( "component", "logbox.system.logging.LogBox" ).init( config );

That's it! Using this DSL approach, your configurations are much more portable now and can even be shared in ANY framework, ColdBox or ColdFusion application. So now let's explore how to bypass this data CFC and use the LogBoxConfig object directly. It is important to understand these methods as they are called for you when you define your LogBox DSL data.

The methods shown below are used to add categories to specific severity levels only. Each method can receive 1 to * category arguments.

• public void debug()

• public void info()

• public void warn()

• public void error()

• public void fatal()

• public void off()

config.debug( "com.model.myclass", "coldbox.system.controller" );
config.info( "com.model.otherclass", "coldbox.system.whatever" );
config.fatal( "com.model.otherclass", "coldbox.system.whatever" );
config.error( "com.model.otherclass", "coldbox.system.whatever" );
config.off( "com.model.otherclass", "coldbox.system.whatever" );

No matter what configuration you decide to use, you will always have to instantiate LogBox with a LogBoxConfig object: logbox.system.logging.config.LogBoxConfig. However you have the option of either talking directly to this CFC or creating a more portable configuration. This portable configuration we denote as a simple data CFC that contains the LogBox configuration data using what we call our LogBox DSL (Domain Specific Language).

The cool thing about this LogBox DSL is that it is exactly the same whether you are using LogBox in ColdBox applications or in any other framework or non-framework ColdFusion application. So you can configure LogBox by:

1. Creating a portable data CFC using the LogBox DSL or

2. Creating the LogBoxConfig object and interacting with its methods

You can also add categories with very granular information using the category() method. This method will allow you to add a category definition with a range of severity levels and even a list of which appenders to respond to.

public void category(
    string name,
    [numeric levelMin='0',]
    [numeric levelMax='4',]
    [string appenders='*']
)

Parameters:

Example

//log all email service messages to the MyLogFileAppender and the Console.
config.category( name="org.model.EmailService", appenders="MyLogFileAppender,Console" );

The first thing you need to do in your config object is add appenders. Each appender is added via the appender() method.

Parameters:

Examples

Configuring a root logger is mandatory for LogBox. This is very easy and just a few arguments.

Parameters