← Back to branch summary

~cdparra/gelee/trunk

« back to all changes in this revision

Viewing changes to webui/ecosystem/extjs/source/data/Api.js

  • Committer: parra
  • Date: 2010-03-15 02:39:02 UTC
  • Revision ID: svn-v4:ac5bba68-f036-4e09-846e-8f32731cc928:trunk/gelee:1433
merged gelee at svn

Show diffs side-by-side

added added

removed removed

Lines of Context:
webui/ecosystem/extjs/source/data/Api.js
 
1
/*
 
2
 * Ext JS Library 3.0 RC2
 
3
 * Copyright(c) 2006-2009, Ext JS, LLC.
 
4
 * licensing@extjs.com
 
5
 * 
 
6
 * http://extjs.com/license
 
7
 */
 
8
 
 
9
/**
 
10
 * @class Ext.data.Api
 
11
 * @extends Object
 
12
 * Ext.data.Api is a singleton designed to manage the data API including methods for validating
 
13
 * a developer's DataProxy API.  Defines variables for CRUD actions create, read, update and destroy in addition to a
 
14
 * mapping of RESTful HTTP methods GET, POST, PUT and DELETE to CRUD actions.
 
15
 * @singleton
 
16
 */
 
17
Ext.data.Api = (function() {
 
18
 
 
19
    // private validActions.  validActions is essentially an inverted hash of Ext.data.Api.actions, where value becomes the key.
 
20
    // Some methods in this singleton (eg: getActions, getVerb) will loop through actions with the code <code>for (var verb in this.actions)</code>
 
21
    // For efficiency, some methods will first check this hash for a match.  Those methods which do acces validActions will cache their result here.
 
22
    // We cannot pre-define this hash since the developer may over-ride the actions at runtime.
 
23
    var validActions = {};
 
24
 
 
25
    return {
 
26
        /**
 
27
         * Defined actions corresponding to remote actions:
 
28
         * <pre><code>
 
29
actions: {
 
30
    create  : 'create',  // Text representing the remote-action to create records on server.
 
31
    read    : 'read',    // Text representing the remote-action to read/load data from server.
 
32
    update  : 'update',  // Text representing the remote-action to update records on server.
 
33
    destroy : 'destroy'  // Text representing the remote-action to destroy records on server.
 
34
}
 
35
         * </code></pre>
 
36
         * @property actions
 
37
         * @type Object
 
38
         */
 
39
        actions : {
 
40
            create  : 'create',
 
41
            read    : 'read',
 
42
            update  : 'update',
 
43
            destroy : 'destroy'
 
44
        },
 
45
 
 
46
        /**
 
47
         * Defined {CRUD action}:{HTTP method} pairs corresponding to remote actions for RESTful proxies.
 
48
         * Defaults to:
 
49
         * <pre><code>
 
50
restActions : {
 
51
    create  : 'POST',
 
52
    read    : 'GET',
 
53
    update  : 'PUT',
 
54
    destroy : 'DELETE'
 
55
},
 
56
         * </code></pre>
 
57
         */
 
58
        restActions : {
 
59
            create  : 'POST',
 
60
            read    : 'GET',
 
61
            update  : 'PUT',
 
62
            destroy : 'DELETE'
 
63
        },
 
64
 
 
65
        /**
 
66
         * Returns true if supplied action-name is a valid API action defined in <code>{@link #actions}</code> constants
 
67
         * @param {String} action
 
68
         * @param {String[]}(Optional) List of available CRUD actions.  Pass in list when executing multiple times for efficiency.
 
69
         * @return {Boolean}
 
70
         */
 
71
        isAction : function(action) {
 
72
            return (Ext.data.Api.actions[action]) ? true : false;
 
73
        },
 
74
 
 
75
        /**
 
76
         * Returns the actual CRUD action KEY "create", "read", "update" or "destroy" from the supplied action-name.  This method is used internally and shouldn't generally
 
77
         * need to be used directly.  The key/value pair of Ext.data.Api.actions will often be identical but this is not necessarily true.  A developer can override this naming
 
78
         * convention if desired.  However, the framework internally calls methods based upon the KEY so a way of retreiving the the words "create", "read", "update" and "destroy" is
 
79
         * required.  This method will cache discovered KEYS into the private validActions hash.
 
80
         * @param {String} name The runtime name of the action.
 
81
         * @return {String||null} returns the action-key, or verb of the user-action or null if invalid.
 
82
         * @nodoc
 
83
         */
 
84
        getVerb : function(name) {
 
85
            if (validActions[name]) {
 
86
                return validActions[name];  // <-- found in cache.  return immediately.
 
87
            }
 
88
            for (var verb in this.actions) {
 
89
                if (this.actions[verb] === name) {
 
90
                    validActions[name] = verb;
 
91
                    break;
 
92
                }
 
93
            }
 
94
            return (validActions[name] !== undefined) ? validActions[name] : null;
 
95
        },
 
96
 
 
97
        /**
 
98
         * Returns true if the supplied API is valid; that is, check that all keys match defined actions
 
99
         * otherwise returns an array of mistakes.
 
100
         * @return {String[]||true}
 
101
         */
 
102
        isValid : function(api){
 
103
            var invalid = [];
 
104
            var crud = this.actions; // <-- cache a copy of the actions.
 
105
            for (var action in api) {
 
106
                if (!(action in crud)) {
 
107
                    invalid.push(action);
 
108
                }
 
109
            }
 
110
            return (!invalid.length) ? true : invalid;
 
111
        },
 
112
 
 
113
        /**
 
114
         * Returns true if the supplied verb upon the supplied proxy points to a unique url in that none of the other api-actions
 
115
         * point to the same url.  The question is important for deciding whether to insert the "xaction" HTTP parameter within an
 
116
         * Ajax request.  This method is used internally and shouldn't generally need to be called directly.
 
117
         * @param {Ext.data.DataProxy} proxy
 
118
         * @param {String} verb
 
119
         * @return {Boolean}
 
120
         */
 
121
        hasUniqueUrl : function(proxy, verb) {
 
122
            var url = (proxy.api[verb]) ? proxy.api[verb].url : null;
 
123
            var unique = true;
 
124
            for (var action in proxy.api) {
 
125
                if ((unique = (action === verb) ? true : (proxy.api[action].url != url) ? true : false) === false) {
 
126
                    break;
 
127
                }
 
128
            }
 
129
            return unique;
 
130
        },
 
131
 
 
132
        /**
 
133
         * This method is used internally by <tt>{@link Ext.data.DataProxy DataProxy}</tt> and should not generally need to be used directly.
 
134
         * Each action of a DataProxy api can be initially defined as either a String or an Object.  When specified as an object,
 
135
         * one can explicitly define the HTTP method (GET|POST) to use for each CRUD action.  This method will prepare the supplied API, setting
 
136
         * each action to the Object form.  If your API-actions do not explicitly define the HTTP method, the "method" configuration-parameter will
 
137
         * be used.  If the method configuration parameter is not specified, POST will be used.
 
138
         <code><pre>
 
139
new Ext.data.HttpProxy({
 
140
    method: "POST",     // <-- default HTTP method when not specified.
 
141
    api: {
 
142
        create: 'create.php',
 
143
        load: 'read.php',
 
144
        save: 'save.php',
 
145
        destroy: 'destroy.php'
 
146
    }
 
147
});
 
148
 
 
149
// Alternatively, one can use the object-form to specify the API
 
150
new Ext.data.HttpProxy({
 
151
    api: {
 
152
        load: {url: 'read.php', method: 'GET'},
 
153
        create: 'create.php',
 
154
        destroy: 'destroy.php',
 
155
        save: 'update.php'
 
156
    }
 
157
});
 
158
        </pre></code>
 
159
         *
 
160
         * @param {Ext.data.DataProxy} proxy
 
161
         */
 
162
        prepare : function(proxy) {
 
163
            if (!proxy.api) {
 
164
                proxy.api = {}; // <-- No api?  create a blank one.
 
165
            }
 
166
            for (var verb in this.actions) {
 
167
                var action = this.actions[verb];
 
168
                proxy.api[action] = proxy.api[action] || proxy.url || proxy.directFn;
 
169
                if (typeof(proxy.api[action]) == 'string') {
 
170
                    proxy.api[action] = {
 
171
                        url: proxy.api[action]
 
172
                    };
 
173
                }
 
174
            }
 
175
        },
 
176
 
 
177
        /**
 
178
         * Prepares a supplied Proxy to be RESTful.  Sets the HTTP method for each api-action to be one of
 
179
         * GET, POST, PUT, DELETE according to the defined {@link #restActions}.
 
180
         * @param {Ext.data.DataProxy} proxy
 
181
         */
 
182
        restify : function(proxy) {
 
183
            proxy.restful = true;
 
184
            for (var verb in this.restActions) {
 
185
                proxy.api[this.actions[verb]].method = this.restActions[verb];
 
186
            }
 
187
        }
 
188
    };
 
189
})();
 
190
 
 
191
 
 
192
/**
 
193
 * Error class for Ext.data.Api errors.
 
194
 */
 
195
Ext.data.Api.Error = Ext.extend(Ext.Error, {
 
196
    constructor : function(message, arg) {
 
197
        this.arg = arg;
 
198
        Ext.Error.call(this, message);
 
199
    },
 
200
    name: 'Ext.data.Api'
 
201
});
 
202
Ext.apply(Ext.data.Api.Error.prototype, {
 
203
    lang: {
 
204
        'action-url-undefined': 'No fallback url defined for this action.  When defining a DataProxy api, please be sure to define an url for each CRUD action in Ext.data.Api.actions or define a default url in addition to your api-configuration.',
 
205
        'invalid': 'received an invalid API-configuration.  Please ensure your proxy API-configuration contains only the actions defined in Ext.data.Api.actions',
 
206
        'invalid-url': 'Invalid url.  Please review your proxy configuration.',
 
207
        'execute': 'Attempted to execute an unknown action.  Valid API actions are defined in Ext.data.Api.actions"'
 
208
    }
 
209
});