public
Created

  • Download Gist
belongs_to.html
HTML
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
 
<h1 id="label-.belongs_to">.belongs_to</h1>
 
<p>(from gem activerecord-2.3.14)</p>
 
<h3 id="label-Implementation+from+ActiveRecord%3A%3AAssociations%3A%3AClassMethods">Implementation from ActiveRecord::Associations::ClassMethods</h3>
<hr style="height: 1px">
 
<pre>belongs_to(association_id, options = {})</pre>
<hr style="height: 1px">
 
<p>Specifies a one-to-one association with another class. This method should
only be used if this class contains the foreign key. If the other class
contains the foreign key, then you should use <code>has_one</code> instead.
See also ActiveRecord::Associations::ClassMethods’s overview on when to
use <code>has_one</code> and when to use <code>belongs_to</code>.</p>
 
<p>Methods will be added for retrieval and query for a single associated
object, for which this object holds an id:</p>
<dl class="rdoc-list label-list"><dt>association(force_reload = false)
<dd>
<p>Returns the associated object. <code>nil</code> is returned if none is
found.</p>
</dd><dt>association=(associate)
<dd>
<p>Assigns the associate object, extracts the primary key, and sets it as the
foreign key.</p>
</dd><dt>build_association(attributes = {})
<dd>
<p>Returns a new object of the associated type that has been instantiated with
<code>attributes</code> and linked to this object through a foreign key,
but has not yet been saved.</p>
</dd><dt>create_association(attributes = {})
<dd>
<p>Returns a new object of the associated type that has been instantiated with
<code>attributes</code>, linked to this object through a foreign key, and
that has already been saved (if it passed the validation).</p>
</dd></dl>
 
<p>(<code>association</code> is replaced with the symbol passed as the first
argument, so <code>belongs_to :author</code> would add among others
<code>author.nil?</code>.)</p>
 
<h3 id="label-Example">Example</h3>
 
<p>A Post class declares <code>belongs_to :author</code>, which will add:</p>
<ul><li>
<p><code>Post#author</code> (similar to <code>Author.find(author_id)</code>)</p>
</li><li>
<p><code>Post#author=(author)</code> (similar to <code>post.author_id =
author.id</code>)</p>
</li><li>
<p><code>Post#author?</code> (similar to <code>post.author ==
some_author</code>)</p>
</li><li>
<p><code>Post#build_author</code> (similar to <code>post.author =
Author.new</code>)</p>
</li><li>
<p><code>Post#create_author</code> (similar to <code>post.author = Author.new;
post.author.save; post.author</code>)</p>
</li></ul>
 
<p>The declaration can also include an options hash to specialize the behavior
of the association.</p>
 
<h3 id="label-Options">Options</h3>
<dl class="rdoc-list label-list"><dt>:class_name
<dd>
<p>Specify the class name of the association. Use it only if that name can’t
be inferred from the association name. So <code>has_one :author</code> 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.</p>
</dd><dt>:conditions
<dd>
<p>Specify the conditions that the associated object must meet in order to be
included as a <code>WHERE</code> SQL fragment, such as <code>authorized =
1</code>.</p>
</dd><dt>:select
<dd>
<p>By default, this is <code>*</code> as in <code>SELECT * FROM</code>, but
can be changed if, for example, you want to do a join but not include the
joined columns. Do not forget to include the primary and foreign keys,
otherwise it will raise an error.</p>
</dd><dt>:foreign_key
<dd>
<p>Specify the foreign key used for the association. By default this is
guessed to be the name of the association with an “_id” suffix. So a
class that defines a <code>belongs_to :person</code> association will use
“person_id” as the default <code>:foreign_key</code>. Similarly,
<code>belongs_to :favorite_person, :class_name =&gt;
&quot;Person&quot;</code> will use a foreign key of
“favorite_person_id”.</p>
</dd><dt>:primary_key
<dd>
<p>Specify the method that returns the primary key of associated object used
for the association. By default this is id.</p>
</dd><dt>:dependent
<dd>
<p>If set to <code>:destroy</code>, the associated object is destroyed when
this object is. If set to <code>:delete</code>, the associated object is
deleted <strong>without</strong> calling its destroy method. This option
should not be specified when <code>belongs_to</code> is used in conjunction
with a <code>has_many</code> relationship on another class because of the
potential to leave orphaned records behind.</p>
</dd><dt>:counter_cache
<dd>
<p>Caches the number of belonging objects on the associate class through the
use of <code>increment_counter</code> and <code>decrement_counter</code>.
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
<code>#{table_name}_count</code> (such as <code>comments_count</code> for a
belonging Comment class) is used on the associate class (such as a Post
class). You can also specify a custom counter cache column by providing a
column name instead of a <code>true</code>/<code>false</code> value to this
option (e.g., <code>:counter_cache =&gt; :my_custom_counter</code>.) Note:
Specifying a counter cache will add it to that model’s list of readonly
attributes using <code>attr_readonly</code>.</p>
</dd><dt>:include
<dd>
<p>Specify second-order associations that should be eager loaded when this
object is loaded.</p>
</dd><dt>:polymorphic
<dd>
<p>Specify this association is a polymorphic association by passing
<code>true</code>. Note: If you’ve enabled the counter cache, then you
may want to add the counter cache attribute to the
<code>attr_readonly</code> list in the associated classes (e.g. <code>class
Post; attr_readonly :comments_count; end</code>).</p>
</dd><dt>:readonly
<dd>
<p>If true, the associated object is readonly through the association.</p>
</dd><dt>:validate
<dd>
<p>If false, don’t validate the associated objects when saving the parent
object. <code>false</code> by default.</p>
</dd><dt>:autosave
<dd>
<p>If true, always save the associated object or destroy it if marked for
destruction, when saving the parent object. Off by default.</p>
</dd><dt>:touch
<dd>
<p>If true, the associated object will be touched (the updated_at/on
attributes set to now) when this record is either saved or destroyed. If
you specify a symbol, that attribute will be updated with the current time
instead of the updated_at/on attribute.</p>
</dd></dl>
 
<p>Option examples:</p>
 
<pre class="ruby"><span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">firm</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;client_of&quot;</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">person</span>, :<span class="ruby-identifier">primary_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;name&quot;</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;person_name&quot;</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">author</span>, :<span class="ruby-identifier">class_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;Person&quot;</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;author_id&quot;</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">valid_coupon</span>, :<span class="ruby-identifier">class_name</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;Coupon&quot;</span>, :<span class="ruby-identifier">foreign_key</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">&quot;coupon_id&quot;</span>,
:<span class="ruby-identifier">conditions</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-string">'discounts &gt; #{payments_count}'</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">attachable</span>, :<span class="ruby-identifier">polymorphic</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">project</span>, :<span class="ruby-identifier">readonly</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">post</span>, :<span class="ruby-identifier">counter_cache</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">company</span>, :<span class="ruby-identifier">touch</span> =<span class="ruby-operator">&gt;</span> <span class="ruby-keyword">true</span>
<span class="ruby-identifier">belongs_to</span> :<span class="ruby-identifier">company</span>, :<span class="ruby-identifier">touch</span> =<span class="ruby-operator">&gt;</span> :<span class="ruby-identifier">employees_last_updated_at</span>
</pre>
 
<p>(from gem activerecord-2.3.14)</p>
 
<h3 id="label-Implementation+from+ActiveRecord%3A%3AConnectionAdapters%3A%3ATable">Implementation from ActiveRecord::ConnectionAdapters::Table</h3>
<hr style="height: 1px">
 
<pre>belongs_to(*args)</pre>
<hr style="height: 1px">
 
<p>(from gem activerecord-2.3.14)</p>
 
<h3 id="label-Implementation+from+ActiveRecord%3A%3AConnectionAdapters%3A%3ATableDefinition">Implementation from ActiveRecord::ConnectionAdapters::TableDefinition</h3>
<hr style="height: 1px">
 
<pre>belongs_to(*args)</pre>
<hr style="height: 1px">

Please sign in to comment on this gist.

Something went wrong with that request. Please try again.