Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Provider.html
index 8c05b82..9309db5 100644 (file)
   </script>
 </head>
 <body onload="prettyPrint(); highlight();">
-  <pre class="prettyprint lang-js"><span id='Ext-direct-Provider'>/**
-</span> * @class Ext.direct.Provider
- * &lt;p&gt;Ext.direct.Provider is an abstract class meant to be extended.&lt;/p&gt;
- * 
- * &lt;p&gt;For example ExtJs implements the following subclasses:&lt;/p&gt;
- * &lt;pre&gt;&lt;code&gt;
-Provider
-|
-+---{@link Ext.direct.JsonProvider JsonProvider} 
-    |
-    +---{@link Ext.direct.PollingProvider PollingProvider}   
-    |
-    +---{@link Ext.direct.RemotingProvider RemotingProvider}   
- * &lt;/code&gt;&lt;/pre&gt;
- * @abstract
+  <pre class="prettyprint lang-js"><span id='Ext-state-Provider'>/**
+</span> * @class Ext.state.Provider
+ * &lt;p&gt;Abstract base class for state provider implementations. The provider is responsible
+ * for setting values  and extracting values to/from the underlying storage source. The 
+ * storage source can vary and the details should be implemented in a subclass. For example
+ * a provider could use a server side database or the browser localstorage where supported.&lt;/p&gt;
+ *
+ * &lt;p&gt;This class provides methods for encoding and decoding &lt;b&gt;typed&lt;/b&gt; variables including 
+ * dates and defines the Provider interface. By default these methods put the value and the
+ * type information into a delimited string that can be stored. These should be overridden in 
+ * a subclass if you want to change the format of the encoded value and subsequent decoding.&lt;/p&gt;
  */
-Ext.define('Ext.direct.Provider', {
-    
-    /* Begin Definitions */
-   
-   alias: 'direct.provider',
-   
+Ext.define('Ext.state.Provider', {
     mixins: {
-        observable: 'Ext.util.Observable'   
+        observable: 'Ext.util.Observable'
     },
-   
-    /* End Definitions */
-   
-<span id='Ext-direct-Provider-cfg-id'>   /**
-</span>     * @cfg {String} id
-     * The unique id of the provider (defaults to an {@link Ext#id auto-assigned id}).
-     * You should assign an id if you need to be able to access the provider later and you do
-     * not have an object reference available, for example:
-     * &lt;pre&gt;&lt;code&gt;
-Ext.direct.Manager.addProvider({
-    type: 'polling',
-    url:  'php/poll.php',
-    id:   'poll-provider'
-});     
-var p = {@link Ext.direct.Manager}.{@link Ext.direct.Manager#getProvider getProvider}('poll-provider');
-p.disconnect();
-     * &lt;/code&gt;&lt;/pre&gt;
+    
+<span id='Ext-state-Provider-cfg-prefix'>    /**
+</span>     * @cfg {String} prefix A string to prefix to items stored in the underlying state store. 
+     * Defaults to &lt;tt&gt;'ext-'&lt;/tt&gt;
      */
+    prefix: 'ext-',
     
     constructor : function(config){
+        config = config || {};
         var me = this;
-        
         Ext.apply(me, config);
-        me.addEvents(
-<span id='Ext-direct-Provider-event-connect'>            /**
-</span>             * @event connect
-             * Fires when the Provider connects to the server-side
-             * @param {Ext.direct.Provider} provider The {@link Ext.direct.Provider Provider}.
-             */            
-            'connect',
-<span id='Ext-direct-Provider-event-disconnect'>            /**
-</span>             * @event disconnect
-             * Fires when the Provider disconnects from the server-side
-             * @param {Ext.direct.Provider} provider The {@link Ext.direct.Provider Provider}.
-             */            
-            'disconnect',
-<span id='Ext-direct-Provider-event-data'>            /**
-</span>             * @event data
-             * Fires when the Provider receives data from the server-side
-             * @param {Ext.direct.Provider} provider The {@link Ext.direct.Provider Provider}.
-             * @param {event} e The Ext.Direct.Event type that occurred.
-             */            
-            'data',
-<span id='Ext-direct-Provider-event-exception'>            /**
-</span>             * @event exception
-             * Fires when the Provider receives an exception from the server-side
-             */                        
-            'exception'
-        );
-        me.mixins.observable.constructor.call(me, config);
+<span id='Ext-state-Provider-event-statechange'>        /**
+</span>         * @event statechange
+         * Fires when a state change occurs.
+         * @param {Provider} this This state provider
+         * @param {String} key The state key which was changed
+         * @param {String} value The encoded value for the state
+         */
+        me.addEvents(&quot;statechange&quot;);
+        me.state = {};
+        me.mixins.observable.constructor.call(me);
     },
     
-<span id='Ext-direct-Provider-method-isConnected'>    /**
-</span>     * Returns whether or not the server-side is currently connected.
-     * Abstract method for subclasses to implement.
+<span id='Ext-state-Provider-method-get'>    /**
+</span>     * Returns the current value for a key
+     * @param {String} name The key name
+     * @param {Mixed} defaultValue A default value to return if the key's value is not found
+     * @return {Mixed} The state data
      */
-    isConnected: function(){
-        return false;
+    get : function(name, defaultValue){
+        return typeof this.state[name] == &quot;undefined&quot; ?
+            defaultValue : this.state[name];
     },
 
-<span id='Ext-direct-Provider-method-connect'>    /**
-</span>     * Abstract methods for subclasses to implement.
-     * @method
+<span id='Ext-state-Provider-method-clear'>    /**
+</span>     * Clears a value from the state
+     * @param {String} name The key name
      */
-    connect: Ext.emptyFn,
-    
-<span id='Ext-direct-Provider-method-disconnect'>    /**
-</span>     * Abstract methods for subclasses to implement.
-     * @method
+    clear : function(name){
+        var me = this;
+        delete me.state[name];
+        me.fireEvent(&quot;statechange&quot;, me, name, null);
+    },
+
+<span id='Ext-state-Provider-method-set'>    /**
+</span>     * Sets the value for a key
+     * @param {String} name The key name
+     * @param {Mixed} value The value to set
+     */
+    set : function(name, value){
+        var me = this;
+        me.state[name] = value;
+        me.fireEvent(&quot;statechange&quot;, me, name, value);
+    },
+
+<span id='Ext-state-Provider-method-decodeValue'>    /**
+</span>     * Decodes a string previously encoded with {@link #encodeValue}.
+     * @param {String} value The value to decode
+     * @return {Mixed} The decoded value
      */
-    disconnect: Ext.emptyFn
-});
-</pre>
+    decodeValue : function(value){
+
+        // a -&gt; Array
+        // n -&gt; Number
+        // d -&gt; Date
+        // b -&gt; Boolean
+        // s -&gt; String
+        // o -&gt; Object
+        // -&gt; Empty (null)
+
+        var me = this,
+            re = /^(a|n|d|b|s|o|e)\:(.*)$/,
+            matches = re.exec(unescape(value)),
+            all,
+            type,
+            value,
+            keyValue;
+            
+        if(!matches || !matches[1]){
+            return; // non state
+        }
+        
+        type = matches[1];
+        value = matches[2];
+        switch (type) {
+            case 'e':
+                return null;
+            case 'n':
+                return parseFloat(value);
+            case 'd':
+                return new Date(Date.parse(value));
+            case 'b':
+                return (value == '1');
+            case 'a':
+                all = [];
+                if(value != ''){
+                    Ext.each(value.split('^'), function(val){
+                        all.push(me.decodeValue(val));
+                    }, me);
+                }
+                return all;
+           case 'o':
+                all = {};
+                if(value != ''){
+                    Ext.each(value.split('^'), function(val){
+                        keyValue = val.split('=');
+                        all[keyValue[0]] = me.decodeValue(keyValue[1]);
+                    }, me);
+                }
+                return all;
+           default:
+                return value;
+        }
+    },
+
+<span id='Ext-state-Provider-method-encodeValue'>    /**
+</span>     * Encodes a value including type information.  Decode with {@link #decodeValue}.
+     * @param {Mixed} value The value to encode
+     * @return {String} The encoded value
+     */
+    encodeValue : function(value){
+        var flat = '',
+            i = 0,
+            enc,
+            len,
+            key;
+            
+        if (value == null) {
+            return 'e:1';    
+        } else if(typeof value == 'number') {
+            enc = 'n:' + value;
+        } else if(typeof value == 'boolean') {
+            enc = 'b:' + (value ? '1' : '0');
+        } else if(Ext.isDate(value)) {
+            enc = 'd:' + value.toGMTString();
+        } else if(Ext.isArray(value)) {
+            for (len = value.length; i &lt; len; i++) {
+                flat += this.encodeValue(value[i]);
+                if (i != len - 1) {
+                    flat += '^';
+                }
+            }
+            enc = 'a:' + flat;
+        } else if (typeof value == 'object') {
+            for (key in value) {
+                if (typeof value[key] != 'function' &amp;&amp; value[key] !== undefined) {
+                    flat += key + '=' + this.encodeValue(value[key]) + '^';
+                }
+            }
+            enc = 'o:' + flat.substring(0, flat.length-1);
+        } else {
+            enc = 's:' + value;
+        }
+        return escape(enc);
+    }
+});</pre>
 </body>
 </html>