Serialization

Search…
Serialization
getMemento
The memento pattern is an established pattern in ColdBox apps. A memento in this case is a simple representation of your entity using arrays, structs, and simple values.
For instance, the following example shows a User entity and its corresponding memento:
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="username";
5
    property name="email";
6
    property name="password";
7
    property name="createdDate";
8
    property name="modifiedDate";
9
​
10
}
Copied!
1
{
2
    "id" = 1,
3
    "username" = "JaneDoe",
4
    "email" = "[email protected]",
5
    "password" = "$2a$04$2nVI5rPOfl6.hrflkhBWOObO5Z7lXGJpi1vlosY74NrL/CKdpWqZS"
6
    "createdDate" = "{ts '2018-03-12 16:14:10'}",
7
    "modifiedDate" = "{ts '2018-03-12 16:14:10'}"
8
}
Copied!
Quick bundles in the excellent Mementifier library to handle converting entities to mementos. This gives you excellent control over serialization using a this.memento struct on the entity and passing in arguments to the getMemento function.
this.memento
By default, Quick includes all defined attributes as includes. You can change this or add other Mementifier options by defining your own this.memento struct on your entity. Your custom this.memento struct will be merged with Quick's default, so you can only define what changes you need.
Here is the default Quick memento struct. It is inside the instanceReady() lifecycle method in this example because retrieveAttributeNames() relies on the entity being wired (though not loaded); it is not otherwise necessary to put this.memento inside instanceReady().
1
function instanceReady() {
2
    this.memento = {
3
        "defaultIncludes" : retrieveAttributeNames( withVirtualAttributes = true ),
4
          "defaultExcludes" : [],
5
          "neverInclude"    : [],
6
          "defaults"        : {},
7
          "mappers"         : {},
8
          "trustedGetters"  : true,
9
          "ormAutoIncludes" : false
10
    };
11
}
Copied!
getMemento Arguments
You can also control the serialization of a memento at call time using Mementifier's getMemento arguments.
1
struct function getMemento(
2
    includes = "", // or []
3
    excludes = "", // or []
4
    struct mappers = {},
5
    struct defaults = {},
6
    boolean ignoreDefaults = false,
7
    boolean trustedGetters
8
)
Copied!
Custom getMemento
If this does not give you the control you need, you can further modify the memento by overriding the getMemento function on your entity. In this case, a $getMemento function will be available which is the Mementifier function.
1
component extends="quick.models.BaseEntity" accessors="true" {
2
​
3
    property name="id";
4
    property name="username";
5
    property name="email";
6
    property name="password";
7
    property name="createdDate";
8
    property name="modifiedDate";
9
​
10
    function getMemento() {
11
        return {
12
            id = getId(),
13
            username = getUsername(),
14
            email = getEmail(),
15
            createdDate = dateFormat( getCreatedDate(), "MM/DD/YYYY" ),
16
            // can also use getAttribute if you want to bypass a custom getter
17
            modifiedDate = dateFormat( retrieveAttribute( "modifiedDate" ), "MM/DD/YYYY" )
18
        };
19
    }
20
​
21
}
Copied!
1
{
2
    "id" = 1,
3
    "username" = "JaneDoe",
4
    "email" = "[email protected]",
5
    "createdDate" = "03/12/2018",
6
    "modifiedDate" = "03/12/2018"
7
}
Copied!
asMemento
Sometimes when retrieving entities or executing a Quick query, you already know you want mementos back. You can skip the step of calling getMemento yourself or mapping over the array of results returned by calling asMemento before executing the query. asMemento takes the same arguments that getMemento does. It will pass those arguments on and convert your entities to mementos after executing the query. This works for all the query execution methods - find, first, get, paginate, etc.
$renderData
The $renderData method is a special method for ColdBox. When returning a model from a handler, this method will be called and the value returned will be used as the serialized response. This let's you simply return an entity from a handler for your API. By default this will call getMemento().
1
component {
2
​
3
    // /users/:id
4
    function show( event, rc, prc ) {
5
        return getInstance( "User" ).findOrFail( rc.id );
6
    }
7
​
8
}
Copied!
1
{
2
    "id" = 1,
3
    "username" = "JaneDoe",
4
    "email" = "[email protected]",
5
    "createdDate" = "03/12/2018",
6
    "modifiedDate" = "03/12/2018"
7
}
Copied!
QuickCollection also defines a $renderData method, which will delegate the call to each entity in the collection and return the array of serialized entities.
Automatically serializing a returned collection only works when using the QuickCollection as your entity's newCollection.
1
component {
2
​
3
    function index( event, rc, prc ) {
4
        return getInstance( "User" ).all();
5
    }
6
​
7
}
Copied!
1
[
2
    {
3
        "id" = 1,
4
        "username" = "JaneDoe",
5
        "email" = "[email protected]",
6
        "createdDate" = "03/12/2018",
7
        "modifiedDate" = "03/12/2018"
8
    },
9
    {
10
        "id" = 2,
11
        "username" = "JohnDoe",
12
        "email" = "[email protected]",
13
        "createdDate" = "03/14/2018",
14
        "modifiedDate" = "03/15/2018"
15
    }
16
]
Copied!
Guide - Previous
Custom Getters & Setters
Next - Guide
Interception Points
Last modified 1yr ago
Copy link
Edit on GitHub
Contents