docs/source/Error.html

   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  */
  90 Ext.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
 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 &quot;msg&quot; 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  * This mechanism is used to notify the user of the first error encountered on the page. This
 259  * was previously internal to Ext.Error.raise and is a desirable feature since errors often
 260  * slip silently under the radar. It cannot live in Ext.Error.raise since there are times
 261  * where exceptions are handled in a try/catch.
 262  */
 263 //&lt;debug&gt;
 264 (function () {
 265     var prevOnError, timer, errors = 0,
 266         extraordinarilyBad = /(out of stack)|(too much recursion)|(stack overflow)|(out of memory)/i,
 267         win = Ext.global;
 268
 269     if (typeof window === 'undefined') {
 270         return; // build system or some such environment...
 271     }
 272
 273     // This method is called to notify the user of the current error status.
 274     function notify () {
 275         var counters = Ext.log.counters,
 276             supports = Ext.supports,
 277             hasOnError = supports &amp;&amp; supports.WindowOnError; // TODO - timing
 278
 279         // Put log counters to the status bar (for most browsers):
 280         if (counters &amp;&amp; (counters.error + counters.warn + counters.info + counters.log)) {
 281             var msg = [ 'Logged Errors:',counters.error, 'Warnings:',counters.warn,
 282                         'Info:',counters.info, 'Log:',counters.log].join(' ');
 283             if (errors) {
 284                 msg = '*** Errors: ' + errors + ' - ' + msg;
 285             } else if (counters.error) {
 286                 msg = '*** ' + msg;
 287             }
 288             win.status = msg;
 289         }
 290
 291         // Display an alert on the first error:
 292         if (!Ext.isDefined(Ext.Error.notify)) {
 293             Ext.Error.notify = Ext.isIE6 || Ext.isIE7; // TODO - timing
 294         }
 295         if (Ext.Error.notify &amp;&amp; (hasOnError ? errors : (counters &amp;&amp; counters.error))) {
 296             Ext.Error.notify = false;
 297
 298             if (timer) {
 299                 win.clearInterval(timer); // ticks can queue up so stop...
 300                 timer = null;
 301             }
 302
 303             alert('Unhandled error on page: See console or log');
 304             poll();
 305         }
 306     }
 307
 308     // Sets up polling loop. This is the only way to know about errors in some browsers
 309     // (Opera/Safari) and is the only way to update the status bar for warnings and other
 310     // non-errors.
 311     function poll () {
 312         timer = win.setInterval(notify, 1000);
 313     }
 314
 315     // window.onerror sounds ideal but it prevents the built-in error dialog from doing
 316     // its (better) thing.
 317     poll();
 318 })();
 319 //&lt;/debug&gt;
 320 </pre>
 321 </body>
 322 </html>