= dm-is-tree

DataMapper plugin enabling easy creation of tree structures from your DM models.

This requires <b>a foreign key property</b> for your model, which by default would be called <tt>:parent_id</tt>.


== Installation

=== Stable

Install the <tt>dm-is-tree</tt> gem.

  $ (sudo)? gem install dm-is-tree

=== Edge

Download or clone <tt>dm-is-versioned</tt> from Github[http://github.com/datamapper/dm-is-tree/].

  $ cd /path/to/dm-is-tree

  $ rake install            # will install dm-is-tree



== Getting started

To start using this gem, just...

  require 'dm-is-tree'


Lets say we have a Category model...

  class Category
    include DataMapper::Resource
    property :id,         Serial
    property :name,       String
  end


...and we want to have a tree structure within it, something like this:

  the_parent
    +- child
        +- grandchild1
        +- grandchild2


To achieve this we just add the following to the model:

  class Category
    <snip...>

    is :tree, :order => :name

  end

  # No need to define the :parent_id property, it will be added automatically
  property :parent_id,  Integer


This will automatically add the following to your model:

=== Instance Methods

* <tt>#parent</tt> / <tt>#parent=</tt>
* <tt>#children</tt> / <tt>#children=</tt>
* <tt>#siblings</tt>
* <tt>#generation</tt>
* <tt>#ancestors</tt>
  - also aliased as <tt>#self_and_siblings</tt> for those used to AR's :acts_as_tree
* <tt>#root</tt>
  - also aliased as <tt>#first_root</tt> for those used to AR's :acts_as_tree

=== Class Methods

* <tt>#first_root</tt>
* <tt>#roots</tt>


== Configuration Options

Before we go onto the usage examples, a few quick words about configuration options available:

=== <tt>:child_key</tt>

Specifies the column name to use for tracking of the tree (default: <tt>#parent_id</tt>).

  class Category
    <snip...>

    is :tree, :child_key => :some_other_foreign_key_id

  end


=== <tt>:model</tt>

Specifies the name of the Model to use for the tree (default: Model class name defined in)

  class Category
    <snip...>

    is :tree, :model => 'SomeStrangeModelName'

  end


=== <tt>:order</tt> [Optional]

Specifies the sort order of the children when retrieving them (default: not present)

  class Category
    <snip...>

    is :tree, :order => [:updated_at, :name]

  end



== Usage

To create the above structure, we would start with:

  the_parent = Category.create(:name => "the_parent")


=== <tt>#parent</tt> & <tt>#parent=</tt>

The <tt>#parent</tt> instance method returns the node referenced by the foreign key - <tt>:parent_id</tt>
or the defined <tt>:child_key</tt>.

  # by default #parent and #parent_id return nil when there is no parent
  the_parent.parent  # => nil


The <tt>#parent=</tt> instance method sets the <tt>:parent_id</tt> foreign key to the parent's id attribute value.

To define a parent you can use either of these syntaxes:

  a_child = Category.create(:name => "a_child", :parent => the_parent)

  a_child = Category.create(:name => "a_child", :parent_id => the_parent.id)

  a_child = Category.create(:name => "a_child")
  a_child.parent = the_parent


When retrieving the parent, you will receive the full parent object ( or <tt>nil</tt> if none was declared )

  a_child.parent  # => the_parent


=== <tt>#children</tt> & <tt>#children=</tt>

The <tt>#children</tt> instance method <b>returns all nodes with the current node as their parent</b>,
in the order specified by the <tt>:order</tt> configuration option.

  # by default #children return an empty Array when there are no children
  a_child.children # => []

  # or an Array with child objects when there are children
  the_parent.children # => [a_child]


The <tt>#children=</tt> instance method adds children by setting the <tt>:parent_id</tt> foreign key
to the parent's id attribute value.

To add a child you can use either of these syntaxes:

  child = the_parent.children.create(:name => "child")

  grandchild1 = Category.create(:name => "grandchild1")
  child.children << grandchild1

  grandchild2 = child.children.create(:name => "grandchild2")


When retrieving children, or a child, you will receive an Array of child objects.

  child.children # => [grandchild1, grandchild2,...]

  # just retrieve the first child
  child.children.first # => grandchild1



=== <tt>#siblings</tt>

The <tt>#siblings</tt> instance method <b>returns all the children of the parent, excluding the current node</b>.

  # by default #siblings return an empty Array when there are no siblings
  the_parent.siblings # => []

  grandchild1.siblings # => [grandchild2]



=== <tt>#generation</tt>

The <tt>#generation</tt> instance method returns all the children of the parent, <b>including the current node</b>.

  # by default #generation return an Array with itself only when it's a 'lonely child'
  the_parent.generation # => [the_parent]

  #
  grandchild1.generation # => [grandchild1, grandchild2]



=== <tt>#ancestors</tt>

The <tt>#ancestors</tt> instance method returns all the ancestors of the current node.

  # by default it returns an empty Array when born through immaculate conception (is root)
  the_parent.ancestors # => []

  grandchild2.ancestors # => [the_parent, a_child]



=== <tt>#root</tt>

The <tt>#root</tt> instance method returns the root (parent) of the current node.

  # by default returns itself only when it's the root node
  the_parent.root # =>  the_parent

  a_child.root # => the_parent

  grandchild2.root # => the_parent



=== <tt>self.#first_root</tt>

The <tt>#first_root</tt> class method returns the first root declared in the model.

  Category.first_root # =>  the_parent


=== <tt>self.#roots</tt>

The <tt>#roots</tt> class method returns an Array of the roots declared in the model.

  Category.roots # =>  [the_parent]

  parent2 = Category.create(:name => 'parent2')


  Category.roots # =>  [the_parent, parent2]


=== Summary

  parent = Category.create(:name => "parent")

  child = parent.children.create(:name => "child")

  grandchild1 = child.children.create(:name => "grandchild1")

  grandchild2 = Category.create(:name => "grandchild2")
  child.children << grandchild2

  grandchild3 = Category.create(:name => "grandchild2")
  grandchild3.parent = child

  parent.parent  # => nil
  child.parent  # => parent

  parent.children  # => [child]
  parent.children.first.children.first  # => grandchild1

  parent.siblings # => []
  grandchild1.siblings # => [grandchild2]

  parent.generation # => [parent]
  grandchild1.generation # => [grandchild1, grandchild2]

  parent.ancestors # => []
  grandchild2.ancestors # => [parent, child]

  parent.root # =>  parent
  parent.root # => parent
  grandchild2.root # => parent


  Category.first_root  # => parent
  Category.roots  # => [parent]



== Gotchas

Now there are some gotcha's that might not be entirely obvious to everyone, so let's clarify
them here.

=== Prevent a node being made a child of it self

By default dm-is-tree allows you to save a record as a child of it self, which is quite unnatural.
To prevent this, I would humbly suggest adding this custom validation code to your model(s).

  class Category
    <snip...>

    # prevent saving Category as child of self, except when new?
    validates_with_method :parent_id,
                          :method => :category_cannot_be_made_a_child_of_self,
                          :unless => :new?

    protected

      def category_cannot_be_made_a_child_of_self
        if self.id === self.parent_id
          return [
            false,
            "A Category [ #{self.name} ] cannot be made a child of it self [ #{self.name} ]"
          ]
        else
          return true
        end
      end

  end

An example:

  parent = Category.create(:name => "parent")
  child = parent.children.create(:name => 'child')

  child.parent = child

  child.save  # => return false

  child.errors.on(:parent_id)
    # => ["A Category [ child ] cannot be made a child of it self [ child ]"]


=== Sorting order within nodes

By default the sorting order is alphabetic, but this spans the entire table (with all nodes),
which might not be what you want.

To prevent this, order the results by <tt>:parent_id</tt> first, and secondly by <tt>:name</tt>
or whatever you wish to sort by.

  class Category
    <snip...>

    is :tree, :order => [:parent_id, :name]

  end


That's about it.


== Errors / Bugs

If something is not behaving intuitively, it is a bug, and should be reported.
Report it here: http://datamapper.lighthouseapp.com/


== TODOs

* Make it automatically prevent saving self as child of self.
* Anything else missing?


== Note on Patches/Pull Requests

* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so we don't break it in a future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  * (if you want to have your own version, that is fine but bump version in a commit by itself we can ignore when we pull)
* Send us a pull request. Bonus points for topic branches.


== Copyright

Copyright (c) 2011 Timothy Bennett. Released under the MIT License.

See LICENSE for details.

=== Credits

Credit also goes to these contributors[http://github.com/datamapper/dm-is-tree/contributors].

Current Maintainer: Garrett Heaver (http://www.linkedin.com/pub/dir/garrett/heaver)
