[cosmo-dev] Web UI Documentation

[Travis Vachon]

Hi Matthew

Thanks for the response! Replies inline.

On Nov 12, 2007, at 9:49 PM, Matthew Eernisse wrote:
>
> 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?

Ah, this looks like a good start, sorry I didn't remember the email.  
I'm going to go through this and make additions where I can and  
suggestions for expansion where I'm not familiar with the code.

>
>
>>    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.

Totally sympathetic here, with the speed of code releases I think  
documentation has definitely taken a back seat, which was half the  
reason I wanted to bring it up ;-)
>
> 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.

The topic system is very flexible and open ended, and I don't think  
your metaphor provides good intuition for how it can be used. Assuming  
performance isn't a factor (that is, assuming it is the same for  
either system; I'll come back to this) in my mind we would replace  
each of the current "actions" with a topic, since these are a pretty  
good summary of the kinds of events we'd want to react to. New topics  
would be added sparingly, as a general rule only when new  
functionality is added.

>
>
> 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).

Do you have any data on this overhead? Also, we aren't talking about  
event.connect, we're talking about dojo.publish and dojo.subscribe.  
I'd like to spend some time today putting together some performance  
data that will hopefully give us better intuition about these  
tradeoffs, I'll check it  into trunk so we can make it part of our  
eventual performance test suite.

>
>
> 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?

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.

The fallacy here is that each topic has only one possible response. Of  
course, if two topics have only one possible response across the  
application, they should not be two different topics.  Several of the  
topics you list aren't like this at all. In an ideal world we wouldn't  
re-render the entire widget for collection added and collection  
deleted, we would just update the appropriate UI (dom nodes)  
accordingly, which in this case would mean significantly different  
operations. On the other hand, I can see an argument that  
"subscription updated" and "collection updated" should not be separate  
topics.

>
>
> 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.

Let's start simple, let's come up with a hard and fast rule that is as  
simple as can possibly work. If we run into a situation where this  
system breaks down we can reconsider the design at that point. I  
propose:

Replace each of the current "actions" with a topic and add new topics  
only when new functionality is added. Topics should be
a) well defined (documented, defined in a well known spot in the code),
b) general purpose (if it is hard to imagine why there would be  
multiple subscribers, just make it a method call),
c) sensible to a human being (e.g. "collection updated" not "x cleared")
d) event oriented, non-imperative (e.g. "collection updated" not  
"rerender").

Publishers should pass along _all_ information relevant to the topic  
they are publishing. Subscribers are unconstrained.

Thoughts?

>
>
>> 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.

Right, and it definitely feels like it, and because there is minimal  
documentation of the current code it's difficult to even have a  
conversation about how we can make it more coherent, glad you're on  
board! To be honest, this is the discussion I really want to have, but  
I think improving the docs are a necessary first step.

>
> 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").

I'll ping you once I'm done going through the wiki page you posted,  
thanks for that!

-Travis