Browse Source

chore(docs): Add API Examples in reference documentation (#329)

* Add reference examples for:
- onError
- onNavigationStateChange
- originWhiteList
- renderError
- renderLoading
- onShouldStartLoadWithRequest

* Update to use jsx as code
Add properties of objects passed into methods

* Add examples for:
- onLoad
- onLoadEnd
- onLoadStart
- onLoadProgress
- style

* Add object descriptions, fix style issues, and remove onShouldStartLoad example

Object Descriptions for:
- onLoad
- onLoadEnd
- onLoadStart
- onLoadProgress

* Update Reference.md
Malcolm Scruggs 5 years ago
parent
commit
34b98de0bd
1 changed files with 215 additions and 0 deletions
  1. 215
    0
      docs/Reference.md

+ 215
- 0
docs/Reference.md View File

@@ -147,6 +147,35 @@ Function that is invoked when the `WebView` load fails.
147 147
 | -------- | -------- |
148 148
 | function | No       |
149 149
 
150
+Example:
151
+
152
+```jsx
153
+<WebView
154
+   source={{ uri: "https://facebook.github.io/react-native" }}
155
+   onError={(syntheticEvent) => {
156
+     const { nativeEvent } = syntheticEvent
157
+     console.warn('WebView error: ', nativeEvent)
158
+   }}
159
+ />
160
+```
161
+
162
+Function passed to `onError` is called with a SyntheticEvent wrapping a nativeEvent with these properties:
163
+
164
+ ```
165
+ canGoBack
166
+ canGoForward
167
+ code
168
+ description
169
+ didFailProvisionalNavigation
170
+ domain
171
+ loading
172
+ target
173
+ title
174
+ url
175
+```
176
+> **_Note_**
177
+> Domain is only used on iOS
178
+
150 179
 ---
151 180
 
152 181
 ### `onLoad`
@@ -157,6 +186,29 @@ Function that is invoked when the `WebView` has finished loading.
157 186
 | -------- | -------- |
158 187
 | function | No       |
159 188
 
189
+Example:
190
+
191
+```jsx
192
+<WebView
193
+  source={{uri: 'https://facebook.github.io/react-native'}}
194
+  onLoad={(syntheticEvent) => {
195
+    const { nativeEvent } = syntheticEvent;
196
+    this.url = nativeEvent.url;
197
+  }}
198
+/>
199
+```
200
+
201
+Function passed to `onLoad` is called with a SyntheticEvent wrapping a nativeEvent with these properties:
202
+
203
+ ```
204
+ canGoBack
205
+ canGoForward
206
+ loading
207
+ target
208
+ title
209
+ url
210
+```
211
+
160 212
 ---
161 213
 
162 214
 ### `onLoadEnd`
@@ -167,6 +219,31 @@ Function that is invoked when the `WebView` load succeeds or fails.
167 219
 | -------- | -------- |
168 220
 | function | No       |
169 221
 
222
+
223
+Example:
224
+
225
+```jsx
226
+<WebView
227
+  source={{uri: 'https://facebook.github.io/react-native'}}
228
+  onLoadEnd={(syntheticEvent) => {
229
+    // update component to be aware of loading status
230
+    const { nativeEvent } = syntheticEvent;
231
+    this.isLoading = nativeEvent.loading;
232
+  }}
233
+/>
234
+```
235
+
236
+Function passed to `onLoadEnd` is called with a SyntheticEvent wrapping a nativeEvent with these properties:
237
+
238
+ ```
239
+ canGoBack
240
+ canGoForward
241
+ loading
242
+ target
243
+ title
244
+ url
245
+```
246
+
170 247
 ---
171 248
 
172 249
 ### `onLoadStart`
@@ -177,6 +254,31 @@ Function that is invoked when the `WebView` starts loading.
177 254
 | -------- | -------- |
178 255
 | function | No       |
179 256
 
257
+
258
+Example:
259
+
260
+```jsx
261
+<WebView
262
+  source={{uri: 'https://facebook.github.io/react-native/='}}
263
+  onLoadStart={(syntheticEvent) => {
264
+    // update component to be aware of loading status
265
+    const { nativeEvent } = syntheticEvent;
266
+    this.isLoading = nativeEvent.loading;
267
+  }}
268
+/>
269
+```
270
+
271
+Function passed to `onLoadStart` is called with a SyntheticEvent wrapping a nativeEvent with these properties:
272
+
273
+ ```
274
+ canGoBack
275
+ canGoForward
276
+ loading
277
+ target
278
+ title
279
+ url
280
+```
281
+
180 282
 ---
181 283
 
182 284
 ### `onLoadProgress`
@@ -192,6 +294,29 @@ Function that is invoked when the `WebView` is loading.
192 294
 | -------- | -------- |
193 295
 | function | No       |
194 296
 
297
+Example:
298
+
299
+```jsx
300
+<WebView
301
+   source={{ uri: "https://facebook.github.io/react-native" }}
302
+   onLoadProgress={({ nativeEvent }) => {
303
+     this.loadingProgress = nativeEvent.progress
304
+   }}
305
+ />
306
+```
307
+
308
+Function passed to `onLoadProgress` is called with a SyntheticEvent wrapping a nativeEvent with these properties:
309
+
310
+ ```
311
+ canGoBack
312
+ canGoForward
313
+ loading
314
+ progress
315
+ target
316
+ title
317
+ url
318
+```
319
+
195 320
 ---
196 321
 
197 322
 ### `onMessage`
@@ -214,6 +339,29 @@ Function that is invoked when the `WebView` loading starts or ends.
214 339
 | -------- | -------- |
215 340
 | function | No       |
216 341
 
342
+Example:
343
+
344
+```jsx
345
+<WebView
346
+   source={{ uri: "https://facebook.github.io/react-native" }}
347
+   onNavigationStateChange={(navState) => {
348
+    // Keep track of going back navigation within component
349
+    this.canGoBack = navState.canGoBack;
350
+}} />
351
+```
352
+
353
+The `navState` object includes these properties:
354
+
355
+ ```
356
+ canGoBack
357
+ canGoForward
358
+ loading
359
+ navigationType
360
+ target
361
+ title
362
+ url
363
+```
364
+
217 365
 ---
218 366
 
219 367
 ### `originWhitelist`
@@ -224,6 +372,16 @@ List of origin strings to allow being navigated to. The strings allow wildcards
224 372
 | ---------------- | -------- |
225 373
 | array of strings | No       |
226 374
 
375
+Example:
376
+
377
+```jsx
378
+//only allow URIs that begin with https:// or git://
379
+<WebView
380
+   source={{ uri: "https://facebook.github.io/react-native" }}
381
+   originWhitelist={['https://*', 'git://*']}
382
+ />
383
+```
384
+
227 385
 ---
228 386
 
229 387
 ### `renderError`
@@ -234,6 +392,18 @@ Function that returns a view to show if there's an error.
234 392
 | -------- | -------- |
235 393
 | function | No       |
236 394
 
395
+
396
+Example:
397
+
398
+```jsx
399
+<WebView
400
+   source={{ uri: "https://facebook.github.io/react-native" }}
401
+   renderError={(errorName) => <Error name={errorName} /> }
402
+ />
403
+```
404
+
405
+The function passed to `renderError` will be called with the name of the error 
406
+
237 407
 ---
238 408
 
239 409
 ### `renderLoading`
@@ -244,6 +414,17 @@ Function that returns a loading indicator. The startInLoadingState prop must be
244 414
 | -------- | -------- |
245 415
 | function | No       |
246 416
 
417
+
418
+Example:
419
+
420
+```jsx
421
+<WebView
422
+   source={{ uri: "https://facebook.github.io/react-native" }}
423
+   startInLoadingState={true}
424
+   renderLoading={() => <Loading /> }
425
+ />
426
+```
427
+
247 428
 ---
248 429
 
249 430
 ### `scalesPageToFit`
@@ -293,6 +474,31 @@ lockIdentifier
293 474
 navigationType
294 475
 ```
295 476
 
477
+Example:
478
+
479
+```jsx
480
+<WebView
481
+  source={{ uri: "https://facebook.github.io/react-native" }}
482
+  onShouldStartLoadWithRequest={(request) => {
483
+    // Only allow navigating within this website
484
+    return request.url.startsWith("https://facebook.github.io/react-native")
485
+  }}
486
+/>
487
+```
488
+
489
+The `request` object includes these properties:
490
+
491
+```
492
+title
493
+url
494
+loading
495
+target
496
+canGoBack
497
+canGoForward
498
+lockIdentifier
499
+navigationType
500
+```
501
+
296 502
 ---
297 503
 
298 504
 ### `startInLoadingState`
@@ -313,6 +519,15 @@ A style object that allow you to customize the `WebView` style. Please note that
313 519
 | ----- | -------- |
314 520
 | style | No       |
315 521
 
522
+Example:
523
+
524
+```jsx
525
+<WebView
526
+   source={{ uri: "https://facebook.github.io/react-native" }}
527
+   style={{marginTop: 20}}
528
+ />
529
+```
530
+
316 531
 ---
317 532
 
318 533
 ### `decelerationRate`