|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Debugging
In any page in which ISC has been loaded, you have access to the Developer Console, which can be opened by entering the following URL into your browser from the running application:
javascript:isc.showConsole()Basic information on the features of the Developer Console can be found in the QuickStart Guide. This topic focuses on use of the log system and related debugging facilities.
The Developer Console contains a "Results" pane that displays a list of diagnostic messages logged by the SmartGWT framework. The "Logging Preferences" menu lets you enable and disable SmartGWT's built-in diagnostics in several categories. Because important diagnostic messages may be logged at any time, you should have the Developer Console open whenever you are working with SmartGWT (and you should bookmark the "javascript:" expression above to make this easier).
Log messages are of the format:
timestamp:priority:category:message
For example, the following log message:
11:59:25:806:INFO:Page:Page loading complete.Occured at 11:59:25 local time and 806 milliseconds. It's priority was
INFO
,
it occurred in the category Page, and the message is "Page loading complete.".
Each logging category has a priority associated with it. If a message's priority is lower than the current priority for the category it is logged in, the message will be suppressed (will not appear in the "Results" pane).
It is critical to be familiar with the diagnostic categories built-in to SmartGWT - you will use them in most debugging sessions. Open the Logging Preferences menu and select "More.." to see a list of diagnostic log categories. Hover over each category name to see a description of what kind of messages are logged in the category.
Isomorphic recommends the FireFox browser as the primary development platform. In FireFox, JavaScript errors are reported both in the SmartGWT Developer Console and in the FireFox JavaScript console, which can be opened by entering the special url "javascript:" in the address bar.
Isomorphic currently recommends that every SmartGWT developer install either the Console2 or Firebug extensions for FireFox. "Console2" simply replaces the default FireFox JavaScript console with a more functional console; Firebug aims to be a true debugger. Both tools will typically load or identify the correct file and line number where a JS error occured.
In Internet Explorer, when JS errors occur, SmartGWT is able to report full stack traces in the Developer Console. This can be invaluable when your code triggers a JS error in the SmartGWT libraries themselves, or when it is unclear how your code is being called. Stack traces from Internet Explorer should always be included in issue reports sent to Isomorphic Software, if at all possible.
The "Evaluate JS Expression" area of the Results Pane in the Developer Console can be used
to inspect the current state of a SmartGWT application. Any SmartGWT or browser
built-in API can be called from the "Evaluate JS Expression" area, and the results will
be intelligently summarized (via com.smartgwt.client..Log#echo
). For example, simply typing a
component's ID and pressing the "Eval JS" button will give you a dump of it's current
property values.
Many, many SmartGWT APIs can be usefully called while troubleshooting, eg,
data
is a com.smartgwt.client.data.ResultSet
when a grid is DataBound and
com.smartgwt.client.data.ResultSet#get
can be called to inspect the current values on records. In addition,
new application code can be tried out, for example, you might repeatedly instantiate a new
component, trying variants on the properties you could give it.
Inspecting transient application state with logs
Transient state, such as the values of local variables in a method that is crashing, can be
sent to the Developer Console via using the com.smartgwt.client..Log
class. For example, to dump the
value of the local variable "request":
isc.logWarn("request is: " + isc.echo(request));
It's a good idea to dump the values of local variables in any method that is crashing or behaving unexpectedly.
Note the use of com.smartgwt.client.util.isc#logWarn
above: in typical debugging sessions,
it's best
to simply use logWarn
method to output diagnostics to ensure your message will
not be suppressed by log priority settings.
NOTE: never use the native alert()
method to output diagnostics. Among other
issues, alert()
can affect timing, masking or altering the behavior you were
trying to debug. SmartGWT's logging system doesn't suffer from these problems and
provides much more control.
If you believe you've discovered a bug in SmartGWT or you are having trouble using SmartGWT APIs, you can report it at http://forums.smartclient.com/, or, if you have Enterprise Support, at the Customer Support Extranet.
How quickly your issue is resolved is entirely up to you. If you follow the steps below and submit an appropriate issue report, you will generally receive a rapid solution from Isomorphic Support, regardless of what support level you have, because Isomorphic aggressively corrects bugs and legitimate usage issues. If you skip steps you are likely to be directed back to this document and asked to submit a more complete issue report.
Before reporting an issue, ensure that you:
echo()
on local variables or other application
state you think is relevant (see "Inspecting Application State" above)
'databinding approach'
you
are using, if applicable
A standalone test case is one of:
Submitting a standalone test case removes any ambiguity as to whether there is a bug in SmartGWT or a bug in your code, and eliminates the possibility of Isomorphic Support responding with a "works for me" result due to incomplete information. Issues with verified test cases are routed directly to the engineer that authored the relevant SmartGWT subsystem, often as the new highest priority task. In addition, the process of preparing a test case very often allows you to solve the issue yourself.
There are two approaches to test case preparation:
For approach #1, find the nearest match to your use case in the ${isc.DocUtils.linkForDocNode('FeatureExplorer')} examples or in the other examples accessible from the Examples folder of the SDK, then try to minimally modify that example to demonstrate your issue. Feature Explorer examples are a particularly good starting point because you can simply copy the code from the Feature Explorer to the Eval JS area of the Developer Console and begin changing it, and if successful this yields a type #1 test case, the easiest for you to submit and most efficient for Isomorphic to work with.
For approach #2,
clientOnly
with that dataset.
dataURL
to point at them.
Calling logWarn()
is fine for a log statement you plan to delete at the end of
the debugging session. However, many log statements have lasting value if you could enable
or disable them only when you need the relevant diagnostics, like SmartGWT's built-in
diagnostic categories. To do this, pick a priority level less than WARN
(INFO
or DEBUG
), and call the corresponding method on the Log
class (logInfo()
or logDebug()
), passing the category name as a
second parameter. For example:
isc.Log.logInfo("first record is: " + isc.Log.echo(myGrid.data.get(0)), "myGridLoading");This message will no longer appear in the Results Pane by default, because its priority (
INFO
) is less than the default of WARN
. To see this message,
open the Logging Preferences menu and pick "More..", then click the "Add" button, enter
"myGridLoading" as the category name and set the priority to INFO
. The message
will now appear next time it is logged.
Now you have a custom log category that you and other developers can use to debug your application, subsystem by subsystem. These diagnostics will be available to you both in development and production environments.
As with SmartGWT's built-in diagnostics, you may choose to log certain messages in your
custom category at the DEBUG
level and a lesser number of messages at the
INFO
level, to create different depths of diagnostic output.
The core log methods (logDebug()
, logInfo()
,
logWarn()
) and the "echo" facilities (echo()
and
echoAll()
) are available on every SmartGWT component and Class. Hence,
in many cases, the special JavaScript value "this" will refer to an object that supports
logWarn()
et al. For example:
Canvas.create({ ID:"canvasExample", contents:"Hello World!", click:"this.logWarn('the Canvas is: ' + this.echo(this))" });The special value "this" is not always set to a SmartGWT component, for example, in some kinds of callbacks (eg
ListGrid.fetchData()
). When in doubt, use these
methods via the Log class as isc.Log.logWarn()
.
Logging performance
Because the log message is actually formed before the call to the log system, logs
that are suppressed can still carry a performance penalty. This is particularly true of
logs that output a lot of data or occur frequently. To avoid this penalty, you can check in
advance whether a message will be suppressed using
com.smartgwt.client..Class#logIsDebugEnabled
and
com.smartgwt.client..Class#logIsInfoEnabled
. For example:
if (isc.Log.logIsInfoEnabled("myGridLoading")) { isc.Log.logInfo("first record is: " + isc.Log.echo(myGrid.data.get(0)), "myGridLoading"); }Generally, it is only important to do this for logs that will occur multiple times during a given user interaction (eg a mousedown or keypress) and/or that call
echo()
on
objects with many properties.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |