aurelia-orm
Version:
Makes working with entities and calling your Rest API simple.
379 lines (221 loc) • 7.3 kB
Markdown
# Entity class
This class can optionally be used with validation.
The following is a full example, with validation included.
For a larger example, take a look at the end of this document.
---------
## .save()
Save the current state of the entity.
**Note**: Will `update` if given entity was populated with data from the server, and create when new. To force an update, use [.update()](#update).
### Parameters
* None
### Returns
A new `Promise` to be resolved when `.save()` has completed.
### Examples
Here's an example on how to speak to a sails based API.
```js
import {UserEntity} from 'entity/user-entity';
import {inject} from 'aurelia-framework';
@inject(UserEntity)
class MyViewModel {
constructor (entity) {
entity.username = 'Bacon';
entity.email = 'bacon@example.org';
entity.password = 'Super secure';
entity.save()
.then(result => {
console.log('User created successfully', result);
})
.catch(error => {
console.error(error);
});
}
}
```
---------
## .isDirty()
Returns if the properties of the entity have changed since fetching it.
### Parameters
* None
### Returns
Boolean indicating if the entity is dirty.
---------
## .isClean()
Returns if the properties of the entity haven't changed since fetching it.
### Parameters
* None
### Returns
Boolean indicating if the entity is clean.
---------
## .isNew()
Returns if the entity is new (e.g. hasn't been persisted to the server).
This essentially checks if the entity has an `id` set.
### Parameters
* None
### Returns
Boolean indicating if the entity is new.pa
---------
## .update()
Save the current state of the entity.
**Note:** Use this method if you want to prevent the module from **creating a new record** and wish to force an **update**. Use [.save()](#save) to create a new record.
### Parameters
* None
### Returns
A new `Promise` to be resolved when `.save()` has completed.
### Examples
Here's an example on how to speak to a sails based API.
```js
import {UserEntity} from 'entity/user-entity';
import {inject} from 'aurelia-framework';
@inject(UserEntity)
class MyViewModel {
constructor (entity) {
entity.username = 'Bacon';
entity.email = 'bacon@example.org';
entity.password = 'Super secure';
entity.save()
.then(result => {
console.log('User created successfully', result);
})
.catch(error => {
console.error(error);
});
}
}
```
---------
## .destroy()
Delete the entity server-side.
### Parameters
* None
### Returns
A new `Promise` to be resolved when `.destroy()` has completed.
### Examples
```js
import {inject} from 'aurelia-framework';
import {EntityManager} from 'aurelia-orm';
@inject(EntityManager)
export class SomeViewModel {
constructor (entityManager) {
let repository = entityManager.getRepository('user');
// Find a single record.
repository.find(7)
.then(entity => {
return entity.destroy()
})
.then(() => console.log('All done!'))
.catch(console.error);
}
}
```
---------
## .asObject()
Returns the data in the entity as a POJO.
**Note:** This method also calls `.asObject()` on all of its associations, if any.
### Parameters
* None
### Returns
An object containing the values from the entity.
---------
## .asJson()
Returns the data in the entity as JSON.
**Note:** This method uses `.asObject()` and for that reason also works with associations.
### Parameters
* None
### Returns
A JSON string containing the values from the entity.
---------
## .hasValidation()
Check if entity has validation enabled.
### Parameters
* None
### Returns
A boolean indicating if validation is enabled or not. This will enable the StandardValidator on the entity.
---------
## .getValidator()
When validation is enabled, this method returns the used Validator instance.
### Parameters
* None
### Returns
An instance of the validator. See [aurelia-validation](http://aurelia.io/hub.html#/doc/article/aurelia/validation).
---------
## .setValidator(validator)
Set the validator. Per default the StandardValidator is used if validation is enabled, but you can set a different Validator implementation if needed.
### Parameters
| Parameter | Type | Description |
| --------- | --------------- | ---------------------------------------- |
| validator | Validator | An instance of a Validator implemenation |
### Returns
Itself
---------
## .validate(propertyName?, rules?)
Calls the validator on the entity. Per default all properties and all rules on the entity are tested, but one can optionally select the propertyName and/or pass the rules to be tested.
If validation is not enabled on the entity, it is considered valid.
### Parameters
| Parameter | Type | Description |
| ------------- | --------------- | ------------------------------------ |
| propertyName | string | (optional) The property to be tested |
| rules | ValidationRules | (optional) The rules to test |
### Returns
Promise<[ValidateResult]>
---------
## .setResource(resource)
Tell the entity what endpoint resource it belongs to. This method is useful if you don't feel like using the decorators.
### Parameters
| Parameter | Type | Description |
| --------- | ------ | ------------------------- |
| resource | string | The name of the resource. |
### Returns
Itself to allow chaining.
---------
## .getResource()
Get the resource this entity belongs to.
**Note:** Also works when called statically on an Entity class.
### Parameters
* None
### Returns
The resource it belongs to (string).
---------
## .getName()
Get the name of this entity.
**Note:** Also works when called statically on an Entity class.
### Parameters
* None
### Returns
The name of the entity when configured using the `@name` decorator.
Defaults to the resource name (or null when also not set).
---------
## .getIdProperty()
Get the id property name of this entity.
**Note:** Also works when called statically on an Entity class.
### Parameters
* None
### Returns
The id property name of the entity. Defaults to 'id' or as configured using the `@idProperty` decorator.
---------
## .setId(id)
Set the id for this entity.
### Parameters
| Parameter | Type | Description |
| --------- | ------------- | --------------------- |
| id | string|number | The id of the entity. |
### Returns
Itself to allow chaining.
---------
## .getId()
Get the id of this entity.
### Parameters
* None
### Returns
The id of the entity instance.
---------
## .setData(data, markClean)
Set the values of the entity.
### Parameters
| Parameter | Type | Description |
| --------- | ------- | ------------------------------------------ |
| data | object | An object of data to assign to the entity. |
| markClean | boolean | Optionally, marks entity as clean |
### Returns
Itself to allow chaining.
For this example, I've made use of [aurelia-form](https://github.com/SpoonX/aurelia-form).
For docs on how to make a form, head over to that repository.