X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/docs/source/Error.html diff --git a/docs/source/Error.html b/docs/source/Error.html index 107059a7..d778f7c1 100644 --- a/docs/source/Error.html +++ b/docs/source/Error.html @@ -3,8 +3,8 @@ The source code - - + + @@ -16,152 +16,144 @@
/**
- * @class Ext.Error
- * @private
- * @extends Error
-
-A wrapper class for the native JavaScript Error object that adds a few useful capabilities for handling
-errors in an Ext application. When you use Ext.Error to {@link #raise} an error from within any class that
-uses the Ext 4 class system, the Error class can automatically add the source class and method from which
-the error was raised. It also includes logic to automatically log the eroor to the console, if available,
-with additional metadata about the error. In all cases, the error will always be thrown at the end so that
-execution will halt.
-
-Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to
-handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,
-although in a real application it's usually a better idea to override the handling function and perform
-logging or some other method of reporting the errors in a way that is meaningful to the application.
-
-At its simplest you can simply raise an error as a simple string from within any code:
-
-#Example usage:#
-
-    Ext.Error.raise('Something bad happened!');
-
-If raised from plain JavaScript code, the error will be logged to the console (if available) and the message
-displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add
-additional metadata about the error being raised.  The {@link #raise} method can also take a config object.
-In this form the `msg` attribute becomes the error description, and any other data added to the config gets
-added to the error object and, if the console is available, logged to the console for inspection.
-
-#Example usage:#
-
-    Ext.define('Ext.Foo', {
-        doSomething: function(option){
-            if (someCondition === false) {
-                Ext.Error.raise({
-                    msg: 'You cannot do that!',
-                    option: option,   // whatever was passed into the method
-                    'error code': 100 // other arbitrary info
-                });
-            }
-        }
-    });
-
-If a console is available (that supports the `console.dir` function) you'll see console output like:
-
-    An error was raised with the following data:
-    option:         Object { foo: "bar"}
-        foo:        "bar"
-    error code:     100
-    msg:            "You cannot do that!"
-    sourceClass:   "Ext.Foo"
-    sourceMethod:  "doSomething"
-
-    uncaught exception: You cannot do that!
-
-As you can see, the error will report exactly where it was raised and will include as much information as the
-raising code can usefully provide.
-
-If you want to handle all application errors globally you can simply override the static {@link #handle} method
-and provide whatever handling logic you need. If the method returns true then the error is considered handled
-and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.
-
-#Example usage:#
-
-    Ext.Error.handle = function(err) {
-        if (err.someProperty == 'NotReallyAnError') {
-            // maybe log something to the application here if applicable
-            return true;
-        }
-        // any non-true return value (including none) will cause the error to be thrown
-    }
-
- * Create a new Error object
- * @param {Object} config The config object
- * @markdown
- * @author Brian Moeskau <brian@sencha.com>
+ * @author Brian Moeskau <brian@sencha.com>
  * @docauthor Brian Moeskau <brian@sencha.com>
+ *
+ * A wrapper class for the native JavaScript Error object that adds a few useful capabilities for handling
+ * errors in an Ext application. When you use Ext.Error to {@link #raise} an error from within any class that
+ * uses the Ext 4 class system, the Error class can automatically add the source class and method from which
+ * the error was raised. It also includes logic to automatically log the eroor to the console, if available,
+ * with additional metadata about the error. In all cases, the error will always be thrown at the end so that
+ * execution will halt.
+ *
+ * Ext.Error also offers a global error {@link #handle handling} method that can be overridden in order to
+ * handle application-wide errors in a single spot. You can optionally {@link #ignore} errors altogether,
+ * although in a real application it's usually a better idea to override the handling function and perform
+ * logging or some other method of reporting the errors in a way that is meaningful to the application.
+ *
+ * At its simplest you can simply raise an error as a simple string from within any code:
+ *
+ * Example usage:
+ *
+ *     Ext.Error.raise('Something bad happened!');
+ *
+ * If raised from plain JavaScript code, the error will be logged to the console (if available) and the message
+ * displayed. In most cases however you'll be raising errors from within a class, and it may often be useful to add
+ * additional metadata about the error being raised.  The {@link #raise} method can also take a config object.
+ * In this form the `msg` attribute becomes the error description, and any other data added to the config gets
+ * added to the error object and, if the console is available, logged to the console for inspection.
+ *
+ * Example usage:
+ *
+ *     Ext.define('Ext.Foo', {
+ *         doSomething: function(option){
+ *             if (someCondition === false) {
+ *                 Ext.Error.raise({
+ *                     msg: 'You cannot do that!',
+ *                     option: option,   // whatever was passed into the method
+ *                     'error code': 100 // other arbitrary info
+ *                 });
+ *             }
+ *         }
+ *     });
+ *
+ * If a console is available (that supports the `console.dir` function) you'll see console output like:
+ *
+ *     An error was raised with the following data:
+ *     option:         Object { foo: "bar"}
+ *         foo:        "bar"
+ *     error code:     100
+ *     msg:            "You cannot do that!"
+ *     sourceClass:   "Ext.Foo"
+ *     sourceMethod:  "doSomething"
+ *
+ *     uncaught exception: You cannot do that!
+ *
+ * As you can see, the error will report exactly where it was raised and will include as much information as the
+ * raising code can usefully provide.
+ *
+ * If you want to handle all application errors globally you can simply override the static {@link #handle} method
+ * and provide whatever handling logic you need. If the method returns true then the error is considered handled
+ * and will not be thrown to the browser. If anything but true is returned then the error will be thrown normally.
+ *
+ * Example usage:
+ *
+ *     Ext.Error.handle = function(err) {
+ *         if (err.someProperty == 'NotReallyAnError') {
+ *             // maybe log something to the application here if applicable
+ *             return true;
+ *         }
+ *         // any non-true return value (including none) will cause the error to be thrown
+ *     }
+ *
  */
 Ext.Error = Ext.extend(Error, {
     statics: {
-        /**
-         * @property ignore
-Static flag that can be used to globally disable error reporting to the browser if set to true
-(defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail
-and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably
-be preferable to supply a custom error {@link #handle handling} function instead.
-
-#Example usage:#
-
-    Ext.Error.ignore = true;
-
-         * @markdown
+        /**
+         * @property {Boolean} ignore
+         * Static flag that can be used to globally disable error reporting to the browser if set to true
+         * (defaults to false). Note that if you ignore Ext errors it's likely that some other code may fail
+         * and throw a native JavaScript error thereafter, so use with caution. In most cases it will probably
+         * be preferable to supply a custom error {@link #handle handling} function instead.
+         *
+         * Example usage:
+         *
+         *     Ext.Error.ignore = true;
+         *
          * @static
          */
         ignore: false,
 
-        /**
-         * @property notify
-Static flag that can be used to globally control error notification to the user. Unlike
-Ex.Error.ignore, this does not effect exceptions. They are still thrown. This value can be
-set to false to disable the alert notification (default is true for IE6 and IE7).
-
-Only the first error will generate an alert. Internally this flag is set to false when the
-first error occurs prior to displaying the alert.
-
-This flag is not used in a release build.
-
-#Example usage:#
-
-    Ext.Error.notify = false;
-
-         * @markdown
+        /**
+         * @property {Boolean} notify
+         * Static flag that can be used to globally control error notification to the user. Unlike
+         * Ex.Error.ignore, this does not effect exceptions. They are still thrown. This value can be
+         * set to false to disable the alert notification (default is true for IE6 and IE7).
+         *
+         * Only the first error will generate an alert. Internally this flag is set to false when the
+         * first error occurs prior to displaying the alert.
+         *
+         * This flag is not used in a release build.
+         *
+         * Example usage:
+         *
+         *     Ext.Error.notify = false;
+         *
          * @static
          */
         //notify: Ext.isIE6 || Ext.isIE7,
 
-        /**
-Raise an error that can include additional data and supports automatic console logging if available.
-You can pass a string error message or an object with the `msg` attribute which will be used as the
-error message. The object can contain any other name-value attributes (or objects) to be logged
-along with the error.
-
-Note that after displaying the error message a JavaScript error will ultimately be thrown so that
-execution will halt.
-
-#Example usage:#
-
-    Ext.Error.raise('A simple string error message');
-
-    // or...
-
-    Ext.define('Ext.Foo', {
-        doSomething: function(option){
-            if (someCondition === false) {
-                Ext.Error.raise({
-                    msg: 'You cannot do that!',
-                    option: option,   // whatever was passed into the method
-                    'error code': 100 // other arbitrary info
-                });
-            }
-        }
-    });
-         * @param {String/Object} err The error message string, or an object containing the
-         * attribute "msg" that will be used as the error message. Any other data included in
-         * the object will also be logged to the browser console, if available.
+        /**
+         * Raise an error that can include additional data and supports automatic console logging if available.
+         * You can pass a string error message or an object with the `msg` attribute which will be used as the
+         * error message. The object can contain any other name-value attributes (or objects) to be logged
+         * along with the error.
+         *
+         * Note that after displaying the error message a JavaScript error will ultimately be thrown so that
+         * execution will halt.
+         *
+         * Example usage:
+         *
+         *     Ext.Error.raise('A simple string error message');
+         *
+         *     // or...
+         *
+         *     Ext.define('Ext.Foo', {
+         *         doSomething: function(option){
+         *             if (someCondition === false) {
+         *                 Ext.Error.raise({
+         *                     msg: 'You cannot do that!',
+         *                     option: option,   // whatever was passed into the method
+         *                     'error code': 100 // other arbitrary info
+         *                 });
+         *             }
+         *         }
+         *     });
+         *
+         * @param {String/Object} err The error message string, or an object containing the attribute "msg" that will be
+         * used as the error message. Any other data included in the object will also be logged to the browser console,
+         * if available.
          * @static
-         * @markdown
          */
         raise: function(err){
             err = err || {};
@@ -194,26 +186,25 @@ execution will halt.
             }
         },
 
-        /**
-Globally handle any Ext errors that may be raised, optionally providing custom logic to
-handle different errors individually. Return true from the function to bypass throwing the
-error to the browser, otherwise the error will be thrown and execution will halt.
-
-#Example usage:#
-
-    Ext.Error.handle = function(err) {
-        if (err.someProperty == 'NotReallyAnError') {
-            // maybe log something to the application here if applicable
-            return true;
-        }
-        // any non-true return value (including none) will cause the error to be thrown
-    }
-
-         * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes
-         * that were originally raised with it, plus properties about the method and class from which
-         * the error originated (if raised from a class that uses the Ext 4 class system).
+        /**
+         * Globally handle any Ext errors that may be raised, optionally providing custom logic to
+         * handle different errors individually. Return true from the function to bypass throwing the
+         * error to the browser, otherwise the error will be thrown and execution will halt.
+         *
+         * Example usage:
+         *
+         *     Ext.Error.handle = function(err) {
+         *         if (err.someProperty == 'NotReallyAnError') {
+         *             // maybe log something to the application here if applicable
+         *             return true;
+         *         }
+         *         // any non-true return value (including none) will cause the error to be thrown
+         *     }
+         *
+         * @param {Ext.Error} err The Ext.Error object being raised. It will contain any attributes that were originally
+         * raised with it, plus properties about the method and class from which the error originated (if raised from a
+         * class that uses the Ext 4 class system).
          * @static
-         * @markdown
          */
         handle: function(){
             return Ext.Error.ignore;
@@ -224,7 +215,8 @@ error to the browser, otherwise the error will be thrown and execution will halt
     name: 'Ext.Error',
 
     /**
-     * @param {String/Object} config The error message string, or an object containing the
+     * Creates new Error object.
+     * @param {String/Object} config The error message string, or an object containing the
      * attribute "msg" that will be used as the error message. Any other data included in
      * the object will be applied to the error instance and logged to the browser console, if available.
      */
@@ -242,16 +234,15 @@ error to the browser, otherwise the error will be thrown and execution will halt
     },
 
     /**
-Provides a custom string representation of the error object. This is an override of the base JavaScript
-`Object.toString` method, which is useful so that when logged to the browser console, an error object will
-be displayed with a useful message instead of `[object Object]`, the default `toString` result.
-
-The default implementation will include the error message along with the raising class and method, if available,
-but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
-a particular error instance, if you want to provide a custom description that will show up in the console.
-     * @markdown
-     * @return {String} The error message. If raised from within the Ext 4 class system, the error message
-     * will also include the raising class and method names, if available.
+     * Provides a custom string representation of the error object. This is an override of the base JavaScript
+     * `Object.toString` method, which is useful so that when logged to the browser console, an error object will
+     * be displayed with a useful message instead of `[object Object]`, the default `toString` result.
+     *
+     * The default implementation will include the error message along with the raising class and method, if available,
+     * but this can be overridden with a custom implementation either at the prototype level (for all errors) or on
+     * a particular error instance, if you want to provide a custom description that will show up in the console.
+     * @return {String} The error message. If raised from within the Ext 4 class system, the error message will also
+     * include the raising class and method names, if available.
      */
     toString: function(){
         var me = this,
@@ -321,20 +312,8 @@ a particular error instance, if you want to provide a custom description that wi
         timer = win.setInterval(notify, 1000);
     }
 
-    // window.onerror is ideal (esp in IE) because you get full context. This is harmless
-    // otherwise (never called) which is good because you cannot feature detect it.
-    prevOnError = win.onerror || Ext.emptyFn;
-    win.onerror = function (message) {
-        ++errors;
-
-        if (!extraordinarilyBad.test(message)) {
-            // too much recursion + our alert right now = crash IE
-            // our polling loop will pick it up even if we don't alert now
-            notify();
-        }
-
-        return prevOnError.apply(this, arguments);
-    };
+    // window.onerror sounds ideal but it prevents the built-in error dialog from doing
+    // its (better) thing.
     poll();
 })();
 //</debug>