Defining An Entity

Search…
Defining An Entity
To get started with Quick, you need an entity. You start by extending quick.models.BaseEntity.
1
// User.cfc
2
component extends="quick.models.BaseEntity" accessors="true" {}
Copied!
That's all that is needed to get started with Quick. There are a few defaults of Quick worth mentioning here.
You can generate Quick entities from CommandBox! Install quick-commands and use quick entity create to get started!
Tables
We don't need to tell Quick what table name to use for our entity. By default, Quick uses the pluralized name of the component for the table name. That means for our User entity Quick will assume the table name is users. You can override this by specifying a table metadata attribute on the component.
1
// User.cfc
2
component table="my_users" extends="quick.models.BaseEntity" accessors="true" {}
Copied!
Inheritance
For more information on using inheritance and child tables in your relational database model, see Subclass Entities.
Primary Key
By default, Quick assumes a primary key of id. The name of this key can be configured by setting variables._key in your component.
1
// User.cfc
2
component extends="quick.models.BaseEntity" accessors="true" {
3
​
4
    variables._key = "user_id";
5
​
6
}
Copied!
Quick also assumes a key type that is auto-incrementing. If you would like a different key type, override thekeyType function and return the desired key type from that function.
1
// User.cfc
2
component extends="quick.models.BaseEntity" accessors="true" {
3
​
4
    function keyType() {
5
        return variables._wirebox.getInstance( "[email protected]" );
6
    }
7
​
8
}
Copied!
Quick ships with the following key types:
AutoIncrementingKeyType
NullKeyType
ReturningKeyType
UUIDKeyType
keyType can be any component that adheres to the keyType interface, so feel free to create your own and distribute them via ForgeBox.
1
interface displayname="KeyType" {
2
​
3
    /**
4
    * Called to handle any tasks before inserting into the database.
5
    * Recieves the entity as the only argument.
6
    */
7
    public void function preInsert( required entity );
8
​
9
    /**
10
    * Called to handle any tasks after inserting into the database.
11
    * Recieves the entity and the queryExecute result as arguments.
12
    */
13
    public void function postInsert( required entity, required struct result );
14
​
15
}
Copied!
Attributes
You specify what attributes are retrieved by adding properties to your component.
1
// User.cfc
2
component extends="quick.models.BaseEntity" accessors="true" {
3
​
4
    property name="id";
5
    property name="username";
6
    property name="email";
7
​
8
}
Copied!
Now, only the id, username, and email attributes will be retrieved.
Make sure to include the primary key (id by default) as a property.
Persistent
To prevent Quick from mapping a property to a database column add the persistent="false" attribute to the property. This is needed mostly when using dependency injection.
1
// User.cfc
2
component extends="quick.models.BaseEntity" accessors="true" {
3
​
4
    property name="bcrypt" inject="@BCrypt" persistent="false";
5
​
6
    property name="id";
7
    property name="username";
8
    property name="email";
9
​
10
}
Copied!
Column
If the column name in your table is not the column name you wish to use in Quick, you can specify the column name using the column metadata attribute. The attribute will be available using the name of the attribute.
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="username" column="user_name";
5
    property name="countryId" column="FK_country_id";
6
​
7
}
Copied!
Null Values
To work around CFML's lack of null, you can use the nullValue and convertToNull attributes.
nullValue defines the value that is considered null for a attribute. By default it is an empty string. ("")
convertToNull is a flag that, when false, will not try to insert null in to the database. By default this flag is true.
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="number" convertToNull="false";
5
    property name="title" nullValue="REALLY_NULL";
6
​
7
}
Copied!
Read Only
The readOnly attribute will prevent setters, updates, and inserts to a attribute when set to true.
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="createdDate" readonly="true";
5
​
6
}
Copied!
SQL Type
In some cases you will need to specify an exact SQL type for your attribute. Any value set for the sqltype attribute will be used when inserting or updating the attribute in the database. It will also be used when you use the attribute in a where constraint.
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="number" sqltype="cf_sql_varchar";
5
​
6
}
Copied!
Casts
The casts attribute allows you to use a value in your CFML code as a certain type while being a different type in the database. A common example of this is a boolean which is usually represented as a BIT in the database.
Two casters ship with Quick: [email protected] and [email protected]. You can add them using those mappings to any applicable columns.
Custom Casts
The casts attribute must point to a WireBox mapping that resolves to a component that implements the quick.models.Casts.CastsAttribute interface. (The implements keyword is optional.) This component defines how to get a value from the database in to the casted value and how to set a casted value back to the database. Below is an example of the built-in BooleanCast, which comes bundled with Quick.
1
// User.cfc
2
component extends="quick.models.BaseEntity" accessors="true" {
3
​
4
    property name="id";
5
    property name="active" casts="[email protected]";
6
​
7
}
Copied!
1
// BooleanCast.cfc
2
component implements="CastsAttribute" {
3
​
4
    /**
5
     * Casts the given value from the database to the target cast type.
6
     *
7
     * @entity      The entity with the attribute being casted.
8
     * @key         The attribute alias name.
9
     * @value       The value of the attribute.
10
     *
11
     * @return      The casted attribute.
12
     */
13
    public any function get(
14
        required any entity,
15
        required string key,
16
        any value
17
    ) {
18
        return isNull( arguments.value ) ? false : booleanFormat( arguments.value );
19
    }
20
​
21
    /**
22
     * Returns the value to assign to the key before saving to the database.
23
     *
24
     * @entity      The entity with the attribute being casted.
25
     * @key         The attribute alias name.
26
     * @value       The value of the attribute.
27
     *
28
     * @return      The value to save to the database. A struct of values
29
     *              can be returned if the cast value affects multiple attributes.
30
     */
31
    public any function set(
32
        required any entity,
33
        required string key,
34
        any value
35
    ) {
36
        return arguments.value ? 1 : 0;
37
    }
38
​
39
}
Copied!
Casted values are lazily loaded and cached for the lifecycle of the component. Only cast values that have been loaded will have set called on them when persisting to the database.
Casts can be composed of multiple fields as well. Take this Address value object, for example:
1
// Address.cfc
2
component accessors="true" {
3
​
4
    property name="streetOne";
5
    property name="streetTwo";
6
    property name="city";
7
    property name="state";
8
    property name="zip";
9
​
10
    function fullStreet() {
11
        var street = [ getStreetOne(), getStreetTwo() ];
12
        return street.filter( function( part ) {
13
            return !isNull( part ) && part != "";
14
        } ).toList( chr( 10 ) );
15
    }
16
​
17
    function formatted() {
18
        return fullStreet() & chr( 10 ) & "#getCity()#, #getState()# #getZip()#";
19
    }
20
​
21
}
Copied!
This component is not a Quick entity. Instead it represents a combination of fields stored on our User entity:
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="username";
5
    property name="firstName" column="first_name";
6
    property name="lastName" column="last_name";
7
    property name="password";
8
​
9
    property name="address"
10
        casts="AddressCast"
11
        persistent="false"
12
        getter="false"
13
        setter="false";
14
    property name="streetOne";
15
    property name="streetTwo";
16
    property name="city";
17
    property name="state";
18
    property name="zip";
19
​
20
}
Copied!
Noticed that the casted address is neither persistent nor does it have a getter or setter created for it.
The last piece of the puzzle is our AddressCast component that handles casting the value to and from the native database values:
1
component implements="quick.models.Casts.CastsAttribute" {
2
​
3
    property name="wirebox" inject="wirebox";
4
​
5
    /**
6
     * Casts the given value from the database to the target cast type.
7
     *
8
     * @entity      The entity with the attribute being casted.
9
     * @key         The attribute alias name.
10
     * @value       The value of the attribute.
11
     * @attributes  The struct of attributes for the entity.
12
     *
13
     * @return      The casted attribute.
14
     */
15
    public any function get(
16
        required any entity,
17
        required string key,
18
        any value
19
    ) {
20
        return wirebox.getInstance( dsl = "Address" )
21
            .setStreetOne( entity.retrieveAttribute( "streetOne" ) )
22
            .setStreetTwo( entity.retrieveAttribute( "streetTwo" ) )
23
            .setCity( entity.retrieveAttribute( "city" ) )
24
            .setState( entity.retrieveAttribute( "state" ) )
25
            .setZip( entity.retrieveAttribute( "zip" ) );
26
    }
27
​
28
    /**
29
     * Returns the value to assign to the key before saving to the database.
30
     *
31
     * @entity      The entity with the attribute being casted.
32
     * @key         The attribute alias name.
33
     * @value       The value of the attribute.
34
     * @attributes  The struct of attributes for the entity.
35
     *
36
     * @return      The value to save to the database. A struct of values
37
     *              can be returned if the cast value affects multiple attributes.
38
     */
39
    public any function set(
40
        required any entity,
41
        required string key,
42
        any value
43
    ) {
44
        return {
45
            "streetOne": arguments.value.getStreetOne(),
46
            "streetTwo": arguments.value.getStreetTwo(),
47
            "city": arguments.value.getCity(),
48
            "state": arguments.value.getState(),
49
            "zip": arguments.value.getZip()
50
        };
51
    }
52
​
53
}
Copied!
You can see that returning a struct of values from the set function assigns multiple attributes from a single cast.
Insert & Update
You can prevent inserting and updating a property by setting the insert or update attribute to false.
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="email" column="email" update="false" insert="true";
5
​
6
}
Copied!
Formula, Computed, or Subselect properties
Quick handles formula, computed, or subselect properties using query scopes and the addSubselect helper method. Check out the docs in query scopes to learn more.​
Multiple datasource support
Quick uses a default datasource and default grammar, as described here. If you are using multiple datasources you can override default datasource by specifying a datasource metadata attribute on the component. If your extra datasource has a different grammar you can override your grammar as well by specifying a grammar attribute.
1
// User.cfc
2
component
3
    datasource="myOtherDatasource"
4
    grammar="[email protected]"
5
    extends="quick.models.BaseEntity"
6
    accessors="true"
7
{
8
    // ....
9
}
Copied!
At the time of writing Valid grammar options are: [email protected], [email protected], [email protected] and [email protected]. Please check the qb docs for additional options.
Comparing Entities
You can compare entities using the isSameAs and isNotSameAs methods. Each method takes another entity and returns true if the two objects represent the same entity.
1
var userOne = getInstance( "User" ).findOrFail( 1 );
2
var userTwo = getInstance( "User" ).findOrFail( 1 );
3
​
4
userOne.isSameAs( userTwo ); // true
5
userOne.isNotSameAs( userTwo ); // false
Copied!