/ext-4.1.0_b3/docs/source/Error.html
HTML | 344 lines | 317 code | 27 blank | 0 comment | 0 complexity | 329b5098a62139190caa793028291805 MD5 | raw file
1<!DOCTYPE html>
2<html>
3<head>
4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5 <title>The source code</title>
6 <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7 <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8 <style type="text/css">
9 .highlight { display: block; background-color: #ddd; }
10 </style>
11 <script type="text/javascript">
12 function highlight() {
13 document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14 }
15 </script>
16</head>
17<body onload="prettyPrint(); highlight();">
18 <pre class="prettyprint lang-js"><span id='Ext-Error'>/**
19</span> * @author Brian Moeskau <brian@sencha.com>
20 * @docauthor Brian Moeskau <brian@sencha.com>
21 *
22 * A wrapper class for the native JavaScript Error object that adds a few useful capabilities for handling
23 * errors in an Ext application. When you use Ext.Error to {@link #raise} an error from within any class that
24 * uses the Ext 4 class system, the Error class can automatically add the source class and method from which
25 * the error was raised. It also includes logic to automatically log the eroor to the console, if available,
26 * with additional metadata about the error. In all cases, the error will always be thrown at the end so that
27 * execution will halt.
28 *
29 * Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to
30 * handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,
31 * although in a real application it's usually a better idea to override the handling function and perform
32 * logging or some other method of reporting the errors in a way that is meaningful to the application.
33 *
34 * At its simplest you can simply raise an error as a simple string from within any code:
35 *
36 * Example usage:
37 *
38 * Ext.Error.raise('Something bad happened!');
39 *
40 * If raised from plain JavaScript code, the error will be logged to the console (if available) and the message
41 * displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add
42 * additional metadata about the error being raised. The {@link #raise} method can also take a config object.
43 * In this form the `msg` attribute becomes the error description, and any other data added to the config gets
44 * added to the error object and, if the console is available, logged to the console for inspection.
45 *
46 * Example usage:
47 *
48 * Ext.define('Ext.Foo', {
49 * doSomething: function(option){
50 * if (someCondition === false) {
51 * Ext.Error.raise({
52 * msg: 'You cannot do that!',
53 * option: option, // whatever was passed into the method
54 * 'error code': 100 // other arbitrary info
55 * });
56 * }
57 * }
58 * });
59 *
60 * If a console is available (that supports the `console.dir` function) you'll see console output like:
61 *
62 * An error was raised with the following data:
63 * option: Object { foo: "bar"}
64 * foo: "bar"
65 * error code: 100
66 * msg: "You cannot do that!"
67 * sourceClass: "Ext.Foo"
68 * sourceMethod: "doSomething"
69 *
70 * uncaught exception: You cannot do that!
71 *
72 * As you can see, the error will report exactly where it was raised and will include as much information as the
73 * raising code can usefully provide.
74 *
75 * If you want to handle all application errors globally you can simply override the static {@link #handle} method
76 * and provide whatever handling logic you need. If the method returns true then the error is considered handled
77 * and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.
78 *
79 * Example usage:
80 *
81 * Ext.Error.handle = function(err) {
82 * if (err.someProperty == 'NotReallyAnError') {
83 * // maybe log something to the application here if applicable
84 * return true;
85 * }
86 * // any non-true return value (including none) will cause the error to be thrown
87 * }
88 *
89 */
90Ext.Error = Ext.extend(Error, {
91 statics: {
92<span id='Ext-Error-static-property-ignore'> /**
93</span> * @property {Boolean} ignore
94 * Static flag that can be used to globally disable error reporting to the browser if set to true
95 * (defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail
96 * and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably
97 * be preferable to supply a custom error {@link #handle handling} function instead.
98 *
99 * Example usage:
100 *
101 * Ext.Error.ignore = true;
102 *
103 * @static
104 */
105 ignore: false,
106
107<span id='Ext-Error-static-property-notify'> /**
108</span> * @property {Boolean} notify
109 * Static flag that can be used to globally control error notification to the user. Unlike
110 * Ex.Error.ignore, this does not effect exceptions. They are still thrown. This value can be
111 * set to false to disable the alert notification (default is true for IE6 and IE7).
112 *
113 * Only the first error will generate an alert. Internally this flag is set to false when the
114 * first error occurs prior to displaying the alert.
115 *
116 * This flag is not used in a release build.
117 *
118 * Example usage:
119 *
120 * Ext.Error.notify = false;
121 *
122 * @static
123 */
124 //notify: Ext.isIE6 || Ext.isIE7,
125
126<span id='Ext-Error-static-method-raise'> /**
127</span> * Raise an error that can include additional data and supports automatic console logging if available.
128 * You can pass a string error message or an object with the `msg` attribute which will be used as the
129 * error message. The object can contain any other name-value attributes (or objects) to be logged
130 * along with the error.
131 *
132 * Note that after displaying the error message a JavaScript error will ultimately be thrown so that
133 * execution will halt.
134 *
135 * Example usage:
136 *
137 * Ext.Error.raise('A simple string error message');
138 *
139 * // or...
140 *
141 * Ext.define('Ext.Foo', {
142 * doSomething: function(option){
143 * if (someCondition === false) {
144 * Ext.Error.raise({
145 * msg: 'You cannot do that!',
146 * option: option, // whatever was passed into the method
147 * 'error code': 100 // other arbitrary info
148 * });
149 * }
150 * }
151 * });
152 *
153 * @param {String/Object} err The error message string, or an object containing the attribute "msg" that will be
154 * used as the error message. Any other data included in the object will also be logged to the browser console,
155 * if available.
156 * @static
157 */
158 raise: function(err){
159 err = err || {};
160 if (Ext.isString(err)) {
161 err = { msg: err };
162 }
163
164 var method = this.raise.caller;
165
166 if (method) {
167 if (method.$name) {
168 err.sourceMethod = method.$name;
169 }
170 if (method.$owner) {
171 err.sourceClass = method.$owner.$className;
172 }
173 }
174
175 if (Ext.Error.handle(err) !== true) {
176 var msg = Ext.Error.prototype.toString.call(err);
177
178 Ext.log({
179 msg: msg,
180 level: 'error',
181 dump: err,
182 stack: true
183 });
184
185 throw new Ext.Error(err);
186 }
187 },
188
189<span id='Ext-Error-static-method-handle'> /**
190</span> * Globally handle any Ext errors that may be raised, optionally providing custom logic to
191 * handle different errors individually. Return true from the function to bypass throwing the
192 * error to the browser, otherwise the error will be thrown and execution will halt.
193 *
194 * Example usage:
195 *
196 * Ext.Error.handle = function(err) {
197 * if (err.someProperty == 'NotReallyAnError') {
198 * // maybe log something to the application here if applicable
199 * return true;
200 * }
201 * // any non-true return value (including none) will cause the error to be thrown
202 * }
203 *
204 * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes that were originally
205 * raised with it, plus properties about the method and class from which the error originated (if raised from a
206 * class that uses the Ext 4 class system).
207 * @static
208 */
209 handle: function(){
210 return Ext.Error.ignore;
211 }
212 },
213
214 // This is the standard property that is the name of the constructor.
215 name: 'Ext.Error',
216
217<span id='Ext-Error-method-constructor'> /**
218</span> * Creates new Error object.
219 * @param {String/Object} config The error message string, or an object containing the
220 * attribute "msg" that will be used as the error message. Any other data included in
221 * the object will be applied to the error instance and logged to the browser console, if available.
222 */
223 constructor: function(config){
224 if (Ext.isString(config)) {
225 config = { msg: config };
226 }
227
228 var me = this;
229
230 Ext.apply(me, config);
231
232 me.message = me.message || me.msg; // 'message' is standard ('msg' is non-standard)
233 // note: the above does not work in old WebKit (me.message is readonly) (Safari 4)
234 },
235
236<span id='Ext-Error-method-toString'> /**
237</span> * Provides a custom string representation of the error object. This is an override of the base JavaScript
238 * `Object.toString` method, which is useful so that when logged to the browser console, an error object will
239 * be displayed with a useful message instead of `[object Object]`, the default `toString` result.
240 *
241 * The default implementation will include the error message along with the raising class and method, if available,
242 * but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
243 * a particular error instance, if you want to provide a custom description that will show up in the console.
244 * @return {String} The error message. If raised from within the Ext 4 class system, the error message will also
245 * include the raising class and method names, if available.
246 */
247 toString: function(){
248 var me = this,
249 className = me.className ? me.className : '',
250 methodName = me.methodName ? '.' + me.methodName + '(): ' : '',
251 msg = me.msg || '(No description provided)';
252
253 return className + methodName + msg;
254 }
255});
256
257/*
258 * Create a function that will throw an error if called (in debug mode) with a message that
259 * indicates the method has been removed.
260 * @param {String} suggestion Optional text to include in the message (a workaround perhaps).
261 * @return {Function} The generated function.
262 * @private
263 */
264Ext.deprecated = function (suggestion) {
265 //<debug>
266 if (!suggestion) {
267 suggestion = '';
268 }
269
270 function fail () {
271 Ext.Error.raise('The method "' + fail.$owner.$className + '.' + fail.$name +
272 '" has been removed. ' + suggestion);
273 }
274
275 return fail;
276 //</debug>
277 return Ext.emptyFn;
278};
279
280/*
281 * This mechanism is used to notify the user of the first error encountered on the page. This
282 * was previously internal to Ext.Error.raise and is a desirable feature since errors often
283 * slip silently under the radar. It cannot live in Ext.Error.raise since there are times
284 * where exceptions are handled in a try/catch.
285 */
286//<debug>
287(function () {
288 var timer, errors = 0,
289 win = Ext.global;
290
291 if (typeof window === 'undefined') {
292 return; // build system or some such environment...
293 }
294
295 // This method is called to notify the user of the current error status.
296 function notify () {
297 var counters = Ext.log.counters,
298 supports = Ext.supports,
299 hasOnError = supports && supports.WindowOnError; // TODO - timing
300
301 // Put log counters to the status bar (for most browsers):
302 if (counters && (counters.error + counters.warn + counters.info + counters.log)) {
303 var msg = [ 'Logged Errors:',counters.error, 'Warnings:',counters.warn,
304 'Info:',counters.info, 'Log:',counters.log].join(' ');
305 if (errors) {
306 msg = '*** Errors: ' + errors + ' - ' + msg;
307 } else if (counters.error) {
308 msg = '*** ' + msg;
309 }
310 win.status = msg;
311 }
312
313 // Display an alert on the first error:
314 if (!Ext.isDefined(Ext.Error.notify)) {
315 Ext.Error.notify = Ext.isIE6 || Ext.isIE7; // TODO - timing
316 }
317 if (Ext.Error.notify && (hasOnError ? errors : (counters && counters.error))) {
318 Ext.Error.notify = false;
319
320 if (timer) {
321 win.clearInterval(timer); // ticks can queue up so stop...
322 timer = null;
323 }
324
325 alert('Unhandled error on page: See console or log');
326 poll();
327 }
328 }
329
330 // Sets up polling loop. This is the only way to know about errors in some browsers
331 // (Opera/Safari) and is the only way to update the status bar for warnings and other
332 // non-errors.
333 function poll () {
334 timer = win.setInterval(notify, 1000);
335 }
336
337 // window.onerror sounds ideal but it prevents the built-in error dialog from doing
338 // its (better) thing.
339 poll();
340})();
341//</debug>
342</pre>
343</body>
344</html>