valuechange.mustache revision 914ece60ab1462a8875210f2f40cb9aa23ea40fe
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<div class="intro">
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <p>The `event-valuechange` module adds a "valueChange" event that fires
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith when the `value` property of a text input element or textarea changes as
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith the result of a keystroke, mouse operation, or input method editor (IME)
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith input event.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<h2>What's the problem?</h2>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<p>The input related events provided by browsers don't cleanly address the
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithvariety of ways users can modify an <input> or <textarea>'s
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith`value`. For example, users might change an input value by</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <li>typing a simple character</li>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <li>typing a multi-stroke character</li>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith using an <a href="http://en.wikipedia.org/wiki/Input_method">Input
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith Method Editor</a>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <li>cutting from or pasting into the value with `ctrl+X` or `cmd+V`</li>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <li>cutting or pasting with a keyboard summoned context menu</li>
914ece60ab1462a8875210f2f40cb9aa23ea40feLuke Smith <li>cutting or pasting from the right-click context menu.</li>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<p>The ideal change event would fire when the value becomes <em>something it
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithwasn't a moment ago</em>.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<p>The `valueChange` event provides more reliable input notifications than
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithnative events like `oninput` and `textInput`, particularly with changes that
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithresult from multiple-keystroke IME input.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke SmithcommentTextarea.on('valueChange', updateLivePreview);
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<h2>How it works</h2>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<p>`valueChange` subscriptions monitor the input's value using a variety of
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithmechanisms including subscriptions to `blur` and various keyboard events, and a
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithpoll to catch the stragglers. It seems like a lot of work, but it's the only
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smithway to be sure.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<p>The polling is only active when the input is focused, so the performance of your app should not be impacted.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<h2>Caveats</h2>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <li>`valueChange` does not (yet) support delegation</li>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `valueChange` only supports subscription on text <input>s and
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <textarea>s, though no steps are taken to ensure the subscribed
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith node is one of these. If you subscribe to a different type of node,
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith and stuff breaks, you were warned.
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `valueChange` does not capture `value` updates done in JavaScript
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith <em>unless the input is currently focused</em>.
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith `node.set('value', 'will probably not trigger valueChange');`