Configuring Client Runtime Logging

by Michela Frigerio
4,165 views Published on May 03, 2013
Applies to: 7.0 or higher
Table of contents

Introduction

The WebRatio Client Runtime is the ECMAScript based execution environment and core set of utilities that hosts client applications. It is a feature available starting from WebRatio 7. There is only a single implicit Runtime instance per Web browser window. The main customization is related to the logging level, which pilots the messages logged by the Client Runtime during the execution of all the JavaScript code included in the Web application.

Client Runtime Configuration

The WebRatio Client Runtime is created with a default configuration that specifies the component's behaviour . It is possible to override or integrate this configuration with a desired set of options. The customization requires the user to write a JavaScript code fragment. This code must be executed when the page is loaded on the Web browser. For this reason it must be included in the page template used by the Web application. There are two different ways to include the code:

  1. write the code directly inside the page template. In this case remember to place the code after the wr:Resources tag, because this tag prints in the JSP page the default configuration of the Client Runtime that must be ovverridden by the custom configuration. The previous condition does not apply if you wrap the code with the jQuery code that listens to the document ready event.
    <script type="text/javascript">
        jQuery(function() {
            ...		
        });
    </script>
  2. write the code inside an external file referenced from the page template. In this case you can write in the page template, after the wr:LinkedResources tag, the following HTML code
     <script src="<path-to-external-script-file>" type="text/javascript">

The method to be used is mergeConfig applied to the current application.

    <script type="text/javascript">
        wr.getApp().mergeConfig({ 
            //custom configuration 
        });
    </script>

The Client Runtime configuration is composed of a list of different configurations, one for each existing JavaScript plugin. In order to be able to customize this configuration it's necessary to know the name of the existing plugins. Considering as example the log plugin, which prints all the JavaScript Client Runtime warning and errors, the name to use for the customization is "log".  Moreover, for each plugin it is possible to decide whether to override the whole configuration (just writing the plugin name )or to integrate the current one with the desired options (adding the '+' character after the plugin name). The latter option is the suggested one. Supposing to customize the "log" plugin the code to use is:

    <script type="text/javascript">
        wr.getApp().mergeConfig({ 
            "log+":{
                //plugin configuration
            } 
        });
    </script>

Once decided the plugin configuration to be customized, it is necessary to know which are the available options. For these you can refer to the Client API contained inside the tool. To open the reference choose from the WebRatio main menu Help -> Web Modeling User Guide -> Client API. To customize the log plugin you can refer to the page related to the class wr.log.LogPlugin.

It is possible to customize each plugin option using the same syntax shown for the plugin. Using a '+' character at the end of the property name, the default configuration is integrated with the new option values, otherwise the configuration for the specific property is fully overwritten. All the above explanation is valid for all the existing plugins and also for custom plugins integrated by the user.

Client Runtime Logging Lifecycle and Configuration

The Client Runtime Logging generates log events during the Web application navigation. A log event is characterized by severity level (wr.log.Level.DEBUG, wr.log.Level.INFO, wr.log.Level.WARN, wr.log.Level.ERROR), a category and a message. Typically, a category is a client runtime class and for each one it is possible to set the log level. The most important category to be aware of is the wr.widgets one that manages all the AJAX widget and features that can be directly modeled inside a WebRatio project.

The log events are filtered depending on category and level and then they are sent to all the registered appenders. An appender is a JavaScript component that has the goal to register or print out the log events messages. There are two available appenders: the ConsoleAppender - that logs inside the Web browser JavaScript console - and the HtmlApplender (used by default) - that writes inside a specific HTML object included in the Web page. It is also possible to specify a custom appender, provided that this appender has been previously defined.

The HtmlAppender generates a bar inside the Web browser page. This bar has a different color depending of the severity of the logged messages:

  • red for error messages
  • yellow for warning messages
  • blue for info messages
  • gray for debugging messages

Look at the following image for an example

Examples

In this section there a list of examples that shows how it is possible to customize the default configuration for the "log" plugin.

Example 1 - Disable the log

Suppose that it is necessary to disable all the client runtime logging since the Web application has been deployed. In this case the default configuration must be overridden substituting the current appender option (that uses the HtmlAppender) with the custom one, which is to use none of the available appenders. The code to be used is something like the following:

    <script type="text/javascript">
        wr.getApp().mergeConfig({ 
            "log+":{
                "appenders": []
            } 
        });
    </script>

Example 2 - Changing the Log appender

Suppose that it is necessary to change the client runtime logging so that all messages are written in the Web browser console. In this case the default configuration must be overridden substituting the current appender option (that uses the HtmlAppender) with the custom one, which is the ConsoleAppender. The code to be used is something like the following:

    <script type="text/javascript">
        wr.getApp().mergeConfig({ 
            "log+":{
                "appenders": ["wr.log.ConsoleAppender"]
            } 
        });
    </script>

Example 3 - Configuring the log level

Suppose that it is necessary to change the client runtime logging level to better debug the client runtime. The log must consider only the AJAX set of widget directly handled by WebRatio through the wr.widgets category. All the rest of the client runtime must log only errors. To define the last condition it is necessary to write an empty category with the correspondent log level.

    <script type="text/javascript">
        wr.getApp().mergeConfig({ 
            "log+":{
                "categories": {
                    "wr.widgets" : wr.log.Level.DEBUG,
                    "" : wr.log.Level.ERROR
                }
            } 
        });
    </script>

Example 4 – Set the Local Storage

Suppose that it is necessary to store the error log on the local storage of the web browser on the client. This allows a user to send the stored log to the administrator in case of problems with the Web application.  This is the suggested configuration for a deployed Web application. In this case the default configuration must be overridden, substituting the current appender option (which uses the HtmlAppender) with the custom option, which is wr.log.LocalAppender. The code could be something like the following:

    <script type="text/javascript">
        if (window.wr && wr.getApp().isConfigurable()) {
            wr.getApp().mergeConfig({
                "log+": {
                    categories: {
                        "": wr.log.Level.DEBUG,
                        "wr.ui.Control": wr.log.Level.WARN
                    },
                    appenders: [{
                        name: "wr.log.LocalAppender",
                        notify: true,
                        notifyMessage: "<strong>A problem occurred</strong><br>Please click on SHOW to display the full log.",
                        notifyStats: false,
                        notifyLevel: wr.log.Level.WARN,
                        maxSize: 512000
                        }
                    ]
                }
            });
        }
    </script>