Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Error.html
index 65a4b75..d778f7c 100644 (file)
+<!DOCTYPE html>
 <html>
 <head>
 <html>
 <head>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
   <title>The source code</title>
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
 </head>
 </head>
-<body  onload="prettyPrint();">
-    <pre class="prettyprint lang-js">/*!
- * Ext JS Library 3.3.1
- * Copyright(c) 2006-2010 Sencha Inc.
- * licensing@sencha.com
- * http://www.sencha.com/license
- */
-<div id="method-Ext.Element-handleError"></div>/**
- * Framework-wide error-handler.  Developers can override this method to provide
- * custom exception-handling.  Framework errors will often extend from the base
- * Ext.Error class.
- * @param {Object/Error} e The thrown exception object.
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-Error'>/**
+</span> * @author Brian Moeskau &lt;brian@sencha.com&gt;
+ * @docauthor Brian Moeskau &lt;brian@sencha.com&gt;
+ *
+ * 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: &quot;bar&quot;}
+ *         foo:        &quot;bar&quot;
+ *     error code:     100
+ *     msg:            &quot;You cannot do that!&quot;
+ *     sourceClass:   &quot;Ext.Foo&quot;
+ *     sourceMethod:  &quot;doSomething&quot;
+ *
+ *     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.handleError = function(e) {
-    throw e;
-};
-
-<div id="cls-Ext.Error"></div>/**
- * @class Ext.Error
- * @extends Error
- * <p>A base error class. Future implementations are intended to provide more
- * robust error handling throughout the framework (<b>in the debug build only</b>)
- * to check for common errors and problems. The messages issued by this class
- * will aid error checking. Error checks will be automatically removed in the
- * production build so that performance is not negatively impacted.</p>
- * <p>Some sample messages currently implemented:</p><pre>
-"DataProxy attempted to execute an API-action but found an undefined
-url / function. Please review your Proxy url/api-configuration."
- * </pre><pre>
-"Could not locate your "root" property in your server response.
-Please review your JsonReader config to ensure the config-property
-"root" matches the property your server-response.  See the JsonReader
-docs for additional assistance."
- * </pre>
- * <p>An example of the code used for generating error messages:</p><pre><code>
-try {
-    generateError({
-        foo: 'bar'
-    });
-}
-catch (e) {
-    console.error(e);
-}
-function generateError(data) {
-    throw new Ext.Error('foo-error', data);
-}
- * </code></pre>
- * @param {String} message
- */
-Ext.Error = function(message) {
-    // Try to read the message from Ext.Error.lang
-    this.message = (this.lang[message]) ? this.lang[message] : message;
-};
+Ext.Error = Ext.extend(Error, {
+    statics: {
+<span id='Ext-Error-static-property-ignore'>        /**
+</span>         * @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,
 
 
-Ext.Error.prototype = new Error();
-Ext.apply(Ext.Error.prototype, {
-    // protected.  Extensions place their error-strings here.
-    lang: {},
+<span id='Ext-Error-static-property-notify'>        /**
+</span>         * @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,
 
 
-    name: 'Ext.Error',
-    <div id="method-Ext.Error-getName"></div>/**
-     * getName
-     * @return {String}
-     */
-    getName : function() {
-        return this.name;
+<span id='Ext-Error-static-method-raise'>        /**
+</span>         * 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 &quot;msg&quot; 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
+         */
+        raise: function(err){
+            err = err || {};
+            if (Ext.isString(err)) {
+                err = { msg: err };
+            }
+
+            var method = this.raise.caller;
+
+            if (method) {
+                if (method.$name) {
+                    err.sourceMethod = method.$name;
+                }
+                if (method.$owner) {
+                    err.sourceClass = method.$owner.$className;
+                }
+            }
+
+            if (Ext.Error.handle(err) !== true) {
+                var msg = Ext.Error.prototype.toString.call(err);
+
+                Ext.log({
+                    msg: msg,
+                    level: 'error',
+                    dump: err,
+                    stack: true
+                });
+
+                throw new Ext.Error(err);
+            }
+        },
+
+<span id='Ext-Error-static-method-handle'>        /**
+</span>         * 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
+         */
+        handle: function(){
+            return Ext.Error.ignore;
+        }
     },
     },
-    <div id="method-Ext.Error-getMessage"></div>/**
-     * getMessage
-     * @return {String}
+
+    // This is the standard property that is the name of the constructor.
+    name: 'Ext.Error',
+
+<span id='Ext-Error-method-constructor'>    /**
+</span>     * Creates new Error object.
+     * @param {String/Object} config The error message string, or an object containing the
+     * attribute &quot;msg&quot; 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.
      */
      */
-    getMessage : function() {
-        return this.message;
+    constructor: function(config){
+        if (Ext.isString(config)) {
+            config = { msg: config };
+        }
+
+        var me = this;
+
+        Ext.apply(me, config);
+
+        me.message = me.message || me.msg; // 'message' is standard ('msg' is non-standard)
+        // note: the above does not work in old WebKit (me.message is readonly) (Safari 4)
     },
     },
-    <div id="method-Ext.Error-toJson"></div>/**
-     * toJson
-     * @return {String}
+
+<span id='Ext-Error-method-toString'>    /**
+</span>     * 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.
      */
      */
-    toJson : function() {
-        return Ext.encode(this);
+    toString: function(){
+        var me = this,
+            className = me.className ? me.className  : '',
+            methodName = me.methodName ? '.' + me.methodName + '(): ' : '',
+            msg = me.msg || '(No description provided)';
+
+        return className + methodName + msg;
     }
 });
     }
 });
-</pre>    
+
+/*
+ * This mechanism is used to notify the user of the first error encountered on the page. This
+ * was previously internal to Ext.Error.raise and is a desirable feature since errors often
+ * slip silently under the radar. It cannot live in Ext.Error.raise since there are times
+ * where exceptions are handled in a try/catch.
+ */
+//&lt;debug&gt;
+(function () {
+    var prevOnError, timer, errors = 0,
+        extraordinarilyBad = /(out of stack)|(too much recursion)|(stack overflow)|(out of memory)/i,
+        win = Ext.global;
+
+    if (typeof window === 'undefined') {
+        return; // build system or some such environment...
+    }
+
+    // This method is called to notify the user of the current error status.
+    function notify () {
+        var counters = Ext.log.counters,
+            supports = Ext.supports,
+            hasOnError = supports &amp;&amp; supports.WindowOnError; // TODO - timing
+
+        // Put log counters to the status bar (for most browsers):
+        if (counters &amp;&amp; (counters.error + counters.warn + counters.info + counters.log)) {
+            var msg = [ 'Logged Errors:',counters.error, 'Warnings:',counters.warn,
+                        'Info:',counters.info, 'Log:',counters.log].join(' ');
+            if (errors) {
+                msg = '*** Errors: ' + errors + ' - ' + msg;
+            } else if (counters.error) {
+                msg = '*** ' + msg;
+            }
+            win.status = msg;
+        }
+
+        // Display an alert on the first error:
+        if (!Ext.isDefined(Ext.Error.notify)) {
+            Ext.Error.notify = Ext.isIE6 || Ext.isIE7; // TODO - timing
+        }
+        if (Ext.Error.notify &amp;&amp; (hasOnError ? errors : (counters &amp;&amp; counters.error))) {
+            Ext.Error.notify = false;
+
+            if (timer) {
+                win.clearInterval(timer); // ticks can queue up so stop...
+                timer = null;
+            }
+
+            alert('Unhandled error on page: See console or log');
+            poll();
+        }
+    }
+
+    // Sets up polling loop. This is the only way to know about errors in some browsers
+    // (Opera/Safari) and is the only way to update the status bar for warnings and other
+    // non-errors.
+    function poll () {
+        timer = win.setInterval(notify, 1000);
+    }
+
+    // window.onerror sounds ideal but it prevents the built-in error dialog from doing
+    // its (better) thing.
+    poll();
+})();
+//&lt;/debug&gt;
+</pre>
 </body>
 </body>
-</html>
\ No newline at end of file
+</html>