Logging and Event Hooks
Logging System
A logging system is implemented in CWASA allowing independent logging of events for different components at a number of levels:
- error: Error reporting using console.error. Always available.
- warn: Warning messages using console.warn. Always available.
- log: Sparing logging using console.log. Aways available.
- info: Additional logging using console.info.
- debug: Sign-level debugging information using console.info.
- trace: Low-level debugging information using console.info.
Messages identify the time, component, and message. For debug and trace the level of reporting is also given.
Main releases of the software do not display logging at a more detailed level than log. Development releases also display info. Only unstable development versions use debug and trace. It may be possible to test these using versions ending in t, u, or v. Unusually, the public method CWASA.getLogger() overrides this convention, allowing a logger to be configured to display messages at any level.
Using Loggers
- CWASA.getLogger(logger, loggerlevel): Configure and receive a CWASA logger.
This method takes a string for a class of logging and the lowest level to log (one of info to trace generally). The result is a logger which is an object whose fields have the names of the levels and hold logging functions. The fields will be null if no logger for the level exists so code must check that the level is supported first.
myLogger = CWASA.getLogger("myLog", "debug");
...
if (typeof (myLogger.trace) === "function") { myLogger.trace("My Message"); }
Further getLogger calls can be used to change the logging level dynamically.
Event Hook System
The CWASA software uses a system of hook functions that are called when significant events occur. This system is used internally but can also be used via a public interface. As a result, external software can receive and generate events.
Hook functions can be added to process events of a particular type. Many events relate to avatar panels and if multiple panels are used on a page, events can be directed to one or all panels. Equally, a hook function can be designated to respond to messages for one or all panels.
Using Hooks
- CWASA.addHook(typ, fun, av): Install a hook function to be called on specific events for specific avatars.
The method takes a string for the type of event, a hook function, and an optional avatar panel index. If no index is given, * is used, indicating that the hook should receive events for all panels.
This example from OneAvTest.html links to existing status events to create a log of messages in a text field.
function addStatus(evt) {
var elt = document.getElementById("myStatusLog");
var msg = evt.msg;
if (evt.av != "*") { msg = "[av" + evt.av + "] " + msg; }
elt.value = elt.value + msg + "\n";
}
CWASA.addHook("status", addStatus);
To post an event use the function
- CWASA.callHookL(typ, msg, av): Post and event to be passed to appropriate hook functions.
As before, the avatar panel index is optional. When omitted, the event will be passed to all hook functions of the given type. The data will be presented in an event object with fields type, for the type, and av, for avatar index. The msg field has a structure depending on the type of event. See example above.
Supported Events
- status: msg is a string. Used for reporting status changes to the console and to fields in the CWASA GUI.
Note: This system is under development and further event types will be added in the near future.
It is perfectly possible to define your own events, install hooks for them, and generate events for them. If the type of event is unknown to CWASA there should be no effect on the rest of the software.
Public CWASA Interface
- CWASA.getLogger(logger, loggerlevel): Configure and receive a CWASA logger.
- CWASA.addHook(typ, fun, av): Install a hook function to be called on specific events for specific avatars.
- CWASA.callHookL(typ, msg, av): Post and event to be passed to appropriate hook functions.