@@ -11,4 +11,4 @@ Including: == Aggregates -Currently includes count, min, max, avg, sum (more info in dm-aggregates/README) \ No newline at end of file +Currently includes count, min, max, avg, sum (more info in dm-aggregates/README) README @@ -1,18 +1,18 @@ dm-is-nested_set ================ -DataMapper plugin allowing the creation of nested sets from data models. +DataMapper plugin allowing the creation of nested sets from data models. Provides all the same functionality as dm-is-tree, plus tons more! Read on. == What is a nested set? -Nested set is a clever model for storing hierarchical data in a flat table. +Nested set is a clever model for storing hierarchical data in a flat table. Instead of (only) storing the id of the parent on each node, a nested set puts all nodes in a clever structure (see Example below). That is what makes it -possible to get the all of the descendants (not only immediate children), +possible to get the all of the descendants (not only immediate children), ancestors, or siblings, in one single query to the database. -The only downside to nested sets (compared to trees] is that the queries it +The only downside to nested sets (compared to trees] is that the queries it takes to know these things, and to move nodes around in the tree are rather complex. That is what this plugin takes care of (+ lots of other neat stuff)! @@ -50,10 +50,10 @@ We have a nested menu of categories. The categories are as follows: - CD Players In a nested set, each of these categories would have 'left' and 'right' fields, -informing about where in the set they are positioned. This can be illustrated: +informing about where in the set they are positioned. This can be illustrated: _____________________________________________________________________________ | _________________________________ __________________________________ | -| | ______ _____ ________ | | _______________ _________ | | +| | ______ _____ ________ | | _______________ _________ | | | | | | | | | | | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 13 CD- 14 15 16 | | | Tube | | LCD | | Plasma | | | | MP3 Players | | Players | | | @@ -76,7 +76,7 @@ and left/right values would now be: _____________________________________________________________________________ | __________________________________ | | _________________________________ | _______________ | | -| | ______ _____ ________ | | | _________ | _________ | | +| | ______ _____ ________ | | | _________ | _________ | | | | | | | | | | | | | | | | | | | | 1 2 3 4 5 6 7 8 9 10 11 12 Flash 13 14 15 CD- 16 17 18 | | | Tube | | LCD | | Plasma | | | | |_________| | | Players | | | @@ -93,5 +93,3 @@ and left/right values would now be: * http://www.developersdex.com/gurus/articles/112.asp * http://dev.mysql.com/tech-resources/articles/hierarchical-data.html * http://www.codeproject.com/KB/database/nestedsets.aspx (nice illustrations) - - dm-is-nested_set/README @@ -6,4 +6,4 @@ TODO * Add function for (re)building nested set from ordinary tree * Caching the finder-methods * Allow options to pass through finders -* Handle children of destroyed objects \ No newline at end of file +* Handle children of destroyed objects dm-is-nested_set/TODO @@ -4,26 +4,26 @@ module DataMapper def self.included(base) base.extend(GenerateMethod) end - + module GenerateMethod - + ## # docs in the works # def is_a_nested_set(options={}) options = { :child_key => :parent_id }.merge(options) - + extend DataMapper::Is::NestedSet::ClassMethods include DataMapper::Is::NestedSet::InstanceMethods - + property :lft, Integer, :writer => :private property :rgt, Integer, :writer => :private - + belongs_to :parent, :class_name => self.name, :child_key => [ options[:child_key] ], :order => [:lft.asc] has n, :children,:class_name => self.name, :child_key => [ options[:child_key] ], :order => [:lft.asc] - + before :create do - # scenarios: + # scenarios: # - user creates a new object and does not specify a parent # - user creates a new object with a direct reference to a parent # - user spawnes a new object, and then moves it to a position @@ -34,15 +34,15 @@ module DataMapper # user has set a parent before saving (and without moving it anywhere). just move into that, and continue # might be som problems here if the referenced parent is not saved. self.move_without_saving(:into => self.parent) - end + end end - + before :update do # scenarios: # - user moves the object to a position # - user has changed the parent # - user has removed any reference to a parent - # - user sets the parent_id to something, and then use #move before saving + # - user sets the parent_id to something, and then use #move before saving if (self.parent && !self.lft) || (self.parent != self.ancestor) # if the parent is set, we try to move this into that parent, otherwise move into root. self.parent ? self.move_without_saving(:into => self.parent) : self.move_without_saving(:into => self.class.root) @@ -57,53 +57,53 @@ module DataMapper end end end # GenerateMethod - + ## # all the ClassMethods. They do not get added before / unless calling is_a_nested_set - # since we dont want to clutter your model unless you need it. + # since we dont want to clutter your model unless you need it. # module ClassMethods - + ## # get the root of the tree. might be changed when support for multiple roots is added. # def root first(:order => [:lft.asc]) end - + def leaves all(:conditions => ["rgt=lft+1"], :order => [:lft.asc]) end - + def reload_positions repository.identity_map(self).each_pair{ |key,obj| obj.reload_position } end - + def rebuild_parent_child_relationships all.each do |n| n.parent = n.ancestor n.save end end - + def offset_nodes_in_set(offset,range) # :nodoc: self.query_set("lft=lft+(?), rgt=rgt+(?)","rgt BETWEEN ?",offset,offset,range) end - + def alter_gap_in_set(pos,addition,opr='>=') # :nodoc: #[:lft,:rgt].each{ |p| self.query_set("\#{p}=\#{p}+(?)","\#{p} \#{opr} ?",addition,pos)} self.query_set("rgt=rgt+(?)","rgt #{opr} ?",addition,pos) self.query_set("lft=lft+(?)","lft #{opr} ?",addition,pos) end - + def query_set(set,where,*pars) # :nodoc: query = %Q{UPDATE #{self.storage_name} SET #{set} WHERE #{where}} repository.adapter.execute(query,*pars) end end - + module InstanceMethods - + ## # reloads the left and right attributes for self. if #move did not use this, we'd get quite # peculiar results, and most likely corrupt the nested sets pretty fast. @@ -111,7 +111,7 @@ module DataMapper def reload_position self.reload_attributes(:lft,:rgt) end - + ## # move self / node to a position in the set. position can _only_ be changed through this # @@ -122,7 +122,7 @@ module DataMapper # * node.move :into => other # same as setting a parent-relationship # # @param vector <Symbol, Hash> A symbol, or a key-value pair that describes the requested movement - # + # # @option :higher<Symbol> move node higher # specifying nr of steps is in the pipeline # @option :highest<Symbol> move node to the top of the list (within its parent) # @option :lower<Symbol> move node lower @@ -130,7 +130,7 @@ module DataMapper # @option :indent<Symbol> move node into sibling above # @option :outdent<Symbol> move node out below its current parent # @option :into<Resource> move node into another node - # @option :above<Resource> move node above other node + # @option :above<Resource> move node above other node # @option :below<Resource> move node below other node # @option :to<Fixnum> move node to a specific location in the nested set # @@ -142,15 +142,15 @@ module DataMapper move_without_saving(vector) save end - + ## # does all the actual movement in #move, but does not save afterwards. this is used internally in # before :save, and will probably be marked private. should not be used by organic beings. # - # @see move_without_saving + # @see move_without_saving def move_without_saving(vector) if vector.is_a? Hash then action,object = vector.keys[0],vector.values[0] else action = vector end - + ## # checking what kind of movement has been requested, and calculate the new position node should move to # @@ -166,10 +166,10 @@ module DataMapper when :below then object ? object.rgt+1 : nil # : "supply an object" when :to then object ? object.to_i : nil # : "supply a number" end - + ## # raising an error whenever it couldnt move seems a bit harsh. want to return self for nesting. - # if anyone has a good idea about how it should react when it cant set a valid position, + # if anyone has a good idea about how it should react when it cant set a valid position, # don't hesitate to find me in #datamapper, or send me an email at sindre -a- identu -dot- no # # raise UnableToPositionError unless position.is_a?(Fixnum) && position > 0 @@ -179,11 +179,11 @@ module DataMapper self.parent = self.ancestor # must set this again, because it might have been changed by the user before move. return false end - + ## # if this node is already positioned we need to move it, and close the gap it leaves behind etc # otherwise we only need to open a gap in the set, and smash that buggar in - # + # if self.lft && self.rgt # raise exception if node is trying to move into one of its descendants (infinate loop, spacetime will warp) raise RecursiveNestingError if position > self.lft && position < self.rgt @@ -205,49 +205,49 @@ module DataMapper # set the position fields self.lft, self.rgt = position, position + 1 end - + self.parent = self.ancestor - + end - + ## # get the level of this node, where 0 is root. temporary solution - # + # # @return <Fixnum> def level ancestors.length end - + ## - # check if this node is a leaf (does not have subnodes). + # check if this node is a leaf (does not have subnodes). # use this instead ofdescendants.empty? # # @par def leaf? rgt-lft == 1 end - + ## # all methods for finding related nodes following ## - + ## # get all ancestors of this node, up to (and including) self - # + # # @return <Collection> Returns def self_and_ancestors self.class.all(:lft.lte => lft, :rgt.gte => rgt, :order => [:lft.asc]) end - + ## # get all ancestors of this node - # + # # @return <Collection> collection of all parents, with root as first item # @see #self_and_ancestors def ancestors self_and_ancestors.reject{|r| r.key == self.key } # because identitymap is not used in console end - + ## # get the parent of this node. Same as #parent, but finds it from lft/rgt instead of parent-key # @@ -255,7 +255,7 @@ module DataMapper def ancestor ancestors.reverse.first end - + ## # get the root this node belongs to. this will atm always be the same as Resource.root, but has a # meaning when scoped sets is implemented @@ -264,7 +264,7 @@ module DataMapper def root ancestors.first end - + ## # get all descendants of this node, including self # @@ -272,7 +272,7 @@ module DataMapper def self_and_descendants self.class.all(:lft => lft..rgt, :order => [:lft.asc]) end - + ## # get all descendants of this node # @@ -281,7 +281,7 @@ module DataMapper def descendants self_and_descendants.reject{|r| r.key == self.key } # because identitymap is not used in console end - + ## # get all descendants of this node that does not have any children # @@ -289,16 +289,16 @@ module DataMapper def leaves self.class.all(:lft => (lft+1)..rgt, :conditions=>["rgt=lft+1"], :order => [:lft.asc]) end - + ## - # get all siblings of this node, and include self + # get all siblings of this node, and include self # # @return <Collection> def self_and_siblings parent_key = self.class.relationships(:default)[:parent].child_key.to_a.first parent ? self.class.all(parent_key => parent.key) : [self] end - + ## # get all siblings of this node # @@ -307,16 +307,16 @@ module DataMapper def siblings self_and_siblings.reject{|r| r.key == self.key } # because identitymap is not used in console end - + ## - # get sibling to the left of/above this node in the nested tree + # get sibling to the left of/above this node in the nested tree # # @return <Resource, NilClass> the resource to the left, or nil if self is leftmost # @see #self_and_siblings def left_sibling self_and_siblings.find {|v| v.rgt == lft-1} end - + ## # get sibling to the right of/above this node in the nested tree # @@ -325,12 +325,12 @@ module DataMapper def right_sibling self_and_siblings.find {|v| v.lft == rgt+1} end - + end - + class UnableToPositionError < StandardError; end class RecursiveNestingError < StandardError; end - + end # NestedSet end # Is end # DataMapper dm-is-nested_set/lib/dm-is-nested_set/is/nested_set.rb @@ -10,15 +10,15 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES property :id, Integer, :serial => true property :name, String - + is_a_nested_set - + auto_migrate!(:default) # convenience method only for speccing. def pos; [lft,rgt] end end - - Category.create!(:id => 1, :name => "Electronics") + + Category.create!(:id => 1, :name => "Electronics") Category.create!(:id => 2, :parent_id => 1, :name => "Televisions") Category.create!(:id => 3, :parent_id => 2, :name => "Tube") Category.create!(:id => 4, :parent_id => 2, :name => "LCD") @@ -28,7 +28,7 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES Category.create!(:id => 8, :parent_id => 7, :name => "Flash") Category.create!(:id => 9, :parent_id => 6, :name => "CD Players") Category.create!(:id => 10,:parent_id => 6, :name => "2 Way Radios") - + # id | lft| rgt| title #======================================== # 1 | 1 | 20 | - Electronics @@ -41,7 +41,7 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES # 8 | 12 | 13 | - Flash # 9 | 15 | 16 | - CD Players # 10 | 17 | 18 | - 2 Way Radios - + # | | | | | | | | | | | | | | | | | | | | # 1 2 3 4 5 6 7 8 9 10 11 12 Flash 13 14 15 16 17 18 19 20 # | | | Tube | | LCD | | Plasma | | | | |___________| | | CD Players | | 2 Way Radios | | | @@ -52,9 +52,9 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES # | | # | Electronics | # |____________________________________________________________________________________________________| - + end - + describe 'Class#rebuild_parent_child_relationships' do it 'should reset all parent_ids correctly' do Category[5].parent_id = nil @@ -63,13 +63,13 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES Category[9].parent_id.should == 6 end end - + describe 'Class#root' do it 'should return the toplevel node' do Category.root.name.should == "Electronics" end end - + describe 'Class#leaves' do it 'should return all nodes without descendants' do repository(:default) do @@ -77,60 +77,60 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES end end end - + describe '#ancestor, #ancestors and #self_and_ancestors' do it 'should return ancestors in an array' do - repository(:default) do |repos| + repository(:default) do |repos| c8 = Category.get(8) c8.ancestor.should == Category.get(7) c8.ancestor.should == c8.parent - + c8.ancestors.map{|a|a.name}.should == ["Electronics","Portable Electronics","MP3 Players"] c8.self_and_ancestors.map{|a|a.name}.should == ["Electronics","Portable Electronics","MP3 Players","Flash"] end end end - + describe '#children' do it 'should return children of node' do r = Category.root r.children.length.should == 2 - + t = r.children.first t.children.length.should == 3 t.children.first.name.should == "Tube" t.children[2].name.should == "Plasma" end end - + describe '#descendants and #self_and_descendants' do it 'should return all subnodes of node' do repository(:default) do r = Category.root r.self_and_descendants.length.should == 10 r.descendants.length.should == 9 - + t = r.children[1] t.descendants.length.should == 4 t.descendants.map{|a|a.name}.should == ["MP3 Players","Flash","CD Players","2 Way Radios"] end end end - + describe '#leaves' do it 'should return all subnodes of node without descendants' do repository(:default) do r = Category.root r.leaves.length.should == 6 - + t = r.children[1] t.leaves.length.should == 3 end end end - + describe '#move' do - + # Outset: # id | lft| rgt| title #======================================== @@ -144,64 +144,64 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES # 8 | 12 | 13 | - Flash # 9 | 15 | 16 | - CD Players # 10 | 17 | 18 | - 2 Way Radios - - + + it 'should move items correctly with :higher / :highest / :lower / :lowest' do repository(:default) do Category[4].pos.should == [5,6] - + Category[4].move(:above => Category[3]) Category[4].pos.should == [3,4] - + Category[4].move(:higher).should == false Category[4].pos.should == [3,4] Category[3].pos.should == [5,6] Category[4].right_sibling.should == Category[3] - + Category[4].move(:lower) Category[4].pos.should == [5,6] Category[4].left_sibling.should == Category[3] Category[4].right_sibling.should == Category[5] - + Category[4].move(:highest) Category[4].pos.should == [3,4] Category[4].move(:higher).should == false - + Category[4].move(:lowest) Category[4].pos.should == [7,8] Category[4].left_sibling.should == Category[5] - + Category[4].move(:higher) # should reset the tree to how it was - + end end - + it 'should move items correctly with :indent / :outdent' do repository(:default) do Category[7].pos.should == [11,14] Category[7].descendants.length.should == 1 - + # The category is at the top of its parent, should not be able to indent. Category[7].move(:indent).should == false - + # After doing this, it tries to move into parent again, and throw false... Category[7].move(:outdent) Category[7].pos.should == [16,19] Category[7].left_sibling.should == Category[6] - + Category[7].move(:higher) # Move up above Portable Electronics - + Category[7].pos.should == [10,13] Category[7].left_sibling.should == Category[2] end end end - + describe 'moving objects with #move_* #and place_node_at' do # it 'should set left/right correctly when adding/moving objects' do # repository(:default) do # Category.auto_migrate! - # + # # c1 = Category.create!(:name => "Electronics") # pos(c1).should == [1,2] # c2 = Category.create(:name => "Televisions") @@ -219,57 +219,57 @@ if HAS_SQLITE3 || HAS_MYSQL || HAS_POSTGRES # pos(c1,c2,c3,c4).should == [1,8,2,3,4,5,6,7] # c2.move :into => c4 # pos(c1,c2,c3,c4).should == [1,8,5,6,2,3,4,7] - # + # # end # end - + it 'should set left/right when choosing a parent' do repository(:default) do Category.auto_migrate! - + c1 = Category.create!(:name => "New Electronics") - + c2 = Category.create!(:name => "OLED TVs") - + c1.pos.should == [1,4] c2.pos.should == [2,3] - + c3 = Category.create(:name => "Portable Electronics") c3.parent=c1 c3.save - + c1.pos.should == [1,6] c2.pos.should == [2,3] c3.pos.should == [4,5] - + c3.parent=c2 c3.save - + c1.pos.should == [1,6] c2.pos.should == [2,5] c3.pos.should == [3,4] - + c3.parent=c1 c3.move(:into => c2) - + c1.pos.should == [1,6] c2.pos.should == [2,5] c3.pos.should == [3,4] - + c4 = Category.create(:name => "Tube", :parent => c2) c5 = Category.create(:name => "Flatpanel", :parent => c2) - + c1.pos.should == [1,10] c2.pos.should == [2,9] c3.pos.should == [3,4] c4.pos.should == [5,6] c5.pos.should == [7,8] - + c5.move(:above => c3) c3.pos.should == [5,6] c4.pos.should == [7,8] c5.pos.should == [3,4] - + end end end dm-is-nested_set/spec/integration/nested_set_spec.rb @@ -1,2 +1,2 @@ --format specdoc ---colour \ No newline at end of file +--colour dm-is-nested_set/spec/spec.opts @@ -90,7 +90,7 @@ class ResourceControllerGenerator < Merb::GeneratorBase end end - #returns the params needed for getting the object. + #returns the params needed for getting the object. # uses params[:id] as a default if no keys has been set in the model. def params_for_get params = properties.select{|p| p.key?}.map{|p| "params[:#{p.field}]"}.join(', ') merb_datamapper/datamapper_generators/resource_controller/resource_controller_generator.rb d04f6ba06fb23ed852bd3e3aa08c99d6da85a51e Dan Kubb dan.kubb@autopilotmarketing.com http://github.com/sam/dm-more/commit/0ff796fa8fe64e1125c74bfd1be405f338fdab9d 0ff796fa8fe64e1125c74bfd1be405f338fdab9d 2008-05-25T16:15:53-07:00 2008-05-25T16:15:53-07:00 Whitespace cleanup with "sake strip" (from dm-dev sake tasks) b4acf877d5042a5e4bccd03e24154f5dcf80e1c3 Dan Kubb dan.kubb@autopilotmarketing.com