Skip to content

Commit

Permalink
Updated README
Browse files Browse the repository at this point in the history
  • Loading branch information
@stefankroes
stefankroes committed Oct 18, 2009
1 parent 48d00be commit 95e6701
Showing 1 changed file with 32 additions and 32 deletions.
64 changes: 32 additions & 32 deletions README.rdoc
View file
Expand Up @@ -29,36 +29,36 @@ Your model is now a tree!

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:

TreeNode.create!(:name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky'))
TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')

You can also create children through the children relation on a node:

node.children.create
node.children.create :name => 'Stinky'

= Navigating Your Tree

To navigate an Ancestry model, use the following methods on any instance / record:

<b>parent</b> Returns the parent of the record
<b>root</b> Returns the root of the tree the record is in
<b>root_id</b> Returns the id of the root of the tree the record is in
<b>is_root?</b> Returns true if the record is a root node, false otherwise
<b>ancestor_ids</b> Returns a list of ancestor ids, starting with the root id and ending with the parent id
<b>ancestors</b> Scopes the model on ancestors of the record
<b>path_ids</b> Returns a list the path ids, starting with the root is and ending with the node's own id
<b>path</b> Scopes model on path records of the record
<b>children</b> Scopes the model on children of the record
<b>child_ids</b> Returns a list of child ids
<b>has_children?</b> Returns true if the record has any children, false otherwise
<b>is_childless?</b> Returns true is the record has no childen, false otherwise
<b>siblings</b> Scopes the model on siblings of the record, the record itself is included
<b>sibling_ids</b> Returns a list of sibling ids
<b>has_siblings?</b> Returns true if the record's parent has more than one child
<b>is_only_child?</b> Returns true if the record is the only child of its parent
<b>descendants</b> Scopes the model on direct and indirect children of the record
<b>descendant_ids</b> Returns a list of a descendant ids
<b>subtree</b> Scopes the model on descendants and itself
<b>subtree_ids</b> Returns a list of all ids in the record's subtree
*parent* Returns the parent of the record
*root* Returns the root of the tree the record is in
*root_id* Returns the id of the root of the tree the record is in
*is_root?* Returns true if the record is a root node, false otherwise
*ancestor_ids* Returns a list of ancestor ids, starting with the root id and ending with the parent id
*ancestors* Scopes the model on ancestors of the record
*path_ids* Returns a list the path ids, starting with the root is and ending with the node's own id
*path* Scopes model on path records of the record
*children* Scopes the model on children of the record
*child_ids* Returns a list of child ids
*has_children?* Returns true if the record has any children, false otherwise
*is_childless?* Returns true is the record has no childen, false otherwise
*siblings* Scopes the model on siblings of the record, the record itself is included
*sibling_ids* Returns a list of sibling ids
*has_siblings?* Returns true if the record's parent has more than one child
*is_only_child?* Returns true if the record is the only child of its parent
*descendants* Scopes the model on direct and indirect children of the record
*descendant_ids* Returns a list of a descendant ids
*subtree* Scopes the model on descendants and itself
*subtree_ids* Returns a list of all ids in the record's subtree

= (Named) Scopes

Expand All @@ -70,11 +70,11 @@ Where possible, the navigation methods return scopes instead of records, this me

For convenience, a couple of named scopes are included at the class level:

<b>roots</b> Only root nodes
<b>ancestors_of(node)</b> Only ancestors of node, node can be either a record or an id
<b>children_of(node)</b> Only children of node, node can be either a record or an id
<b>descendants_of(node)</b> Only descendants of node, node can be either a record or an id
<b>siblings_of(node)</b> Only siblings of node, node can be either a record or an id
*roots* Only root nodes
*ancestors_of(node)* Only ancestors of node, node can be either a record or an id
*children_of(node)* Only children of node, node can be either a record or an id
*descendants_of(node)* Only descendants of node, node can be either a record or an id
*siblings_of(node)* Only siblings of node, node can be either a record or an id

Thanks to some convenient rails magic, it is even possible to create nodes through the children and siblings scopes:

Expand All @@ -87,11 +87,11 @@ Thanks to some convenient rails magic, it is even possible to create nodes throu

The acts_as_tree methods supports two options:

<b>ancestry_column</b> Pass in a symbol to instruct Ancestry to use a different column name to store record ancestry
<b>orphan_strategy</b> Instruct Ancestry what to do with children of a node that is destroyed:
<b>:destroy</b> All children are destroyed as well (default)
<b>:rootify</b> The children of the destroyed node become root nodes
<b>:restrict</b> An AncestryException is raised if any children exist
*ancestry_column* Pass in a symbol to instruct Ancestry to use a different column name to store record ancestry
*orphan_strategy* Instruct Ancestry what to do with children of a node that is destroyed:
*:destroy* All children are destroyed as well (default)
*:rootify* The children of the destroyed node become root nodes
*:restrict* An AncestryException is raised if any children exist

= Arrangement

Expand Down

0 comments on commit 95e6701

Please sign in to comment.