From c56aec256472c9f06bdfbac1b8d470d74da8311e Mon Sep 17 00:00:00 2001 From: Keenan Brock Date: Thu, 19 Apr 2018 17:34:11 -0400 Subject: [PATCH] improve docs for instance methods --- README.md | 73 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 5152ab92..b1fb6bfe 100644 --- a/README.md +++ b/README.md @@ -83,35 +83,46 @@ node.children.create :name => 'Stinky' # Navigating your tree -To navigate an Ancestry model, use the following methods on any instance / -record: - - parent Returns the parent of the record, nil for a root node - parent_id Returns the id of the parent of the record, nil for a root node - root Returns the root of the tree the record is in, self for a root node - root_id Returns the id of the root of the tree the record is in - root?, 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 id 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_parent? Returns true if the record has a parent, false otherwise - has_children? Returns true if the record has any children, false otherwise - is_childless? Returns true is the record has no children, 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 - depth Return the depth of the node, root nodes are at depth 0 - -* If the record is a root, other root records are considered siblings - +To navigate an Ancestry model, use the following instance methods: + +| method |return value| +|-------------------|------------| +|`parent` |parent of the record, nil for a root node| +|`parent_id` |parent id of the record, nil for a root node| +|`root` |root of the record's tree, self for a root node| +|`root_id` |root id of the record's tree, self for a root node| +|`root?`
`is_root?` | true if the record is a root node, false otherwise| +|`ancestors` |ancestors of the record, starting with the root and ending with the parent| +|`ancestors?` |true if the record has ancestors (aka not a root node)| +|`ancestor_ids` |ancestor ids of the record| +|`path` |path of the record, starting with the root and ending with self| +|`path_ids` |a list the path ids, starting with the root id and ending with the node's own id| +|`children` |direct children of the record| +|`child_ids` |direct children's ids| +|`has_parent?`
`ancestors?` |true if the record has a parent, false otherwise| +|`has_children?`
`children?` |true if the record has any children, false otherwise| +|`is_childless?`
`childless?` |true is the record has no children, false otherwise| +|`siblings` |siblings of the record, the record itself is included*| +|`sibling_ids` |sibling ids| +|`has_siblings?`
`siblings?` |true if the record's parent has more than one child| +|`is_only_child?`
`only_child?` |true if the record is the only child of its parent| +|`descendants` |direct and indirect children of the record| +|`descendant_ids` |direct and indirect children's ids of the record| +|`subtree` |the model on descendants and itself| +|`subtree_ids` |a list of all ids in the record's subtree| +|`depth` |the depth of the node, root nodes are at depth 0| + +\* If the record is a root, other root records are considered siblings +\* Siblings returns the record itself + +There are also instance methods to determine the relationship between 2 nodes: + +|method |return value| +|-------------------|---------------| +|`parent_of?(node)` | node's parent is this record| +|`root_of?(node)` | node's root is this record| +|`ancestor_of?(node)`| node's ancestors include this record| +|`child_of?(node)` | node is record's parent| # Options for `has_ancestry` @@ -143,7 +154,7 @@ example: ```ruby node.children.where(:name => 'Mary').exists? -node.subtree.order(:name).limit(10).each do; ...; end +node.subtree.order(:name).limit(10).each { ... } node.descendants.count ``` @@ -301,7 +312,7 @@ the order of siblings depends on their order in the original array. # Migrating from plugin that uses parent_id column Most current tree plugins use a parent_id column (has_ancestry, -awesome_nested_set, better_nested_set, acts_as_nested_set). With ancestry its +awesome_nested_set, better_nested_set, acts_as_nested_set). With ancestry it is 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: