Skip to content

Commit

Permalink
Update model API docs to use the new packages import syntax (#6137)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bmac @runspired
bmac authored and runspired committed Jun 25, 2019
1 parent a2308b7 commit ff850b3
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 83 deletions.
36 changes: 18 additions & 18 deletions packages/model/addon/-private/attr.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,16 +25,16 @@ function hasValue(internalModel, key) {
}

/**
`DS.attr` defines an attribute on a [DS.Model](/api/data/classes/DS.Model.html).
`attr` defines an attribute on a [Model](/api/data/classes/DS.Model.html).
By default, attributes are passed through as-is, however you can specify an
optional type to have the value automatically transformed.
Ember Data ships with four basic transform types: `string`, `number`,
`boolean` and `date`. You can define your own transforms by subclassing
[DS.Transform](/api/data/classes/DS.Transform.html).
[Transform](/api/data/classes/DS.Transform.html).
Note that you cannot use `attr` to define an attribute of `id`.
`DS.attr` takes an optional hash as a second parameter, currently
`attr` takes an optional hash as a second parameter, currently
supported options are:
- `defaultValue`: Pass a string or a function to be called to set the attribute
Expand All @@ -43,25 +43,25 @@ function hasValue(internalModel, key) {
Example
```app/models/user.js
import DS from 'ember-data';
import Model, { attr } from '@ember-data/model';
export default DS.Model.extend({
username: DS.attr('string'),
email: DS.attr('string'),
verified: DS.attr('boolean', { defaultValue: false })
export default Model.extend({
username: attr('string'),
email: attr('string'),
verified: attr('boolean', { defaultValue: false })
});
```
Default value can also be a function. This is useful it you want to return
a new object for each attribute.
```app/models/user.js
import DS from 'ember-data';
import Model, { attr } from '@ember-data/model';
export default DS.Model.extend({
username: DS.attr('string'),
email: DS.attr('string'),
settings: DS.attr({
export default Model.extend({
username: attr('string'),
email: attr('string'),
settings: attr({
defaultValue() {
return {};
}
Expand All @@ -74,19 +74,19 @@ function hasValue(internalModel, key) {
transformation and adapt the corresponding value, based on the config:
```app/models/post.js
import DS from 'ember-data';
import Model, { attr } from '@ember-data/model';
export default DS.Model.extend({
text: DS.attr('text', {
export default Model.extend({
text: attr('text', {
uppercase: true
})
});
```
```app/transforms/text.js
import DS from 'ember-data';
import Transform from '@ember-data/serializer/transform';
export default DS.Transform.extend({
export default Transform.extend({
serialize(value, options) {
if (options.uppercase) {
return value.toUpperCase();
Expand Down
56 changes: 27 additions & 29 deletions packages/model/addon/-private/relationships/belongs-to.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ import { normalizeModelName } from '@ember-data/store';
import { DEBUG } from '@glimmer/env';

/**
`DS.belongsTo` is used to define One-To-One and One-To-Many
relationships on a [DS.Model](/api/data/classes/DS.Model.html).
`belongsTo` is used to define One-To-One and One-To-Many
relationships on a [Model](/api/data/classes/DS.Model.html).
`DS.belongsTo` takes an optional hash as a second parameter, currently
`belongsTo` takes an optional hash as a second parameter, currently
supported options are:
- `async`: A boolean value used to explicitly declare this to be an async relationship. The default is true.
Expand All @@ -17,52 +17,52 @@ import { DEBUG } from '@glimmer/env';
#### One-To-One
To declare a one-to-one relationship between two models, use
`DS.belongsTo`:
`belongsTo`:
```app/models/user.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
profile: DS.belongsTo('profile')
export default Model.extend({
profile: belongsTo('profile')
});
```
```app/models/profile.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
user: DS.belongsTo('user')
export default Model.extend({
user: belongsTo('user')
});
```
#### One-To-Many
To declare a one-to-many relationship between two models, use
`DS.belongsTo` in combination with `DS.hasMany`, like this:
`belongsTo` in combination with `hasMany`, like this:
```app/models/post.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
comments: DS.hasMany('comment')
export default Model.extend({
comments: hasMany('comment')
});
```
```app/models/comment.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
post: DS.belongsTo('post')
export default Model.extend({
post: belongsTo('post')
});
```
You can avoid passing a string as the first parameter. In that case Ember Data
will infer the type from the key name.
```app/models/comment.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
post: DS.belongsTo()
export default Model.extend({
post: belongsTo()
});
```
Expand All @@ -75,10 +75,10 @@ import { DEBUG } from '@glimmer/env';
to be loaded before or along-side the primary resource.
```app/models/comment.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
post: DS.belongsTo('post', {
export default Model.extend({
post: belongsTo('post', {
async: false
})
});
Expand All @@ -94,9 +94,7 @@ import { DEBUG } from '@glimmer/env';
```
@namespace
@method belongsTo
@for DS
@param {String} modelName (optional) type of the relationship
@param {Object} options (optional) a hash of options
@return {Ember.computed} relationship
Expand All @@ -116,9 +114,9 @@ export default function belongsTo(modelName, options) {
}

assert(
'The first argument to DS.belongsTo must be a string representing a model type key, not an instance of ' +
'The first argument to belongsTo must be a string representing a model type key, not an instance of ' +
inspect(userEnteredModelName) +
". E.g., to define a relation to the Person model, use DS.belongsTo('person')",
". E.g., to define a relation to the Person model, use belongsTo('person')",
typeof userEnteredModelName === 'string' || typeof userEnteredModelName === 'undefined'
);

Expand All @@ -145,7 +143,7 @@ export default function belongsTo(modelName, options) {
warn(
`You provided a serialize option on the "${key}" property in the "${
this._internalModel.modelName
}" class, this belongs in the serializer. See DS.Serializer and it's implementations https://emberjs.com/api/data/classes/DS.Serializer.html`,
}" class, this belongs in the serializer. See Serializer and it's implementations https://emberjs.com/api/data/classes/DS.Serializer.html`,
false,
{
id: 'ds.model.serialize-option-in-belongs-to',
Expand All @@ -157,7 +155,7 @@ export default function belongsTo(modelName, options) {
warn(
`You provided an embedded option on the "${key}" property in the "${
this._internalModel.modelName
}" class, this belongs in the serializer. See DS.EmbeddedRecordsMixin https://emberjs.com/api/data/classes/DS.EmbeddedRecordsMixin.html`,
}" class, this belongs in the serializer. See EmbeddedRecordsMixin https://emberjs.com/api/data/classes/DS.EmbeddedRecordsMixin.html`,
false,
{
id: 'ds.model.embedded-option-in-belongs-to',
Expand Down
72 changes: 36 additions & 36 deletions packages/model/addon/-private/relationships/has-many.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,63 +7,63 @@ import { normalizeModelName } from '@ember-data/store';
import { DEBUG } from '@glimmer/env';

/**
`DS.hasMany` is used to define One-To-Many and Many-To-Many
relationships on a [DS.Model](/api/data/classes/DS.Model.html).
`hasMany` is used to define One-To-Many and Many-To-Many
relationships on a [Model](/api/data/classes/DS.Model.html).
`DS.hasMany` takes an optional hash as a second parameter, currently
`hasMany` takes an optional hash as a second parameter, currently
supported options are:
- `async`: A boolean value used to explicitly declare this to be an async relationship. The default is true.
- `inverse`: A string used to identify the inverse property on a related model.
#### One-To-Many
To declare a one-to-many relationship between two models, use
`DS.belongsTo` in combination with `DS.hasMany`, like this:
`belongsTo` in combination with `hasMany`, like this:
```app/models/post.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
comments: DS.hasMany('comment')
export default Model.extend({
comments: hasMany('comment')
});
```
```app/models/comment.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
post: DS.belongsTo('post')
export default Model.extend({
post: belongsTo('post')
});
```
#### Many-To-Many
To declare a many-to-many relationship between two models, use
`DS.hasMany`:
`hasMany`:
```app/models/post.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
tags: DS.hasMany('tag')
export default Model.extend({
tags: hasMany('tag')
});
```
```app/models/tag.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
posts: DS.hasMany('post')
export default Model.extend({
posts: hasMany('post')
});
```
You can avoid passing a string as the first parameter. In that case Ember Data
will infer the type from the singularized key name.
```app/models/post.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
tags: DS.hasMany()
export default Model.extend({
tags: hasMany()
});
```
Expand All @@ -79,24 +79,24 @@ import { DEBUG } from '@glimmer/env';
However, sometimes you may have multiple `belongsTo`/`hasMany` for the
same type. You can specify which property on the related model is
the inverse using `DS.hasMany`'s `inverse` option:
the inverse using `hasMany`'s `inverse` option:
```app/models/comment.js
import DS from 'ember-data';
import Model, { belongsTo } from '@ember-data/model';
export default DS.Model.extend({
onePost: DS.belongsTo('post'),
twoPost: DS.belongsTo('post'),
redPost: DS.belongsTo('post'),
bluePost: DS.belongsTo('post')
export default Model.extend({
onePost: belongsTo('post'),
twoPost: belongsTo('post'),
redPost: belongsTo('post'),
bluePost: belongsTo('post')
});
```
```app/models/post.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
comments: DS.hasMany('comment', {
export default Model.extend({
comments: hasMany('comment', {
inverse: 'redPost'
})
});
Expand All @@ -112,17 +112,17 @@ import { DEBUG } from '@glimmer/env';
to be loaded before or along-side the primary resource.
```app/models/post.js
import DS from 'ember-data';
import Model, { hasMany } from '@ember-data/model';
export default DS.Model.extend({
comments: DS.hasMany('comment', {
export default Model.extend({
comments: hasMany('comment', {
async: false
})
});
```
In contrast to async relationship, accessing a sync relationship
will always return a [DS.ManyArray](/api/data/classes/DS.ManyArray.html) instance
will always return a [ManyArray](/api/data/classes/DS.ManyArray.html) instance
containing the existing local resources. But it will error on access
when any of the known related resources have not been loaded.
Expand Down Expand Up @@ -150,9 +150,9 @@ export default function hasMany(type, options) {
}

assert(
`The first argument to DS.hasMany must be a string representing a model type key, not an instance of ${inspect(
`The first argument to hasMany must be a string representing a model type key, not an instance of ${inspect(
type
)}. E.g., to define a relation to the Comment model, use DS.hasMany('comment')`,
)}. E.g., to define a relation to the Comment model, use hasMany('comment')`,
typeof type === 'string' || typeof type === 'undefined'
);

Expand Down

0 comments on commit ff850b3

Please sign in to comment.