API for dispatching "resourcewillchange" events when DOM node is going to be removed

[matthewdunsdon]

When handle closing resources or removing a DOM node, I use code like the following in several places:

if (appNode && appNode.dispatchEvent) {
  appNode.dispatchEvent(new CustomEvent('resourcewillchange'))
}

Should address supply an API for doing this?

---

💡 One idea I had was to do something like...

define([ '@zambezi/address/lib/address', '@zambezi/address/lib/unregister'], function(address, unregister) {
  return function (req, res) {
    res(ok(view))

    function view(node) {
      var panelNode = createPanelNode(node)
      address('/my/app/notifications-panel').into(panelNode).get()

      node.addEventListener('app_closing', function() {
        unregister(panelNode)
        getPanelContainerNode(node).removeChild(panelNode)
      })
    }
  }
})

[mstade]

I think the use case here might need some further elaborating. So you have a view, that immediately upon render addresses another view into itself, and when that view says it's closing. You want to let the parent views know that the resource will change – yet, the resource doesn't actually change, does it?

I'm a bit confused by this to be honest, can you explain it to me like I'm five? :o)

[matthewdunsdon]

The problem I am facing is seen when address stream, address view and react are used together. Currently when a Address React wrapper component is unmounted, it does not make any calls to address to unmount or unregister any address views on a DOM node. This is problematic when you have a stream set up in an address view, as you have no events messages to listen to, so that your can close the subscription, when your parent DOM node is removed from the page (or when the parent react component is unmounted). The only events that you get is when a new address view is requested for the same DOM node.

We have used the resourcewillchange event to indicate that the resource is changing. It other apps, we used the event before removing the parent DOM node from the page, so that the resource can unmount gracefully. Before we did this explicitly by doing the following in the parent view

appEvents.on('close-panel', function() {
  if (panelNode && panelNode.dispatchEvent) {
    panelNode.dispatchEvent(new CustomEvent('resourcewillchange'))
  }
  // Then actually remove the DOM from the page.
})

Rather than doing something like this in the address react component, I was wanting some API that I could call with the DOM node and that it could make sure the resourcewillchange event is dispatched.

[matthewdunsdon]

Fixed initial example, cause it seemed to be confusing.

Sorry about that 😞

[mstade]

I'm still not quite following, can you describe the hierarchy here, what happens, what doesn't happen, and what you'd expect to happen. The when and the where is also pertinent.

[matthewdunsdon]

Here is a simplified example:

Suppose we have a parent address view at the top, which wants to render a dynamic number of children address views. These rendered children views are changed based upon some subscribed event that occurs in the parent.

• When a new view is needed then the parent calls address(specificRoute).into(newNode).get() and there is no issue since no clean up is needed.
• When a view needs changing then the parent calls address(specificRoute).into(existingNode).get() and there is no issue since the child can listen to resourcewillchange.
• When a view needs removing / unregistering / unmounting / cleaning up then the is no oblivious solution:
  • You could call appNode.dispatchEvent(new CustomEvent('resourcewillchange')) but this is not documented as a solution.
  • You could call address('/clean-up').into(existingNode).get() to trick address to sending the resourcewillchange but this feels hacky and may require me to create my own /'clean-up' resource

The child view, needs to know when it is no longer being used, so that a can close gracefully.

---

I am suggesting that we add something like the following to the address library so that the parent view can require in functionality to dispatch an event without knowing the internals or name or the event:

// unregister.js
export default unregister(node) {
  if (node && node.dispatchEvent) {
    node.dispatchEvent(new CustomEvent('resourcewillchange'))
  }
}

In the future, the event resourcewillchange may change or a new event may be created especially of this case.

[mstade]

The child view, needs to know when it is no longer being used, so that a can close gracefully.

Am I right in saying this is the crux of the matter? I think my confusion here is that your event dispatching seems to come from the child view, but the above says the child needs to know when it's being removed – so really the event dispatching would be happening in the parent then, but dispatched on the child node?

[matthewdunsdon]

Yes, the event dispatching would be happening in the parent and dispatched on the child node.

[mstade]

So the way that views work is that they are effectively a custom media type that we've come up with, which effectively just says what the response of a view resource is – i.e. the view function. One thing that we could certainly do, and have talked about it in the past, is extending this media type to allow for lifecycle like methods. Particularly the need for clean up has shown up in the past.

As it stands, when you do something like address('/some/resource').into(node).get() the body of the response is the view function itself. All address really does with the into convenience API is to call the function on the relevant node, but you could just do this too:

address('/some/resource')
  .view()
  .get()
  .on('ok', res => res.body(node))

So I'm thinking that just like you could call the view function yourself, if you need to deal with unregistering (or indeed other things) we could provide a hook for this on the returned view function. Something like so:

let childView

address('/some/resource')
  .into(node)
  .get()
  .on('ok', res => {
    childView = res.body
  })

// At some other time
childView.remove(node)

How you store a reference to the child view function or when you call remove (or whatever we'd like to call it) doesn't really matter much. In address, we could then change the view semantics to attach a function like so on to the view function:

view.remove = function(node) {
  // Dispatch things or whatever here
}

The reason I'd rather do this than provide a special address API for this is that views already get too much special treatment, which is an API surface area that's difficult to back out of if we want to come up with a different way to implement views down the line. Putting this extra functionality on the body of the view response instead means it's limited to that media type, and other view media types can have other functionality more suitable to it.

What do you think @matthewdunsdon?

[matthewdunsdon]

@mstade Sounds like a good approach to me. I'll have a go at making the change to the view code on Monday, unless anyone jumps in and raises an objection.