Define an association that this object belongs to.

An attribute will be created matching the name of the attribute with ‘_id’ on the end, or the foreign key (:foreign_key) provided.

Searching for the assocated object is performed using a string (:proxy) to be evaulated in the context of the owner. Typically this will be set to the class name (:class_name), or determined automatically if the owner belongs to a proxy object.

If the association owner is proxied by another model, than an attempt will be made to automatically determine the correct place to request the documents. Typically, this is a method with the pluralized name of the association inside owner‘s owner, or proxy.

For example, imagine a company acts as a proxy for invoices and clients. If an invoice belongs to a client, the invoice will need to access the list of clients via the proxy. So a request to search for the associated client from an invoice would look like:

   self.company.clients

If the name of the collection proxy is not the pluralized assocation name, it can be set with the :proxy_name option.

Provide access to a collection of objects where the associated property contains a list of the collection item ids.

The following:

    collection_of :groups

creates a pseudo property called "groups" which allows access to a CollectionOfProxy object. Adding, replacing or removing entries in this proxy will cause the matching property array, in this case "group_ids", to be kept in sync.

Any manual changes made to the collection ids property (group_ids), unless replaced, will require a reload of the CollectionOfProxy for the two sets of data to be in sync:

    group_ids = ['123']
    groups == [Group.get('123')]
    group_ids << '321'
    groups == [Group.get('123')]
    groups(true) == [Group.get('123'), Group.get('321')]

Of course, saving the parent record will store the collection ids as they are found.

The CollectionOfProxy supports the following array functions, anything else will cause a mismatch between the collection objects and collection ids:

    groups << obj
    groups.push obj
    groups.unshift obj
    groups[0] = obj
    groups.pop == obj
    groups.shift == obj

Addtional options match those of the the belongs_to method.

NOTE: This method is not recommended for large collections or collections that change frequently! Use with prudence.