[Chandler-dev] What every parcel writer should know about how to add collections to the sidebar

[John Anderson]

Awhile ago I updated ModifyCollectionEvent so it could be used by 
parcels to add a collection to the sidebar. Since then, it's become 
clear that most uses of ModifyCollectionEvent are to add items to the 
sidebar. So I've renamed it AddToSidebarEvent and updated the default 
values to make it easier to use. I also incorporated Alec's suggestion 
to allow a user-defined function to be used to create a new collection.

Here's a more detailed description of the new event taken from the code:

    Adds items to the sidebar. The items may be either a collection or tree
    of blocks.   
   
    You can add an item to the sidebar in two different ways: Either add a
    reference to a template item to the C{items} attribute and a copy of
    the template will be added when the event is dispatched. Or implement
    the C{onNewItem} method on your subclass of AddToSidebarEvent and it
    will be called to create the item added to the sidebar. If your method
    returns None then nothing will be added to the sidebar.
   
    By default the item will be selected and it's displayName will be
    disambiguated, i.e. a "-NN" suffix added to make it unique.
   
    By setting the preferredKind UserCollection attribute of your 
collection,
    it will be displayed in a particular application area as follows:
   
    If preferredKind attribute is absent (the default) then the collection
    will be the current application area.
   
    If preferredKind attribute is None the collection will be viewed in All
   
    if preferredKind attribute is the kind associated with another 
application
    area it will be displayed in that area. For example if preferredKind is
   
    schema.ns('osaf.pim.calendar.Calendar', 
theView).CalendarEventMixin.getKind (theView)
   
    it will be displayed in the calendar area.
   
    For more advanced options see AddToViewableCollectionEvent.

John