PageRenderTime 25ms CodeModel.GetById 18ms app.highlight 2ms RepoModel.GetById 1ms app.codeStats 0ms

/ext-4.1.1a/docs/source/Error.html

https://bitbucket.org/johnsont/picture-my-story
HTML | 346 lines | 319 code | 27 blank | 0 comment | 0 complexity | 08ce188c736325ab2318baf362ac9e5f 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 &lt;brian@sencha.com&gt;
 20 * @docauthor Brian Moeskau &lt;brian@sencha.com&gt;
 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: &quot;bar&quot;}
 64 *         foo:        &quot;bar&quot;
 65 *     error code:     100
 66 *     msg:            &quot;You cannot do that!&quot;
 67 *     sourceClass:   &quot;Ext.Foo&quot;
 68 *     sourceMethod:  &quot;doSomething&quot;
 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 &quot;msg&quot; 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                msg;
166
167            if (method) {
168                if (method.$name) {
169                    err.sourceMethod = method.$name;
170                }
171                if (method.$owner) {
172                    err.sourceClass = method.$owner.$className;
173                }
174            }
175
176            if (Ext.Error.handle(err) !== true) {
177                msg = Ext.Error.prototype.toString.call(err);
178
179                Ext.log({
180                    msg: msg,
181                    level: 'error',
182                    dump: err,
183                    stack: true
184                });
185
186                throw new Ext.Error(err);
187            }
188        },
189
190<span id='Ext-Error-static-method-handle'>        /**
191</span>         * Globally handle any Ext errors that may be raised, optionally providing custom logic to
192         * handle different errors individually. Return true from the function to bypass throwing the
193         * error to the browser, otherwise the error will be thrown and execution will halt.
194         *
195         * Example usage:
196         *
197         *     Ext.Error.handle = function(err) {
198         *         if (err.someProperty == 'NotReallyAnError') {
199         *             // maybe log something to the application here if applicable
200         *             return true;
201         *         }
202         *         // any non-true return value (including none) will cause the error to be thrown
203         *     }
204         *
205         * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes that were originally
206         * raised with it, plus properties about the method and class from which the error originated (if raised from a
207         * class that uses the Ext 4 class system).
208         * @static
209         */
210        handle: function(){
211            return Ext.Error.ignore;
212        }
213    },
214
215    // This is the standard property that is the name of the constructor.
216    name: 'Ext.Error',
217
218<span id='Ext-Error-method-constructor'>    /**
219</span>     * Creates new Error object.
220     * @param {String/Object} config The error message string, or an object containing the
221     * attribute &quot;msg&quot; that will be used as the error message. Any other data included in
222     * the object will be applied to the error instance and logged to the browser console, if available.
223     */
224    constructor: function(config){
225        if (Ext.isString(config)) {
226            config = { msg: config };
227        }
228
229        var me = this;
230
231        Ext.apply(me, config);
232
233        me.message = me.message || me.msg; // 'message' is standard ('msg' is non-standard)
234        // note: the above does not work in old WebKit (me.message is readonly) (Safari 4)
235    },
236
237<span id='Ext-Error-method-toString'>    /**
238</span>     * Provides a custom string representation of the error object. This is an override of the base JavaScript
239     * `Object.toString` method, which is useful so that when logged to the browser console, an error object will
240     * be displayed with a useful message instead of `[object Object]`, the default `toString` result.
241     *
242     * The default implementation will include the error message along with the raising class and method, if available,
243     * but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
244     * a particular error instance, if you want to provide a custom description that will show up in the console.
245     * @return {String} The error message. If raised from within the Ext 4 class system, the error message will also
246     * include the raising class and method names, if available.
247     */
248    toString: function(){
249        var me = this,
250            className = me.sourceClass ? me.sourceClass : '',
251            methodName = me.sourceMethod ? '.' + me.sourceMethod + '(): ' : '',
252            msg = me.msg || '(No description provided)';
253
254        return className + methodName + msg;
255    }
256});
257
258/*
259 * Create a function that will throw an error if called (in debug mode) with a message that
260 * indicates the method has been removed.
261 * @param {String} suggestion Optional text to include in the message (a workaround perhaps).
262 * @return {Function} The generated function.
263 * @private
264 */
265Ext.deprecated = function (suggestion) {
266    //&lt;debug&gt;
267    if (!suggestion) {
268        suggestion = '';
269    }
270
271    function fail () {
272        Ext.Error.raise('The method &quot;' + fail.$owner.$className + '.' + fail.$name + 
273                '&quot; has been removed. ' + suggestion);
274    }
275
276    return fail;
277    //&lt;/debug&gt;
278    return Ext.emptyFn;
279};
280
281/*
282 * This mechanism is used to notify the user of the first error encountered on the page. This
283 * was previously internal to Ext.Error.raise and is a desirable feature since errors often
284 * slip silently under the radar. It cannot live in Ext.Error.raise since there are times
285 * where exceptions are handled in a try/catch.
286 */
287//&lt;debug&gt;
288(function () {
289    var timer, errors = 0,
290        win = Ext.global,
291        msg;
292
293    if (typeof window === 'undefined') {
294        return; // build system or some such environment...
295    }
296
297    // This method is called to notify the user of the current error status.
298    function notify () {
299        var counters = Ext.log.counters,
300            supports = Ext.supports,
301            hasOnError = supports &amp;&amp; supports.WindowOnError; // TODO - timing
302
303        // Put log counters to the status bar (for most browsers):
304        if (counters &amp;&amp; (counters.error + counters.warn + counters.info + counters.log)) {
305            msg = [ 'Logged Errors:',counters.error, 'Warnings:',counters.warn,
306                        'Info:',counters.info, 'Log:',counters.log].join(' ');
307            if (errors) {
308                msg = '*** Errors: ' + errors + ' - ' + msg;
309            } else if (counters.error) {
310                msg = '*** ' + msg;
311            }
312            win.status = msg;
313        }
314
315        // Display an alert on the first error:
316        if (!Ext.isDefined(Ext.Error.notify)) {
317            Ext.Error.notify = Ext.isIE6 || Ext.isIE7; // TODO - timing
318        }
319        if (Ext.Error.notify &amp;&amp; (hasOnError ? errors : (counters &amp;&amp; counters.error))) {
320            Ext.Error.notify = false;
321
322            if (timer) {
323                win.clearInterval(timer); // ticks can queue up so stop...
324                timer = null;
325            }
326
327            alert('Unhandled error on page: See console or log');
328            poll();
329        }
330    }
331
332    // Sets up polling loop. This is the only way to know about errors in some browsers
333    // (Opera/Safari) and is the only way to update the status bar for warnings and other
334    // non-errors.
335    function poll () {
336        timer = win.setInterval(notify, 1000);
337    }
338
339    // window.onerror sounds ideal but it prevents the built-in error dialog from doing
340    // its (better) thing.
341    poll();
342}());
343//&lt;/debug&gt;
344</pre>
345</body>
346</html>