====== 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).

==== Example ====

A Post class declares **belongsTo('author')**, which will add:
<code php>
$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();)
</code>

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

==== Options ====

  * **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 [[http://forum.akelos.org/discussion/121/belongsto-countercache-setting-problem/|not yet implemented]]

Option examples
<code php>
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'"));
</code>