add extjs 6.0.1 sources

[extjs.git] / extjs / packages / core / src / data / reader / Json.js

/**\r
 * The JSON Reader is used by a Proxy to read a server response that is sent back in JSON format. This usually\r
 * happens as a result of loading a Store - for example we might create something like this:\r
 *\r
 *     Ext.define('User', {\r
 *         extend: 'Ext.data.Model',\r
 *         fields: ['id', 'name', 'email']\r
 *     });\r
 *\r
 *     var store = Ext.create('Ext.data.Store', {\r
 *         model: 'User',\r
 *         proxy: {\r
 *             type: 'ajax',\r
 *             url : 'users.json',\r
 *             reader: {\r
 *                 type: 'json'\r
 *             }\r
 *         }\r
 *     });\r
 *\r
 * The example above creates a 'User' model. Models are explained in the {@link Ext.data.Model Model} docs if you're\r
 * not already familiar with them.\r
 *\r
 * We created the simplest type of JSON Reader possible by simply telling our {@link Ext.data.Store Store}'s\r
 * {@link Ext.data.proxy.Proxy Proxy} that we want a JSON Reader. The Store automatically passes the configured model to the\r
 * Store, so it is as if we passed this instead:\r
 *\r
 *     reader: {\r
 *         type : 'json',\r
 *         model: 'User'\r
 *     }\r
 *\r
 * The reader we set up is ready to read data from our server - at the moment it will accept a response like this:\r
 *\r
 *     [\r
 *         {\r
 *             "id": 1,\r
 *             "name": "Ed Spencer",\r
 *             "email": "ed@sencha.com"\r
 *         },\r
 *         {\r
 *             "id": 2,\r
 *             "name": "Abe Elias",\r
 *             "email": "abe@sencha.com"\r
 *         }\r
 *     ]\r
 *\r
 * ## Reading other JSON formats\r
 *\r
 * If you already have your JSON format defined and it doesn't look quite like what we have above, you can usually\r
 * pass JsonReader a couple of configuration options to make it parse your format. For example, we can use the\r
 * {@link #cfg-rootProperty} configuration to parse data that comes back like this:\r
 *\r
 *     {\r
 *         "users": [\r
 *            {\r
 *                "id": 1,\r
 *                "name": "Ed Spencer",\r
 *                "email": "ed@sencha.com"\r
 *            },\r
 *            {\r
 *                "id": 2,\r
 *                "name": "Abe Elias",\r
 *                "email": "abe@sencha.com"\r
 *            }\r
 *         ]\r
 *     }\r
 *\r
 * To parse this we just pass in a {@link #rootProperty} configuration that matches the 'users' above:\r
 *\r
 *     reader: {\r
 *         type: 'json',\r
 *         rootProperty: 'users'\r
 *     }\r
 *\r
 * Sometimes the JSON structure is even more complicated. Document databases like CouchDB often provide metadata\r
 * around each record inside a nested structure like this:\r
 *\r
 *     {\r
 *         "total": 122,\r
 *         "offset": 0,\r
 *         "users": [\r
 *             {\r
 *                 "id": "ed-spencer-1",\r
 *                 "value": 1,\r
 *                 "user": {\r
 *                     "id": 1,\r
 *                     "name": "Ed Spencer",\r
 *                     "email": "ed@sencha.com"\r
 *                 }\r
 *             }\r
 *         ]\r
 *     }\r
 *\r
 * In the case above the record data is nested an additional level inside the "users" array as each "user" item has\r
 * additional metadata surrounding it ('id' and 'value' in this case). To parse data out of each "user" item in the\r
 * JSON above we need to specify the {@link #record} configuration like this:\r
 *\r
 *     reader: {\r
 *         type  : 'json',\r
 *         rootProperty  : 'users',\r
 *         record: 'user'\r
 *     }\r
 *\r
 * ## Response MetaData\r
 *\r
 * The server can return metadata in its response, in addition to the record data, that describe attributes\r
 * of the data set itself or are used to reconfigure the Reader. To pass metadata in the response you simply\r
 * add a `metaData` attribute to the root of the response data. The metaData attribute can contain anything,\r
 * but supports a specific set of properties that are handled by the Reader if they are present:\r
 * \r
 * - {@link #rootProperty}: the property name of the root response node containing the record data\r
 * - {@link #totalProperty}: property name for the total number of records in the data\r
 * - {@link #successProperty}: property name for the success status of the response\r
 * - {@link #messageProperty}: property name for an optional response message\r
 * - {@link Ext.data.Model#cfg-fields fields}: Config used to reconfigure the Model's fields before converting the\r
 * response data into records\r
 * \r
 * An initial Reader configuration containing all of these properties might look like this ("fields" would be\r
 * included in the Model definition, not shown):\r
 *\r
 *     reader: {\r
 *         type : 'json',\r
 *         rootProperty : 'root',\r
 *         totalProperty  : 'total',\r
 *         successProperty: 'success',\r
 *         messageProperty: 'message'\r
 *     }\r
 *\r
 * If you were to pass a response object containing attributes different from those initially defined above, you could\r
 * use the `metaData` attribute to reconfigure the Reader on the fly. For example:\r
 *\r
 *     {\r
 *         "count": 1,\r
 *         "ok": true,\r
 *         "msg": "Users found",\r
 *         "users": [{\r
 *             "userId": 123,\r
 *             "name": "Ed Spencer",\r
 *             "email": "ed@sencha.com"\r
 *         }],\r
 *         "metaData": {\r
 *             "rootProperty": "users",\r
 *             "totalProperty": 'count',\r
 *             "successProperty": 'ok',\r
 *             "messageProperty": 'msg'\r
 *         }\r
 *     }\r
 *\r
 * You can also place any other arbitrary data you need into the `metaData` attribute which will be ignored by the Reader,\r
 * but will be accessible via the Reader's {@link #metaData} property (which is also passed to listeners via the Proxy's\r
 * {@link Ext.data.proxy.Proxy#metachange metachange} event (also relayed by the store). Application code can then\r
 * process the passed metadata in any way it chooses.\r
 * \r
 * A simple example for how this can be used would be customizing the fields for a Model that is bound to a grid. By passing\r
 * the `fields` property the Model will be automatically updated by the Reader internally, but that change will not be\r
 * reflected automatically in the grid unless you also update the column configuration. You could do this manually, or you\r
 * could simply pass a standard grid {@link Ext.panel.Table#columns column} config object as part of the `metaData` attribute\r
 * and then pass that along to the grid. Here's a very simple example for how that could be accomplished:\r
 *\r
 *     // response format:\r
 *     {\r
 *         ...\r
 *         "metaData": {\r
 *             "fields": [\r
 *                 { "name": "userId", "type": "int" },\r
 *                 { "name": "name", "type": "string" },\r
 *                 { "name": "birthday", "type": "date", "dateFormat": "Y-j-m" },\r
 *             ],\r
 *             "columns": [\r
 *                 { "text": "User ID", "dataIndex": "userId", "width": 40 },\r
 *                 { "text": "User Name", "dataIndex": "name", "flex": 1 },\r
 *                 { "text": "Birthday", "dataIndex": "birthday", "flex": 1, "format": 'Y-j-m', "xtype": "datecolumn" }\r
 *             ]\r
 *         }\r
 *     }\r
 *\r
 * The Reader will automatically read the meta fields config and rebuild the Model based on the new fields, but to handle\r
 * the new column configuration you would need to handle the metadata within the application code. This is done simply enough\r
 * by handling the metachange event on either the store or the proxy, e.g.:\r
 *\r
 *     var store = Ext.create('Ext.data.Store', {\r
 *         ...\r
 *         listeners: {\r
 *             'metachange': function(store, meta) {\r
 *                 myGrid.reconfigure(store, meta.columns);\r
 *             }\r
 *         }\r
 *     });\r
 *\r
 */\r
Ext.define('Ext.data.reader.Json', {\r
    extend: 'Ext.data.reader.Reader',\r
    \r
    requires: [\r
        'Ext.JSON'\r
    ],\r
    \r
    alternateClassName: 'Ext.data.JsonReader',\r
    alias : 'reader.json',\r
\r
    config: {\r
        /**\r
        * @cfg {String} record The optional location within the JSON response that the record data itself can be found at.\r
        * See the JsonReader intro docs for more details. This is not often needed.\r
        */\r
       record: null,\r
    \r
        /**\r
        * @cfg {String} [metaProperty]\r
        * Name of the property from which to retrieve the `metaData` attribute. See {@link #metaData}.\r
        */\r
        metaProperty: 'metaData',\r
\r
        /**\r
        * @cfg {Boolean} useSimpleAccessors True to ensure that field names/mappings are treated as literals when\r
        * reading values.\r
        *\r
        * For example, by default, using the mapping "foo.bar.baz" will try and read a property foo from the root, then a property bar\r
        * from foo, then a property baz from bar. Setting the simple accessors to true will read the property with the name\r
        * "foo.bar.baz" direct from the root object.\r
        */\r
        useSimpleAccessors: false,\r
        \r
        /**\r
         * @cfg {Boolean} preserveRawData\r
         * The reader will keep a copy of the most recent request in the {@link #rawData} property. For performance reasons,\r
         * the data object for each record is used directly as the model data. This means that these objects may be modified and\r
         * thus modify the raw data. To ensure the objects are copied, set this option to `true`. NB: This only applies to items \r
         * that are read as part of the data array, any other metadata will not be modified:\r
         * \r
         *     {\r
         *         "someOtherData": 1, // Won't be modified\r
         *         "root": [{}, {}, {}] // The objects here will be modified\r
         *     }\r
         */\r
        preserveRawData: false\r
    },\r
    \r
    updateRootProperty: function() {\r
        this.forceBuildExtractors();    \r
    },\r
    \r
    updateMetaProperty: function() {\r
        this.forceBuildExtractors();\r
    },\r
\r
    /**\r
     * Reads a JSON object and returns a ResultSet. Uses the internal getTotal and getSuccess extractors to\r
     * retrieve meta data from the response, and extractData to turn the JSON data into model instances.\r
     * @param {Object} data The raw JSON data\r
     * @param {Object} [readOptions] See {@link #read} for details.\r
     * @return {Ext.data.ResultSet} A ResultSet containing model instances and meta data about the results\r
     */\r
    readRecords: function(data, readOptions, /* private */ internalReadOptions) {\r
        var me = this,\r
            meta;\r
            \r
        //this has to be before the call to super because we use the meta data in the superclass readRecords\r
        if (me.getMeta) {\r
            meta = me.getMeta(data);\r
            if (meta) {\r
                me.onMetaChange(meta);\r
            }\r
        } else if (data.metaData) {\r
            me.onMetaChange(data.metaData);\r
        }\r
\r
        return me.callParent([data, readOptions, internalReadOptions]);\r
    },\r
\r
    getResponseData: function(response) {\r
        var error;\r
\r
        try {\r
            return Ext.decode(response.responseText);\r
        } catch (ex) {\r
            error = this.createReadError(ex.message);\r
\r
            Ext.Logger.warn('Unable to parse the JSON returned by the server');\r
            this.fireEvent('exception', this, response, error);\r
            return error;\r
        }\r
    },\r
\r
    buildExtractors : function() {\r
        var me = this,\r
            metaProp, rootProp;\r
\r
        // Will only return true if we need to build\r
        if (me.callParent(arguments)) {\r
            metaProp = me.getMetaProperty();\r
            rootProp = me.getRootProperty();\r
            if (rootProp) {\r
                me.getRoot = me.getAccessor(rootProp);\r
            } else {\r
                me.getRoot = Ext.identityFn;\r
            }\r
        \r
            if (metaProp) {\r
                me.getMeta = me.getAccessor(metaProp);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     * We're just preparing the data for the superclass by pulling out the record objects we want. If a {@link #record}\r
     * was specified we have to pull those out of the larger JSON object, which is most of what this function is doing\r
     * @param {Object} root The JSON root node\r
     * @param {Object} [readOptions] See {@link #read} for details.\r
     * @return {Ext.data.Model[]} The records\r
     */\r
    extractData: function(root, readOptions) {\r
        var recordName = this.getRecord(),\r
            data = [],\r
            length, i;\r
\r
        if (recordName) {\r
            length = root.length;\r
            \r
            if (!length && Ext.isObject(root)) {\r
                length = 1;\r
                root = [root];\r
            }\r
\r
            for (i = 0; i < length; i++) {\r
                data[i] = root[i][recordName];\r
            }\r
        } else {\r
            data = root;\r
        }\r
        return this.callParent([data, readOptions]);\r
    },\r
    \r
    getModelData: function(raw) {\r
        return this.getPreserveRawData() ? Ext.apply({}, raw) : raw;    \r
    },\r
\r
    /**\r
     * @private\r
     * @method\r
     * Returns an accessor function for the given property string. Gives support for properties such as the following:\r
     *\r
     * - 'someProperty'\r
     * - 'some.property'\r
     * - '["someProperty"]'\r
     * - 'values[0]'\r
     * \r
     * This is used by {@link #buildExtractors} to create optimized extractor functions for properties that are looked\r
     * up directly on the source object (e.g. {@link #successProperty}, {@link #messageProperty}, etc.).\r
     */\r
    createAccessor: (function() {\r
        var re = /[\[\.]/;\r
\r
        return function(expr) {\r
            var me = this,\r
                simple = me.getUseSimpleAccessors(),\r
                operatorIndex, result,\r
                current, parts, part, inExpr,\r
                isDot, isLeft, isRight,\r
                special, c, i, bracketed, len;\r
\r
            if (!(expr || expr === 0)) {\r
                return;\r
            }\r
\r
            if (typeof expr === 'function') {\r
                return expr;\r
            }\r
            \r
            if (!simple) {\r
                operatorIndex = String(expr).search(re);\r
            }\r
            \r
            if (simple === true || operatorIndex < 0) {\r
                result = function(raw) {\r
                    return raw[expr];\r
                };\r
            } else {\r
                // The purpose of this part is to generate a "safe" accessor for any complex \r
                // json expression. For example 'foo.bar.baz' will get transformed:\r
                // raw.foo && raw.foo.bar && raw.foo.bar.baz\r
                current = 'raw';\r
                parts = [];\r
                part = '';\r
                inExpr = 0;\r
                len = expr.length;\r
\r
                // The <= is intentional here. We handle the last character\r
                // being undefined so that we can append any final values at\r
                // the end\r
                for (i = 0; i <= len; ++i) {\r
                    c = expr[i];\r
\r
                    isDot = c === '.';\r
                    isLeft = c === '[';\r
                    isRight = c === ']';\r
\r
                    special = isDot || isLeft || isRight || !c;\r
                    // If either:\r
                    // a) Not a special char\r
                    // b) We're nested more than 1 deep, no single char can bring us out\r
                    // c) We are in an expr & it's not an ending brace\r
                    // Then just push the character on\r
                    if (!special || inExpr > 1 || (inExpr && !isRight)) {\r
                        part += c;\r
                    } else if (special) {\r
                        bracketed = false;\r
                        if (isLeft) {\r
                            ++inExpr;\r
                        } else if (isRight) {\r
                            --inExpr;\r
                            bracketed = true;\r
                        }\r
\r
                        if (part) {\r
                            if (bracketed) {\r
                                part = '[' + part + ']';\r
                            } else {\r
                                part = '.' + part;\r
                            }\r
                            current += part;\r
                            // Concatting the empty string to the start fixes a very odd intermittent bug with IE9/10.\r
                            // On some occasions, without it, it will end up generating\r
                            // raw.foo.bar.baz && raw.foo.bar.baz && raw.foo.bar.baz\r
                            // At this point, not really sure why forcibly casting it to a string makes a difference\r
                            parts.push('' + current);\r
                            part = '';\r
                        }\r
                    }\r
                }\r
                result = parts.join(' && ');\r
                result = Ext.functionFactory('raw', 'return ' + result);\r
            }\r
            return result;\r
        };\r
    }()),\r
\r
    /**\r
     * @private\r
     * @method\r
     * Returns an accessor function for the passed Field. Gives support for properties such as the following:\r
     * \r
     * - 'someProperty'\r
     * - 'some.property'\r
     * - '["someProperty"]'\r
     * - 'values[0]'\r
     * \r
     * This is used by {@link #buildExtractors} to create optimized extractor expressions when converting raw\r
     * data into model instances. This method is used at the field level to dynamically map values to model fields.\r
     */\r
    createFieldAccessor: function(field) {\r
        // Need to capture me for the extractor\r
        var me = this,\r
            mapping = field.mapping,\r
            hasMap = mapping || mapping === 0,\r
            map    = hasMap ? mapping : field.name;\r
            \r
        if (hasMap) {\r
            if (typeof map === 'function') {\r
                return function(raw) {\r
                    return field.mapping(raw, me);\r
                };\r
            } else {\r
                return me.createAccessor(map);\r
            }    \r
        }\r
    },\r
\r
    getAccessorKey: function(prop) {\r
        var simple = this.getUseSimpleAccessors() ? 'simple' : '';\r
        return this.$className + simple + prop;\r
    },\r
\r
    privates: {\r
        copyFrom: function(reader) {\r
            this.callParent([reader]);\r
            this.getRoot = reader.getRoot;\r
        }\r
    }\r
});\r