by Dave Draper
It seems like quite a while ago that I asked the Community for suggestions for topics to blog about around Alfresco Share and even went to the trouble of raising a JIRA issue for community members to add their ideas to. It's been extremely busy at Alfresco over the last few months as we've been finished off 4.2 Enterprise and preparing for Alfresco Summit, but I've finally found some time to catch-up!
This first post was suggested by Peter Löfgren and regards the new debugging options that are available in Share when you're running in 'client-debug' mode and this topic nicely ties into a couple of other concepts that are worth exploring.
Enabling Client-Debug Mode
When Alfresco is running in production it's important to make sure that its performing as well as possible. From a web client point of view this means ensuring that the JavaScript and CSS resources that are being loaded are 'minified' to the smallest functional size to reduce the amount of data that the browser needs to load. The downside of this is that it becomes harder to debug because line breaks are removed and variable names are shortened removing any meaning from them.
It is possible to switch Share in to 'client-debug' mode so that the uncompressed resources are downloaded. This is done by modifying the 'client-debug' XML value found in the configuration. The default setting is found in 'tomcat/webapps/share/WEB-INF/classes/alfresco/share-config.xml'. Setting this value to 'true' in Alfresco Share 4.2 Enterprise (or 4.2.e Community) will have the following effects:
This menu relates only to the new style of widgets that have been used to create the updated header bar so will NOT effect the logging from any of the old YUI2 based client-side widgets. The following options are provided
The main thing to notice is the how each line of debug is prefixed, e.g. 'alfresco/core/Core[createWidget] >>'. The first part is the widget that has output the log message and the value between the square brackets is the function that output the log message. This information is obtained directly from the calling function (where the browser supports it) so long as the function has been declared according to the following standard:
...and for log requests to be made as follows:
All logging is decoupled over a publication/subscription model and calling 'alfLog' function publishes on a specific log topic ('ALF_LOG_REQUEST') to which the default logging Service ('alfresco/services/LoggingService') subscribes. The logging service inspects the calling function and attempts to determine the widget name and function name from the supplied data. The pattern it looks for is that the widget name and function are delimited by the last double underscore '__' and it converts single underscores into forward slashes.
By providing the widget and function names it should be easier to get identify exactly in the source code where problems exist.
The other benefit from defining widget function names using this pattern is that they can then be passed through a logging filter.
If you click the 'Update Logging Preferences' option from the 'Debug Menu' you will be presented with a dialog for entering a filter.
Currently the filtering is done through Regular Expressions and allow you to filter logging output to show you just the code that you're interested. The screenshot shows the value 'alfresco/menus/.*' being entered and will result in only logging from the widgets in the 'alfresco/menus' package being output.
The code that outputs the log is intentionally decoupled from the code that is requesting logging. This means that it's possible to swap out or modify the logging behaviour without needing to re-write all the code that requests logs.
By default the log output is written to the browser console but this means that the information is only available to the end-user. It would be entirely possible to switch out the default LoggingService and replace it with a service that captures logging output and posts it back to the server in batches so that end-user errors are captured and available for analysis by Admins or IT.
In order to use the logging you should ensure that your widgets 'mixin' the 'alfresco/core/Core' module. This module effectively provides an API to the core client side features for logging, data bindings, widget model processing and pub/sub.
The advantage of writing to this API is that it is possible to modify the client-side internal capabilities without breaking any existing widgets. Since we started creating the new widget library that has allowed us to make substantial changes to these features without needing to update the widgets that use them.
It's worth noting that the Debug Menu and the Logging Service are included by default by the Share header component. If you are writing pages that don't use those components it's important to ensure that you include at least the Logging Service and a mechanism for updating logging preferences.
It's also important to note that the filter information is persisted to a users preferences by default. This means that if you are debugging using different user accounts you will need to update the preferences for each user that you login with.
Hopefully this has provided a useful introduction to the new debug features that are available in 4.2.e Community and 4.2 Enterprise. We're going to continue to make improvements for debugging the new widget library. Improving the development experience is something we're taking seriously and as we implement use cases using this new approach we will strive to add debug features to benefit both Alfresco developers and the wider Alfresco Community.
Introduction
It seems like quite a while ago that I asked the Community for suggestions for topics to blog about around Alfresco Share and even went to the trouble of raising a JIRA issue for community members to add their ideas to. It's been extremely busy at Alfresco over the last few months as we've been finished off 4.2 Enterprise and preparing for Alfresco Summit, but I've finally found some time to catch-up!
This first post was suggested by Peter Löfgren and regards the new debugging options that are available in Share when you're running in 'client-debug' mode and this topic nicely ties into a couple of other concepts that are worth exploring.
Enabling Client-Debug Mode
When Alfresco is running in production it's important to make sure that its performing as well as possible. From a web client point of view this means ensuring that the JavaScript and CSS resources that are being loaded are 'minified' to the smallest functional size to reduce the amount of data that the browser needs to load. The downside of this is that it becomes harder to debug because line breaks are removed and variable names are shortened removing any meaning from them.
It is possible to switch Share in to 'client-debug' mode so that the uncompressed resources are downloaded. This is done by modifying the 'client-debug' XML value found in the configuration. The default setting is found in 'tomcat/webapps/share/WEB-INF/classes/alfresco/share-config.xml'. Setting this value to 'true' in Alfresco Share 4.2 Enterprise (or 4.2.e Community) will have the following effects:
- The underlying Surf platform will serve uncompressed JavaScript and CSS resources
- A new LoggingService will be included in pages
- A new Debug Menu will be displayed on the main header menu.
The New Debug Menu
This menu relates only to the new style of widgets that have been used to create the updated header bar so will NOT effect the logging from any of the old YUI2 based client-side widgets. The following options are provided
- Toggle logging on and off ('Debug logging')
- Toggle full logging on and off ('Show All Logs')
- Toggle just the warning messages ('Show Warning Messages')
- Toggle just the error messages ('Show Error Messages')
- Configure the filter for messages ('Update Logging Preferences')
The main thing to notice is the how each line of debug is prefixed, e.g. 'alfresco/core/Core[createWidget] >>'. The first part is the widget that has output the log message and the value between the square brackets is the function that output the log message. This information is obtained directly from the calling function (where the browser supports it) so long as the function has been declared according to the following standard:
createWidget: function alfresco_core_Core__createWidget(config, domNode, callback, callbackArgs) {...and for log requests to be made as follows:
this.alfLog('log', 'Creating widget: ',config);All logging is decoupled over a publication/subscription model and calling 'alfLog' function publishes on a specific log topic ('ALF_LOG_REQUEST') to which the default logging Service ('alfresco/services/LoggingService') subscribes. The logging service inspects the calling function and attempts to determine the widget name and function name from the supplied data. The pattern it looks for is that the widget name and function are delimited by the last double underscore '__' and it converts single underscores into forward slashes.
By providing the widget and function names it should be easier to get identify exactly in the source code where problems exist.
Logging Filters
The other benefit from defining widget function names using this pattern is that they can then be passed through a logging filter.
If you click the 'Update Logging Preferences' option from the 'Debug Menu' you will be presented with a dialog for entering a filter.
Currently the filtering is done through Regular Expressions and allow you to filter logging output to show you just the code that you're interested. The screenshot shows the value 'alfresco/menus/.*' being entered and will result in only logging from the widgets in the 'alfresco/menus' package being output.
Decoupling and Alternate Logging Services
The code that outputs the log is intentionally decoupled from the code that is requesting logging. This means that it's possible to swap out or modify the logging behaviour without needing to re-write all the code that requests logs.
By default the log output is written to the browser console but this means that the information is only available to the end-user. It would be entirely possible to switch out the default LoggingService and replace it with a service that captures logging output and posts it back to the server in batches so that end-user errors are captured and available for analysis by Admins or IT.
Using the 'alfresco/core/Core' Mixin
In order to use the logging you should ensure that your widgets 'mixin' the 'alfresco/core/Core' module. This module effectively provides an API to the core client side features for logging, data bindings, widget model processing and pub/sub.
The advantage of writing to this API is that it is possible to modify the client-side internal capabilities without breaking any existing widgets. Since we started creating the new widget library that has allowed us to make substantial changes to these features without needing to update the widgets that use them.
Debug Menu and Logging Service Caveats
It's worth noting that the Debug Menu and the Logging Service are included by default by the Share header component. If you are writing pages that don't use those components it's important to ensure that you include at least the Logging Service and a mechanism for updating logging preferences.
It's also important to note that the filter information is persisted to a users preferences by default. This means that if you are debugging using different user accounts you will need to update the preferences for each user that you login with.
Summary
Hopefully this has provided a useful introduction to the new debug features that are available in 4.2.e Community and 4.2 Enterprise. We're going to continue to make improvements for debugging the new widget library. Improving the development experience is something we're taking seriously and as we implement use cases using this new approach we will strive to add debug features to benefit both Alfresco developers and the wider Alfresco Community.
1 Comment
