Nesting Leaves

Just like any other complex software challenge it makes sense to break
down a complex user interface into smaller testable chunks. While it
is possible to make a single Leaf, View and LeafModel set handle a
complex interface that would reject many of the benefits the Leaf module
can bring you by nesting components.

Controls are a great example of component nesting. Each control
wraps a presentation of HTML along with the detection of the control's
value changing and surfaces those changes through events to the
parent Leaf.

A Leaf for the page with a View and LeafModel combined with
standard controls is often enough compartmentalisation for many
tasks like a contact form for example. However more complex interfaces
may lend themselves to being composed of several smaller leaf
components interacting through events. For example a payment recording
interface might compose it's interface by creating and using
PaymentList, EntryForm and BatchTotal leaves.

Creating nested leaves

The View must create any nested leaves it will need in the
special function createSubLeaves(). If created elsewhere the
nested leaf will not be included in event processing and so its
user interactions will not be regarded.

In createSubLeaves() the View should call registerSubLeaf() and
pass the list of leaf objects it needs.

It is important to note that the Leaf class has no role in
creating nested leaves. It is the View that is electing to create
the nested leaves in order to fulfill its contract (via the LeafModel)
with the Leaf class. The View could be swapped with another that
used different nested leaves or none at all and the Leaf class would
not be aware.

All Leaf objects have a name. Control leaves expect the name to be
passed to it as this is required to setup automatic data bindings.
Other leaf classes may not require a name in which case the class
name would be used instead.

Printing nested leaves

Registered leaves are added to the $leaves array on the View class
using the leaf name as an index. Leaf objects implement the
__toString()
function and so can be 'printed' directly: