An ‘active’ collection that reflects a relation. A collection stores entitities that participate in a relation.

Methods
Attributes
[RW] building Is the collection in build mode?
[RW] building_members When the collection is in building mode or the owner object is unsaved, added members are accumulated in the building_memebers array. These relations are serialized when the owner object is saved (or when save_building_members is explicitly called).
[RW] count_proc A method used to count the objects that belong to the collection.
[RW] find_options The default find options.
[RW] find_proc A method used to find the objects that belong to the collection.
[RW] insert_proc A method used to add insert objects in the collection.
[RW] loaded Is the collection loaded?
[RW] member_class The class of the members of this collection.
[RW] members The members of this collection. Keeps the objects that belong to this collection.
[RW] owner The owner of this collection.
[RW] remove_proc A method used to remove objects from the collection.
Public Class methods
new(owner = nil, member_class = nil, insert_proc = nil, remove_proc = nil, find_proc = nil, count_proc = nil, find_options = {})

Initialize the collection.

[ show source ]

    # File lib/og/collection.rb, line 62
62:   def initialize(owner = nil, member_class = nil, insert_proc = nil, 
63:       remove_proc = nil, find_proc = nil, 
64:       count_proc = nil, find_options = {})
65:     @owner = owner
66:     @member_class = member_class
67:     @insert_proc = insert_proc
68:     @remove_proc = remove_proc
69:     @find_proc = find_proc
70:     @count_proc = count_proc
71:     @find_options = find_options
72:     @members = []
73:     @loaded = false
74:     @building = false
75:   end
Public Instance methods
<<(obj, options = nil)

Alias for #push

[](idx)

Defined to avoid the method missing overhead.

[ show source ]

     # File lib/og/collection.rb, line 118
118:   def [](idx)
119:     load_members
120:     @members[idx]
121:   end
add(obj, options = nil)

Alias for #push

clear()

Alias for #remove_all

count(reload = false)

Alias for #size

delete(*objects)

Delete a member from the collection AND the store.

[ show source ]

     # File lib/og/collection.rb, line 170
170:   def delete(*objects)
171:     objects = objects.flatten
172: 
173:     objects.reject! { |obj| @members.delete(obj) if obj.unsaved? }
174:     return if objects.empty?
175: 
176:     @owner.transaction do
177:       objects.each do |obj| 
178:         obj.delete
179:         @members.delete(obj) 
180:       end
181:     end
182:   end
delete_all()

Delete all members of the collection. Also delete from the store.

[ show source ]

     # File lib/og/collection.rb, line 215
215:   def delete_all
216:     @owner.transaction do
217:       self.each { |obj| obj.delete }
218:     end
219:     @members.clear
220:   end
delete_if(&block)

Delete a member from the collection AND the store, if the condition block evaluates to true.

[ show source ]

     # File lib/og/collection.rb, line 187
187:   def delete_if(&block)
188:     objects = @members.select(&block)
189: 
190:     objects.reject! { |obj| @members.delete(obj) if obj.unsaved? }
191:     return if objects.empty?
192: 
193:     @owner.transaction do
194:       objects.each do |obj|
195:         obj.delete
196:         @members.delete(obj)
197:       end
198:     end
199:   end
each(&block)

Defined to avoid the method missing overhead.

[ show source ]

     # File lib/og/collection.rb, line 111
111:   def each(&block)
112:     load_members
113:     @members.each(&block)
114:   end
find(options = {})

Allows to perform a scoped query.

[ show source ]

     # File lib/og/collection.rb, line 235
235:   def find(options = {})
236:     tmp = nil
237:     @member_class.with_scope(options) do
238:       tmp = @owner.send(@find_proc, @find_options)
239:     end
240:     return tmp
241:   end
find_one(options = {})

Find one object.

[ show source ]

     # File lib/og/collection.rb, line 245
245:   def find_one options = {}
246:     find(options).first
247:   end
load_members()

Load the members of the collection.

[ show source ]

    # File lib/og/collection.rb, line 79
79:   def load_members
80:     unless @loaded or @owner.unsaved?
81:       @members = @owner.send(@find_proc, @find_options)
82:       @loaded = true
83:     end
84:     @members
85:   end
method_missing(symbol, *args, &block)

Try to execute an accumulator or else redirect all other methods to the members array.

An example of the accumulator:

foo_foobars = foo1.bars.foobars

[ show source ]

     # File lib/og/collection.rb, line 269
269:   def method_missing(symbol, *args, &block)
270:     load_members
271:     if @member_class.instance_methods.include? symbol.to_s
272:       @members.inject([]) { |a, x| a << x.send(symbol) }.flatten
273:     else
274:       @members.send(symbol, *args, &block)
275:     end
276:   end
push(obj, options = nil)

Add a new member to the collection. this method will overwrite any objects already existing in the collection.

If the collection is in build mode or the object is unsaved, the member is accumulated in a buffer. All accumulated members relations are saved when the object is saved.

This method is also aliased as << add

[ show source ]

     # File lib/og/collection.rb, line 132
132:   def push(obj, options = nil)
133:     remove(obj) if members.include?(obj)
134:     @members << obj
135:     unless @building or owner.unsaved?
136:       @owner.send(@insert_proc, obj, options)
137:     else
138:       (@building_members ||= []) << obj
139:       @owner.instance_variable_set '@pending_building_collections', true
140:     end
141:   end
reload(options = {})

Reload the collection.

[ show source ]

    # File lib/og/collection.rb, line 89
89:   def reload(options = {})
90:     # gmosx, NOOO: this was a bug! it corrupts the default options.
91:     #  @find_options = options
92:     @members = @owner.send(@find_proc, options)
93:   end
remove(*objects)

Remove a member from the collection, the actual object is not deleted.

[ show source ]

     # File lib/og/collection.rb, line 151
151:   def remove(*objects)
152:     objects = objects.flatten
153: 
154:     objects.reject! { |obj| @members.delete(obj) if obj.unsaved? }
155:     return if objects.empty?
156: 
157:     @owner.transaction do
158:       objects.each do |obj| 
159:         @owner.send(@remove_proc, obj)
160:         @members.delete(obj) 
161:       end
162:     end
163:   end
remove_all()

Remove all members from the collection.

This method is also aliased as clear

[ show source ]

     # File lib/og/collection.rb, line 203
203:   def remove_all
204:     @owner.transaction do
205:       self.each { |obj| @owner.send(@remove_proc, obj) }
206:     end
207:     @members.clear
208:     @loaded = false # gmosx: IS this needed?
209:   end
save_building_members(options = nil)

In building mode, relations for this collection are accumulated in @building_relations. These relations are saved my calling this method.

[ show source ]

     # File lib/og/collection.rb, line 253
253:   def save_building_members(options = nil)
254:     return unless @building_members
255:     
256:     for obj in @building_members
257:       @owner.send(@insert_proc, obj, options)
258:     end
259:     @building_members = nil
260:   end
size(reload = false)

Return the size of a collection.

This method is also aliased as count

[ show source ]

     # File lib/og/collection.rb, line 224
224:   def size(reload = false)
225:     if @loaded and !reload
226:       return @members.size
227:     else
228:       return @owner.send(@count_proc)
229:     end
230:   end
to_ary()

Convert the collection to an array.

[ show source ]

     # File lib/og/collection.rb, line 104
104:   def to_ary
105:     load_members
106:     @members
107:   end
unload()

Unload the members (clear the cache).

[ show source ]

     # File lib/og/collection.rb, line 97
 97:   def unload
 98:     @members.clear
 99:     @loaded = false
100:   end