[v4] Rename "ref" to "key"

Currently, Marko supports “scoped IDs” in the form of a “ref”:

<div>
  <button ref="ok" type="button">OK</button>
  <button ref="cancel" type="button">Cancel</button>
</div>

A nested element/widget can be looked up by a ref:

var okButton = this.getEl('button');

A “ref” attribute results in an ID attribute being assigned to the final element. For example:

<div>
  <button id="w0-ok" type="button">OK</button>
  <button cancel="w0-cancel" type="button">Cancel</button>
</div>

morphdom uses the “id” attribute as a “key” to match up elements during a diff/patch. Therefore, marko is using the “ref” attribute for two purposes:

• To assign a key for diffing/patching
• To assign a key for referencing nested elements/widgets

A “key” is the more general term (“scoped-id” is more appropriate, but too long) and “key” is already well understood to be used for matching up elements during diffing/patching.

As a late breaking change for the Marko v4 release, we want to rename “ref” to “key”. We will introduce deprecation warnings, but we do not want to ship the “v4” release with support for “ref”.

Thoughts? Concerns? Thanks in advance.

[Hesulan]

Ah, forgot about React. I’d say those are pretty good reasons to make the switch.

[patrick-steele-idem]

@Hesulan For better or worse, React and all of the React variants have already hijacked the “key” attribute: https://facebook.github.io/react/docs/lists-and-keys.html#keys

The key attribute that we are proposing for Marko would serve the exact same purpose as developers are used to with React. The only difference is that we would also be using the key attribute to allow an element/widget to be referenced by the key (that is, getEl(<key>), getWidget(<key>)). In comparison, React has a separate concept of a ref which started out as a string, but is now a function:

<input
  type="text"
  ref={(input) => { this.textInput = input; }} />

That is another reason we want to get away from ref.

(side note, React requires a lot of code to reference an element… uggh)

@mindeavor

Does using a ref prevent the element from being messed with during a redraw?

No, it doesn’t impact rendering. It only impacts how elements are matched up for diffing purposes. DOM elements with the same key are guaranteed to be diffed against each other. Even without specifying a key things will still render correctly, but the developer might notice unexpected behavior (e.g., focus moving to the wrong element or CSS transitions being applied incorrectly).