add extjs 6.0.1 sources

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

/**\r
 * This class is used to write {@link Ext.data.Model} data to the server in a JSON format.\r
 * The {@link #allowSingle} configuration can be set to false to force the records to always\r
 * be encoded in an array, even if there is only a single record being sent.\r
 */\r
Ext.define('Ext.data.writer.Json', {\r
    extend: 'Ext.data.writer.Writer',\r
    alternateClassName: 'Ext.data.JsonWriter',\r
    alias: 'writer.json',\r
    \r
    config: {\r
        /**\r
        * @cfg {String} rootProperty The HTTP parameter name by which JSON encoded records will be passed to the server if the\r
        * {@link #encode} option is `true`.\r
        */\r
        rootProperty: undefined,\r
    \r
        /**\r
        * @cfg {Boolean} [encode=false] Configure `true` to send record data (all record fields if {@link #writeAllFields} is `true`)\r
        * as a JSON encoded HTTP parameter named by the {@link #rootProperty} configuration.\r
        * \r
        * The encode option should only be set to true when a {@link #rootProperty} is defined, because the values will be\r
        * sent as part of the request parameters as opposed to a raw post. The root will be the name of the parameter\r
        * sent to the server.\r
        */\r
        encode: false,\r
    \r
        /**\r
        * @cfg {Boolean} [allowSingle=true] Configure with `false` to ensure that records are always wrapped in an array, even if there is only\r
        * one record being sent. When there is more than one record, they will always be encoded into an array.\r
        */\r
        allowSingle: true,\r
    \r
        /**\r
        * @cfg {Boolean} [expandData=false] By default, when dot-delimited field {@link #nameProperty mappings} are\r
        * used (e.g. `name: 'myProperty', mapping: 'my.nested.property'`) the writer will simply output a flat data\r
        * object containing the mapping string literal as the property name (e.g. `{ 'my.nested.property': 'foo' }`).\r
        * \r
        * Mappings are used to map incoming nested JSON to flat Ext models. In many case, the data output by the\r
        * writer should preferrably match the original nested data format. Setting this config to `true` will ensure\r
        * that the output will instead look like `{ my: { nested: { property: 'foo' }}}`. The output is generated\r
        * by {@link #getExpandedData}, which can optionally be overridden to apply more customized logic.\r
        */\r
        expandData: false\r
    },\r
    \r
    //<debug>\r
    constructor: function(config) {\r
        if (config && config.hasOwnProperty('root')) {\r
            config = Ext.apply({}, config);\r
            config.rootProperty = config.root;\r
            delete config.root;\r
            Ext.log.warn('Ext.data.writer.Json: Using the deprecated "root" configuration. Use "rootProperty" instead.');\r
        }\r
        this.callParent([config]);\r
    },\r
    //</debug>\r
    \r
    /**\r
     * @protected\r
     * The Reader classes support dot-delimited data mappings for extracting nested raw data into fields, so the\r
     * writer must support converting the flat {@link Ext.data.Model} structure back into the original nested data\r
     * format. Using the same mappings when available, the Writer will simply split each delimiter into a nested\r
     * object in the output, which should exactly match the input format. For example, record data like this:\r
     * \r
     *     my.nested.property: 'foo',\r
     *     my.nested.another: 'bar',\r
     *     my.somethingElse: 123\r
     * \r
     * should write out as...\r
     * \r
     *     my: {\r
     *         nested: {\r
     *             property: 'foo',\r
     *             another: 'bar\r
     *         },\r
     *         somethingElse: 123\r
     *     }\r
     *\r
     * This behavior is governed by the {@link #expandData} config. By default, this option is `false` for\r
     * compatibility reasons, and will output a flat structure matching the flat record format. Setting this config\r
     * to `true` will enable the expanded mapping behavior as shown here. This method could also be overridden\r
     * to provide an even more customized output data structure.\r
     */\r
    getExpandedData: function(data) {\r
        var dataLength = data.length,\r
            i = 0,\r
            item,\r
            prop,\r
            nameParts,\r
            j,\r
            tempObj,\r
            \r
            toObject = function(name, value) {\r
                var o = {};\r
                o[name] = value;\r
                return o;\r
            };\r
        \r
        for (; i < dataLength; i++) {\r
            item = data[i];\r
            \r
            for (prop in item) {\r
                if (item.hasOwnProperty(prop)) {\r
                    // e.g. my.nested.property: 'foo'\r
                    nameParts = prop.split('.');\r
                    j = nameParts.length - 1;\r
                    \r
                    if (j > 0) {\r
                        // Initially this will be the value 'foo'.\r
                        // Equivalent to rec['my.nested.property']\r
                        tempObj = item[prop];\r
                        \r
                        for (; j > 0; j--) {\r
                            // Starting with the value above, we loop inside out, assigning the\r
                            // current object as the value for the parent name. Work all\r
                            // the way up until only the root name is left to assign.\r
                            tempObj = toObject(nameParts[j], tempObj);\r
                        }\r
                        \r
                        // At this point we'll have all child properties rolled up into a single\r
                        // object like `{ nested: { property: 'foo' }}`. Now add the root name\r
                        // (e.g. 'my') to the record data if needed (do not overwrite existing):\r
                        item[nameParts[0]] = item[nameParts[0]] || {};\r
                        // Since there could be duplicate names at any level of the nesting be sure\r
                        // to merge rather than assign when setting the object as the value:\r
                        Ext.Object.merge(item[nameParts[0]], tempObj);\r
                        // Finally delete the original mapped property from the record\r
                        delete item[prop];\r
                    }\r
                }\r
            }\r
        }\r
        return data;\r
    },\r
    \r
    writeRecords: function(request, data) {\r
        var me = this,\r
            root = me.getRootProperty(),\r
            json, single, transform;\r
        \r
        if (me.getExpandData()) {\r
            data = me.getExpandedData(data);\r
        }\r
        \r
        if (me.getAllowSingle() && data.length === 1) {\r
            // convert to single object format\r
            data = data[0];\r
            single = true;\r
        }\r
        \r
        transform = this.getTransform();\r
        if (transform) {\r
            data = transform(data, request);\r
        }\r
        \r
        if (me.getEncode()) {\r
            if (root) {\r
                // sending as a param, need to encode\r
                request.setParam(root, Ext.encode(data));\r
            } else {\r
                //<debug>\r
                Ext.raise('Must specify a root when using encode');\r
                //</debug>\r
            }\r
        } else if (single || (data && data.length)) {\r
            // send as jsonData\r
            json = request.getJsonData() || {};\r
            if (root) {\r
                json[root] = data;\r
            } else {\r
                json = data;\r
            }\r
            request.setJsonData(json);\r
        }\r
        return request;\r
    }\r
});\r