The library for web and native user interfaces.
[docs] Improve "Event Handling" documentation.
Added some additional examples to explain common usage patterns for custom events.
yungsters committed
May 29, 2013 at 13:48 UTC
99088b38d3554105d6ea8694c38c2e172227e804
1 file changed
+100
docs/docs/event-handling.md
+100
@@ -122,3 +122,103 @@ var handleToggle = function(enabled) {
122
};
123
var myToggleLink = <ToggleLink onToggle={handleToggle} />;
124
```
125
+
126
+### Common Patterns
127
+
128
+With React your event handlers should be quite small. Large event handlers may
129
+be symptomatic of code that should be moved into helpers or into `render()`.
130
+Here are some common usage patterns for event handlers.
131
+
132
+#### Updating State
133
+
134
+The most common thing to do in response to a user action is to call
135
+`this.setState()` to update the component's state, which will in turn trigger
136
+an update to the rendered component.
137
+
138
+#### Server Requests
139
+
140
+Many event handlers will issue a server request to read or write some data in
141
+response to an event. The response handler for the request will often call
142
+`this.setState()`.
143
+
144
+#### Invoke a Callback
145
+
146
+Your component will often be a small, reusable building block that does not know
147
+how to respond to a user action. In these situations, we delegate the
148
+responsibility to the owner by exposing a handler on `this.props`. This is what
149
+the `ToggleLink` example above is doing.
150
+
151
+#### Inter-component Communication
152
+
153
+A common scenario involves communicating to **Component A** that a user action
154
+has occurred on **Component B**. To solve this problem, a common parent to
155
+both components should listen for the event on **Component B**, update its
156
+internal state, and pass that data into **Component A**.
157
+
158
+For example, say we have two components: **Clicker**, a component that fires an
159
+`onCountChange` custom event, and **ClickCountLabel**, a component that displays
160
+the number of clicks that have happened:
161
+
162
+```javascript
163
+var Clicker = React.createClass({
164
+ getInitialState: function() {
165
+ return {count: 0};
166
+ },
167
+ render: function() {
168
+ return <span onClick={this.handleClick}>Click me!</span>;
169
+ },
170
+ handleClick: React.autoBind(function() {
171
+ this.setState({count: this.state.count + 1});
172
+ if (this.props.onCountChange) {
173
+ this.props.onCountChange(this.state.count);
174
+ }
175
+ })
176
+});
177
+
178
+var ClickCountLabel = React.createClass({
179
+ render: function() {
180
+ return <p>You have clicked <strong>{this.props.count}</strong> times.</p>;
181
+ }
182
+});
183
+
184
+var ClickApp = React.createClass({
185
+ render: function() {
186
+ var count = 0;
187
+ return (
188
+ <div>
189
+ <Clicker onCountChange={this.handleCountChange} />
190
+ <ClickCountLabel count={count} />
191
+ </div>
192
+ );
193
+ },
194
+ handleCountChange: React.autoBind(function(count) {
195
+ // Somehow update `count`.
196
+ })
197
+});
198
+```
199
+
200
+In order to communicate the click count from `Clicker` to `ClickCountLabel`, we
201
+modify `ClickApp` to maintain state that will be passed into `ClickCountLabel`:
202
+
203
+```javascript{2-4,6,15}
204
+var ClickApp = React.createClass({
205
+ getInitialState: function() {
206
+ return {count: 0};
207
+ },
208
+ render: function() {
209
+ var count = this.state.count;
210
+ return (
211
+ <div>
212
+ <Clicker onCountChange={this.handleCountChange} />
213
+ <ClickCountLabel count={count} />
214
+ </div>
215
+ );
216
+ },
217
+ handleCountChange: React.autoBind(function(count) {
218
+ this.setState({count: count});
219
+ })
220
+});
221
+```
222
+
223
+Now when `Clicker` fires the `onCountChange` event, the `ClickCountLabel` will
224
+get updated!