[Dev] Change to detail view subtree mechanism: they're now annotations

[Bryan Stearns]

I've changed the way the detail view locates the blocks to be displayed 
for the selected item... I've updated all the parcels in our tree to 
work the new way, but I figured I'd explain the change here for future 
reference (and yes, I'll figure out where the docs need to change too).

When displaying an item, which can be stamped as more than one Kind, the 
detail view collects "subtrees" of block to be included: a Note gets the 
body field & title, a CalendarEvent gets the date-time stuff, an Email 
gets to/from/etc.

Previously, a specific class existed (named TrunkSubtree) that had a 
Kind attribute and a rootBlocks list; as you'd guess, it mapped a Kind 
to the blocks that were to show up for that Kind. (Actually, there was a 
subclass of TrunkSubtree, DetailTrunkSubtree, that existed solely so 
that the detail view could find _its_ TrunkSubtrees.)

I've changed this (today, rev 9337) as part of doing more 
TrunkParentBlock->BranchPointBlock renaming: TrunkSubtree and 
DetailTrunkSubtree are gone. Instead, there's now a schema.Annotation 
called BranchSubtree, which directly annotates Kinds. (The schema API 
provides the Anootation mechanism: the attributes of an Annotation 
actually reside on the item that's being annotated, and a wrapper is 
used to access these extra attributes on a particular annotated Item.)

The BranchSubtree annotation adds a "rootBlocks" list to the Kind, just 
like the old TrunkSubtree's rootblocks attribute; now, though, when the 
detail view has to build a view for a particular item, it can just look 
at the item's Kinds and collects all the rootBlocks it finds. This is 
simpler and more direct.

Parcel authors don't need to understand much about this mechanism; the 
detail parcel provides a new shortcut function "makeSubtree(parcel, 
kindOrClass, rootBlocks)" that builds the annotation and sticks the 
provided list of rootBlocks on it. (To make things extra simple, that 
second parameter can be a class, and the function will get the Kind for 
the class.)

For example, here's the old way the Amazon parcel attached its blocks to 
its Kind (AmazonItem):
    *detail.DetailTrunkSubtree.update(parcel, "amazon_detail_view",*
        *key = AmazonItem.getKind(parcel.itsView),
        rootBlocks =* [
            detail.MarkupBar,
            AmazonDetailBlock.update(parcel, "amazonDetail",
                blockName = "amazonDetail",
                size = SizeType(100,50),
                minimumSize = SizeType(100,50),
            ),
        ])

The new way looks like:
    *makeSubtree(parcel, AmazonItem,* [
        detail.MarkupBar,
        AmazonDetailBlock.update(parcel, "amazonDetail",
            blockName = "amazonDetail",
            size = SizeType(100,50),
            minimumSize = SizeType(100,50),
        ),
    ])

...Bryan

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osafoundation.org/pipermail/dev/attachments/20060203/2a7672a8/attachment.htm