Adding support for a fully-rendered notification on views?

[chikamichi]

Hi,

When using Giraffe, a common pattern emerged: I use afterRender hooks a lot to create subviews. I don't know if its the recommended way of doing it, but it feels smooth enough that I keep doing it without any issues.

Current implementation of render in Giraffe.View is as follow:

render: (options) =>
    # …
    @afterRender.apply @, arguments
    @trigger 'rendered', @, options

The "rendered" event will thus fire without waiting for any sub-rendering that may occur within afterRender (for instance, rendering of subviews). It thus prevents from doing some DOM manipulation that require the subview's DOM to exist in the document DOM (because subviews' DOM may not be available yet for it they have not been attached yet) or that require any sort of asynchronous post-processing for that matter (waiting for data from an API to fill in, waiting for animations to run, waiting for a semaphore to unlock, waiting for another subview to render/get its data etc.)

I got around this by having my subviews expose a "rendering promise", and by having their common parent view's afterRender hook (where the subviews are created) monitor those promises, so as to fire a "fully_rendered" event when all subviews are completely rendered. The callback to this event is then a good place to perform any DOM manipulation on the parent view and its subviews.

I wonder whether Giraffe could add built-in support for such a logic. Given the piece of code above, it could look like this:

render: (options) =>
    # …
    afterRendering = @afterRender.apply @, arguments
    afterRendering.done => @trigger 'fully_rendered', @, options
    @trigger 'rendered', @, options

with afterRender having a new default implementation (currently: ->):

afterRender: ->
    @fullyRendered.resolve()
    return @fullyRendered.promise()

where @fullyRendered is a new $.Deferred() stored on the view.

Someone willing to create subviews inside an afterRender hook could then do something like this in a view:

# ParentView:
afterRender: ->
    @subview1 = new SubView1()
    @subview2 = new SubView2()

    $.when(@subview1.fullyRendered, @subview2.fullyRendered).done =>
      @manipulateDOM()
      @fullyRendered.resolve()

    return @fullyRendered.promise()

manipulateDOM: ->
  @subview1.$('.tool.delete').popup
    content: 'Delete this subview'
  # whatever…

And later on, somewhere else I'd rather use events than binding to a promise:

@parentView = new ParentView()
@listenTo @parentView, 'fully_rendered', @doStuff

One could use @parentView.fullyRendered.done -> …, but somehow, I feel like promises are more of an internal (yet very useful) trick. YMMV 🌌

Obviously, the public API could be simplified to its bare minimum by wrapping afterRender inside some wrapper that would return @fullyRendered.promise(), while @fullyRendered.resolve() could also be hidden behind something like @nowFullyRendered(), so the end user may only ever need to return @nowFullyRendered() to gain access to the feature (if he needs to!).

What do you think?

[chikamichi]

Just to let you know about my setup regarding this feature:

Giraffe.View::_trackFullRendering = ->
  @_fullyRendered = new $.Deferred()
  @fullyRendered = @_fullyRendered.promise()
  @fullyRendered.done =>
    @onFullyRendered.call(@)
    @trigger.call(@, 'fully_rendered', @)

Giraffe.View::beforeInitialize = _.wrap Giraffe.View::beforeInitialize, (beforeInitialize) ->
  @_trackFullRendering()
  beforeInitialize.call(@)

Giraffe.View::beforeRender = _.wrap Giraffe.View::beforeRender, (beforeRender) ->
  @_trackFullRendering() if @_fullyRendered?.state() isnt "pending"

# Override this to perform actions once the view has been fully rendered.
Giraffe.View::onFullyRendered = ->

# @see #afterRender below.
Giraffe.View::nowFullyRendered = ->
  @_fullyRendered.resolve()

# !!! MONKEY PATCHING OF Giraffe.View::afterRender

# Override this hook as you'd like, but if you do and want to track when
# the view is fully rendered, then you must call @nowFullyRendered()
# at some point within the hook.
Giraffe.View::afterRender = ->
  @nowFullyRendered()

So, the public API consists of:

• the fullyRendered promise (useful for composition)
• the onFullyRendered hook
• the "fully_rendered" event

When overriding an afterRender hook, I'd call @nowFullyRendered() when the view is actually ready. Most of the time, my afterRender hooks perform asynchronous stuff (like, creating and rendering subviews which do post-fetching of data on external API…), so I'd use $.when to track the resolution states of the subviews I'm working with (using their fullyRendered promises), and eventually call @nowFullyRendered() once they are all done! Obviously, the main benefit of this pattern is that it can be recursive, for the subviews may do the same, and so on.

One can override the onFullyRendered hook within a view, to perform actions once the view is fully rendered. This is kind of a Giraffe-ish pattern I guess.

Or, one can listen for the "fully_rendered" event, which is basically the same thing as overriding onFullyRendered, but more Backbone-ish and would better fit within an event-based view management.

Thin footprint within the business code, yet very handy!

[chikamichi]

I wonder whether this could rather be kind of an extension to Giraffe though. Maybe it does not belong to a core features' set. I found it _very_ helpful in my codebase, but well… 🌵 💀

[ryanatkn]

Thanks for taking the time to write up this proposal. It's a really interesting idea and it seems to fit into the existing code well.

afterRender is meant to be the best place to create and attach subviews. For the normal case where everything is synchronous, this works well for arbitrarily complex view hierarchies, but like you've shown anything asynchronous is going to be trickier. The solution that I've been using for this problem is Facebook's Flux architecture, where the state of the stores/models is always reflected in the UI, and any asynchronous update (like data being fetched) simply changes the state which triggers a re-render. This has some tradeoffs as compared to using promises at the view layer (animations being more difficult, for one) but I wouldn't be confident in making Giraffe prescriptive on this point, unless we got a lot more feedback that it's the preferred way to do things.

I think the only downside to implementing your proposal beyond the breaking change would be the overhead of creating and resolving lots of unused promises, so it'd be good to hear what others think of it. If nothing else it would make a good addition to Giraffe.Contrib. If you make a PR I think we'd happily include it, and with more feedback it could make its way into the main lib.

[chikamichi]

That's very interesting you mention the flux workflow, because that was my first attempt at solving my "async" rendering issues. I found it hard (or at least awkward) to mix the concept within a legacy Backbone application, though, so I came up with this promise-based architecture and I must say that I like the fact that it's really lightweight from the application perspective. As a Giraffe application developer, it doesn't drift away from the Backbone paradigm (Giraffe is all about "follow[ing] the Backbone philosophy of unopinionated simplicity to provide commonly needed features with few assumptions"), and you only have to call @nowFullyRendered() in your afterRender hooks if you do override them, maybe use someView.fullyRendered promises to monitor full rendering if you need it, and maybe write some onFullyRendered hooks if you need them.

As with anything that's async by nature, it only works/shines if the whole stack uses the pattern, hence the fact that I wrapped some of the existing functions to automate the promise creation/tracking/resolution. Again, nothing to worry about as a Giraffe application developer, and it's fully downward-compatible.

I wouldn't be so afraid of resolving lots of unused promises, for the deferrables have a quite small footprint. It must be noted that one doesn't have to use jQuery's implementation, which may not be the best one available out there (design- and performance-wise). As all of the Promise A+ compatible libs implement the same API, Giraffe could accept any of them through a configuration key, while defaulting to jQuery's I guess.

I'll work on a PR in January 2015, after 🎉

[chikamichi]

Oh, speaking about Giraffe.Contrib, and because it just came to my mind: I remember being confused when I first discovered the project about the Giraffe.Contrib thing. The README doesn't really explain what it is (ie. extensions to the core features that are App, View, Model, Collection, Router). Then I realized by looking at the source code, and went from 😕 to 😃 .

[ryanatkn]

I also abandoned trying to integrate React/Flux with Backbone and am currently working on a project without Backbone. I'm not using any notion of being fully rendered - if there's data available, render it, if there's an error, show it, else show a loading animation. However I haven't had to do much post-render DOM manipulation and I can see how your pattern gives a lot of control. I'm not sure what all of the tradeoffs are, and I'd probably want to write some benchmarks before moving it from contrib to the main lib, but I like the idea a lot. Also +1 to configuring the Promise lib.