Ancestry

The tree structure implementations for Ecto.

Getting started
TODO
Options for use Ancestry
Arrangement
Examples
Contributing
Make a pull request
License
Credits

Getting started

If available in Hex, the package can be installed by adding ancestry to your list of dependencies in mix.exs:

def deps do
  [
    {:ancestry, "~> 0.1.1"}
  ]
end

Gen migration file to add string field in your model.

mix ecto.gen.migration add_ancestry_to_<model>

Add ancestry field and index to migration file.

def change do
  alter table(:my_models) do
    add :ancestry, :string
  end
  create index(:my_models, [:ancestry])
end

mix ecto.migration

Add use Ancestry, repo: MyApp.repo to you model.ex

defmodule MyModel do
  use Ecto.Schema
  use Ancestry, repo: MyApp.repo

  import Ecto.Changeset

  schema "my_models" do
    field :ancestry, :string
  end

  def changeset(struct, params) do
    struct
    |> cast(params, [:ancestry])
  end
end

TODO

method	return value	usage example	finished?
`roots`	all root node	`MyModel.roots`	`true`
`parent`	parent of the record, nil for a root node	`MyModel.parent(record)`	`true`
`parent_id`	parent id of the record, nil for a root node	`MyModel.parent_id(record)`	`true`
`has_parent?`	true if the record has a parent, false otherwise	`MyModel.has_parent?(record)`	`true`
`root`	root of the record's tree, self for a root node	`MyModel.root(record)`	`true`
`root_id`	root id of the record's tree, self for a root node	`MyModel.root_id(record)`	`true`
`is_root?`	true if the record is a root node, false otherwise	`MyModel.is_root?(record)`	`true`
`ancestors`	ancestors of the record, starting with the root and ending with the parent	`MyModel.ancestors(record)`	`true`
`ancestor_ids`	ancestor ids of the record	`MyModel.ancestor_ids(record)`	`true`
`children`	direct children of the record	`MyModel.children(record)`	`true`
`child_ids`	direct children's ids	`MyModel.child_ids(record)`	`true`
`has_children?`	true if the record has any children, false otherwise	`MyModel.has_children?(record)`	`true`
`is_childless?`	true is the record has no children, false otherwise	`MyModel.is_childless?(record)`	`true`
`siblings`	siblings of the record, the record itself is included*	`MyModel.siblings(record)`	`true`
`sibling_ids`	sibling ids	`MyModel.sibling_ids(record)`	`true`
`has_siblings?`	true if the record's parent has more than one child	`MyModel.has_siblings?(record)`	`true`
`is_only_child?`	true if the record is the only child of its parent	`MyModel.is_only_child?(record)`	`true`
`descendants`	direct and indirect children of the record	`MyModel.descendants(record)`	`true`
`descendant_ids`	direct and indirect children's ids of the record	`MyModel.descendant_ids(record)`	`true`
`subtree`	the model on descendants and itself	`MyModel.subtree(record)`	`true`
`subtree_ids`	a list of all ids in the record's subtree	`MyModel.subtree_ids(record)`	`true`
`path`	path of the record, starting with the root and ending with self	`MyModel.path(record)`	`true`
`path_ids`	a list the path ids, starting with the root id and ending with the node's own id	`MyModel.path_ids(record)`	`true`
`depth`	the depth of the node, root nodes are at depth 0	`MyModel.depth(record)`	`true`

Options for `use Ancestry`

The use Ancestry method supports the following options:

:repo                  The current app repo
:ancestry_column       Pass in a symbol to store ancestry in a different column
: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
                       :adopt     The orphan subtree is added to the parent of the deleted node.
                                  If the deleted node is Root, then rootify the orphan subtree.

Arrangement

Ancestry can arrange an entire subtree into nested hashes for easy navigation after retrieval from the database.

MyModel.arrange(record) =>
%{
  id: 1,
  name: "root",
  ancestry: nil,
  children: [
    %{
      id: "2",
      name: "childA",
      ancestry: "1",
      children: [
        %{
          id: 3,
          name: "childA1",
          ancestry: "1/2",
          children: []
        }
      ]
    }
  ],
}

Examples

# use `MyModel.delete` deal with orphan strategy.
iex> MyModel.delete(record)

# use `MyModel.get_ancestry_value(record, "children|siblings")` gen `ancestry` value
iex> MyModel.get_ancestry_value(record, "children")

Contributing

Bug report or pull request are welcome.

Make a pull request

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Please write unit test with your code if necessary.

License

The gem is available as open source under the terms of the MIT License.

Credits

ancestry - Organise ActiveRecord model into a tree structure(Ruby classes).