# populate

Populate an entity with a structure of name-value pairs. Make sure the names of the properties match the keys in the structure.

## Returns

* This function returns *the populated object*

## Arguments

| Key                  | Type    | Required | Default | Description                                                                                                      |
| -------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| target               | any     | Yes      | ---     | The entity to populate                                                                                           |
| memento              | struct  | Yes      | ---     | The structure of name-value pairs to try to populate the entity with                                             |
| scope                | string  | No       |         | Use scope injection instead of setter injection, no need of setters, just tell us what scope to inject to        |
| trustedSetter        | Boolean | No       | false   | Do not check if the setter exists, just call it, great for usage with onMissingMethod() and virtual properties   |
| include              | string  | No       |         | A list of keys to ONLY include in the population                                                                 |
| exclude              | string  | No       |         | A list of keys to exclude from the population                                                                    |
| nullEmptyInclude     | string  | No       |         | A list of keys to NULL when empty, specifically for ORM population. You can also specify "\*" for all fields     |
| nullEmptyExclude     | string  | No       |         | A list of keys to NOT NULL when empty, specifically for ORM population. You can also specify "\*" for all fields |
| composeRelationships | boolean | No       | true    | When true, will automatically attempt to compose relationships from memento                                      |

> **INFO** With composeRelationships=true, you can populate one-to-many, many-to-one, many-to-many, and one-to-one relationships from property values in the memento. For 'many-to-one' and 'one-to-one' relationships, the value of the property in the memento should be a single value of the primary key of the target entity to be loaded. For 'one-to-many' and 'many-to-many' relationships, the value of the property in the memento should a comma-delimited list or array of the primary keys of the target entities to be loaded.

## Examples

```javascript
var user = ormService.populate( ormService.new("User"), data );

// populate with includes only
var user = ormService.populate( ormService.new("User"), data, "fname,lname,email" );

//populate with excludes
var user = ormService.populate(target=ormService.new("User"),memento=data,exclude="id,setup,total" );

// populate with null values when value is empty string
var user = ormService.populate(target=ormService.new("User"),memento=data,nullEmptyInclude="lastName,dateOfBirth" );

// populate many-to-one relationship
var data = {
    firstName = "Luis",
    role = 1 // "role" is the name of the many-to-one relational property, and one is the key value
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the role relationship will be composed, and the value will be set to the appropriate instance of the Role model

// populate one-to-many relationship
var data = {
    firstName = "Luis",
    favColors = "1,2,3" ( or [1,2,3] ) // favColors is the name of the one-to-many relational property, and 1, 2 and 3 are key values of favColor models
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true );
// the favColors property will be set to an array of favColor entities

// only compose some relationships
var data = {
    firstName = "Luis",
    role = 1,
    favColors = [ 1, 3, 19 ]
};
var user = ormService.populate( target=ormService.new("User"), memento=data, composeRelationships=true, exclude="favColors" );
// in this example, "role" will be composed, but "favColors" will be excluded
```