Katie Capps Parlante wrote:
Thanks
John, these are good comments. I'll see what I can do with them. ;)
Cheers,
Katie
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.
This was a big point of confusion when I first started working on
chandler.. I didn't understand how objects were persisted in the
repository, but code wasn't.
The way I look at it now is that an "object" is really an "object
instance" and the only thing that's really important in an "object
instance" is the data, which in python is simply stored in attributes.
As long as all data in a python class is representable in the
repository, then that's all you need to store.
I imagine a diagram kinda like
Stored on Disk | Running in Memory
|
+---------------+ |
| Repository |____ |
| (data) | \ |
+---------------+ \ | +----------------------+
\_|__| Running Chandler |
+---------------+ / | | (code+data in memory)|
| Python source |_____/ | +----------------------+
| (code) | |
+---------------+ |
|
Where there is a two way arrow between the repository and the running
chandler, and a one-way arrow from Python source to the running
chandler.
Alec
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
|
