[cosmo-dev] Web UI Documentation

[Matthew Eernisse]

Howdy.

I agree in principle with pretty much everything in your e-mail, 
although I would qualify my support in a few areas I'll detail below.

Travis Vachon wrote:
> A simple step we could take to make adding new UI functionality 
> considerably less painful for other developers would be to document the 
> various display code APIs. Basic concepts I would really like to see 
> covered include:
> 
> 1) Lifecycle of various UI elements
>     a) Formalized documentation on functions like "render"
>     b) Discussion of ways to hook in to various parts of the UI 
> rendering process

It's pretty embryonic, but I did document at least some of that stuff 
here when I wrote the layout engine:

http://chandlerproject.org/Journal/UILayoutAndRendering

The information in it is still all accurate.

I posted an e-mail to the list about this, but it's not something like a 
service API that a lot of outside parties touch, so it's easily lost in 
the wiki ether.

Is it even linked from anywhere?

>     c) Discussion of useful functions like "add event to canvas", 
> "select collection" and "redraw canvas from currently loaded data," 
> among others.

Because of the speed at which we've added stuff like list view and the 
generic data-model, all of the code for the things you're mentioning 
here has undergone significant refactoring or rewriting, so documenting 
that in any detail and keeping it in sync with all the changes to the 
code would have been a pretty big challenge given our limited resources.

However, having said that, I think that things may have solidified 
enough that documenting some of these things would not require copious 
rewriting every three or four months.

I'd like to hope that most of the refactoring now will be limited to 
cleaning up obvious messes like cosmo.view.cal.canvas.

> 2) Event system
>     "Application level" event notifications are currently handled with a 
> few multi-purpose dojo topics "/calEvent", "/appEvent" and possibly 
> others. Unfortunately, I'm not aware of any documentation on what each 
> of these topics are supposed to be used for or how they should be used. 
>  From looking at the code I gather that they tend to parse "action" 
> properties and use switch statements to decide what to do. Leaving aside 
> that this seems like a reinvention of the dojo topic functionality, the 
> fact that there does not appear to be documentation on what kind of 
> "actions" can be sent with these topics means that attempting to extend 
> this functionality is nearly impossible. It would be great to have 
> documentation on this.

Bobby actually crafted a nice proposal on use of notifications in the 
Web UI:

http://chandlerproject.org/Projects/HighLevelCosmoUIEventsProposal

In a mailing list thread that started here:

http://lists.osafoundation.org/pipermail/cosmo-dev/2007-February/003034.html

We talked a little bit more about it here:

http://lists.osafoundation.org/pipermail/cosmo-dev/2007-May/003690.html

Regarding your perception that the current implementation of pub/sub in 
the app is a reinvention of Dojo topic functionality -- I guess we have 
a fundamental difference in understanding of the purpose of topics.

My understanding of topics (rightly or wrongly) is that they are 
essentially channels of communication for messages in the app -- similar 
to TV or radio stations, where transimitted messages are all of a 
particular flavor (e.g., AOR, country-western, alternative, etc.) The 
various UI widgets 'tune in' to a topic (or topics) they're interested 
in, and respond to whatever messages come in on the channel.

Creating a separate topic for each possible message that a particular UI 
element can respond to would seem to me to be analogous to having a 
large number of radio stations that can only one song apiece.

Could be that my mental model for topics is out of whack, and needs 
adjusting.

I agree wholeheartedly that the current implementation with the big ol' 
switch could be slow (it's faster to set up, but likely slower to 
respond) -- there are some easy optimiziations we could consider like 
hash-mapping response functions, if we decide it's still a viable approach.

However, taking the opposite tack of defining separate subscriptions and 
response methods for each possible message has some issues as well 
(particularly in view of the relatively large overhead of the 
event.connect call the subscription requires, although this may be 
better in Dojo 1.x).

Just as an example, the messages the collection selector would respond 
to are "collection updated," "collection added," "collection deleted," 
"subscription updated," "subscription added," "subscription deleted" -- 
is that right?

Defining a separate subscription and specific response method for each 
of those, when they all have on only one possible response -- to 
re-render the widget -- seems totally silly to me. I could be missing 
something totally obvious, but it just doesn't make sense to me.

Maybe that means instead of having one single hard-and-fast rule about 
how we apply topics, we need to design something flexible enough for 
simple communications (where a UI element responds to pretty much any 
input the same way) or more complicated interactions like we have with 
the cal canvas.

> 
>  From what I've seen, code comments are, for the most part, pretty good. 
> Unfortunately, they do not give a good picture or intuition for how to 
> use the display code as a coherent whole. This sense is critical for 
> developers who want to add new functionality (like me!). As we move 
> toward 1.0 having this kind of information available will be critical to 
> attracting developers and evolving the code collaboratively, so I hope 
> we can make this a pretty high priority.

I agree completely that this is a significant problem. One of the 
reasons there is no picture of the display code as a coherent whole is 
that frankly, it isn't one. Rather than having a big design up front, 
it's evolved organically over a fairly short period of time.

Every time we add a large new feature, it's a big question of how much 
we refactoring and rewriting we can or should do to make things more 
coherent. As we all know, you have to draw the line somewhere, or you 
never ship.

On the other hand, I would like to think there are some things we can do 
to make all the UI code more approachable (especially since I have no 
idea where things are in your code or Bobby's code either :)), and would 
welcome some ideas about how we can document this stuff to make it more 
palatable to third-party consumers (where that third party is 
essentially "anyone who didn't actually write the code").

Thanks for getting the ball rolling on this.


Matthew