Ancestry
The tree structure implementations for Ecto.
Table of contents
- Getting started
- Navigation
- 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.3"}
]
endGen 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])
endmix ecto.migrationAdd 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
endNavigation
| 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")
# use `MyModel.arrange`
iex> MyModel.get_ancestry_value(record)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 mix is available as open source under the terms of the MIT License.
Credits
- ancestry - Organise ActiveRecord model into a tree structure(Ruby classes).
