Belongs to

The information below is copied from the API documentation on belongs_to associations
http://api.akelos.org/ActiveRecord/Associations/AkBelongsTo.html

Belongs to adds the following methods for retrieval and query for a single associated object that this object holds an id to.

• belongsTo→assign($association_id, $Associate); - assigns the associate object, extracts the primary key, and sets it as the foreign key.
• belongsTo→build($association_id, $attributes = array()); - returns a new object of the associated type that has been instantiated with attributes and linked to this object through a foreign key but has not yet been saved.
• belongsTo→create($association_id, $attributes = array()); - returns a new object of the associated type that has been instantiated with attributes and linked to this object through a foreign key and that has already been saved (if it passed the validation).

A Post class declares belongsTo('author'), which will add:

$Post->author->load(); (similar to $Author->find($author_id);)
$Post->author->assign($Author); (similar to $Post->author_id = $Author->getId();)
$Post->author->build($Author); (similar to $Post->author = new Author();)
$Post->author->create($Author); (similar to $Post->author = new Author(); $Post->author->save();)

The declaration can also include an options hash to specialize the behavior of the association.

• class_name - specify the class name of the association. Use it only if that name can't be inferred from the association name. So belongsTo('author') will by default be linked to the 'Author' class, but if the real class name is 'Person', you'll have to specify it with this option.
• conditions - specify the conditions that the associated object must meet in order to be included as a “WHERE” sql fragment, such as “authorized = 1”.
• order - specify the order from which the associated object will be picked at the top. Specified as an “ORDER BY” sql fragment, such as “last_name, first_name DESC”
• primary_key_name- specify the foreign key used for the association. By default this is guessed to be the name of the associated class in lower-case and “_id” suffixed. So a 'Person' class that makes a belongsTo association to a 'Boss' class will use “boss_id” as the default primary_key_name.
• counter_cache - caches the number of belonging objects on the associate class through use of increment_counter and decrement_counter. The counter cache is incremented when an object of this class is created and decremented when it's destroyed. This requires that a column named ”#{table_name}_count” (such as comments_count for a belonging Comment class) is used on the associate class (such as a Post class). Note: counter_cache is not yet implemented

Option examples

var $belongs_to = array('firm', array('primary_key_name' => 'client_of'));
 
var $belongs_to = array('author', array('class_name' => 'Person',
                                        'primary_key_name' => 'author_id'));
 
var $belongs_to = array('valid_coupon', array('class_name' => 'Coupon',
                                              'primary_key_name' => 'coupon_id',
                                              'conditions' => "'discounts' > 'payments_count'"));