Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / guides / data / README.md
1 # Data
2 ______________________________________________
3
4 The data package is what loads and saves all of the data in your application and consists of 41 classes, but there are three that are more important than all the others - {@link Ext.data.Model Model}, {@link Ext.data.Store Store} and {@link Ext.data.proxy.Proxy}. These are used by almost every application, and are supported by a number of satellite classes:
5
6 {@img data-package.png Data package overview}
7
8 ### Models and Stores
9 The centerpiece of the data package is Ext.data.Model. A Model represents some type of data in an application - for example an e-commerce app might have models for Users, Products and Orders. At its simplest a Model is just a set of fields and their data. We’re going to look at four of the principal parts of Model — {@link Ext.data.Field Fields}, {@link Ext.data.proxy.Proxy Proxies}, {@link Ext.data.Association Associations} and {@link Ext.data.validations Validations}.
10
11 {@img model.png Model architecture}
12
13 Let's look at how we create a model now:
14
15     Ext.define('User', {
16         extend: 'Ext.data.Model',
17         fields: [
18             { name: 'id', type: 'int' },
19             { name: 'name', type: 'string' }
20         ]
21     });
22
23 Models are typically used with a Store, which is basically a collection of Model instances. Setting up a Store and loading its data is simple:
24
25     Ext.create('Ext.data.Store', {
26         model: 'User',
27         proxy: {
28             type: 'ajax',
29             url : 'users.json',
30             reader: 'json'
31         },
32         autoLoad: true
33     });
34
35 We configured our Store to use an {@link Ext.data.proxy.Ajax Ajax Proxy}, telling it the url to load data from and the {@link Ext.data.reader.Reader Reader} used to decode the data. In this case our server is returning JSON, so we've set up a {@link Ext.data.reader.Json Json Reader} to read the response.
36 The store auto-loads a set of User model instances from the url `users.json`.  The `users.json` url should return a JSON string that looks something like this:
37
38     {
39         success: true,
40         users: [
41             { id: 1, name: 'Ed' },
42             { id: 2, name: 'Tommy' }
43         ]
44     }
45
46 For a live demo please see the [Simple Store](guides/data/examples/simple_store/index.html) example.
47
48 ### Inline data
49
50 Stores can also load data inline. Internally, Store converts each of the objects we pass in as {@link Ext.data.Store#data data} into {@link Ext.data.Model Model} instances:
51
52     Ext.create('Ext.data.Store', {
53         model: 'User',
54         data: [
55             { firstName: 'Ed',    lastName: 'Spencer' },
56             { firstName: 'Tommy', lastName: 'Maintz' },
57             { firstName: 'Aaron', lastName: 'Conran' },
58             { firstName: 'Jamie', lastName: 'Avins' }
59         ]
60     });
61
62 [Inline Data example](guides/data/examples/inline_data/index.html)
63
64 ### Sorting and Grouping
65
66 Stores are able to perform sorting, filtering and grouping locally, as well as supporting remote sorting, filtering and grouping:
67
68     Ext.create('Ext.data.Store', {
69         model: 'User',
70
71         sorters: ['name', 'id'],
72         filters: {
73             property: 'name',
74             value   : 'Ed'
75         },
76         groupField: 'age',
77         groupDir: 'DESC'
78     });
79
80 In the store we just created, the data will be sorted first by name then id; it will be filtered to only include Users with the name 'Ed' and the data will be grouped by age in descending order. It's easy to change the sorting, filtering and grouping at any time through the Store API.  For a live demo, see the [Sorting Grouping Filtering Store](guides/data/examples/sorting_grouping_filtering_store/index.html) example.
81
82 ### Proxies
83
84 Proxies are used by Stores to handle the loading and saving of Model data. There are two types of Proxy: Client and Server. Examples of client proxies include Memory for storing data in the browser's memory and Local Storage which uses the HTML 5 local storage feature when available. Server proxies handle the marshaling of data to some remote server and examples include Ajax, JsonP and Rest.
85
86 Proxies can be defined directly on a Model like so:
87
88     Ext.define('User', {
89         extend: 'Ext.data.Model',
90         fields: ['id', 'name', 'age', 'gender'],
91         proxy: {
92             type: 'rest',
93             url : 'data/users',
94             reader: {
95                 type: 'json',
96                 root: 'users'
97             }
98         }
99     });
100
101     // Uses the User Model's Proxy
102     Ext.create('Ext.data.Store', {
103         model: 'User'
104     });
105
106 This helps us in two ways. First, it's likely that every Store that uses the User model will need to load its data the same way, so we avoid having to duplicate the Proxy definition for each Store. Second, we can now load and save Model data without a Store:
107
108     // Gives us a reference to the User class
109     var User = Ext.ModelMgr.getModel('User');
110
111     var ed = Ext.create('User', {
112         name: 'Ed Spencer',
113         age : 25
114     });
115
116     // We can save Ed directly without having to add him to a Store first because we
117     // configured a RestProxy this will automatically send a POST request to the url /users
118     ed.save({
119         success: function(ed) {
120             console.log("Saved Ed! His ID is "+ ed.getId());
121         }
122     });
123
124     // Load User 1 and do something with it (performs a GET request to /users/1)
125     User.load(1, {
126         success: function(user) {
127             console.log("Loaded user 1: " + user.get('name'));
128         }
129     });
130
131 There are also Proxies that take advantage of the new capabilities of HTML5 - [LocalStorage](#/api/Ext.data.proxy.LocalStorage) and [SessionStorage](#/api/Ext.data.proxy.SessionStorage). Although older browsers don't support these new HTML5 APIs, they're so useful that a lot of applications will benefit enormously from their presence.
132
133 [Example of a Model that uses a Proxy directly](guides/data/examples/model_with_proxy/index.html)
134
135 ### Associations
136 Models can be linked together with the Associations API. Most applications deal with many different Models, and the Models are almost always related. A blog authoring application might have models for User, Post and Comment. Each User creates Posts and each Post receives Comments. We can express those relationships like so:
137
138     Ext.define('User', {
139         extend: 'Ext.data.Model',
140         fields: ['id', 'name'],
141         proxy: {
142             type: 'rest',
143             url : 'data/users',
144             reader: {
145                 type: 'json',
146                 root: 'users'
147             }
148         },
149
150         hasMany: 'Post' // shorthand for { model: 'Post', name: 'posts' }
151     });
152
153     Ext.define('Post', {
154         extend: 'Ext.data.Model',
155         fields: ['id', 'user_id', 'title', 'body'],
156
157         proxy: {
158             type: 'rest',
159             url : 'data/posts',
160             reader: {
161                 type: 'json',
162                 root: 'posts'
163             }
164         },
165         belongsTo: 'User',
166         hasMany: { model: 'Comment', name: 'comments' }
167     });
168
169     Ext.define('Comment', {
170         extend: 'Ext.data.Model',
171         fields: ['id', 'post_id', 'name', 'message'],
172
173         belongsTo: 'Post'
174     });
175
176 It's easy to express rich relationships between different Models in your application. Each Model can have any number of associations with other Models and your Models can be defined in any order. Once we have a Model instance we can easily traverse the associated data - for example, if we wanted to log all Comments made on each Post for a given User, we can do something like this:
177
178     // Loads User with ID 1 and related posts and comments using User's Proxy
179     User.load(1, {
180         success: function(user) {
181             console.log("User: " + user.get('name'));
182
183             user.posts().each(function(post) {
184                 console.log("Comments for post: " + post.get('title'));
185
186                 post.comments().each(function(comment) {
187                     console.log(comment.get('message'));
188                 });
189             });
190         }
191     });
192
193 Each of the hasMany associations we created above results in a new function being added to the Model. We declared that each User model hasMany Posts, which added the `user.posts()` function we used in the snippet above. Calling `user.posts()` returns a {@link Ext.data.Store Store} configured with the Post model. In turn, the Post model gets a `comments()` function because of the hasMany Comments association we set up.
194
195
196 Associations aren't just helpful for loading data - they're useful for creating new records too:
197
198     user.posts().add({
199         title: 'Ext JS 4.0 MVC Architecture',
200         body: 'It\'s a great Idea to structure your Ext JS Applications using the built in MVC Architecture...'
201     });
202
203     user.posts().sync();
204
205 Here we instantiate a new Post, which is automatically given the User's id in the user_id field. Calling sync() saves the new Post via its configured Proxy - this, again, is an asynchronous operation to which you can pass a callback if you want to be notified when the operation completed.
206
207
208 The belongsTo association also generates new methods on the model, here's how we can use those:
209
210     // get the user reference from the post's belongsTo association
211     post.getUser(function(user) {
212         console.log('Just got the user reference from the post: ' + user.get('name'))
213     });
214
215     // try to change the post's user
216     post.setUser(100, {
217         callback: function(product, operation) {
218             if (operation.wasSuccessful()) {
219                 console.log('Post\'s user was updated');
220             } else {
221                 console.log('Post\'s user could not be updated');
222             }
223         }
224     });
225
226 Once more, the loading function (getUser) is asynchronous and requires a callback function to get at the user instance. The setUser method simply updates the foreign_key (user_id in this case) to 100 and saves the Post model. As usual, callbacks can be passed in that will be triggered when the save operation has completed - whether successful or not.
227
228 ### Loading Nested Data
229
230 You may be wondering why we passed a `success` function to the User.load call but didn't have to do so when accessing the User's posts and comments. This is because the above example assumes that when we make a request to get a user the server returns the user data in addition to all of its nested Posts and Comments. By setting up associations as we did above, the framework can automatically parse out nested data in a single request. Instead of making a request for the User data, another for the Posts data and then yet more requests to load the Comments for each Post, we can return all of the data in a single server response like this:
231
232     {
233         success: true,
234         users: [
235             {
236                 id: 1,
237                 name: 'Ed',
238                 age: 25,
239                 gender: 'male',
240                 posts: [
241                     {
242                         id   : 12,
243                         title: 'All about data in Ext JS 4',
244                         body : 'One areas that has seen the most improvement...',
245                         comments: [
246                             {
247                                 id: 123,
248                                 name: 'S Jobs',
249                                 message: 'One more thing'
250                             }
251                         ]
252                     }
253                 ]
254             }
255         ]
256     }
257
258 The data is all parsed out automatically by the framework. It's easy to configure your Models' Proxies to load data from almost anywhere, and their Readers to handle almost any response format. As with Ext JS 3, Models and Stores are used throughout the framework by many of the components such a Grids, Trees and Forms.
259
260 See the [Associations and Validations](guides/data/examples/associations_validations/index.html) demo for a working example of models that use relationships.
261
262 Of course, it's possible to load your data in a non-nested fashion.  This can be useful if you need to "lazy load" the relational data only when it's needed.  Let's just load the User data like before, except we'll assume the response only includes the User data without any associated Posts. Then we'll add a call to `user.posts().load()` in our callback to get the related Post data:
263
264     // Loads User with ID 1 User's Proxy
265     User.load(1, {
266         success: function(user) {
267             console.log("User: " + user.get('name'));
268
269             // Loads posts for user 1 using Post's Proxy
270             user.posts().load({
271                 callback: function(posts, operation) {
272                     Ext.each(posts, function(post) {
273                         console.log("Comments for post: " + post.get('title'));
274
275                         post.comments().each(function(comment) {
276                             console.log(comment.get('message'));
277                         });
278                     });
279                 }
280             });
281         }
282     });
283
284 For a full example see [Lazy Associations](guides/data/examples/lazy_associations/index.html)
285
286 ### Validations
287
288 As of Ext JS 4 Models became a lot richer with support for validating their data. To demonstrate this we're going to build upon the example we used above for associations. First let's add some validations to the `User` model:
289
290     Ext.define('User', {
291         extend: 'Ext.data.Model',
292         fields: ...,
293
294         validations: [
295             {type: 'presence', name: 'name'},
296             {type: 'length',   name: 'name', min: 5},
297             {type: 'format',   name: 'age', matcher: /\d+/},
298             {type: 'inclusion', name: 'gender', list: ['male', 'female']},
299             {type: 'exclusion', name: 'name', list: ['admin']}
300         ],
301
302         proxy: ...
303     });
304
305 Validations follow the same format as field definitions. In each case, we specify a field and a type of validation. The validations in our example are expecting the name field to be present and to be at least 5 characters in length, the age field to be a number, the gender field to be either "male" or "female", and the username to be anything but "admin". Some validations take additional optional configuration - for example the length validation can take min and max properties, format can take a matcher, etc. There are five validations built into Ext JS and adding custom rules is easy. First, let's meet the ones built right in:
306
307 - `presence` simply ensures that the field has a value. Zero counts as a valid value but empty strings do not.
308 - `length` ensures that a string is between a min and max length. Both constraints are optional.
309 - `format` ensures that a string matches a regular expression format. In the example above we ensure that the age field is 4 numbers followed by at least one letter.
310 - `inclusion` ensures that a value is within a specific set of values (e.g. ensuring gender is either male or female).
311 - `exclusion` ensures that a value is not one of the specific set of values (e.g. blacklisting usernames like 'admin').
312
313 Now that we have a grasp of what the different validations do, let's try using them against a User instance. We'll create a user and run the validations against it, noting any failures:
314
315     // now lets try to create a new user with as many validation errors as we can
316     var newUser = Ext.create('User', {
317         name: 'admin',
318         age: 'twenty-nine',
319         gender: 'not a valid gender'
320     });
321
322     // run some validation on the new user we just created
323     var errors = newUser.validate();
324
325     console.log('Is User valid?', errors.isValid()); //returns 'false' as there were validation errors
326     console.log('All Errors:', errors.items); //returns the array of all errors found on this model instance
327
328     console.log('Age Errors:', errors.getByField('age')); //returns the errors for the age field
329
330 The key function here is validate(), which runs all of the configured validations and returns an [Errors](#/api/Ext.data.Errors) object. This simple object is just a collection of any errors that were found, plus some convenience methods such as `isValid()` - which returns true if there were no errors on any field - and `getByField()`, which returns all errors for a given field.
331
332 For a complete example that uses validations please see [Associations and Validations](guides/data/examples/associations_validations/index.html)
333