[Cosmo-dev] Topics Proposal

[Matthew Eernisse]

Resending because it got trapped in moderation purgatory ...

I'm copy-pasting stuff here from the wiki page to avoid cluttering the
page with chitchat. It'll also make it clearer what points I'm talking
about.

One of my biggest questions was this -- what exactly defines "high-level
events"? Does that mean that the use of topics should be reserved solely
for these? Or would there be other places in the UI code potentially
using topics in a different way?

Bobby Rullo wrote:
> Hi all. Here is my first attempt at a proposal for a notification 
> framework for the CosmoUI
> 
> http://wiki.osafoundation.org/Projects/HighLevelCosmoUIEventsProposal

> Well Defined
> The messages that are sent via topics will be well-defined 
> and documented, so that future elements can take advantage
> of them. Ad-hoc topics or messages should not be created,
> and existing ones should be either formalized or removed.

Agreed. Well-defined and documented is good.

However, I would add that I'm not delusional enough to believe that we
can actually *pre-define* every topic or message -- there will be things
that shake out during implementation that will necessitate our making
changes to our plan. In that case we'll have to formalize the changes as
we go.

I also have some questions about how granular we want to be, for
example, in attempting to pre-define what's in a package of data sent
with all published messages of a particular type. When I was
implementing recurrence, there were many occasions where I was totally
unable to anticipate all the things up-front that the canvas might need
to know to re-render after a particular kind of update.

It's information about the initial state of the canvas and the type of
update (e.g., weird things like moving back the end-date of the
recurrence to a date *before* the event in the recurrence where the
selection currently sits) -- and passing that info from the point where
the edit starts, through (sometimes multiple) asynchronous calls, and to
the rendering code.

> When not to...
> Topics should not be used where simple method dispatching would
> do just as well if not better. In other words, if your topic
> is very case-specific and you only expect one subscriber ever,
> please re-consider whether or not to use topics.

Good vote. I can think of at least one place in cosmo/view/cal.js (the
display of the modal dialog for asking users how they want to apply
their changes) where I think my use of topics was gratuitous.

> Service Layer - When topics get published
> This may be obvious, but Messages will get published on a topic 
> AFTER a service call has been completed - successfully or not.

Sometimes we will need to publish messages to pieces of the UI *in
preparation for* a service call, so the UI code can do things like show
a 'processing' message or make a backup copy of the data in the item for
the update-failure rollback.

The coordination between the minical, the go-to date box, and
week-to-week navigation arrows is a good example of this.

> Whodunnit? 
> It's preferable that the publishing of a particular message 
> happens at one place in the code, so there is no ambiguity as to 
> "who" should do the calling. For some messages, this is pretty
> clear: since all saving of items happens at the service layer,
> the service layer should be publishing topics.

I may be totally missing something here, but I can't see how limiting
the publish call to the service layer resolves the question of who is
doing the calling. It seems like you have two choices -- (1) disparate
UI elements publishing directly to a topic, or (2) disparate UI elements
each calling methods in the service layer that will then publish to a topic.

Both approaches will require building in something specific to indicate
where (i.e., from which piece of the UI) the chain of execution started.

A good example of this is the fix for bug 7678 -- the minical needs to
know if the call to change the view date-range originated with itself,
or somewhere else. Based on that, it knows whether to re-render
completely, or just change the selection location.

One way to deal with this might be a formalized piece of data in
published messages such as messageOriginator or some such.

It also seems like deciding that "publishing of a particular message
should only happen in one place in the code" might be giving up a little
too much of the advantage of decentralization that topics give us.

> Loading an item(s) is not an Event
> Loading items will not cause a message to be published. Travis 
> and I agonized over this, but for performance reasons and
> philosophical reasons we don't think this is a good idea. The
> rule for model related messages is that messages only get
> published when something changes - the fact that something
> loaded is not a change.

Practically speaking, there needs to be some way to tell the various
affected pieces of the UI, "hey, the data from the server is all there
now, you can render (or re-render) the view." Since we're talking about
a number of autonomous UI widgets, why would we not use topics to
communicate that to them?

User interaction usually looks like this:

1. User tries to do something in the UI (load, update, whatever)
2. UI gives 'processing' feedback of some kind
3. UI code makes a request to the server
4. Response comes back, either successful/unsuccessful
5. UI code either (a) displays the current view, or (b) shows a "sorry,
Charlie" message and restores the previous view

 From the perspective of (for example) the canvas rendering code, it's
pretty much the same, whether you're talking about the initial load of a
collection, navigating week-to-week, or making changes to an item. I
think it makes sense to treat them all the same way, but I'm open to
specific, concrete arguments about why we shouldn't.

> type = "updated" <-- either "updated", "created" or "deleted"

I'm not sure about Dashboard view, but the calendar canvas will need a
little more granularity to know how to render the result. It needs
metadata (e.g., the saveType prop currently used) along with the main
message so that it knows *what flavor* of update/removal success/failure
it has.

Also, when an error occurs, the UI work doesn't stop with displaying the
error message -- there is rollback rendering to do. So the message type
either needs to encompass a notion of success/failure (as with the
saveAction property (with values like removeSuccess or saveFailed) in
the current code), or we'll want a success/failure flag to indicate the
final status of the operation.

> item = <<object>> <-- the item in its updated form (null if deletion)

In cases with recurrence, updating the UI correctly requires more than
the currently selected (or even the currently updated) item -- an
example of this is the instanceEvent and originalEvent properties being
passed now in the data object published through topics.

>  Retrofitting with Existing Code, Widgets

De-coupling the callers and handlers in the existing code is something
we definitely need to continue doing. I did a big round of that during
recurrence, and some more stuff in cal_main.js at the end of 0.6.

One place I'd really like to revisit is how the Draggable hands off the
update process after its 'drop' method is called. However, there's not
much more refactoring we can do there until we figure out where the
stuff in legacy/cal_event.js is going.

That's all I've got for now. Very, very good work with this stuff,
y'all. I'm really looking forward to moving these ideas into the codebase.


Matthew