The relational model extends the model. The idea is
that while a model is great for a single record, sometimes you need hierarchies
in your data, and you need each part of the hierarchy to be a model/collection.
The relational model lets you specify a structure and will automatically
convert data passed in into that structure.
This can be very useful if your backing store is a document store, or if your
API returns nested data.
The main relational class. Extends Composer.Model, so
anything the model has, this has as well.
That said, we’re going to re-document some of the behavior of Composer.Model
here because RelationalModel overrides it and changes it.
Without a specification, a relational model will act exactly like a model. The
specification lets the model know which pieces of data should be
models/collections and where to find them.
Let’s do an example without a relational model and see the result:
Note that the data exists in the model as we passed it. We have to specifically
ask for various parts of the data using object/array syntax. This may be what
you want, or you may want a hierarchy of models/collections:
The obvious benefit to using the relational model is that your nested data now
has the same capabilities your top-level items do (including eventing).
Example relation specification, showing all options:
Relational models that extend others automatically get the relationships defined
in the parent class, even if the child specifies another set of relations:
toJSON :: function(options)
Like Model.toJSON, this function serializes
the data contained in the model into objects/arrays. However, this function also
aggregates the serialized results from all its sub-objects:
options can contain the following items:
skip_relational - if true, will not return relational data in the toJSON
serialization (the keys of the relations will be deleted from the resulting
object). This can be useful for serializing a relational object without grabbing
the entire tree.
set :: function(data, options)
Set, like Model.set, sets data into the
relational model, but is also responsible for turning the nested data into your
While its funcationality is the same as Model.set, it’s worth mentioning that
this function does most of the magic.