Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Cleaned README

  • Loading branch information...
commit e3311f895397a35f689b4ce0e06b41a77d16dc21 1 parent bbc1928
Stefan Kroes authored

Showing 1 changed file with 3 additions and 289 deletions. Show diff stats Hide diff stats

  1. +3 289 README.rdoc
292 README.rdoc
Source Rendered
... ... @@ -1,305 +1,19 @@
1   -= Ancestry
2   -
3   -Ancestry is a gem/plugin that allows the records of a Ruby on Rails ActiveRecord model to be organised as a tree structure (or hierarchy). It uses a single, intuitively formatted database column, using a variation on the materialised path pattern. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single sql query. Additional features are STI support, scopes, depth caching, depth constraints, easy migration from older plugins/gems, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.
  1 += Tapestry
4 2
5 3 = Installation
6 4
7   -To apply Ancestry to any ActiveRecord model, follow these simple steps:
8   -
9   -1. Install
10   - - <b>Rails 2</b>
11   - - Add to config/environment.rb: <b>config.gem 'ancestry'</b>
12   - - Install required gems: <b>sudo rake gems:install</b>
13   - - <b>Rails 3</b>
14   - - Add to Gemfile: <b>gem 'ancestry'</b>
15   - - Install required gems: <b>bundle install</b>
16   -
17   -2. Add ancestry column to your table
18   - - Create migration: <b>rails g migration add_ancestry_to_[table] ancestry:string</b>
19   - - Add index to migration: <b>add_index [table], :ancestry</b> (UP) / <b>remove_index [table], :ancestry</b> (DOWN)
20   - - Migrate your database: <b>rake db:migrate</b>
21   -
22   -3. Add ancestry to your model
23   - - Add to app/models/[model].rb: <b>has_ancestry</b>
24   -
25   -Your model is now a tree!
26   -
27   -= Using acts_as_tree instead of has_ancestry
28   -
29   -In version 1.2.0 the <b>acts_as_tree</b> method was <b>renamed to has_ancestry</b> in order to allow usage of both the acts_as_tree gem and the ancestry gem in a single application. To not break backwards compatibility, the has_ancestry method is aliased with acts_as_tree if ActiveRecord::Base does not respond to acts_as_tree. acts_as_tree will continue to be supported in the future as I personally prefer it.
30   -
31   -= Organising records into a tree
32   -
33   -You can use the parent attribute to organise your records into a tree. If you have the id of the record you want to use as a parent and don't want to fetch it, you can also use parent_id. Like any virtual model attributes, parent and parent_id can be set using parent= and parent_id= on a record or by including them in the hash passed to new, create, create!, update_attributes and update_attributes!. For example:
34   -
35   - TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')
36   -
37   -You can also create children through the children relation on a node:
38   -
39   - node.children.create :name => 'Stinky'
40   -
41   -= Navigating your tree
42   -
43   -To navigate an Ancestry model, use the following methods on any instance / record:
44   -
45   - parent Returns the parent of the record, nil for a root node
46   - parent_id Returns the id of the parent of the record, nil for a root node
47   - root Returns the root of the tree the record is in, self for a root node
48   - root_id Returns the id of the root of the tree the record is in
49   - is_root? Returns true if the record is a root node, false otherwise
50   - ancestor_ids Returns a list of ancestor ids, starting with the root id and ending with the parent id
51   - ancestors Scopes the model on ancestors of the record
52   - path_ids Returns a list the path ids, starting with the root id and ending with the node's own id
53   - path Scopes model on path records of the record
54   - children Scopes the model on children of the record
55   - child_ids Returns a list of child ids
56   - has_children? Returns true if the record has any children, false otherwise
57   - is_childless? Returns true is the record has no childen, false otherwise
58   - siblings Scopes the model on siblings of the record, the record itself is included
59   - sibling_ids Returns a list of sibling ids
60   - has_siblings? Returns true if the record's parent has more than one child
61   - is_only_child? Returns true if the record is the only child of its parent
62   - descendants Scopes the model on direct and indirect children of the record
63   - descendant_ids Returns a list of a descendant ids
64   - subtree Scopes the model on descendants and itself
65   - subtree_ids Returns a list of all ids in the record's subtree
66   - depth Return the depth of the node, root nodes are at depth 0
67   -
68   -= Options for has_ancestry
69   -
70   -The has_ancestry methods supports the following options:
71   -
72   - :ancestry_column Pass in a symbol to store ancestry in a different column
73   - :orphan_strategy Instruct Ancestry what to do with children of a node that is destroyed:
74   - :destroy All children are destroyed as well (default)
75   - :rootify The children of the destroyed node become root nodes
76   - :restrict An AncestryException is raised if any children exist
77   - :cache_depth Cache the depth of each node in the 'ancestry_depth' column (default: false)
78   - If you turn depth_caching on for an existing model:
79   - - Migrate: add_column [table], :ancestry_depth, :integer, :default => 0
80   - - Build cache: TreeNode.rebuild_depth_cache!
81   - :depth_cache_column Pass in a symbol to store depth cache in a different column
82   - :primary_key_format Supply a regular expression that matches the format of your primary key.
83   - By default, primary keys only match integers ([0-9]+).
84   -
85   -= (Named) Scopes
86   -
87   -Where possible, the navigation methods return scopes instead of records, this means additional ordering, conditions, limits, etc. can be applied and that the result can be either retrieved, counted or checked for existence. For example:
88   -
89   - node.children.exists?(:name => 'Mary')
90   - node.subtree.all(:order => :name, :limit => 10).each do; ...; end
91   - node.descendants.count
92   -
93   -For convenience, a couple of named scopes are included at the class level:
94   -
95   - roots Root nodes
96   - ancestors_of(node) Ancestors of node, node can be either a record or an id
97   - children_of(node) Children of node, node can be either a record or an id
98   - descendants_of(node) Descendants of node, node can be either a record or an id
99   - subtree_of(node) Subtree of node, node can be either a record or an id
100   - siblings_of(node) Siblings of node, node can be either a record or an id
101   -
102   -Thanks to some convenient rails magic, it is even possible to create nodes through the children and siblings scopes:
103   -
104   - node.children.create
105   - node.siblings.create!
106   - TestNode.children_of(node_id).new
107   - TestNode.siblings_of(node_id).create
108   -
109   -= Selecting nodes by depth
110   -
111   -When depth caching is enabled (see has_ancestry options), five more named scopes can be used to select nodes on their depth:
112   -
113   - before_depth(depth) Return nodes that are less deep than depth (node.depth < depth)
114   - to_depth(depth) Return nodes up to a certain depth (node.depth <= depth)
115   - at_depth(depth) Return nodes that are at depth (node.depth == depth)
116   - from_depth(depth) Return nodes starting from a certain depth (node.depth >= depth)
117   - after_depth(depth) Return nodes that are deeper than depth (node.depth > depth)
118   -
119   -The depth scopes are also available through calls to descendants, descendant_ids, subtree, subtree_ids, path and ancestors. In this case, depth values are interpreted relatively. Some examples:
120   -
121   - node.subtree(:to_depth => 2) Subtree of node, to a depth of node.depth + 2 (self, children and grandchildren)
122   - node.subtree.to_depth(5) Subtree of node to an absolute depth of 5
123   - node.descendants(:at_depth => 2) Descendant of node, at depth node.depth + 2 (grandchildren)
124   - node.descendants.at_depth(10) Descendants of node at an absolute depth of 10
125   - node.ancestors.to_depth(3) The oldest 4 ancestors of node (its root and 3 more)
126   - node.path(:from_depth => -2) The node's grandparent, parent and the node itself
127   -
128   - node.ancestors(:from_depth => -6, :to_depth => -4)
129   - node.path.from_depth(3).to_depth(4)
130   - node.descendants(:from_depth => 2, :to_depth => 4)
131   - node.subtree.from_depth(10).to_depth(12)
132   -
133   -Please note that depth constraints cannot be passed to ancestor_ids and path_ids. The reason for this is that both these relations can be fetched directly from the ancestry column without performing a database query. It would require an entirely different method of applying the depth constraints which isn't worth the effort of implementing. You can use ancestors(depth_options).map(&:id) or ancestor_ids.slice(min_depth..max_depth) instead.
134   -
135   -= STI support
136   -
137   -Ancestry works fine with STI. Just create a STI inheritance hierarchy and build an Ancestry tree from the different classes/models. All Ancestry relations that where described above will return nodes of any model type. If you do only want nodes of a specific subclass you'll have to add a condition on type for that.
138   -
139   -= Arrangement
140   -
141   -Ancestry can arrange an entire subtree into nested hashes for easy navigation after retrieval from the database. TreeNode.arrange could for example return:
142   -
143   - { #<TreeNode id: 100018, name: "Stinky", ancestry: nil>
144   - => { #<TreeNode id: 100019, name: "Crunchy", ancestry: "100018">
145   - => { #<TreeNode id: 100020, name: "Squeeky", ancestry: "100018/100019">
146   - => {}
147   - }
148   - }
149   - }
150   -
151   -The arrange method also works on a scoped class, for example:
152   -
153   - TreeNode.find_by_name('Crunchy').subtree.arrange
154   -
155   -The arrange method takes ActiveRecord find options. If you want your hashes to be ordered, you should pass the order to the arrange method instead of to the scope. This only works for Ruby 1.9 and later since before that hashes weren't ordered. For example:
156   -
157   - TreeNode.find_by_name('Crunchy').subtree.arrange(:order => :name)
158   -
159   -= Migrating from plugin that uses parent_id column
160   -
161   -Most current tree plugins use a parent_id column (has_ancestry, awesome_nested_set, better_nested_set, acts_as_nested_set). With ancestry its easy to migrate from any of these plugins, to do so, use the build_ancestry_from_parent_ids! method on your ancestry model. These steps provide a more detailed explanation:
162   -
163   -1. Add ancestry column to your table
164   - - Create migration: <b>rails g migration add_ancestry_to_[table] ancestry:string</b>
165   - - Add index to migration: <b>add_index [table], :ancestry</b> (UP) / <b>remove_index [table], :ancestry</b> (DOWN)
166   - - Migrate your database: <b>rake db:migrate</b>
167   -
168   -2. Remove old tree plugin or gem and add in Ancestry
169   - - Remove plugin: rm -Rf vendor/plugins/[old plugin]
170   - - Remove gem config line from environment.rb: config.gem [old gem]
171   - - Add Ancestry to environment.rb: config.gem :ancestry
172   - - See 'Installation' for more info on installing and configuring gems
173   -
174   -3. Change your model
175   - - Remove any macros required by old plugin/gem from app/models/[model].rb
176   - - Add to app/models/[model].rb: <b>has_ancestry</b>
177   -
178   -4. Generate ancestry columns
179   - - In './script.console': <b>[model].build_ancestry_from_parent_ids!</b>
180   - - Make sure it worked ok: <b>[model].check_ancestry_integrity!</b>
181   -
182   -5. Change your code
183   - - Most tree calls will probably work fine with ancestry
184   - - Others must be changed or proxied
185   - - Check if all your data is intact and all tests pass
186   -
187   -6. Drop parent_id column:
188   - - Create migration: <b>rails g migration remove_parent_id_from_[table]</b>
189   - - Add to migration: <b>remove_column [table], :parent_id</b> (UP) / <b>add_column [table], :parent_id, :integer</b> (DOWN)
190   - - Migrate your database: <b>rake db:migrate</b>
191   -
192   -= Integrity checking and restoration
193   -
194   -I don't see any way Ancestry tree integrity could get compromised without explicitly setting cyclic parents or invalid ancestry and circumventing validation with update_attribute, if you do, please let me know.
195   -
196   -Ancestry includes some methods for detecting integrity problems and restoring integrity just to be sure. To check integrity use: [Model].check_ancestry_integrity!. An AncestryIntegrityException will be raised if there are any problems. You can also specify :report => :list to return an array of exceptions or :report => :echo to echo any error messages. To restore integrity use: [Model].restore_ancestry_integrity!.
197   -
198   -For example, from IRB:
199   -
200   - >> stinky = TreeNode.create :name => 'Stinky'
201   - $ #<TreeNode id: 1, name: "Stinky", ancestry: nil>
202   - >> squeeky = TreeNode.create :name => 'Squeeky', :parent => stinky
203   - $ #<TreeNode id: 2, name: "Squeeky", ancestry: "1">
204   - >> stinky.update_attribute :parent, squeeky
205   - $ true
206   - >> TreeNode.all
207   - $ [#<TreeNode id: 1, name: "Stinky", ancestry: "1/2">, #<TreeNode id: 2, name: "Squeeky", ancestry: "1/2/1">]
208   - >> TreeNode.check_ancestry_integrity!
209   - !! Ancestry::AncestryIntegrityException: Conflicting parent id in node 1: 2 for node 1, expecting nil
210   - >> TreeNode.restore_ancestry_integrity!
211   - $ [#<TreeNode id: 1, name: "Stinky", ancestry: 2>, #<TreeNode id: 2, name: "Squeeky", ancestry: nil>]
212   -
213   -Additionally, if you think something is wrong with your depth cache:
214   -
215   - >> TreeNode.rebuild_depth_cache!
216   -
217 5 = Tests
218 6
219   -The Ancestry gem comes with a unit test suite consisting of about 1800 assertions in about 30 tests. It takes about 10 seconds to run on sqlite. To run it yourself check out the repository from GitHub, copy test/database.example.yml to test/database.yml and type 'rake'. You can pass rake style options for ActiveRecord version to test against (e.g. ar=3.0.1) and database to test against (e.g. db=mysql). The test suite is located in test/has_ancestry_test.rb.
220   -
221 7 = Internals
222 8
223   -As can be seen in the previous section, Ancestry stores a path from the root to the parent for every node. This is a variation on the materialised path database pattern. It allows Ancestry to fetch any relation (siblings, descendants, etc.) in a single sql query without the complicated algorithms and incomprehensibility associated with left and right values. Additionally, any inserts, deletes and updates only affect nodes within the affected node's own subtree.
224   -
225   -In the example above, the ancestry column is created as a string. This puts a limitation on the depth of the tree of about 40 or 50 levels, which I think may be enough for most users. To increase the maximum depth of the tree, increase the size of the string that is being used or change it to a text to remove the limitation entirely. Changing it to a text will however decrease performance because an index cannot be put on the column in that case.
226   -
227   -The materialised path pattern requires Ancestry to use a 'like' condition in order to fetch descendants. This should not be particularly slow however since the the condition never starts with a wildcard which allows the DBMS to use the column index. If you have any data on performance with a large number of records, please drop me line.
228   -
229 9 = Version history
230 10
231   -The latest version of ancestry is recommended. The three numbers of each version numbers are respectively the major, minor and patch versions. We started with major version 1 because it looks so much better and ancestry was already quite mature and complete when it was published. The major version is only bumped when backwards compatibility is broken. The minor version is bumped when new features are added. The patch version is bumped when bugs are fixed.
232   -
233   -- Version 1.2.3 (2010-10-28)
234   - - Fixed error with determining ActiveRecord version
235   - - Added option to specify :primary_key_format (thanks goes to rolftimmermans)
236   -- Version 1.2.2 (2010-10-24)
237   - - Fixed all deprecation warnings for rails 3.0.X
238   - - Added :report option to check_ancestry_integrity!
239   - - Changed ActiveRecord dependency to 2.2.2
240   - - Tested and fixed for ruby 1.8.7 and 1.9.2
241   - - Changed usage of update_attributes to update_attribute to allow ancestry column protection
242   -- Version 1.2.0 (2009-11-07)
243   - - Removed some duplication in has_ancestry
244   - - Cleaned up plugin pattern according to http://yehudakatz.com/2009/11/12/better-ruby-idioms/
245   - - Moved parts of ancestry into seperate files
246   - - Made it possible to pass options into the arrange method
247   - - Renamed acts_as_tree to has_ancestry
248   - - Aliased has_ancestry as acts_as_tree if acts_as_tree is available
249   - - Added subtree_of scope
250   - - Updated ordered_by_ancestry scope to support Microsoft SQL Server
251   - - Added empty hash as parameter to exists? calls for older ActiveRecord versions
252   -- Version 1.1.4 (2009-11-07)
253   - - Thanks to a patch from tom taylor, Ancestry now works with different primary keys
254   -- Version 1.1.3 (2009-11-01)
255   - - Fixed a pretty bad bug where several operations took far too many queries
256   -- Version 1.1.2 (2009-10-29)
257   - - Added validation for depth cache column
258   - - Added STI support (reported broken)
259   -- Version 1.1.1 (2009-10-28)
260   - - Fixed some parentheses warnings that where reported
261   - - Fixed a reported issue with arrangement
262   - - Fixed issues with ancestors and path order on postgres
263   - - Added ordered_by_ancestry scope (needed to fix issues)
264   -- Version 1.1.0 (2009-10-22)
265   - - Depth caching (and cache rebuilding)
266   - - Depth method for nodes
267   - - Named scopes for selecting by depth
268   - - Relative depth options for tree navigation methods:
269   - - ancestors
270   - - path
271   - - descendants
272   - - descendant_ids
273   - - subtree
274   - - subtree_ids
275   - - Updated README
276   - - Easy migration from existing plugins/gems
277   - - acts_as_tree checks unknown options
278   - - acts_as_tree checks that options are hash
279   - - Added a bang (!) to the integrity functions
280   - - Since these functions should only be used from ./script/console and not from your application, this change is not considered as breaking backwards compatibility and the major version wasn't bumped.
281   - - Updated install script to point to documentation
282   - - Removed rails specific init
283   - - Removed uninstall script
284   -- Version 1.0.0 (2009-10-16)
285   - - Initial version
286   - - Tree building
287   - - Tree navigation
288   - - Integrity checking / restoration
289   - - Arrangement
290   - - Orphan strategies
291   - - Subtree movement
292   - - Named scopes
293   - - Validations
294   -
295 11 = Future work
296 12
297   -I will try to keep Ancestry up to date with changing versions of Rails and Ruby and also with any bug reports I might receive. I will implement new features on request as I see fit. One thing I definitely want to do soon is some proper performance testing.
298   -
299 13 = Contact and copyright
300 14
301   -Bug report? Faulty/incomplete documentation? Feature request? Please post an issue on 'http://github.com/stefankroes/ancestry/issues'. Please also contact me at s.a.kroes[at]gmail.com if it's urgent.
  15 +Bug report? Faulty/incomplete documentation? Feature request? Please post an issue on 'http://github.com/stefankroes/tapestry/issues'. Please also contact me at s.a.kroes[at]gmail.com if it's urgent.
302 16
303   -Question? Contact me at s.a.kroes[at]gmail.com, make sure you read the documentation. You can also join the #ancestry channel on IRC (irc.freenode.net).
  17 +Question? Contact me at s.a.kroes[at]gmail.com, make sure you read the documentation.
304 18
305 19 Copyright (c) 2009 Stefan Kroes, released under the MIT license

0 comments on commit e3311f8

Please sign in to comment.
Something went wrong with that request. Please try again.