Skip to content

Commit

Permalink
Formatting and grammatical fixes for the acts_as_* documentation [sea…
Browse files Browse the repository at this point in the history 
…nhussey, kampers] Closes #9107

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7366 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information
@NZKoz
NZKoz committed Aug 28, 2007
1 parent 5840108 commit 5972fd4
Show file tree
Hide file tree
Showing 3 changed files with 30 additions and 30 deletions.
16 changes: 8 additions & 8 deletions activerecord/lib/active_record/acts/list.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ def self.included(base)
base.extend(ClassMethods)
end

# This act provides the capabilities for sorting and reordering a number of objects in a list.
# The class that has this specified needs to have a "position" column defined as an integer on
# This +acts_as+ extension provides the capabilities for sorting and reordering a number of objects in a list.
# The class that has this specified needs to have a +position+ column defined as an integer on
# the mapped database table.
#
# Todo list example:
Expand All @@ -25,9 +25,9 @@ def self.included(base)
module ClassMethods
# Configuration options are:
#
# * +column+ - specifies the column name to use for keeping the position integer (default: position)
# * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach "_id"
# (if that hasn't been already) and use that as the foreign key restriction. It's also possible
# * +column+ - specifies the column name to use for keeping the position integer (default: +position+)
# * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach <tt>_id</tt>
# (if it hasn't already been added) and use that as the foreign key restriction. It's also possible
# to give it an entire string that is interpolated if you need a tighter scope than just a foreign key.
# Example: <tt>acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0'</tt>
def acts_as_list(options = {})
Expand Down Expand Up @@ -71,7 +71,7 @@ def position_column

# All the methods available to a record that has had <tt>acts_as_list</tt> specified. Each method works
# by assuming the object to be the item in the list, so <tt>chapter.move_lower</tt> would move that chapter
# lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return true if that chapter is
# lower in the list of all chapters. Likewise, <tt>chapter.first?</tt> would return +true+ if that chapter is
# the first in the list of all chapters.
module InstanceMethods
# Insert the item at the given position (defaults to the top position of 1).
Expand Down Expand Up @@ -136,13 +136,13 @@ def decrement_position
update_attribute position_column, self.send(position_column).to_i - 1
end

# Return true if this object is the first in the list.
# Return +true+ if this object is the first in the list.
def first?
return false unless in_list?
self.send(position_column) == 1
end

# Return true if this object is the last in the list.
# Return +true+ if this object is the last in the list.
def last?
return false unless in_list?
self.send(position_column) == bottom_position_in_list
Expand Down
26 changes: 13 additions & 13 deletions activerecord/lib/active_record/acts/nested_set.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@ def self.included(base)
base.extend(ClassMethods)
end

# This acts provides Nested Set functionality. Nested Set is similiar to Tree, but with
# This +acts_as+ extension provides Nested Set functionality. Nested Set is similiar to Tree, but with
# the added feature that you can select the children and all of their descendents with
# a single query. A good use case for this is a threaded post system, where you want
# to display every reply to a comment without multiple selects.
#
# A google search for "Nested Set" should point you in the direction to explain the
# A Google search for "Nested Set" should point you to in the right direction to explain the
# database theory. I figured out a bunch of this from
# http://threebit.net/tutorials/nestedset/tutorial1.html
#
Expand Down Expand Up @@ -55,27 +55,27 @@ def self.included(base)
# So, to get all children of an entry, you
# SELECT * WHERE CHILD.LEFT IS BETWEEN PARENT.LEFT AND PARENT.RIGHT
#
# To get the count, it's (LEFT - RIGHT + 1)/2, etc.
# To get the count, it's <tt>(LEFT - RIGHT + 1)/2</tt>, etc.
#
# To get the direct parent, it falls back to using the PARENT_ID field.
# To get the direct parent, it falls back to using the +PARENT_ID+ field.
#
# There are instance methods for all of these.
#
# The structure is good if you need to group things together; the downside is that
# keeping data integrity is a pain, and both adding and removing an entry
# require a full table write.
#
# This sets up a before_destroy trigger to prune the tree correctly if one of its
# This sets up a +before_destroy+ callback to prune the tree correctly if one of its
# elements gets deleted.
#
module ClassMethods
# Configuration options are:
#
# * +parent_column+ - specifies the column name to use for keeping the position integer (default: parent_id)
# * +left_column+ - column name for left boundry data, default "lft"
# * +right_column+ - column name for right boundry data, default "rgt"
# * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach "_id"
# (if that hasn't been already) and use that as the foreign key restriction. It's also possible
# * +parent_column+ - specifies the column name to use for keeping the position integer (default: +parent_id+)
# * +left_column+ - column name for left boundry data, default +lft+
# * +right_column+ - column name for right boundry data, default +rgt+
# * +scope+ - restricts what is to be considered a list. Given a symbol, it'll attach <tt>_id</tt>
# (if it hasn't already been added) and use that as the foreign key restriction. It's also possible
# to give it an entire string that is interpolated if you need a tighter scope than just a foreign key.
# Example: <tt>acts_as_list :scope => 'todo_list_id = #{todo_list_id} AND completed = 0'</tt>
def acts_as_nested_set(options = {})
Expand Down Expand Up @@ -115,19 +115,19 @@ def parent_column() "#{configuration[:parent_column]}" end
end

module InstanceMethods
# Returns true is this is a root node.
# Returns +true+ is this is a root node.
def root?
parent_id = self[parent_column]
(parent_id == 0 || parent_id.nil?) && (self[left_col_name] == 1) && (self[right_col_name] > self[left_col_name])
end

# Returns true is this is a child node
# Returns +true+ is this is a child node
def child?
parent_id = self[parent_column]
!(parent_id == 0 || parent_id.nil?) && (self[left_col_name] > 1) && (self[right_col_name] > self[left_col_name])
end

# Returns true if we have no idea what this is
# Returns +true+ if we have no idea what this is
def unknown?
!root? && !child?
end
Expand Down
18 changes: 9 additions & 9 deletions activerecord/lib/active_record/acts/tree.rb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ def self.included(base)
base.extend(ClassMethods)
end

# Specify this act if you want to model a tree structure by providing a parent association and a children
# association. This act requires that you have a foreign key column, which by default is called parent_id.
# Specify this +acts_as+ extension if you want to model a tree structure by providing a parent association and a children
# association. This requires that you have a foreign key column, which by default is called +parent_id+.
#
# class Category < ActiveRecord::Base
# acts_as_tree :order => "name"
Expand All @@ -28,17 +28,17 @@ def self.included(base)
# root.children.first.children.first # => subchild1
#
# In addition to the parent and children associations, the following instance methods are added to the class
# after specifying the act:
# * siblings : Returns all the children of the parent, excluding the current node ([ subchild2 ] when called from subchild1)
# * self_and_siblings : Returns all the children of the parent, including the current node ([ subchild1, subchild2 ] when called from subchild1)
# * ancestors : Returns all the ancestors of the current node ([child1, root] when called from subchild2)
# * root : Returns the root of the current node (root when called from subchild2)
# after calling <tt>acts_as_tree</tt>:
# * <tt>siblings</tt> - Returns all the children of the parent, excluding the current node (<tt>[subchild2]</tt> when called on <tt>subchild1</tt>)
# * <tt>self_and_siblings</tt> - Returns all the children of the parent, including the current node (<tt>[subchild1, subchild2]</tt> when called on <tt>subchild1</tt>)
# * <tt>ancestors</tt> - Returns all the ancestors of the current node (<tt>[child1, root]</tt> when called on <tt>subchild2</tt>)
# * <tt>root</tt> - Returns the root of the current node (<tt>root</tt> when called on <tt>subchild2</tt>)
module ClassMethods
# Configuration options are:
#
# * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: parent_id)
# * <tt>foreign_key</tt> - specifies the column name to use for tracking of the tree (default: +parent_id+)
# * <tt>order</tt> - makes it possible to sort the children according to this SQL snippet.
# * <tt>counter_cache</tt> - keeps a count in a children_count column if set to true (default: false).
# * <tt>counter_cache</tt> - keeps a count in a +children_count+ column if set to +true+ (default: +false+).
def acts_as_tree(options = {})
configuration = { :foreign_key => "parent_id", :order => nil, :counter_cache => nil }
configuration.update(options) if options.is_a?(Hash)
Expand Down

0 comments on commit 5972fd4

Please sign in to comment.