container

A container is a Class Object that can both contain other class objects and itself be contained.

###addChild(child[, name])

The child argument should be an instance of a sudo Class (or a POJO). This object will be pushed into the container's collection of children with a few properties added to it, establishing the parent-child relationship:

• A reference to the container will be added to the child at child.parent
• An integer will be added to the child, at child.index representing the index at which the child resides in the parent container's children array.
• If the optional name argument was passed it is appended to the child at child.name.

If the optional name argument is passed the parent container places the name into its childNames hash with the name as a key, and the index of the child as its value. Finally, after all the above has occurred the parent container will look for the presence of a addedToParent method on the child, call it if present passing itself an the argument, then return this.

###addedToParent(parent)

A "virtual" method than can optionally exist on a container class. If a class instance has this method it will be called by a parent container when the class instance is added to that parent. The parent will pass itself as the argument.

###getChild(identifier)

The "identifier" argument could be either an integer, causing the parent container to fetch the child residing at that index in its children array, or a string - in which case the parent container will fetch the child using the optional name argument passed when it was added. Returns the child found (or undefined if not).

###removeChild(argument)

You may pass three types as "argument"

• An integer, assumed to be an index.
• A string. The parent container will assume this is a name
• An object. This will be assumed to be a class instance that was previously added with addChild.

Once the input is normalized, and the child found it will be removed from this.children and this.childNames. All remaining children will have their index property adjusted accordingly, and the child will have its parent, index, and name properties removed.

Note: No adjustment to DOM elements are performed on sudo.View type parent containers or children when adding and removing. Override methods and use the provided base() functionality if needed.

###removedFromParent(parent)

If present on a child being removed will be called by the parent with the parent sending itself as the argument.

###bubble

A simple method that, by default, returns a child's parent if it has one. This method is used by the container.send method to "bubble" messages (method calls) up through a heirarchy when no target is known. (see container.send).

###send(arguments)

This is a call to a specified method on an (un)specified target. Internally the terms sendMethod and sendTarget are used. The sendMethod is a named method that is expected to exist on some ancestor of the child container calling send. The ancestor in question will be located using the container.bubble method. In a simple case:

this.send('foo');

Called from a child container class would locate the first ancestor via container.bubble (usually will be child.parent), this object has now been identified as the possible sendTarget, and look for a method named 'foo' on it. If found, the method would be called with the child itself as the first argument. If not found, container.bubble would continue (locating parent.parent) looking for the sendMethod ('foo' in this case).

Any number of arguments can be passed after the initial sendMethod and those will be passed on to the eventual sendTarget along with the "sender". This means that the signature of a sendMethod should always be at least (sender). The 'foo' sendMethod from above then would, at least, look like:

parent.foo = function(sender) {
  // do stuff with sender
};

####Normalizing the Arguments to Send

Only the first argument passed to send will be inspected for information. All others will be simply passed to the sendTarget when found.

1. sendMethod must be located first. The Class calling send will:

2. Check its data hash for a sendMethod

3. Use the first argument passed to send if it is a string

4. If the first argument is an object: 1. Look for a sendMethod 2. Look for a data.sendMethod (this works for custom event.data)

5. sendTarget is found next by:

6. Class inspects its data hash for sendTarget

7. Class will use the bubble method

Once both are located sendTarget.sendmethod(sender, ...) is called. Note: the scope of the method called will be bound to the object that owns it (the sendTarget).

While you do not (and usually will not need to) explicitly state sendTargets or sendmethods in a child (via its data hash), you can if you choose.

#####Explicit sendTarget and sendTarget

You can always explicitly state both the sendTarget and sendMethod in a child's data hash and they will take precedence, negating the need to send them via arguments. You could then simply:

this.send();

#####Explicit sendTarget

If only a sendTarget is placed in the data hash, the send method will find the sendMethod in the arguments (string or in a data object).