[cosmo-dev] Web UI Documentation
travis at osafoundation.org
Fri Nov 9 13:41:12 PST 2007
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
c) Discussion of useful functions like "add event to canvas", "select
collection" and "redraw canvas from currently loaded data," among
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.
More information about the cosmo-dev