ancestry 3.0.5 → 3.2.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/CHANGELOG.md +277 -0
- data/README.md +83 -202
- data/lib/ancestry.rb +28 -1
- data/lib/ancestry/class_methods.rb +55 -31
- data/lib/ancestry/has_ancestry.rb +37 -26
- data/lib/ancestry/instance_methods.rb +67 -102
- data/lib/ancestry/locales/en.yml +16 -0
- data/lib/ancestry/materialized_path.rb +100 -17
- data/lib/ancestry/materialized_path_pg.rb +23 -0
- data/lib/ancestry/version.rb +1 -1
- metadata +25 -52
- data/ancestry.gemspec +0 -53
- data/init.rb +0 -1
- data/install.rb +0 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 2f1ae94346d7ad0aa07830437239dc7f13dda73408c61a118e60f53ef21e6282
|
|
4
|
+
data.tar.gz: 1eb3e39a50b257dddc13559d52b03955c8174682f990a723614ca9e2e3dc6945
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 87a3c689530416fd20fa4064bb7c610e8e9e3b013324776e5a7c96ad7cb0a8f1a136dfbe71ada9e53b5116ef41602dab7d2d7664e2fc047e8a31f7a6598e2238
|
|
7
|
+
data.tar.gz: f420ad732aca06c42116a97db60898db8712163aae660d13b8f0d32b806eaa6e81edac4ba2eb167986456995859cfd52da829abbbdf7d3377177b9f9049b73d5
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
# Ancestry Changelog
|
|
2
|
+
|
|
3
|
+
Doing our best at supporting [SemVer](http://semver.org/) with
|
|
4
|
+
a nice looking [Changelog](http://keepachangelog.com).
|
|
5
|
+
|
|
6
|
+
## Version [HEAD] <small>now</small>
|
|
7
|
+
|
|
8
|
+
* dropped support for rails 4.2 and 5.0
|
|
9
|
+
|
|
10
|
+
## Versions [3.2.1] <small>2020-09-23</small>
|
|
11
|
+
|
|
12
|
+
* fixed gemspec to include locales and pg (thx @HectorMF)
|
|
13
|
+
|
|
14
|
+
## Versions [3.2.0] <small>2020-09-23</small>
|
|
15
|
+
|
|
16
|
+
* introduce i18n
|
|
17
|
+
* pg sql optimization for ancestry changes (thx @suonlight and @geis)
|
|
18
|
+
* pg sql optimization for sorting (thx @brendon and @d-m-u)
|
|
19
|
+
* fix to humanise model name (thx @mkllnk)
|
|
20
|
+
* able to convert to ancestry from a parent_id column with a different name
|
|
21
|
+
* documentation fixes for better diagrams and grammar (thx @dtamais, @d-m-u, and @CamilleDrapier)
|
|
22
|
+
|
|
23
|
+
## Versions [3.1.0] <small>2020-08-03</small>
|
|
24
|
+
|
|
25
|
+
* `:primary_key_format` method lets you change syntax. good for uuids.
|
|
26
|
+
* changed code from being `ancestry` string to `ancestry_ids` focused. May break monkey patches.
|
|
27
|
+
* Moved many methods from `has_ancestry` and `InstanceMethods` to `MaterializedPath`. May break monkey patches.
|
|
28
|
+
* Removed tests for `mysql` driver. Starting with rails 4.1, it supports `mysql2` driver.
|
|
29
|
+
* Better documentation for relationships (thnx @dtamai and @d-m-u)
|
|
30
|
+
* Fix creating children in `after_*` callbacks (thx @jstirk)
|
|
31
|
+
|
|
32
|
+
## Version [3.0.7] <small>2018-11-06</small>
|
|
33
|
+
|
|
34
|
+
* Fixed rails 5.1 change detection (thx @jrafanie)
|
|
35
|
+
* Introduce counter cache (thx @hw676018683)
|
|
36
|
+
|
|
37
|
+
## Version [3.0.6] <small>2018-11-06</small>
|
|
38
|
+
|
|
39
|
+
* Fixed rails 4.1 version check (thx @myxoh)
|
|
40
|
+
|
|
41
|
+
## Version [3.0.5] <small>2018-11-06</small>
|
|
42
|
+
|
|
43
|
+
## Changed
|
|
44
|
+
|
|
45
|
+
* Added indirect children support (thx @tilo)
|
|
46
|
+
* Fixed test sorting for pg on mac osx
|
|
47
|
+
|
|
48
|
+
## Fixes
|
|
49
|
+
|
|
50
|
+
* Reduced memory footprint of parsing ancestry column (thx @NickLaMuro)
|
|
51
|
+
|
|
52
|
+
## Version [3.0.4] <small>2018-10-27</small>
|
|
53
|
+
|
|
54
|
+
## Fixes
|
|
55
|
+
|
|
56
|
+
* Properly detects non-integer columns (thx @adam101)
|
|
57
|
+
* Arrange no longer drops nodes due to missing parents (thx @trafium)
|
|
58
|
+
|
|
59
|
+
## Version [3.0.3] <small>2018-10-23</small>
|
|
60
|
+
|
|
61
|
+
This branch (3.x) should still be compatible with rails 3 and 4.
|
|
62
|
+
Rails 5.1 and 5.2 support were introduced in this version, but ongoing support
|
|
63
|
+
has been moved to ancestry 4.0
|
|
64
|
+
|
|
65
|
+
## Fixes
|
|
66
|
+
|
|
67
|
+
* Reduce object allocation (thx @NickLaMuro)
|
|
68
|
+
* Rails 5.1 fixes (thx @ctrombley)
|
|
69
|
+
* Avoid redundant query to DB in subtree_of scope (thx @Slike9)
|
|
70
|
+
* Syntax tweaks (thx @ekohl, @richardonrails)
|
|
71
|
+
* Fixed reverse ordering
|
|
72
|
+
* Dropped builds for ruby 1.9.3, 2.0, 2.1, and 2.2
|
|
73
|
+
* Dropped builds for Rails 3.x and 4.x (will use Active Record `or` syntax)
|
|
74
|
+
|
|
75
|
+
## Version [3.0.2] <small>2018-04-24</small>
|
|
76
|
+
|
|
77
|
+
## Fixes
|
|
78
|
+
|
|
79
|
+
* fixed `order_by_ancestry` bug
|
|
80
|
+
* fixed order tests for postgres on mac (it uses a different collation)
|
|
81
|
+
* fixed documentation (thx @besquared, @danfrenette, @eiwi1101, @isimluk, @mabusaad, @tilsammans)
|
|
82
|
+
* added missing `Ancestry::version`
|
|
83
|
+
* added Rails 5.2 support (thx @jjuliano)
|
|
84
|
+
|
|
85
|
+
## Version [3.0.1] <small>2017-07-05</small>
|
|
86
|
+
|
|
87
|
+
## Fixes
|
|
88
|
+
|
|
89
|
+
* added gem metadata
|
|
90
|
+
* fixed keep a changelog link (thx @mattbrictson)
|
|
91
|
+
* added alias has_parent?
|
|
92
|
+
* fixed bug where unscoping too much (thx @brendon)
|
|
93
|
+
* fixed tests on mysql 5.7 and rails 3.2
|
|
94
|
+
* Dropped 3.1 scope changes
|
|
95
|
+
|
|
96
|
+
## Version [3.0.0] <small>2017-05-18</small>
|
|
97
|
+
|
|
98
|
+
## Changed
|
|
99
|
+
|
|
100
|
+
* Dropping Rails 3.0, and 3.1. Added Rails 5.1 support (thx @ledermann)
|
|
101
|
+
* Dropping Rails 4.0, 4.1 for build reasons. Since 4.2 is supported, all 4.x should still work.
|
|
102
|
+
|
|
103
|
+
## Fixes
|
|
104
|
+
|
|
105
|
+
* Performance: Use `pluck` vs `map` for ids (thx @njakobsen and @culturecode)
|
|
106
|
+
* Fixed acts_as_tree compatibility (thx @crazymykl)
|
|
107
|
+
* Fixed loading ActiveRails prematurely (thx @vovimayhem)
|
|
108
|
+
* Fixes exist (thx @ledermann)
|
|
109
|
+
* Properly touches parents when different class for STI (thx @samtgarson)
|
|
110
|
+
* Fixed issues with parent_id (only present on master) (thx @domcleal)
|
|
111
|
+
|
|
112
|
+
## Version [2.2.2] <small>2016-11-01</small>
|
|
113
|
+
|
|
114
|
+
### Changed
|
|
115
|
+
|
|
116
|
+
* Use `COALESCE` only for sorting versions greater than 5.0
|
|
117
|
+
* Fixed bug with explicit order clauses (introduced in 2.2.0)
|
|
118
|
+
* No longer load schema on `has_ancestry` load (thx @ledermann)
|
|
119
|
+
|
|
120
|
+
## Version [2.2.1] <small>2016-10-25</small>
|
|
121
|
+
|
|
122
|
+
Sorry for blip, local master got out of sync with upstream master.
|
|
123
|
+
Missed 2 commits (which are feature adds)
|
|
124
|
+
|
|
125
|
+
### Added
|
|
126
|
+
* Use like (vs ilike) for rails 5.0 (performance enhancement)
|
|
127
|
+
* Use `COALESCE` for sorting on pg, mysql, and sqlite vs `CASE`
|
|
128
|
+
|
|
129
|
+
## Version [2.2.0] <small>2016-10-25</small>
|
|
130
|
+
|
|
131
|
+
### Added
|
|
132
|
+
* Predicates for scopes: e.g.: `ancestor_of?`, `parent_of?` (thx @neglectedvalue)
|
|
133
|
+
* Scope `path_of`
|
|
134
|
+
|
|
135
|
+
### Changed
|
|
136
|
+
* `arrange` now accepts blocks (thx @mastfish)
|
|
137
|
+
* Performance tuning `arrange_node` (thx @fryguy)
|
|
138
|
+
* In orphan strategy, set `ancestry` to `nil` for no parents (thx @haslinger)
|
|
139
|
+
* Only updates `updated_at` when a record is changed (thx @brocktimus)
|
|
140
|
+
* No longer casts text primary key as an integer
|
|
141
|
+
* Upgrading tests for ruby versions (thx @brocktimus, @fryguy, @yui-knk)
|
|
142
|
+
* Fix non-default ancestry not getting used properly (thx @javiyu)
|
|
143
|
+
|
|
144
|
+
## Version [2.1.0] <small>2014-04-16</small>
|
|
145
|
+
* Added arrange_serializable (thx @krishandley, @chicagogrrl)
|
|
146
|
+
* Add the :touch to update ancestors on save (thx @adammck)
|
|
147
|
+
* Change conditions into arel (thx @mlitwiniuk)
|
|
148
|
+
* Added children? & siblings? alias (thx @bigtunacan)
|
|
149
|
+
* closure_tree compatibility (thx @gzigzigzeo)
|
|
150
|
+
* Performance tweak (thx @mjc)
|
|
151
|
+
* Improvements to organization (thx @xsuchy, @ryakh)
|
|
152
|
+
|
|
153
|
+
## Version [2.0.0] <small>2013-05-17</small>
|
|
154
|
+
* Removed rails 2 compatibility
|
|
155
|
+
* Added table name to condition constructing methods (thx @aflatter)
|
|
156
|
+
* Fix depth_cache not being updated when moving up to ancestors (thx @scottatron)
|
|
157
|
+
* add alias :root? to existing is_root? (thx @divineforest)
|
|
158
|
+
* Add block to sort_by_ancestry (thx @Iliya)
|
|
159
|
+
* Add attribute query method for parent_id (thx @sj26)
|
|
160
|
+
* Fixed and tested for rails 4 (thx @adammck, @Nihad, @Systho, @Philippe, e.a.)
|
|
161
|
+
* Fixed overwriting ActiveRecord::Base.base_class (thx @Rozhnov)
|
|
162
|
+
* New adopt strategy (thx unknown)
|
|
163
|
+
* Many more improvements
|
|
164
|
+
|
|
165
|
+
## Version [1.3.0] <small>2012-05-04</small>
|
|
166
|
+
* Ancestry now ignores default scopes when moving or destroying nodes, ensuring tree consistency
|
|
167
|
+
* Changed ActiveRecord dependency to 2.3.14
|
|
168
|
+
|
|
169
|
+
## Version [1.2.5] <small>2012-03-15</small>
|
|
170
|
+
* Fixed warnings: "parenthesize argument(s) for future version"
|
|
171
|
+
* Fixed a bug in the restore_ancestry_integrity! method (thx Arthur Holstvoogd)
|
|
172
|
+
|
|
173
|
+
## Version [1.2.4] <small>2011-04-22</small>
|
|
174
|
+
* Prepended table names to column names in queries (thx @raelik)
|
|
175
|
+
* Better check to see if acts_as_tree can be overloaded (thx @jims)
|
|
176
|
+
* Performance inprovements (thx @kueda)
|
|
177
|
+
|
|
178
|
+
## Version [1.2.3] <small>2010-10-28</small>
|
|
179
|
+
* Fixed error with determining ActiveRecord version
|
|
180
|
+
* Added option to specify :primary_key_format (thx @rolftimmermans)
|
|
181
|
+
|
|
182
|
+
## Version [1.2.2] <small>2010-10-24</small>
|
|
183
|
+
* Fixed all deprecation warnings for rails 3.0.X
|
|
184
|
+
* Added `:report` option to `check_ancestry_integrity!`
|
|
185
|
+
* Changed ActiveRecord dependency to 2.2.2
|
|
186
|
+
* Tested and fixed for ruby 1.8.7 and 1.9.2
|
|
187
|
+
* Changed usage of `update_attributes` to `update_attribute` to allow ancestry column protection
|
|
188
|
+
|
|
189
|
+
## Version [1.2.0] <small>2009-11-07</small>
|
|
190
|
+
* Removed some duplication in has_ancestry
|
|
191
|
+
* Cleaned up plugin pattern according to http://yehudakatz.com/2009/11/12/better-ruby-idioms/
|
|
192
|
+
* Moved parts of ancestry into seperate files
|
|
193
|
+
* Made it possible to pass options into the arrange method
|
|
194
|
+
* Renamed acts_as_tree to has_ancestry
|
|
195
|
+
* Aliased has_ancestry as acts_as_tree if acts_as_tree is available
|
|
196
|
+
* Added subtree_of scope
|
|
197
|
+
* Updated ordered_by_ancestry scope to support Microsoft SQL Server
|
|
198
|
+
* Added empty hash as parameter to exists? calls for older ActiveRecord versions
|
|
199
|
+
|
|
200
|
+
## Version [1.1.4] <small>2009-11-07</small>
|
|
201
|
+
* Thanks to a patch from tom taylor, Ancestry now works with different primary keys
|
|
202
|
+
|
|
203
|
+
## Version [1.1.3] <small>2009-11-01</small>
|
|
204
|
+
* Fixed a pretty bad bug where several operations took far too many queries
|
|
205
|
+
|
|
206
|
+
## Version [1.1.2] <small>2009-10-29</small>
|
|
207
|
+
* Added validation for depth cache column
|
|
208
|
+
* Added STI support (reported broken)
|
|
209
|
+
|
|
210
|
+
## Version [1.1.1] <small>2009-10-28</small>
|
|
211
|
+
* Fixed some parentheses warnings that where reported
|
|
212
|
+
* Fixed a reported issue with arrangement
|
|
213
|
+
* Fixed issues with ancestors and path order on postgres
|
|
214
|
+
* Added ordered_by_ancestry scope (needed to fix issues)
|
|
215
|
+
|
|
216
|
+
## Version [1.1.0] <small>2009-10-22</small>
|
|
217
|
+
* Depth caching (and cache rebuilding)
|
|
218
|
+
* Depth method for nodes
|
|
219
|
+
* Named scopes for selecting by depth
|
|
220
|
+
* Relative depth options for tree navigation methods:
|
|
221
|
+
* ancestors
|
|
222
|
+
* path
|
|
223
|
+
* descendants
|
|
224
|
+
* descendant_ids
|
|
225
|
+
* subtree
|
|
226
|
+
* subtree_ids
|
|
227
|
+
* Updated README
|
|
228
|
+
* Easy migration from existing plugins/gems
|
|
229
|
+
* acts_as_tree checks unknown options
|
|
230
|
+
* acts_as_tree checks that options are hash
|
|
231
|
+
* Added a bang (!) to the integrity functions
|
|
232
|
+
* Since these functions should only be used from ./script/console and not
|
|
233
|
+
from your application, this change is not considered as breaking backwards
|
|
234
|
+
compatibility and the major version wasn't bumped.
|
|
235
|
+
* Updated install script to point to documentation
|
|
236
|
+
* Removed rails specific init
|
|
237
|
+
* Removed uninstall script
|
|
238
|
+
|
|
239
|
+
## Version 1.0.0 <small>2009-10-16</small>
|
|
240
|
+
* Initial version
|
|
241
|
+
* Tree building
|
|
242
|
+
* Tree navigation
|
|
243
|
+
* Integrity checking / restoration
|
|
244
|
+
* Arrangement
|
|
245
|
+
* Orphan strategies
|
|
246
|
+
* Subtree movement
|
|
247
|
+
* Named scopes
|
|
248
|
+
* Validations
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
[HEAD]: https://github.com/stefankroes/ancestry/compare/v3.2.0...HEAD
|
|
252
|
+
[3.1.0]: https://github.com/stefankroes/ancestry/compare/v3.1.0...v3.2.0
|
|
253
|
+
[3.1.0]: https://github.com/stefankroes/ancestry/compare/v3.0.7...v3.1.0
|
|
254
|
+
[3.0.7]: https://github.com/stefankroes/ancestry/compare/v3.0.6...v3.0.7
|
|
255
|
+
[3.0.6]: https://github.com/stefankroes/ancestry/compare/v3.0.5...v3.0.6
|
|
256
|
+
[3.0.5]: https://github.com/stefankroes/ancestry/compare/v3.0.4...v3.0.5
|
|
257
|
+
[3.0.4]: https://github.com/stefankroes/ancestry/compare/v3.0.3...v3.0.4
|
|
258
|
+
[3.0.3]: https://github.com/stefankroes/ancestry/compare/v3.0.2...v3.0.3
|
|
259
|
+
[3.0.2]: https://github.com/stefankroes/ancestry/compare/v3.0.1...v3.0.2
|
|
260
|
+
[3.0.1]: https://github.com/stefankroes/ancestry/compare/v3.0.0...v3.0.1
|
|
261
|
+
[3.0.0]: https://github.com/stefankroes/ancestry/compare/v2.2.2...v3.0.0
|
|
262
|
+
[2.2.2]: https://github.com/stefankroes/ancestry/compare/v2.2.1...v2.2.2
|
|
263
|
+
[2.2.1]: https://github.com/stefankroes/ancestry/compare/v2.2.0...v2.2.1
|
|
264
|
+
[2.2.0]: https://github.com/stefankroes/ancestry/compare/v2.1.0...v2.2.0
|
|
265
|
+
[2.1.0]: https://github.com/stefankroes/ancestry/compare/v2.0.0...v2.1.0
|
|
266
|
+
[2.0.0]: https://github.com/stefankroes/ancestry/compare/v1.3.0...v2.0.0
|
|
267
|
+
[1.3.0]: https://github.com/stefankroes/ancestry/compare/v1.2.5...v1.3.0
|
|
268
|
+
[1.2.5]: https://github.com/stefankroes/ancestry/compare/v1.2.4...v1.2.5
|
|
269
|
+
[1.2.4]: https://github.com/stefankroes/ancestry/compare/v1.2.3...v1.2.4
|
|
270
|
+
[1.2.3]: https://github.com/stefankroes/ancestry/compare/v1.2.2...v1.2.3
|
|
271
|
+
[1.2.2]: https://github.com/stefankroes/ancestry/compare/v1.2.0...v1.2.2
|
|
272
|
+
[1.2.0]: https://github.com/stefankroes/ancestry/compare/v1.1.4...v1.2.0
|
|
273
|
+
[1.1.4]: https://github.com/stefankroes/ancestry/compare/v1.1.3...v1.1.4
|
|
274
|
+
[1.1.3]: https://github.com/stefankroes/ancestry/compare/v1.1.2...v1.1.3
|
|
275
|
+
[1.1.2]: https://github.com/stefankroes/ancestry/compare/v1.1.1...v1.1.2
|
|
276
|
+
[1.1.1]: https://github.com/stefankroes/ancestry/compare/v1.1.0...v1.1.1
|
|
277
|
+
[1.1.0]: https://github.com/stefankroes/ancestry/compare/v1.0.0...v1.1.0
|
data/README.md
CHANGED
|
@@ -3,24 +3,24 @@
|
|
|
3
3
|
# Ancestry
|
|
4
4
|
|
|
5
5
|
Ancestry is a gem that allows the records of a Ruby on Rails
|
|
6
|
-
ActiveRecord model to be organised as a tree structure (or hierarchy). It
|
|
7
|
-
|
|
8
|
-
relations (ancestors, parent, root, children, siblings, descendants)
|
|
9
|
-
of them
|
|
6
|
+
ActiveRecord model to be organised as a tree structure (or hierarchy). It employs
|
|
7
|
+
the materialised path pattern and exposes all the standard tree structure
|
|
8
|
+
relations (ancestors, parent, root, children, siblings, descendants), allowing all
|
|
9
|
+
of them to be fetched in a single SQL query. Additional features include STI
|
|
10
10
|
support, scopes, depth caching, depth constraints, easy migration from older
|
|
11
11
|
gems, integrity checking, integrity restoration, arrangement of
|
|
12
|
-
(sub)
|
|
12
|
+
(sub)trees into hashes, and various strategies for dealing with orphaned
|
|
13
13
|
records.
|
|
14
14
|
|
|
15
15
|
NOTE:
|
|
16
16
|
|
|
17
|
-
- Ancestry
|
|
17
|
+
- Ancestry 2.x supports Rails 4.1 and earlier
|
|
18
|
+
- Ancestry 3.x supports Rails 5.0 and 4.2
|
|
18
19
|
- Ancestry 4.0 only supports rails 5.0 and higher
|
|
19
20
|
|
|
20
21
|
# Installation
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
|
|
23
|
+
Follow these simple steps to apply Ancestry to any ActiveRecord model:
|
|
24
24
|
|
|
25
25
|
## Install
|
|
26
26
|
|
|
@@ -54,7 +54,7 @@ $ rake db:migrate
|
|
|
54
54
|
|
|
55
55
|
|
|
56
56
|
## Add ancestry to your model
|
|
57
|
-
* Add to
|
|
57
|
+
* Add to app/models/[model.rb]:
|
|
58
58
|
|
|
59
59
|
```ruby
|
|
60
60
|
# app/models/[model.rb]
|
|
@@ -68,9 +68,9 @@ Your model is now a tree!
|
|
|
68
68
|
|
|
69
69
|
# Using acts_as_tree instead of has_ancestry
|
|
70
70
|
|
|
71
|
-
In version 1.2.0 the **acts_as_tree** method was **renamed to has_ancestry**
|
|
71
|
+
In version 1.2.0, the **acts_as_tree** method was **renamed to has_ancestry**
|
|
72
72
|
in order to allow usage of both the acts_as_tree gem and the ancestry gem in a
|
|
73
|
-
single application.
|
|
73
|
+
single application. The `acts_as_tree` method will continue to be supported in the future.
|
|
74
74
|
|
|
75
75
|
# Organising records into a tree
|
|
76
76
|
|
|
@@ -81,64 +81,38 @@ parent_id can be set using parent= and parent_id= on a record or by including
|
|
|
81
81
|
them in the hash passed to new, create, create!, update_attributes and
|
|
82
82
|
update_attributes!. For example:
|
|
83
83
|
|
|
84
|
-
|
|
85
|
-
TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')
|
|
86
|
-
```
|
|
84
|
+
`TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')`.
|
|
87
85
|
|
|
88
|
-
|
|
86
|
+
Children can be created through the children relation on a node: `node.children.create :name => 'Stinky'`.
|
|
89
87
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
88
|
+
# Tree Navigation
|
|
89
|
+
|
|
90
|
+
The node with the large border is the reference node (the node from which the navigation method is invoked.)
|
|
91
|
+
The yellow nodes are those returned by the method.
|
|
92
|
+
|
|
93
|
+
| | | |
|
|
94
|
+
|:-: |:-: |:-: |
|
|
95
|
+
|**parent** |**root**<sup><a href="#fn1" id="ref1">1</a></sup> |**ancestors** |
|
|
96
|
+
| | | |
|
|
97
|
+
| nil for a root node |self for a root node |root..parent |
|
|
98
|
+
| `parent_id` |`root_id` |`ancestor_ids` |
|
|
99
|
+
| `has_parent?` |`is_root?` |`ancestors?` |
|
|
100
|
+
|`parent_of?` |`root_of?` |`ancestor_of?` |
|
|
101
|
+
|**children** |**descendants** |**indirects** |
|
|
102
|
+
| | | |
|
|
103
|
+
| `child_ids` |`descendant_ids` |`indirect_ids` |
|
|
104
|
+
| `has_children?` | | |
|
|
105
|
+
| `child_of?` |`descendant_of?` |`indirect_of?` |
|
|
106
|
+
|**siblings** |**subtree** |**path** |
|
|
107
|
+
| | | |
|
|
108
|
+
| includes self |self..indirects |root..self |
|
|
109
|
+
|`sibling_ids` |`subtree_ids` |`path_ids` |
|
|
110
|
+
|`has_siblings?` | | |
|
|
111
|
+
|`sibling_of?(node)` | | |
|
|
93
112
|
|
|
94
|
-
#
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
| method |return value|
|
|
99
|
-
|-------------------|------------|
|
|
100
|
-
|`parent` |parent of the record, nil for a root node|
|
|
101
|
-
|`parent_id` |parent id of the record, nil for a root node|
|
|
102
|
-
|`root` |root of the record's tree, self for a root node|
|
|
103
|
-
|`root_id` |root id of the record's tree, self for a root node|
|
|
104
|
-
|`root?` <br/> `is_root?` | true if the record is a root node, false otherwise|
|
|
105
|
-
|`ancestors` |ancestors of the record, starting with the root and ending with the parent|
|
|
106
|
-
|`ancestors?` |true if the record has ancestors (aka not a root node)|
|
|
107
|
-
|`ancestor_ids` |ancestor ids of the record|
|
|
108
|
-
|`path` |path of the record, starting with the root and ending with self|
|
|
109
|
-
|`path_ids` |a list the path ids, starting with the root id and ending with the node's own id|
|
|
110
|
-
|`children` |direct children of the record|
|
|
111
|
-
|`child_ids` |direct children's ids|
|
|
112
|
-
|`has_parent?` <br/> `ancestors?` |true if the record has a parent, false otherwise|
|
|
113
|
-
|`has_children?` <br/> `children?` |true if the record has any children, false otherwise|
|
|
114
|
-
|`is_childless?` <br/> `childless?` |true is the record has no children, false otherwise|
|
|
115
|
-
|`siblings` |siblings of the record, the record itself is included*|
|
|
116
|
-
|`sibling_ids` |sibling ids|
|
|
117
|
-
|`has_siblings?` <br/> `siblings?` |true if the record's parent has more than one child|
|
|
118
|
-
|`is_only_child?` <br/> `only_child?` |true if the record is the only child of its parent|
|
|
119
|
-
|`descendants` |direct and indirect children of the record|
|
|
120
|
-
|`descendant_ids` |direct and indirect children's ids of the record|
|
|
121
|
-
|`indirects` |indirect children of the record|
|
|
122
|
-
|`indirect_ids` |indirect children's ids of the record|
|
|
123
|
-
|`subtree` |the model on descendants and itself|
|
|
124
|
-
|`subtree_ids` |a list of all ids in the record's subtree|
|
|
125
|
-
|`depth` |the depth of the node, root nodes are at depth 0|
|
|
126
|
-
|
|
127
|
-
\* If the record is a root, other root records are considered siblings
|
|
128
|
-
\* Siblings returns the record itself
|
|
129
|
-
|
|
130
|
-
There are also instance methods to determine the relationship between 2 nodes:
|
|
131
|
-
|
|
132
|
-
|method |return value|
|
|
133
|
-
|-------------------|---------------|
|
|
134
|
-
|`parent_of?(node)` | node's parent is this record|
|
|
135
|
-
|`root_of?(node)` | node's root is this record|
|
|
136
|
-
|`ancestor_of?(node)`| node's ancestors include this record|
|
|
137
|
-
|`child_of?(node)` | node is record's parent|
|
|
138
|
-
|`descendant_of?(node)` | node is one of this record's ancestors|
|
|
139
|
-
|`indirect_of?(node)` | node is one of this record's ancestors but not a parent|
|
|
140
|
-
|
|
141
|
-
# Options for `has_ancestry`
|
|
113
|
+
<sup id="fn1">1. [other root records are considered siblings]<a href="#ref1" title="Jump back to footnote 1.">↩</a></sup>
|
|
114
|
+
|
|
115
|
+
# `has_ancestry` options
|
|
142
116
|
|
|
143
117
|
The has_ancestry method supports the following options:
|
|
144
118
|
|
|
@@ -147,24 +121,22 @@ The has_ancestry method supports the following options:
|
|
|
147
121
|
:destroy All children are destroyed as well (default)
|
|
148
122
|
:rootify The children of the destroyed node become root nodes
|
|
149
123
|
:restrict An AncestryException is raised if any children exist
|
|
150
|
-
:adopt The orphan subtree is added to the parent of the deleted node
|
|
151
|
-
If the deleted node is Root, then rootify the orphan subtree
|
|
124
|
+
:adopt The orphan subtree is added to the parent of the deleted node
|
|
125
|
+
If the deleted node is Root, then rootify the orphan subtree
|
|
152
126
|
:cache_depth Cache the depth of each node in the 'ancestry_depth' column (default: false)
|
|
153
127
|
If you turn depth_caching on for an existing model:
|
|
154
128
|
- Migrate: add_column [table], :ancestry_depth, :integer, :default => 0
|
|
155
129
|
- Build cache: TreeNode.rebuild_depth_cache!
|
|
156
130
|
:depth_cache_column Pass in a symbol to store depth cache in a different column
|
|
157
|
-
:primary_key_format Supply a regular expression that matches the format of your primary key
|
|
158
|
-
By default, primary keys only match integers ([0-9]+)
|
|
131
|
+
:primary_key_format Supply a regular expression that matches the format of your primary key
|
|
132
|
+
By default, primary keys only match integers ([0-9]+)
|
|
159
133
|
:touch Instruct Ancestry to touch the ancestors of a node when it changes, to
|
|
160
134
|
invalidate nested key-based caches. (default: false)
|
|
161
135
|
|
|
162
136
|
# (Named) Scopes
|
|
163
137
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
the result can be either retrieved, counted or checked for existence. For
|
|
167
|
-
example:
|
|
138
|
+
The navigation methods return scopes instead of records, where possible. Additional ordering,
|
|
139
|
+
conditions, limits, etc. can be applied and the results can be retrieved, counted, or checked for existence:
|
|
168
140
|
|
|
169
141
|
```ruby
|
|
170
142
|
node.children.where(:name => 'Mary').exists?
|
|
@@ -172,7 +144,7 @@ node.subtree.order(:name).limit(10).each { ... }
|
|
|
172
144
|
node.descendants.count
|
|
173
145
|
```
|
|
174
146
|
|
|
175
|
-
|
|
147
|
+
A couple of class-level named scopes are included:
|
|
176
148
|
|
|
177
149
|
roots Root nodes
|
|
178
150
|
ancestors_of(node) Ancestors of node, node can be either a record or an id
|
|
@@ -182,8 +154,7 @@ For convenience, a couple of named scopes are included at the class level:
|
|
|
182
154
|
subtree_of(node) Subtree of node, node can be either a record or an id
|
|
183
155
|
siblings_of(node) Siblings of node, node can be either a record or an id
|
|
184
156
|
|
|
185
|
-
|
|
186
|
-
through the children and siblings scopes:
|
|
157
|
+
It is possible thanks to some convenient rails magic to create nodes through the children and siblings scopes:
|
|
187
158
|
|
|
188
159
|
node.children.create
|
|
189
160
|
node.siblings.create!
|
|
@@ -192,8 +163,8 @@ through the children and siblings scopes:
|
|
|
192
163
|
|
|
193
164
|
# Selecting nodes by depth
|
|
194
165
|
|
|
195
|
-
|
|
196
|
-
scopes can be used to select nodes
|
|
166
|
+
With depth caching enabled (see has_ancestry options), an additional five named
|
|
167
|
+
scopes can be used to select nodes by depth:
|
|
197
168
|
|
|
198
169
|
before_depth(depth) Return nodes that are less deep than depth (node.depth < depth)
|
|
199
170
|
to_depth(depth) Return nodes up to a certain depth (node.depth <= depth)
|
|
@@ -201,42 +172,27 @@ scopes can be used to select nodes on their depth:
|
|
|
201
172
|
from_depth(depth) Return nodes starting from a certain depth (node.depth >= depth)
|
|
202
173
|
after_depth(depth) Return nodes that are deeper than depth (node.depth > depth)
|
|
203
174
|
|
|
204
|
-
|
|
205
|
-
descendant_ids
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
node.subtree.to_depth(5) Subtree of node to an absolute depth of 5
|
|
210
|
-
node.descendants(:at_depth => 2) Descendant of node, at depth node.depth + 2 (grandchildren)
|
|
211
|
-
node.descendants.at_depth(10) Descendants of node at an absolute depth of 10
|
|
212
|
-
node.ancestors.to_depth(3) The oldest 4 ancestors of node (its root and 3 more)
|
|
213
|
-
node.path(:from_depth => -2) The node's grandparent, parent and the node itself
|
|
175
|
+
Depth scopes are also available through calls to `descendants`,
|
|
176
|
+
`descendant_ids`, `subtree`, `subtree_ids`, `path` and `ancestors` (with relative depth).
|
|
177
|
+
Note that depth constraints cannot be passed to `ancestor_ids` or `path_ids` as both relations
|
|
178
|
+
can be fetched directly from the ancestry column without needing a query. Use
|
|
179
|
+
`ancestors(depth_options).map(&:id)` or `ancestor_ids.slice(min_depth..max_depth)` instead.
|
|
214
180
|
|
|
215
181
|
node.ancestors(:from_depth => -6, :to_depth => -4)
|
|
216
182
|
node.path.from_depth(3).to_depth(4)
|
|
217
183
|
node.descendants(:from_depth => 2, :to_depth => 4)
|
|
218
184
|
node.subtree.from_depth(10).to_depth(12)
|
|
219
185
|
|
|
220
|
-
Please note that depth constraints cannot be passed to ancestor_ids and
|
|
221
|
-
path_ids. The reason for this is that both these relations can be fetched
|
|
222
|
-
directly from the ancestry column without performing a database query. It
|
|
223
|
-
would require an entirely different method of applying the depth constraints
|
|
224
|
-
which isn't worth the effort of implementing. You can use
|
|
225
|
-
ancestors(depth_options).map(&:id) or ancestor_ids.slice(min_depth..max_depth)
|
|
226
|
-
instead.
|
|
227
|
-
|
|
228
186
|
# STI support
|
|
229
187
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
you do only want nodes of a specific subclass you'll have to add a condition
|
|
234
|
-
on type for that.
|
|
188
|
+
To use with STI: create a STI inheritance hierarchy and build a tree from the different
|
|
189
|
+
classes/models. All Ancestry relations that were described above will return nodes of any model type. If
|
|
190
|
+
you do only want nodes of a specific subclass, a type condition is required.
|
|
235
191
|
|
|
236
192
|
# Arrangement
|
|
237
193
|
|
|
238
|
-
|
|
239
|
-
|
|
194
|
+
A subtree can be arranged into nested hashes for easy navigation after database retrieval.
|
|
195
|
+
`TreeNode.arrange` could, for instance, return:
|
|
240
196
|
|
|
241
197
|
```ruby
|
|
242
198
|
{
|
|
@@ -249,43 +205,20 @@ after retrieval from the database. TreeNode.arrange could for example return:
|
|
|
249
205
|
}
|
|
250
206
|
```
|
|
251
207
|
|
|
252
|
-
The arrange method
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
TreeNode.find_by_name('Crunchy').subtree.arrange
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
The arrange method takes `ActiveRecord` find options. If you want your hashes to
|
|
259
|
-
be ordered, you should pass the order to the arrange method instead of to the
|
|
260
|
-
scope. example:
|
|
208
|
+
The `arrange` method can work on a scoped class (`TreeNode.find_by(:name => 'Crunchy').subtree.arrange`),
|
|
209
|
+
and can take ActiveRecord find options. If you want ordered hashes, pass the order to the method instead of
|
|
210
|
+
the scope as follows:
|
|
261
211
|
|
|
262
|
-
|
|
263
|
-
TreeNode.find_by_name('Crunchy').subtree.arrange(:order => :name)
|
|
264
|
-
```
|
|
212
|
+
`TreeNode.find_by(:name => 'Crunchy').subtree.arrange(:order => :name)`.
|
|
265
213
|
|
|
266
|
-
|
|
214
|
+
The `arrange_serializable` method returns the arranged nodes as a nested array of hashes. Order
|
|
215
|
+
can be passed in the same fashion as to the `arrange` method:
|
|
216
|
+
`TreeNode.arrange_serializable(:order => :name)` The result can easily be serialized to json with `to_json`
|
|
217
|
+
or other formats. You can also supply your own serialization logic with blocks.
|
|
267
218
|
|
|
268
|
-
|
|
219
|
+
Using `ActiveModel` serializers:
|
|
269
220
|
|
|
270
|
-
|
|
271
|
-
[
|
|
272
|
-
{
|
|
273
|
-
"ancestry" => nil, "id" => 1, "children" => [
|
|
274
|
-
{ "ancestry" => "1", "id" => 2, "children" => [] }
|
|
275
|
-
]
|
|
276
|
-
}
|
|
277
|
-
]
|
|
278
|
-
```
|
|
279
|
-
|
|
280
|
-
You can also supply your own serialization logic using blocks:
|
|
281
|
-
|
|
282
|
-
For example, using `ActiveModel` Serializers:
|
|
283
|
-
|
|
284
|
-
```ruby
|
|
285
|
-
TreeNode.arrange_serializable do |parent, children|
|
|
286
|
-
MySerializer.new(parent, children: children)
|
|
287
|
-
end
|
|
288
|
-
```
|
|
221
|
+
`TreeNode.arrange_serializable { |parent, children| MySerializer.new(parent, children: children) }`.
|
|
289
222
|
|
|
290
223
|
Or plain hashes:
|
|
291
224
|
|
|
@@ -298,39 +231,22 @@ TreeNode.arrange_serializable do |parent, children|
|
|
|
298
231
|
end
|
|
299
232
|
```
|
|
300
233
|
|
|
301
|
-
The result of arrange_serializable can easily be serialized to json with
|
|
302
|
-
`to_json`, or some other format:
|
|
303
|
-
|
|
304
|
-
```
|
|
305
|
-
TreeNode.arrange_serializable.to_json
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
You can also pass the order to the arrange_serializable method just as you can
|
|
309
|
-
pass it to the arrange method:
|
|
310
|
-
|
|
311
|
-
```
|
|
312
|
-
TreeNode.arrange_serializable(:order => :name)
|
|
313
|
-
```
|
|
314
|
-
|
|
315
234
|
# Sorting
|
|
316
235
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
TreeNode.sort_by_ancestry(array_of_nodes)
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
Note that since materialised path trees don't support ordering within a rank,
|
|
325
|
-
the order of siblings depends on their order in the original array.
|
|
236
|
+
The `sort_by_ancestry` class method: `TreeNode.sort_by_ancestry(array_of_nodes)` can be used
|
|
237
|
+
to sort an array of nodes as if traversing in preorder. (Note that since materialised path
|
|
238
|
+
trees do not support ordering within a rank, the order of siblings is
|
|
239
|
+
dependant upon their original array order.)
|
|
326
240
|
|
|
327
241
|
# Migrating from plugin that uses parent_id column
|
|
328
242
|
|
|
329
243
|
Most current tree plugins use a parent_id column (has_ancestry,
|
|
330
|
-
awesome_nested_set, better_nested_set, acts_as_nested_set). With
|
|
331
|
-
easy to migrate from any of these plugins
|
|
332
|
-
build_ancestry_from_parent_ids
|
|
333
|
-
|
|
244
|
+
awesome_nested_set, better_nested_set, acts_as_nested_set). With Ancestry it is
|
|
245
|
+
easy to migrate from any of these plugins. To do so, use the
|
|
246
|
+
`build_ancestry_from_parent_ids!` method on your ancestry model.
|
|
247
|
+
|
|
248
|
+
<details>
|
|
249
|
+
<summary>Details</summary>
|
|
334
250
|
|
|
335
251
|
1. Add ancestry column to your table
|
|
336
252
|
* Create migration: **rails g migration [add_ancestry_to_](table)
|
|
@@ -340,7 +256,7 @@ provide a more detailed explanation:
|
|
|
340
256
|
* Migrate your database: **rake db:migrate**
|
|
341
257
|
|
|
342
258
|
|
|
343
|
-
2. Remove old tree gem and add in Ancestry to
|
|
259
|
+
2. Remove old tree gem and add in Ancestry to Gemfile
|
|
344
260
|
* See 'Installation' for more info on installing and configuring gems
|
|
345
261
|
|
|
346
262
|
|
|
@@ -351,7 +267,7 @@ provide a more detailed explanation:
|
|
|
351
267
|
|
|
352
268
|
|
|
353
269
|
4. Generate ancestry columns
|
|
354
|
-
* In
|
|
270
|
+
* In rails console: **[model].build_ancestry_from_parent_ids!**
|
|
355
271
|
* Make sure it worked ok: **[model].check_ancestry_integrity!**
|
|
356
272
|
|
|
357
273
|
|
|
@@ -365,42 +281,7 @@ provide a more detailed explanation:
|
|
|
365
281
|
* Create migration: `rails g migration [remove_parent_id_from_](table)`
|
|
366
282
|
* Add to migration: `remove_column [table], :parent_id`
|
|
367
283
|
* Migrate your database: `rake db:migrate`
|
|
368
|
-
|
|
369
|
-
# Integrity checking and restoration
|
|
370
|
-
|
|
371
|
-
I don't see any way Ancestry tree integrity could get compromised without
|
|
372
|
-
explicitly setting cyclic parents or invalid ancestry and circumventing
|
|
373
|
-
validation with update_attribute, if you do, please let me know.
|
|
374
|
-
|
|
375
|
-
Ancestry includes some methods for detecting integrity problems and restoring
|
|
376
|
-
integrity just to be sure. To check integrity use:
|
|
377
|
-
[Model].check_ancestry_integrity!. An AncestryIntegrityException will be
|
|
378
|
-
raised if there are any problems. You can also specify :report => :list to
|
|
379
|
-
return an array of exceptions or :report => :echo to echo any error messages.
|
|
380
|
-
To restore integrity use: [Model].restore_ancestry_integrity!.
|
|
381
|
-
|
|
382
|
-
For example, from IRB:
|
|
383
|
-
|
|
384
|
-
```
|
|
385
|
-
>> stinky = TreeNode.create :name => 'Stinky'
|
|
386
|
-
$ #<TreeNode id: 1, name: "Stinky", ancestry: nil>
|
|
387
|
-
>> squeeky = TreeNode.create :name => 'Squeeky', :parent => stinky
|
|
388
|
-
$ #<TreeNode id: 2, name: "Squeeky", ancestry: "1">
|
|
389
|
-
>> stinky.update_attribute :parent, squeeky
|
|
390
|
-
$ true
|
|
391
|
-
>> TreeNode.all
|
|
392
|
-
$ [#<TreeNode id: 1, name: "Stinky", ancestry: "1/2">, #<TreeNode id: 2, name: "Squeeky", ancestry: "1/2/1">]
|
|
393
|
-
>> TreeNode.check_ancestry_integrity!
|
|
394
|
-
!! Ancestry::AncestryIntegrityException: Conflicting parent id in node 1: 2 for node 1, expecting nil
|
|
395
|
-
>> TreeNode.restore_ancestry_integrity!
|
|
396
|
-
$ [#<TreeNode id: 1, name: "Stinky", ancestry: 2>, #<TreeNode id: 2, name: "Squeeky", ancestry: nil>]
|
|
397
|
-
```
|
|
398
|
-
|
|
399
|
-
Additionally, if you think something is wrong with your depth cache:
|
|
400
|
-
|
|
401
|
-
```
|
|
402
|
-
>> TreeNode.rebuild_depth_cache!
|
|
403
|
-
```
|
|
284
|
+
</details>
|
|
404
285
|
|
|
405
286
|
# Running Tests
|
|
406
287
|
|