From ff850b317145c338174e5e6017e7eadd09976ef0 Mon Sep 17 00:00:00 2001 From: Brendan McLoughlin Date: Wed, 12 Jun 2019 20:04:41 -0400 Subject: [PATCH] Update model API docs to use the new packages import syntax (#6137) --- packages/model/addon/-private/attr.js | 36 +++++----- .../-private/relationships/belongs-to.js | 56 +++++++-------- .../addon/-private/relationships/has-many.js | 72 +++++++++---------- 3 files changed, 81 insertions(+), 83 deletions(-) diff --git a/packages/model/addon/-private/attr.js b/packages/model/addon/-private/attr.js index c9396112d07..85666cd88c6 100644 --- a/packages/model/addon/-private/attr.js +++ b/packages/model/addon/-private/attr.js @@ -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 @@ -43,12 +43,12 @@ 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 }) }); ``` @@ -56,12 +56,12 @@ function hasValue(internalModel, key) { 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 {}; } @@ -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(); diff --git a/packages/model/addon/-private/relationships/belongs-to.js b/packages/model/addon/-private/relationships/belongs-to.js index 3fa6b04bc81..2ebcbf3851d 100644 --- a/packages/model/addon/-private/relationships/belongs-to.js +++ b/packages/model/addon/-private/relationships/belongs-to.js @@ -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. @@ -17,41 +17,41 @@ 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') }); ``` @@ -59,10 +59,10 @@ import { DEBUG } from '@glimmer/env'; 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() }); ``` @@ -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 }) }); @@ -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 @@ -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' ); @@ -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', @@ -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', diff --git a/packages/model/addon/-private/relationships/has-many.js b/packages/model/addon/-private/relationships/has-many.js index 4c431ac5137..7b9c40e32c8 100644 --- a/packages/model/addon/-private/relationships/has-many.js +++ b/packages/model/addon/-private/relationships/has-many.js @@ -7,10 +7,10 @@ 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. @@ -18,41 +18,41 @@ import { DEBUG } from '@glimmer/env'; #### 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') }); ``` @@ -60,10 +60,10 @@ import { DEBUG } from '@glimmer/env'; 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() }); ``` @@ -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' }) }); @@ -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. @@ -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' );