1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<div class="intro">
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove <p>The `event-valuechange` module adds a "valuechange" event that fires
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove when the `value` property of an `<input>` or `<textarea>` element 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
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grovevariety of ways users can modify an `<input>` or `<textarea>`'s
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove`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>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove <li>cutting from or pasting into the value with `Ctrl+X` or `Cmd+V`</li>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove <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>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove<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>
154bc262955366ec077dbb8a74f32469e20109a0Ryan GrovecommentTextarea.on('valuechange', updateLivePreview);
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<h2>How it works</h2>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove<p>`valuechange` subscriptions monitor the element's value using a variety of
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grovemechanisms including subscriptions to `focus` 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>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove<p>Polling is only active when the element is focused, and only one element is
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grovepolled at a time, so the performance of your app should not be impacted.</p>
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith<h2>Caveats</h2>
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove `valuechange` only supports subscriptions on `<input>` and
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove `<textarea>` elements, although it doesn't prevent you from subscribing
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove on other types of elements. If you subscribe on a different type of element
77c61f48946d06f2e1a4339a1ea83fa6f49ed085Luke Smith and stuff breaks, you were warned.
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove `valuechange` does not capture `value` updates done in JavaScript
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove <em>unless the input is currently focused and polling</em>. It's meant
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove to capture changes made by the user, not by other code. So:
154bc262955366ec077dbb8a74f32469e20109a0Ryan Grove `node.set('value', 'probably will not trigger valuechange');`