--- !ruby/object:RI::MethodDescription 
aliases: []

block_params: 
comment: 
- !ruby/struct:SM::Flow::P 
  body: Associates two classes via an intermediate join table. Unless the join table is explicitly specified as an option, it is guessed using the lexical order of the class names. So a join between Developer and Project will give the default join table name of &quot;developers_projects&quot; because &quot;D&quot; outranks &quot;P&quot;. Note that this precedence is calculated using the <tt>&lt;</tt> operator for String. This means that if the strings are of different lengths, and the strings are equal when compared up to the shortest length, then the longer string is considered of higher lexical precedence than the shorter one. For example, one would expect the tables &quot;paper_boxes&quot; and &quot;papers&quot; to generate a join table name of &quot;papers_paper_boxes&quot; because of the length of the name &quot;paper_boxes&quot;, but it in fact generates a join table name of &quot;paper_boxes_papers&quot;. Be aware of this caveat, and use the custom <tt>:join_table</tt> option if you need to.
- !ruby/struct:SM::Flow::P 
  body: "Deprecated: Any additional fields added to the join table will be placed as attributes when pulling records out through <tt>has_and_belongs_to_many</tt> associations. Records returned from join tables with additional attributes will be marked as readonly (because we can't save changes to the additional attributes). It's strongly recommended that you upgrade any associations with attributes to a real join model (see introduction)."
- !ruby/struct:SM::Flow::P 
  body: "Adds the following methods for retrieval and query: <tt>collection</tt> is replaced with the symbol passed as the first argument, so <tt>has_and_belongs_to_many :categories</tt> would add among others <tt>categories.empty?</tt>."
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection(force_reload = false)</tt> - Returns an array of all the associated objects. An empty array is returned if none are found.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection&lt;&lt;(object, ...)</tt> - Adds one or more objects to the collection by creating associations in the join table (<tt>collection.push</tt> and <tt>collection.concat</tt> are aliases to this method).
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.delete(object, ...)</tt> - Removes one or more objects from the collection by removing their associations from the join table. This does not destroy the objects.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection=objects</tt> - Replaces the collection's content by deleting and adding objects as appropriate.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection_singular_ids</tt> - Returns an array of the associated objects' ids.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection_singular_ids=ids</tt> - Replace the collection by the objects identified by the primary keys in <tt>ids</tt>.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.clear</tt> - Removes every object from the collection. This does not destroy the objects.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.empty?</tt> - Returns <tt>true</tt> if there are no associated objects.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.size</tt> - Returns the number of associated objects.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.find(id)</tt> - Finds an associated object responding to the <tt>id</tt> and that meets the condition that it has to be associated with this object.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.build(attributes = {})</tt> - Returns a new object of the collection type that has been instantiated with <tt>attributes</tt> and linked to this object through the join table, but has not yet been saved.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>collection.create(attributes = {})</tt> - Returns a new object of the collection type that has been instantiated with <tt>attributes</tt>, linked to this object through the join table, and that has already been saved (if it passed the validation).
  type: :BULLET
- !ruby/struct:SM::Flow::P 
  body: "Example: A Developer class declares <tt>has_and_belongs_to_many :projects</tt>, which will add:"
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects&lt;&lt;</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.delete</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects=</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#project_ids</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#project_ids=</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.clear</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.empty?</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.size</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.find(id)</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.build</tt> (similar to <tt>Project.new(&quot;project_id&quot; =&gt; id)</tt>)
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>Developer#projects.create</tt> (similar to <tt>c = Project.new(&quot;project_id&quot; =&gt; id); c.save; c</tt>)
  type: :BULLET
- !ruby/struct:SM::Flow::P 
  body: The declaration may include an options hash to specialize the behavior of the association.
- !ruby/struct:SM::Flow::P 
  body: "Options are:"
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:class_name</tt> - Specify the class name of the association. Use it only if that name can't be inferred from the association name. So <tt>has_and_belongs_to_many :projects</tt> will by default be linked to the Project class, but if the real class name is SuperProject, you'll have to specify it with this option.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: "<tt>:join_table</tt> - Specify the name of the join table if the default based on lexical order isn't what you want. WARNING: If you're overwriting the table name of either class, the <tt>table_name</tt> method MUST be declared underneath any <tt>has_and_belongs_to_many</tt> declaration in order to work."
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:foreign_key</tt> - Specify the foreign key used for the association. By default this is guessed to be the name of this class in lower-case and &quot;_id&quot; suffixed. So a Person class that makes a <tt>has_and_belongs_to_many</tt> association will use &quot;person_id&quot; as the default <tt>:foreign_key</tt>.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:association_foreign_key</tt> - Specify the association foreign key used for the association. By default this is guessed to be the name of the associated class in lower-case and &quot;_id&quot; suffixed. So if the associated class is Project, the <tt>has_and_belongs_to_many</tt> association will use &quot;project_id&quot; as the default <tt>:association_foreign_key</tt>.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:conditions</tt> - Specify the conditions that the associated object must meet in order to be included as a <tt>WHERE</tt> SQL fragment, such as <tt>authorized = 1</tt>. Record creations from the association are scoped if a hash is used. <tt>has_many :posts, :conditions =&gt; {:published =&gt; true}</tt> will create published posts with <tt>@blog.posts.create</tt> or <tt>@blog.posts.build</tt>.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:order</tt> - Specify the order in which the associated objects are returned as an <tt>ORDER BY</tt> SQL fragment, such as <tt>last_name, first_name DESC</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:uniq</tt> - If true, duplicate associated objects will be ignored by accessors and query methods.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:finder_sql</tt> - Overwrite the default generated SQL statement used to fetch the association with a manual statement
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:delete_sql</tt> - Overwrite the default generated SQL statement used to remove links between the associated classes with a manual statement.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:insert_sql</tt> - Overwrite the default generated SQL statement used to add links between the associated classes with a manual statement.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:extend</tt> - Anonymous module for extending the proxy, see &quot;Association extensions&quot;.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:include</tt> - Specify second-order associations that should be eager loaded when the collection is loaded.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:group</tt> - An attribute name by which the result should be grouped. Uses the <tt>GROUP BY</tt> SQL-clause.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:limit</tt> - An integer determining the limit on the number of rows that should be returned.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:offset</tt> - An integer determining the offset from where the rows should be fetched. So at 5, it would skip the first 4 rows.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:select</tt> - By default, this is <tt>*</tt> as in <tt>SELECT * FROM</tt>, 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.
  - !ruby/struct:SM::Flow::LI 
    label: "*"
    body: <tt>:readonly</tt> - If true, all the associated objects are readonly through the association.
  type: :BULLET
- !ruby/struct:SM::Flow::P 
  body: "Option examples:"
- !ruby/struct:SM::Flow::VERB 
  body: "  has_and_belongs_to_many :projects\n  has_and_belongs_to_many :projects, :include =&gt; [ :milestones, :manager ]\n  has_and_belongs_to_many :nations, :class_name =&gt; &quot;Country&quot;\n  has_and_belongs_to_many :categories, :join_table =&gt; &quot;prods_cats&quot;\n  has_and_belongs_to_many :categories, :readonly =&gt; true\n  has_and_belongs_to_many :active_projects, :join_table =&gt; 'developers_projects', :delete_sql =&gt;\n  'DELETE FROM developers_projects WHERE active=1 AND developer_id = #{id} AND project_id = #{record.id}'\n"
full_name: ActiveRecord::Associations::ClassMethods#has_and_belongs_to_many
is_singleton: false
name: has_and_belongs_to_many
params: (association_id, options = {}, &extension)
visibility: public
