feat(Relationships): Get a new filled instance of a relationship by c…

…alling the `fill` method on the relationship object

models/Relationships/BaseRelationship.cfc

@@ -280,6 +280,29 @@ component accessors="true" implements="IRelationship" {
 		return variables.relationshipBuilder.findOrCreate( argumentCollection = arguments );
 	}
 
+	/**
+	 * Creates a new unloaded related entity and sets attributes data from a struct of key / value pairs.
+	 * This method does the following, in order:
+	 * 1. Guard against read-only attributes
+	 * 2. Attempt to call a relationship setter.
+	 * 2. Calls custom attribute setters for attributes that exist
+	 * 3. Throws an error if an attribute does not exist
+	 *
+	 * @attributes                   A struct of key / value pairs.
+	 * @ignoreNonExistentAttributes  If true, does not throw an exception if an
+	 *                               attribute does not exist.  Instead, it skips
+	 *                               the non-existent attribute.
+	 *
+	 * @return                       quick.models.BaseEntity
+	 */
+	public any function fill(
+		struct attributes                   = {},
+		boolean ignoreNonExistentAttributes = false,
+		any include                         = [],
+		any exclude                         = []
+	) {
+		return newEntity().fill( argumentCollection = arguments );
+	}
 	/**
 	 * Returns all results for the related entity.
 	 * Note: `all` resets any query restrictions, including relationship restrictions.
@@ -629,6 +652,17 @@ component accessors="true" implements="IRelationship" {
 		return newEntity;
 	}
 
+	/**
+	 * Returns a new instance of the entity, pre-associated to the parent entity. Does not persist it.
+	 *
+	 * @return      quick.models.BaseEntity
+	 */
+	public any function newEntity() {
+		var newInstance = variables.related.newEntity();
+		setForeignAttributesForCreate( newInstance );
+		return newInstance;
+	}
+
 	private boolean function entityHasAttribute(
 		required any entity,
 		required string key,

models/Relationships/HasOneOrMany.cfc

@@ -324,17 +324,6 @@ component
 		return newEntity().fill( arguments.attributes ).save();
 	}
 
-	/**
-	 * Returns a new instance of the entity, pre-associated to the parent entity. Does not persist it.
-	 *
-	 * @return      quick.models.BaseEntity
-	 */
-	public any function newEntity() {
-		var newInstance = variables.related.newEntity();
-		setForeignAttributesForCreate( newInstance );
-		return newInstance;
-	}
-
 	/**
 	 * Sets the parent key value as the foreign key for the entity.
 	 *

tests/specs/integration/BaseEntity/Relationships/RelationshipLoadingSpec.cfc

@@ -78,6 +78,16 @@ component extends="tests.resources.ModuleIntegrationSpec" {
 				} );
 			} );
 
+			it( "gets a new instance of an entity when calling fill", () => {
+				var elpete  = getInstance( "User" ).findOrFail( 1 );
+				var newPost = elpete.posts().fill( { "body" : "test body" } );
+				expect( newPost ).notToBeNull();
+				expect( newPost ).toBeInstanceOf( "Post" );
+				expect( newPost.isLoaded() ).toBeFalse();
+				expect( newPost.getBody() ).toBe( "test body" );
+				expect( newPost.getUser_Id() ).toBe( 1 );
+			} );
+
 			it( "can call fetch methods on the relationship builder", () => {
 				var elpete             = getInstance( "User" ).findOrFail( 1 );
 				var elpeteFavoritePost = elpete.favoritePost().first();