[cosmo-dev] Web UI Documentation

[Travis Vachon]

Hi folks

I spent some time this week implementing add/delete collection  
functionality in the Web UI. As people following in IRC may have  
gathered, I found the process somewhat frustrating. Most difficult was  
interacting with the list and calendar canvas display code, to the  
point that Matthew ended up taking the bug over.

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
	c) Discussion of useful functions like "add event to canvas", "select  
collection" and "redraw canvas from currently loaded data," among  
others.

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.


 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.

Thoughts? Thanks!

-Travis