Thanks John, these are good comments. I'll see what I can do with them. ;)
Cheers,
Katie
John Anderson wrote:
I reviewed the draft of the 0.6 architecture writeup. Overall, I thought
it was excellent. Feel free to incorporate the following comments if you
think they are appropriate:
In "Data Driven Architecture":
You mention that "The Python code isn't persisted". I think this might
be a little misleading since, when you use a persisted Item, it's
methods are always exists. Perhaps you should say Python code isn't
stored in the repository, or Python code in the application is
automatically associated with Items in the repository, or maybe you
shouldn't mention anything.
Under the description of Collections, you might want to mention that
Collections can be made by combining two or more Collections with
boolean operations. Rather than saying collections use queries, you
might say Collections can contain all the items of a Kind, or filter
another Collection using a Python expression.
In "Data Application Layer":
You might make a distinction between loading all the parcels the first
time -- which should be thought of more like a "build a step" and
loading parcels that were installed after Chandler has already been
run. Even though this isn't always how we ran Chandler today as we
develop, it's important for developers to understand that the repository
always exists and when users typically run Chandler, most parcels were
usually loaded some time in the past. Maybe you could say: Parcels are
not loaded each time you run Chandler, unless they have changed.
The description of how the MainView object gets populated with UI Item
objects seems a bit off. During the initial repository build step, A
tiny topmost tree of blocks rooted at the MainView, some template trees
of blocks, collections, but not including most the UI Items that
eventually get displayed are loaded into the repository. All these are
Items, no different from other Items, loaded from Parcels. After the
repository is built, when the UI is first displayed (i.e. when rendering
the MainView), the BranchPoint Block's controller delegate creates trees
of UI blocks from a combination of code and templates. These trees of
blocks make up most of the UI that is actually displayed.
You might mention the repository viewer as an early "experimental"
parcel, not feature.
In "CPIA":
It wasn't clear in your diagram whether the diagram was supposed to
represent the arrangement of UI on the screen, or the arrangement of
Blocks in the repository. If it's the latter, menu items and toolbar
items can be anywhere in a tree of blocks, not just at the top.
You might mention that the Sidebar contains a Collection of Collections
instead of a list of Collections, and that any number of items can be
selected in the Sidebar instead of just one, however, only one is
displayed in the SummaryViews/DetailView.
In the second paragraph after the first diagram, I'd describe the
typical function of a block as storing the persistent state of the UI
and delegating the display an Item to a widget, and not mention pulling
it from the Repository, since that's an automatic function of all Items.
In the paragraph just after the second diagram (and the one following
it), I would avoid using the term "render", e.g. In the sentence: The
Block delegates the rendering work to a delegate object, called a Widget
because we also use the term render to describe the process of creating
the widget. Perhaps you could say: The Block delegates the work of
display and user-interaction to a delegate object, ...
In the next paragraph, beginning with "Block objects store
information..." you mention that the selection is on the Block. We
recently moved the selection to the Collection (now a
IndexedSelectionCollection, described below) in contents. It contains
the selection and the sort, e.g. order of items in the collection that
is displayed on screen. Now when a single Calendar block is used to
display different contents, each contents has its own selection.
Under "Key decisions" I had never heard of the phrase "We're not trying
to boil the ocean here." After a little googling, it was still unclear,
but my guess is it means trying to solve an intractable problem. Using
CPIA for non-Chandler applications doesn't seem intractable, but
instead, is not an OSAF goal. If people interpret Chandler as a
personal information manager, they might conclude that the CPIA
framework excludes non-PIM content items. Also, CPIA doesn't preclude
interfaces without Sidebars, SummaryViews DetailViews, e.g. the
RepositoryViewer. Perhaps it would make more sense to instead say: OSAF
doesn't intend to use CPIA for any other purpose than building the
Chandler user-interface and allowing for extensions, e.g. extending the
DetailView
Under "Most CPIA code can be found here:" there isn't a SummaryTable
block today. The summary table uses a Table block which is a general
purpose table.
Somewhere nearby the discussion of "The Parcel Developer's Guide to the
Schema API", you might mention that the repository's data model differs
from Python's data model. Notable examples include ref collections,
bidirectional refs, and restrictions on using single refs.
Under "Extension Parcels" the repository viewer and CPIA Viewer are
simple extensions that don't use the SummaryTable or Detail blocks.
In "Threading Model"
The last sentence might be rewritten as follows: As the new changes are
picked up, Blocks are notified about changes to their contents which
caused their Widgets to repaint repaint the affected data in the next
Paint cycle.
In "Collections and Notifications"
You might start with a brief description of each of the different kinds
of Collections:
KindCollection: a collection of all Items of a particular kind
ListCollection: an explicit list of items
DifferenceCollection: a collection that results from the difference of
two source Collections.
UnionCollection: a collection that results from the union of two or more
source Collections
IntersectionCollection: a collection that results from the intersection
of two or more source Collections
FilteredCollection: a collection that contains only those items from
another collection that match a Python filter expression
InclusionExclusionCollection: a compound collection that implements add
by adding items to a unioned, "inclusions" ListCollection, and delete by
adding items to a difference, "exclusion" ListCollection, and always
excludes items in a Trash collection. InclusionExclusionCollection was
implemented as a convenience since most user Collections in the Sidebar
need this functionality.
IndexedSelectionCollection: A collection that adds an index, e.g.for
ordering items in the collection, and a selection for selecting a subset
of the items to source collection. IndexedSelectionCollection allow the
user interface to order and store selections on existing Collections.
As mentioned above, you might replace querying for items with
Collections of all items of a particular kind and filtering another
Collection with a Python expression.
It might be better not to mention Repository Sets in an overview
document since Collections were designed so that you didn't need to know
anything about Repository Sets, which are just an implementation detail
from the API point of view. Also the details of implementation of
Notifications are quite complicated and subject to change. It might be
better to mention that Blocks, when rendered (i.e. displayed on the
screen), that have a contents attribute, will automatically be notified
about changes to their contents in wxWidget's OnIdle processing. Blocks
coordinate with their widget to make sure that changes to the data are
reflected properly on the screen.
The Attribute Editor notification mechanism, using monitors, doesn't
pick up changes from other views, so we will soon switch over to use the
same notification mechanism that we use for Collections today.
John
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
