You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
It's recommended to put models inside factories, this is usefull later when defining relations and inheritance, since the angular $injector is used by these features. It's also the angular way of doing things. This guide will skip the factory code in examples for simplicity sake.
17
17
18
-
The first and only required parameter is the base url for the model, if null is given then the model is considered unbound.
18
+
The first and only required parameter is the base url for the model, if null is given then the model is considered nested.
19
19
20
-
Unbound models can only be fetched/created/updated when bound to other models (via a relation).
20
+
Nested models can only be fetched/created/updated when bound to other models (using a relation).
21
21
22
22
Refer to {@tutorial model} for information about how to use the generated model.
23
23
24
24
## Advanced model building
25
25
26
-
Restmod offers two ways of customizing a model's behaviour, **definition blocks** and **definition objects**, both are used by passing the required parameters to the `model` function after the base url parameter.
26
+
Restmod offers two ways of customizing a model's behaviour, **definition blocks** and **definition objects**, both are used by passing the required parameters to the `Model.mix` static method.
27
27
28
28
### Model definition blocks
29
29
30
30
If a function is given to `model`, then the function is called in the builder context (`this` points to the builder).
31
31
32
32
```javascript
33
-
$restmod.model('/model-base-url', function() {
34
-
this.attrMask('createdBy', SyncMask.DECODE) // Set an attribute mask
33
+
restmod.model('/model-base-url').mix(function() {
34
+
this.attrMask('createdBy', 'R') // Set an attribute mask
35
35
.attrDefault('createdBy', 'This is read only') // Set an attribute default value
36
-
.beforeSave(function() { // Set a model hook
36
+
.on('before-save', function() { // Set a model hook
37
37
alert('model will be saved!')
38
38
});
39
39
});
40
40
```
41
41
42
-
Even though the preferred way of customizing a model is using the definition object, some builder methods like `beforeCreate`can only be accesed through the builder context.
42
+
Even though the preferred way of customizing a model is using the definition object, some builder methods like `extend`can only be accesed through the builder context.
43
43
44
-
For more information about available builder functions check *The Builder DSL* section below and the ModelBuilder class documentation.
44
+
For more information about available builder functions check the ModelBuilder class documentation.
45
45
46
46
### The model definition object
47
47
@@ -50,229 +50,59 @@ It is also posible to provide an plain object to the `model` method. This object
50
50
A model assigns one or more modifiers to model instance properties.
51
51
52
52
```javascript
53
-
$restmod.model('api/bikes', {
53
+
restmod.model('api/bikes').mix({
54
54
created_at: { serialize:'RailsDate' }, // set a serializer
55
-
createdBy: { init:'This is readonly', mask:SyncMask.DECODE }, // set a default value and a mask
55
+
createdBy: { init:'This is readonly', mask:'R' }, // set a default value and a mask
56
56
parts: { hasMany:'Part' } // set a relation with another model built by a factory called 'Part'
57
57
});
58
58
```
59
59
60
60
Property modifiers map directly to builder DSL functions, so using
61
61
62
62
```javascript
63
-
$restmod.model('', {
63
+
restmod.model('').mix({
64
64
prop: { init:20 }
65
65
});
66
66
```
67
67
68
68
Is equivalent to
69
69
70
70
```javascript
71
-
$restmod.model('', function() {
71
+
restmod.model('').mix(function() {
72
72
this.attrDefault('prop', 20);
73
73
}
74
74
```
75
75
76
-
For more information about available property modifiers check the {@link ModelBuilder} class documentation.
76
+
For more information about available property modifiers check the {@link BuilderApi} documentation.
77
77
78
78
Some plugins also add additional modifiers.
79
79
80
80
Property modifiers map directly to builder DSL methods, but not every builder method is available as a property behavior modifier. The model definition object only provides a subset of the available builder DSL methods.
81
81
82
82
### The mixin chain
83
83
84
-
You are not restricted to use only one building method, multiple object and function blocks can be passed to the `model` function and are processed sequentially by the model builder. This is called the mixin chain.
84
+
You are not restricted to use only one building method, multiple object and function blocks can be passed to the `mix` function and are processed sequentially by the builder. This is called the mixin chain.
85
85
86
86
In addition to definition objects and functions, the mixin chain also allows for model or mixin names, if a name is given, the model/mixin is looked up using the injector and its mixin chain is injected in the current chain.
87
87
88
88
```javascript
89
89
// Example using multiple mixins
90
-
$restmod.model('api/bikes',
91
-
'Vehicle', // inject Vehicle mixin chain first
90
+
restmod.model('api/bikes').mix('Vehicle', // inject Vehicle mixin chain first
92
91
// Then a model definition object
93
92
{
94
93
brakes: { serialize:'Brakes' },
95
94
},
96
95
// Finally a model definition block
97
96
function() {
98
-
this.beforeCreate(function() {
97
+
this.on('before-create', function() {
99
98
100
99
});
101
100
})
102
101
```
103
102
104
103
#### The global mixin chain
105
104
106
-
It is also posible to define a common mixin chain for all models in the application, this is done using the `pushModelBase` method available at the $restmodProvider provider in the configuration stage.
107
-
108
-
## The builder DSL
109
-
110
-
### Defaults
111
-
112
-
A default value can be given to any model property, this is done via de `init` property modifier. Check the {@link ModelBuilder#attrDefault} docs for more information.
113
-
114
-
```javascript
115
-
var Model =$restmod.model(null, {
116
-
owner: { init:'anonymous' }
117
-
};
118
-
```
119
-
120
-
If a function is provided then it will be evaluated every time a model instance is created and its return value assigned to the property.
121
-
122
-
### Property transformation
123
-
124
-
It is posible to specify how a given property is serialized or deserialized using the `encode` or `decode` property modifiers respectively. This modifiers take a filter name or a function and applies it to the property value during transformation. Check the {@link ModelBuilder#attrDecoder} and {@link ModelBuilder#attrEncoder} docs for more information.
125
-
126
-
```javascript
127
-
var Model =$restmod.model(null, {
128
-
createdAt: { encode:'date', param:'yyyy-MM-dd' }, // use the angular date filter to serialize
129
-
sku: { decode:function(v) { returnv.replace(/[^\d]+/,''); } } // use an inline function to deserialize
130
-
});
131
-
```
132
-
133
-
Another way of specifying how a property is serialized is using a serializer. A serializer is an object that defines al least a decode or an encode method (or both). The methods are called with the property value and are expected to return a new value. The `serialize` modifier can be used to define a Serializer, if a *string* is given then the angular injector is used to load the required serializer by appending 'Serializer' to the given string. Check the {@link ModelBuilder#attrSerializer} docs for more information.
134
-
135
-
```javascript
136
-
var Model =$restmod.model(null, {
137
-
createdAt: { serialize:'date' }, // will search for a 'DateSerializer' in the current injector.
Masks can be used to prevent certain properties to be sent to or loaded from the server. They specify a set actions a property is masked from. Available mask values are enumerated in the {@link SyncMask} constant and can be combined using bit operations.
151
-
152
-
Masks can be specified using the `mask` or `ignore` property modifiers. Check the {@link ModelBuilder#attrMask} docs for more information.
153
-
154
-
```javascript
155
-
var Model =$restmod.model(null, {
156
-
viewed: { mask:true }, // the property value is never sent to or loaded from the server.
157
-
createdAt: { mask:SyncMask.ENCODE }, // this property value is never sent to the server (but it is loaded from)
158
-
createdBy: { mask:SyncMask.ENCODE_UPDATE } // this property value is not sent to the server during an update
159
-
});
160
-
```
161
-
162
-
### Defining relations
163
-
164
-
Relations can be specified between models using the `hasMany` and `hasOne` modifiers. Check the {@link ModelBuilder#hasMany} and {@link ModelBuilder#hasOne} docs for more information.
165
-
166
-
```javascript
167
-
angular.module('test')
168
-
.factory('Part', function($restmod) {
169
-
return$restmod.model(null);
170
-
})
171
-
.factory('Bike', function($restmod) {
172
-
return$restmode.model('/bikes', {
173
-
parts: { hasMany:'Part' }
174
-
});
175
-
});
176
-
```
177
-
178
-
More about relations in the {@tutorial model} guide.
179
-
180
-
### Hooks
181
-
182
-
A model behavior can be modified using a wide range of hooks provided by restmod. The hooks are placed on model's lifecycle key points and can be used to modify/extend the model behavior.
183
-
184
-
```javascript
185
-
var Model =$restmod.model(null, function() {
186
-
// make a property undefined after every save.
187
-
this.on('after-save', function() {
188
-
deletethis.sendOnce;
189
-
});
190
-
};
191
-
```
192
-
193
-
Notes:
194
-
* The before-request hooks can be used to modify the request before is sent.
195
-
* The after-request[-error] hooks can be used to modify the request before processed by model.
196
-
* The model builder provides a set of shorthand methods to subscribe to the most common hooks
197
-
198
-
Additional hooks can be called by user defined methods using the `$callback` method
199
-
200
-
#### Object lifecycle hooks
201
-
202
-
For `$fetch`:
203
-
204
-
* before-fetch
205
-
* before-request
206
-
* after-request[-error]
207
-
* after-feed (only called if no errors)
208
-
* after-fetch[-error]
209
-
210
-
For `$fetch` on a collection:
211
-
212
-
* before-fetch-many
213
-
* before-request
214
-
* after-request[-error]
215
-
* after-feed (only called if no errors)
216
-
* after-fetch-many[-error]
217
-
218
-
For `$save` when creating:
219
-
220
-
* before-render
221
-
* before-save
222
-
* before-create
223
-
* before-request
224
-
* after-request[-error]
225
-
* after-feed (only called if no errors)
226
-
* after-create[-error]
227
-
* after-save[-error]
228
-
229
-
For `$save` when updating:
230
-
231
-
* before-render
232
-
* before-save
233
-
* before-update
234
-
* before-request
235
-
* after-request[-error]
236
-
* after-feed (only called if no errors)
237
-
* after-update[-error]
238
-
* after-save[-error]
239
-
240
-
For `$destroy`:
241
-
242
-
* before-destroy
243
-
* before-request
244
-
* after-request[-error]
245
-
* after-destroy[-error]
246
-
247
-
### Adding new methods and actions
248
-
249
-
Methods can be added or overriden both in model instances and model collections using the builder {@link ModelBuilder#define} and the {@link ModelBuilder#classDefine} respectively. Methods that override another method through these functions will have access to the this.$super property that points to the old method (prebound, so its not necessary to call this.$super.call).
250
-
251
-
```javascript
252
-
$restmod.model(null, function() {
253
-
// add the $create method to model instances
254
-
this.define('$create', function() {
255
-
this.id=undefined;
256
-
returnthis.$save();
257
-
});
258
-
259
-
// override model collection's $fetch method
260
-
this.classDefine('$fetch', function() {
261
-
this.$super({ forceParam:'This parameter will be included in all fetch requests' });
262
-
});
263
-
});
264
-
```
265
-
266
-
It is also posible to add or override a model **instance** method using a definition object
267
-
268
-
```javascript
269
-
$restmod.model(null, {
270
-
$create:function() {
271
-
this.id=undefined;
272
-
returnthis.$save();
273
-
}
274
-
});
275
-
```
105
+
It is also posible to define a common mixin chain for all models in the application, this is done using the `rebase` method available at the restmodProvider provider in the configuration stage.
Copy file name to clipboardExpand all lines: docs/index.md
+7-4Lines changed: 7 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,9 +11,9 @@ For a quick usage reference checkout the [README](https://github.com/platanus/an
11
11
12
12
The main entry point for the library is the [$restmod service]($restmod.html). This service provides the `model` factory method that allow creation of new models via the builder DSL.
13
13
14
-
There is also a [$restmod provider]($restmodProvider.html) that allows some global configuration of models.
14
+
There is also a [restmod provider]($restmodProvider.html) that allows some global configuration of models.
15
15
16
-
### The Model Builder
16
+
### The Model Builder API
17
17
18
18
The model builder provides a rich DSL used to describe new model types. There is also support for builder extensions!
19
19
@@ -23,10 +23,10 @@ An extensive description of the builder usage and options can be found in the [B
23
23
24
24
Every call to `$restmod.model` generates a new model type.
25
25
26
-
The model type has a set of static methods, these are listed in the [StaticApi](StaticApi.html) section.
27
-
28
26
Every instance of the model is called a record, every record has its own set of instance methods, check the [RecordApi](RecordApi.html) section for reference.
29
27
28
+
The model type has a set of static methods, these are listed in the [StaticApi](StaticApi.html) section.
29
+
30
30
### The Collection Type
31
31
32
32
For every model type there is also a collection type, the collection type holds a set of records bound to a given resource url.
@@ -42,5 +42,8 @@ The restmod lib includes a couple of mixins that can be included in the project
42
42
*[PagedModel](PagedModel.html): basic paging support, included in **plugins/paged.js**. (very basic)
43
43
*[DirtyModel](DirtyModel.html): change tracking for record properties, included in **plugins/dirty.js**.
44
44
*[DebouncedModel](DebouncedModel.html): provides a debounced/throttled implementation of $save, included in **plugins/debounced.js**. (DEPRECATED: To be moved to a separate library!)
45
+
*[DebouncedModel](DebouncedModel.html): provides a debounced/throttled implementation of $save, included in **plugins/debounced.js**. (DEPRECATED: To be moved to a separate library!)
46
+
*[DebouncedModel](DebouncedModel.html): provides a debounced/throttled implementation of $save, included in **plugins/debounced.js**. (DEPRECATED: To be moved to a separate library!)
47
+
45
48
46
49
Check the [$restmod service]($restmod.html) docs for more information about mixin creation.
0 commit comments