extjs-rails 4.1.0.alpha1

data/app/assets/javascripts/extjs-rails/src/data/reader/Xml.js

@@ -0,0 +1,292 @@
+/**
+ * @author Ed Spencer
+ *
+ * The XML Reader is used by a Proxy to read a server response that is sent back in XML format. This usually happens as
+ * a result of loading a Store - for example we might create something like this:
+ *
+ *     Ext.define('User', {
+ *         extend: 'Ext.data.Model',
+ *         fields: ['id', 'name', 'email']
+ *     });
+ *
+ *     var store = Ext.create('Ext.data.Store', {
+ *         model: 'User',
+ *         proxy: {
+ *             type: 'ajax',
+ *             url : 'users.xml',
+ *             reader: {
+ *                 type: 'xml',
+ *                 record: 'user',
+ *                 root: 'users'
+ *             }
+ *         }
+ *     });
+ *
+ * The example above creates a 'User' model. Models are explained in the {@link Ext.data.Model Model} docs if you're not
+ * already familiar with them.
+ *
+ * We created the simplest type of XML Reader possible by simply telling our {@link Ext.data.Store Store}'s {@link
+ * Ext.data.proxy.Proxy Proxy} that we want a XML Reader. The Store automatically passes the configured model to the
+ * Store, so it is as if we passed this instead:
+ *
+ *     reader: {
+ *         type : 'xml',
+ *         model: 'User',
+ *         record: 'user',
+ *         root: 'users'
+ *     }
+ *
+ * The reader we set up is ready to read data from our server - at the moment it will accept a response like this:
+ *
+ *     <?xml version="1.0" encoding="UTF-8"?>
+ *     <users>
+ *         <user>
+ *             <id>1</id>
+ *             <name>Ed Spencer</name>
+ *             <email>ed@sencha.com</email>
+ *         </user>
+ *         <user>
+ *             <id>2</id>
+ *             <name>Abe Elias</name>
+ *             <email>abe@sencha.com</email>
+ *         </user>
+ *     </users>
+ *
+ * First off there's {@link #root} option to define the root node `<users>` (there should be only one in a well-formed
+ * XML document). Then the XML Reader uses the configured {@link #record} option to pull out the data for each record -
+ * in this case we set record to 'user', so each `<user>` above will be converted into a User model.
+ *
+ * Note that XmlReader doesn't care whether your {@link #root} and {@link #record} elements are nested deep inside a
+ * larger structure, so a response like this will still work:
+ *
+ *     <?xml version="1.0" encoding="UTF-8"?>
+ *     <deeply>
+ *         <nested>
+ *             <xml>
+ *                 <users>
+ *                     <user>
+ *                         <id>1</id>
+ *                         <name>Ed Spencer</name>
+ *                         <email>ed@sencha.com</email>
+ *                     </user>
+ *                     <user>
+ *                         <id>2</id>
+ *                         <name>Abe Elias</name>
+ *                         <email>abe@sencha.com</email>
+ *                     </user>
+ *                 </users>
+ *             </xml>
+ *         </nested>
+ *     </deeply>
+ *
+ * # Response metadata
+ *
+ * The server can return additional data in its response, such as the {@link #totalProperty total number of records} and
+ * the {@link #successProperty success status of the response}. These are typically included in the XML response like
+ * this:
+ *
+ *     <?xml version="1.0" encoding="UTF-8"?>
+ *     <users>
+ *         <total>100</total>
+ *         <success>true</success>
+ *         <user>
+ *             <id>1</id>
+ *             <name>Ed Spencer</name>
+ *             <email>ed@sencha.com</email>
+ *         </user>
+ *         <user>
+ *             <id>2</id>
+ *             <name>Abe Elias</name>
+ *             <email>abe@sencha.com</email>
+ *         </user>
+ *     </users>
+ *
+ * If these properties are present in the XML response they can be parsed out by the XmlReader and used by the Store
+ * that loaded it. We can set up the names of these properties by specifying a final pair of configuration options:
+ *
+ *     reader: {
+ *         type: 'xml',
+ *         root: 'users',
+ *         totalProperty  : 'total',
+ *         successProperty: 'success'
+ *     }
+ *
+ * These final options are not necessary to make the Reader work, but can be useful when the server needs to report an
+ * error or if it needs to indicate that there is a lot of data available of which only a subset is currently being
+ * returned.
+ *
+ * # Response format
+ *
+ * **Note:** in order for the browser to parse a returned XML document, the Content-Type header in the HTTP response
+ * must be set to "text/xml" or "application/xml". This is very important - the XmlReader will not work correctly
+ * otherwise.
+ */
+Ext.define('Ext.data.reader.Xml', {
+    extend: 'Ext.data.reader.Reader',
+    alternateClassName: 'Ext.data.XmlReader',
+    alias : 'reader.xml',
+
+    /**
+     * @cfg {String} record (required)
+     * The DomQuery path to the repeated element which contains record information.
+     */
+
+    /**
+     * @private
+     * Creates a function to return some particular key of data from a response. The totalProperty and
+     * successProperty are treated as special cases for type casting, everything else is just a simple selector.
+     * @param {String} key
+     * @return {Function}
+     */
+    createAccessor: function(expr) {
+        var me = this;
+
+        if (Ext.isEmpty(expr)) {
+            return Ext.emptyFn;
+        }
+
+        if (Ext.isFunction(expr)) {
+            return expr;
+        }
+
+        return function(root) {
+            return me.getNodeValue(Ext.DomQuery.selectNode(expr, root));
+        };
+    },
+
+    getNodeValue: function(node) {
+        if (node && node.firstChild) {
+            return node.firstChild.nodeValue;
+        }
+        return undefined;
+    },
+
+    //inherit docs
+    getResponseData: function(response) {
+        var xml = response.responseXML,
+            error,
+            msg;
+
+        if (!xml) {
+            msg = 'XML data not found in the response';               
+
+            error = new Ext.data.ResultSet({
+                total  : 0,
+                count  : 0,
+                records: [],
+                success: false,
+                message: msg
+            });
+
+            this.fireEvent('exception', this, response, error);
+
+            Ext.Logger.warn(msg);
+
+            return error;
+        }
+
+        return this.readRecords(xml);
+    },
+
+    /**
+     * Normalizes the data object.
+     * @param {Object} data The raw data object
+     * @return {Object} The documentElement property of the data object if present, or the same object if not.
+     */
+    getData: function(data) {
+        return data.documentElement || data;
+    },
+
+    /**
+     * @private
+     * Given an XML object, returns the Element that represents the root as configured by the Reader's meta data.
+     * @param {Object} data The XML data object
+     * @return {XMLElement} The root node element
+     */
+    getRoot: function(data) {
+        var nodeName = data.nodeName,
+            root     = this.root;
+
+        if (!root || (nodeName && nodeName == root)) {
+            return data;
+        } else if (Ext.DomQuery.isXml(data)) {
+            // This fix ensures we have XML data
+            // Related to TreeStore calling getRoot with the root node, which isn't XML
+            // Probably should be resolved in TreeStore at some point
+            return Ext.DomQuery.selectNode(root, data);
+        }
+    },
+
+    /**
+     * @private
+     * We're just preparing the data for the superclass by pulling out the record nodes we want.
+     * @param {XMLElement} root The XML root node
+     * @return {Ext.data.Model[]} The records
+     */
+    extractData: function(root) {
+        var recordName = this.record;
+
+        //<debug>
+        if (!recordName) {
+            Ext.Error.raise('Record is a required parameter');
+        }
+        //</debug>
+
+        if (recordName != root.nodeName) {
+            root = Ext.DomQuery.select(recordName, root);
+        } else {
+            root = [root];
+        }
+        return this.callParent([root]);
+    },
+
+    /**
+     * @private
+     * See Ext.data.reader.Reader's getAssociatedDataRoot docs.
+     * @param {Object} data The raw data object
+     * @param {String} associationName The name of the association to get data for (uses associationKey if present)
+     * @return {XMLElement} The root
+     */
+    getAssociatedDataRoot: function(data, associationName) {
+        return Ext.DomQuery.select(associationName, data)[0];
+    },
+
+    /**
+     * Parses an XML document and returns a ResultSet containing the model instances.
+     * @param {Object} doc Parsed XML document
+     * @return {Ext.data.ResultSet} The parsed result set
+     */
+    readRecords: function(doc) {
+        // it's possible that we get passed an array here by associations.
+        // Make sure we strip that out (see Ext.data.reader.Reader#readAssociated)
+        if (Ext.isArray(doc)) {
+            doc = doc[0];
+        }
+
+        /**
+         * @property {Object} xmlData
+         * Copy of {@link #rawData}.
+         * @deprecated Will be removed in Ext JS 5.0. Use {@link #rawData} instead.
+         */
+        this.xmlData = doc;
+        return this.callParent([doc]);
+    },
+
+    /**
+     * @private
+     * Returns an accessor expression for the passed Field from an XML element using either the Field's mapping, or
+     * its ordinal position in the fields collsction as the index.
+     * This is used by buildExtractors to create optimized on extractor function which converts raw data into model instances.
+     */
+    createFieldAccessExpression: function(field, fieldVarName, dataName) {
+        var selector = field.mapping || field.name,
+            result;
+
+        if (typeof selector === 'function') {
+            result = fieldVarName + '.mapping(' + dataName + ', this)';
+        } else {
+            result = 'me.getNodeValue(Ext.DomQuery.selectNode("' + selector + '", ' + dataName + '))';
+        }
+        return result;
+    }
+});

data/app/assets/javascripts/extjs-rails/src/data/validations.js

@@ -0,0 +1,149 @@
+/**
+ * @author Ed Spencer
+ *
+ * This singleton contains a set of validation functions that can be used to validate any type of data. They are most
+ * often used in {@link Ext.data.Model Models}, where they are automatically set up and executed.
+ */
+Ext.define('Ext.data.validations', {
+    singleton: true,
+    
+    /**
+     * @property {String} presenceMessage
+     * The default error message used when a presence validation fails.
+     */
+    presenceMessage: 'must be present',
+    
+    /**
+     * @property {String} lengthMessage
+     * The default error message used when a length validation fails.
+     */
+    lengthMessage: 'is the wrong length',
+    
+    /**
+     * @property {Boolean} formatMessage
+     * The default error message used when a format validation fails.
+     */
+    formatMessage: 'is the wrong format',
+    
+    /**
+     * @property {String} inclusionMessage
+     * The default error message used when an inclusion validation fails.
+     */
+    inclusionMessage: 'is not included in the list of acceptable values',
+    
+    /**
+     * @property {String} exclusionMessage
+     * The default error message used when an exclusion validation fails.
+     */
+    exclusionMessage: 'is not an acceptable value',
+    
+    /**
+     * @property {String} emailMessage
+     * The default error message used when an email validation fails
+     */
+    emailMessage: 'is not a valid email address',
+    
+    /**
+     * @property {RegExp} emailRe
+     * The regular expression used to validate email addresses
+     */
+    emailRe: /^([a-zA-Z0-9_\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$/,
+    
+    /**
+     * Validates that the given value is present.
+     * For example:
+     *
+     *     validations: [{type: 'presence', field: 'age'}]
+     *
+     * @param {Object} config Config object
+     * @param {Object} value The value to validate
+     * @return {Boolean} True if validation passed
+     */
+    presence: function(config, value) {
+        // No configs read, so allow just value to be passed
+        if (arguments.length === 1) {
+            value = config;
+        }
+        
+        //we need an additional check for zero here because zero is an acceptable form of present data
+        return !!value || value === 0;
+    },
+    
+    /**
+     * Returns true if the given value is between the configured min and max values.
+     * For example:
+     *
+     *     validations: [{type: 'length', field: 'name', min: 2}]
+     *
+     * @param {Object} config Config object
+     * @param {String} value The value to validate
+     * @return {Boolean} True if the value passes validation
+     */
+    length: function(config, value) {
+        if (value === undefined || value === null) {
+            return false;
+        }
+        
+        var length = value.length,
+            min    = config.min,
+            max    = config.max;
+        
+        if ((min && length < min) || (max && length > max)) {
+            return false;
+        } else {
+            return true;
+        }
+    },
+    
+    /**
+     * Validates that an email string is in the correct format
+     * @param {Object} config Config object
+     * @param {String} email The email address
+     * @return {Boolean} True if the value passes validation
+     */
+    email: function(config, email) {
+        return Ext.data.validations.emailRe.test(email);
+    },
+    
+    /**
+     * Returns true if the given value passes validation against the configured `matcher` regex.
+     * For example:
+     *
+     *     validations: [{type: 'format', field: 'username', matcher: /([a-z]+)[0-9]{2,3}/}]
+     *
+     * @param {Object} config Config object
+     * @param {String} value The value to validate
+     * @return {Boolean} True if the value passes the format validation
+     */
+    format: function(config, value) {
+        return !!(config.matcher && config.matcher.test(value));
+    },
+    
+    /**
+     * Validates that the given value is present in the configured `list`.
+     * For example:
+     *
+     *     validations: [{type: 'inclusion', field: 'gender', list: ['Male', 'Female']}]
+     *
+     * @param {Object} config Config object
+     * @param {String} value The value to validate
+     * @return {Boolean} True if the value is present in the list
+     */
+    inclusion: function(config, value) {
+        return config.list && Ext.Array.indexOf(config.list,value) != -1;
+    },
+    
+    /**
+     * Validates that the given value is present in the configured `list`.
+     * For example:
+     *
+     *     validations: [{type: 'exclusion', field: 'username', list: ['Admin', 'Operator']}]
+     *
+     * @param {Object} config Config object
+     * @param {String} value The value to validate
+     * @return {Boolean} True if the value is not present in the list
+     */
+    exclusion: function(config, value) {
+        return config.list && Ext.Array.indexOf(config.list,value) == -1;
+    }
+});

data/app/assets/javascripts/extjs-rails/src/data/writer/Json.js

@@ -0,0 +1,81 @@
+/**
+ * @class Ext.data.writer.Json
+
+This class is used to write {@link Ext.data.Model} data to the server in a JSON format.
+The {@link #allowSingle} configuration can be set to false to force the records to always be
+encoded in an array, even if there is only a single record being sent.
+
+ * @markdown
+ */
+Ext.define('Ext.data.writer.Json', {
+    extend: 'Ext.data.writer.Writer',
+    alternateClassName: 'Ext.data.JsonWriter',
+    alias: 'writer.json',
+    
+    /**
+     * @cfg {String} root The key under which the records in this Writer will be placed. Defaults to <tt>undefined</tt>.
+     * Example generated request, using root: 'records':
+<pre><code>
+{'records': [{name: 'my record'}, {name: 'another record'}]}
+</code></pre>
+     */
+    root: undefined,
+    
+    /**
+     * @cfg {Boolean} encode True to use Ext.encode() on the data before sending. Defaults to <tt>false</tt>.
+     * The encode option should only be set to true when a {@link #root} is defined, because the values will be
+     * sent as part of the request parameters as opposed to a raw post. The root will be the name of the parameter
+     * sent to the server.
+     */
+    encode: false,
+    
+    /**
+     * @cfg {Boolean} allowSingle False to ensure that records are always wrapped in an array, even if there is only
+     * one record being sent. When there is more than one record, they will always be encoded into an array.
+     * Defaults to <tt>true</tt>. Example:
+     * <pre><code>
+// with allowSingle: true
+"root": {
+    "first": "Mark",
+    "last": "Corrigan"
+}
+
+// with allowSingle: false
+"root": [{
+    "first": "Mark",
+    "last": "Corrigan"
+}]
+     * </code></pre>
+     */
+    allowSingle: true,
+    
+    //inherit docs
+    writeRecords: function(request, data) {
+        var root = this.root;
+        
+        if (this.allowSingle && data.length == 1) {
+            // convert to single object format
+            data = data[0];
+        }
+        
+        if (this.encode) {
+            if (root) {
+                // sending as a param, need to encode
+                request.params[root] = Ext.encode(data);
+            } else {
+                //<debug>
+                Ext.Error.raise('Must specify a root when using encode');
+                //</debug>
+            }
+        } else {
+            // send as jsonData
+            request.jsonData = request.jsonData || {};
+            if (root) {
+                request.jsonData[root] = data;
+            } else {
+                request.jsonData = data;
+            }
+        }
+        return request;
+    }
+});