DDAU for public properties with common behaviour

README.md

Patterns for common behaviour of Ember components without violating DDAU

DDAU (data down action up) is the common pattern for creating ideomatic components in modern Ember.js. This prevents (unexpectedly) changing your application state in components, and enables you to put your state management logic to where it belongs: the component/controller/service that "owns" that state.

But what to do if you want to enable controlling some specific part of your component for some rare cases where this is needed, but have a default common behaviour (just UI related) for controlling that property where this is not needed in most cases.

Let's look at this with an example: we want to create a component for a simple dropdown button. It has a open property that controls the state of its dropdown menu being shown: when you click on the button that property is set to true which renders the dropdown menu, and when you click again outside of it it will set it to false and thus hide the menu. So far so good, this is the default behaviour you would expect, and that is fine as long as this property is declared as private.

But what if you want to enable your application to programmatically control opening or closing the dropdown menu. At first this seems easy, just declare the open property as public and create a binding to that property in your component invocation:

{{drop-down open=someOtherProperty}}

But then when the default behaviour remains in place, with Ember's two-way bindings changing the open property within the component because of some click events will propagate that change to someOtherProperty, so changing your application state within the dropdown and thus violating the DDAU principle.

So our problem in a nutshell: we want the component to have its default behaviour for 99% of the cases were we do not need full control, but allow this control for some rare cases without violating DDAU. And a common pattern agreed upon by the Ember community for solving that problem seems to be missing, or at least I have not been able to identify one so far.

So here are my candidates...

A) Pure DDAU

The component does not set the public properties at all, thus all property bindings effectively become one-way.

export default Ember.Component.extend({
  open: false,
  onChange: () => {},
  _open() {
    this.get('onChange')(true);
  }
});

{{drop-down open=someOtherProperty onChange=(action (mut someOtherProperty))}}

Pros:

• Purest DDAU approach

Cons:

• delegates the handling of the open state to the user of the component, even when not required
• requires a lot of boilerplate for each component use

B) Apply default behaviour only when not controlling property

The component checks wheather the open property is used, and if so the user of the component takes over control, otherwise the default behaviour is applied. This is similar to what https://github.com/jquense/uncontrollable does for React components.

export default Ember.Component.extend({
  open: false,
  onChange: () => {},
  _open() {
    if (this.attrs.open === undefined) {
      this.set('open', true);
    }
    this.get('onChange')(true);
  }
});

Uncontrolled: {{drop-down}}
Controlled: {{drop-down open=someOtherProperty onChange=(action (mut someOtherProperty))}}

Pros:

• Allows a controlled (matches case A) and an uncontrolled (default behaviour, no boilerplate required) way of using the component

Cons:

• Just by using the open property it looses its default behaviour, which might be unexpected by the user

C) Provide default behaviour with an overridable action

The default behaviour is implemented in the default action, that can be overriden.

export default Ember.Component.extend({
  open: false,
  onChange: (state) => this.set('open', state),
  _open() {
    this.get('onChange').call(this, true);
  }
});

Uncontrolled: {{drop-down}}
Controlled: {{drop-down open=someOtherProperty onChange=(action (mut someOtherProperty))}}
Two-way binding, violates DDAU: {{drop-down open=someOtherProperty}}

Pros:

• Allows a controlled (matches case A) and an uncontrolled (default behaviour, no boilerplate required) way of using the component
• Probably quite easy to reason about
• Allows two-way binding by not using a custom action handler, if that is what the user desires (is this a pro or rather a con? :))

Cons:

• Can accidentally violate DDAU if user binds to open property but forgets to add custom action handler
• If the user wants to make use of the onChange action for some other purposes than controlling the UI state, he/she is still forced to control the UI state
• If he/she forgets to do so the component will accidentally loose its expected behaviour

D) Disable default behaviour by action's return value

The default behaviour remains in place as long as you do not return false from the action, which signals that you want to take over control.

export default Ember.Component.extend({
  open: false,
  onChange: () => {},
  _open() {
    if (this.get('onChange')(true) !== false) {
      this.set('open', true);
    }
  }
});

Uncontrolled: {{drop-down}}
Controlled: {{drop-down open=someOtherProperty onChange=(action "dropdown")}}

Pros:

• Allows a controlled (matches case A) and an uncontrolled (default behaviour, no boilerplate required) way of using the component
• Allows two-way binding by not returning false, if that is what the user desires (is this a pro or rather a con? :))
• Does not accidentally loose its expected behaviour

Cons:

• Can violate DDAU if user binds to open property but forgets to return false

@cibernox Thanks a lot for taking the time to comment on this in such verbosity!

To be honest I had a look at ember-power-select and ember-basic-dropdown before writing this to see if I can deduce something from it. :) But I missed the registerAPI part, it seems to be undocumented right? Just found it now when looking at the source...

Anyways, I see your option E is pretty similar in principle to what @bendemboski proposed in his comment above and during some chat yesterday on Slack. We can call it "Actions Down", can we?

It changes the "down" part of interacting with the component from the declarative flow of data that Ember manages for you to an imperative API. While that might be appropriate for that case, I see a downside here, that I think might be pretty severe!

That is that once the public API of the component has been registered with the parent (component/controller), the parent then holds a reference to the actions that is not bound to the lifecycle of the component. I.e. when the component is destroyed but not the parent, then it is still holding references to it. Which means:

• as the actions will hold a reference to the component through their this scope, that component will never be garbage collected (and with that all other stuff that the component might still reference) as long as the references exist
• this problem gets even more serious when the parent holding the API references is a controller, as controllers are not disposed (singletons)
• could be solved by some unregister API, but that would add to the API surface area, and probably be error prone (requires user to take care of)
• the actions might still be called from the parent even if the component is already destroyed. So required if (this.get('isDestroyed') return guards everywhere

All this does not happen when relying on "data down" instead of "actions down", as Ember will manage the flow of data and setting up/tearing down the bindings during the component`s lifecycle.

So I am not 100% sure this is the way to go for me...

As a side note: it seems Gist does not send out notifications on new comments/mentions: isaacs/github#21
That is so lame! So beware when taking part here, will have to revisit!?

I'm not sure if this covers 100% of what you are looking for but I would solve the problem with a computed property.
I created this ember twiddle (gist)

Here are the importend lines:

{{drop-down isOpen=isOpen}}

export default Ember.Component.extend({
  open: computed('isOpen', {
    get() {
      return getWithDefault(this, 'isOpen', false);
    },
    set(key, value) {
      return value;
    }
  })
});

@fsmanuel Indeed it seems to do everything I was looking for, with so little effort. Awesome!

The key seems to be the setter function there, which at first sight seems to do nothing. But if you omit it, it actually behaves totally different, in that the CP won't react to changes to isOpen anymore once you set the property.

If it's like this:

export default Ember.Component.extend({
  open: computed('isOpen', {
    get() {
      return getWithDefault(this, 'isOpen', false);
    }
  })
});

The CP would react to changes to isOpen until you set it (by clicking on your component in the Twiddle), then it looses its "binding" and only holds the value that was last set. I really thought that CPs always behave like that. But it seems as soon as you add the "useless" setter method, this changes so that even after setting the CP it will still react to changes of isOpen.

Was not aware of this. Is this actually documented somewhere so we can rely an that behaviour?

In your Twiddle the isOpen controller property cannot be updated bases on the component state, but that's what an onChange action of the component would solve anyways, so it seems indeed this could be everything I need! :)

For the record: the above mentioned concerns that the differing behaviour of CPs with and without a setter might be not documented are actually void: it's here: http://emberjs.com/api/classes/Ember.ComputedProperty.html:

You can overwrite computed property with normal property (no longer computed), that won't change if dependencies change, if you set computed property and it won't have setter accessor function defined.

@simonihmig It should be easy to make it a computed property:

function readsWithDefault(dependentKey, defaultValue) {
  return computed(dependentKey, {
    get() {
      return getWithDefault(this, dependentKey, defaultValue);
    },
    set(key, value) {
      return value;
    }
  });
}

export default Ember.Component.extend({
  open: readsWithDefault('isOpen', false)
});

@simonihmig your concerns about leaking are valid. The component should nullify the remote controller in the willDestroy hook to avoid that. The reason for this approach is that there is more actions than open/close, some of which like reposition is not something you can trigger changing a property.

I needed a way of triggering actions from the outside, and since I had that, I put everything there. Although I do provide an initiallyOpened=true/false option to render the dropdown open in the first place, but it never updates again, from that point on the component holds its own state.