View source for Logging and Event Hooks

[[Main Page|Home]] >> [[CWA Signing Avatars|CWASA]]
----
== 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 avatar instances.

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 '''OneAvClientTest.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 an example above and more examples on the '''OneAv*Test.html''' pages.

=== Supported Events ===

* '''status''': '''msg''' is a string. Used for reporting status changes to the console and to fields in the CWASA GUI. 

* '''avatarloading''': '''msg''' is a string naming the avatar being loaded. Used for updating avatar menus in the CWASA GUI. 

* '''avatarloaded''': '''msg''' is a string naming the avatar that has been loaded. Used for updating avatar menus in the CWASA GUI. If loading an avatar fails, the following '''avatarloaded''' event will indicate that the original avatar is reinstated.

* '''sigmlloading''': '''msg''' is null. Indicates that SiGML data is being processed. Used to update the CWASA GUI.

* '''sigmlloaded''': '''msg''' is an object with fields '''s''' for the number of signs and '''f''' for the number of frames. Not used by the CWASA GUI.

* '''animactive''': '''msg''' is null. Indicates that animation is in progress. Used to update the CWASA GUI. Will normally be issued before '''sigmlloaded''' has been signalled.

* '''animidle''': '''msg''' is null. Indicates that animation has ceased. Used to update the CWASA GUI.

* '''avatarfps''': '''msg''' is a floating point number giving the frames per second at which the designated avatar is rendering. Used to update the CWASA GUI. 

* '''avatarframe''': '''msg''' is an object with fields '''s''' for the sign index and '''f''' for frame index. Used to update the CWASA GUI. Called per frame. The indices are based at 0 so adding 1 will give a more natural presentation.

* '''avatarsign''': '''msg''' is an object with fields '''g''' for the sign gloss, '''s''' for the sign index and '''f''' for frame index. Used to update the CWASA GUI. Called per sign and at the end of animation. The indices are based at 0 so adding 1 will give a more natural presentation. The frame index will be in the range associated with the sign.

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 will 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.
 
----
[[Main Page|Home]] >> [[CWA Signing Avatars|CWASA]]