Added first draft of docs folder and documentation

README.md

@@ -10,7 +10,7 @@
 * [x] Android
 * [ ] Windows 10 (coming soon)
 
-## Installation
+## Getting Started
 
 *Note: this is currently a work-in-progress and not yet published to NPM.*
 
@@ -19,6 +19,8 @@ $ npm install --save https://github.com/react-native-community/react-native-webv
 $ react-native link react-native-webview
 ```
 
+Read our [Getting Started Guide](./docs/Getting-Started.md) for more.
+
 ## Usage
 
 Import the `WebView` component from `react-native-webview` and use it like so:
@@ -41,9 +43,7 @@ class MyWebComponent extends Component {
 }
 ```
 
-Additional properties are supported and will be added here; for now, refer to the previous React Native WebView documentation for more.
-
-[https://facebook.github.io/react-native/docs/webview](https://facebook.github.io/react-native/docs/webview)
+For more, read the [API Reference](./docs/Reference.md) and [Guide](./docs/Guide.md).
 
 ## Migrate from React Native core WebView to React Native WebView
 

docs/Getting-Started.md

@@ -0,0 +1,59 @@
+# React Native WebView Getting Started Guide
+
+Here's how to get started quickly with the React Native WebView.
+
+#### 1. Add react-native-webview to your dependencies
+
+```
+$ npm install --save https://github.com/react-native-community/react-native-webview
+```
+
+#### 2. Link native dependencies
+
+React Native modules that include native Objective-C, Swift, Java, or Kotlin code have to be "linked" so that the compiler knows to include them in the app.
+
+Thankfully, there's a way to do this from the terminal with one command:
+
+```
+$ react-native link react-native-webview
+```
+
+_NOTE: If you ever need to uninstall React Native WebView, run `react-native unlink react-native-webview` to unlink it._
+
+#### 3. Import the webview into your component
+
+```js
+import React, { Component } from 'react';
+import { WebView } from 'react-native-webview';
+
+class MyWeb extends Component {
+  render() {
+    return (
+      <WebView
+        source={{uri: 'https://infinite.red'}}
+        style={{marginTop: 20}}
+      />
+    );
+  }
+}
+```
+
+Minimal example with inline HTML:
+
+```js
+import React, { Component } from 'react';
+import { WebView } from 'react-native-webview';
+
+class MyInlineWeb extends Component {
+  render() {
+    return (
+      <WebView
+        originWhitelist={['*']}
+        source={{ html: '<h1>Hello world</h1>' }}
+      />
+    );
+  }
+}
+```
+
+Next, check out the [API Reference](Reference.md) or [In-Depth Guide](Guide.md).

docs/Guide.md

@@ -0,0 +1,5 @@
+# React Native WebView Guide
+
+This document walks you through the most common use cases for React Native WebView. It doesn't cover [the full API](Reference.md), but after reading it you should have a good sense for how the WebView works and common patterns for using the WebView.
+
+_Coming soon!_

docs/Reference.md

@@ -0,0 +1,493 @@
+# React Native WebView API Reference
+
+This document lays out the current public properties and methods for the React Native WebView.
+
+> **Security Warning:** Currently, `onMessage` and `postMessage` do not allow specifying an origin. This can lead to cross-site scripting attacks if an unexpected document is loaded within a `WebView` instance. Please refer to the MDN documentation for [`Window.postMessage()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) for more details on the security implications of this.
+
+## Props Index
+
+- [`source`](Reference.md#source)
+- [`automaticallyAdjustContentInsets`](Reference.md#automaticallyadjustcontentinsets)
+- [`injectJavaScript`](Reference.md#injectjavascript)
+- [`injectedJavaScript`](Reference.md#injectedjavascript)
+- [`mediaPlaybackRequiresUserAction`](Reference.md#mediaplaybackrequiresuseraction)
+- [`nativeConfig`](Reference.md#nativeconfig)
+- [`onError`](Reference.md#onerror)
+- [`onLoad`](Reference.md#onload)
+- [`onLoadEnd`](Reference.md#onloadend)
+- [`onLoadStart`](Reference.md#onloadstart)
+- [`onMessage`](Reference.md#onmessage)
+- [`onNavigationStateChange`](Reference.md#onnavigationstatechange)
+- [`originWhitelist`](Reference.md#originwhitelist)
+- [`renderError`](Reference.md#rendererror)
+- [`renderLoading`](Reference.md#renderloading)
+- [`scalesPageToFit`](Reference.md#scalespagetofit)
+- [`onShouldStartLoadWithRequest`](Reference.md#onshouldstartloadwithrequest)
+- [`startInLoadingState`](Reference.md#startinloadingstate)
+- [`style`](Reference.md#style)
+- [`decelerationRate`](Reference.md#decelerationrate)
+- [`domStorageEnabled`](Reference.md#domstorageenabled)
+- [`javaScriptEnabled`](Reference.md#javascriptenabled)
+- [`mixedContentMode`](Reference.md#mixedcontentmode)
+- [`thirdPartyCookiesEnabled`](Reference.md#thirdpartycookiesenabled)
+- [`userAgent`](Reference.md#useragent)
+- [`allowsInlineMediaPlayback`](Reference.md#allowsinlinemediaplayback)
+- [`bounces`](Reference.md#bounces)
+- [`contentInset`](Reference.md#contentinset)
+- [`dataDetectorTypes`](Reference.md#datadetectortypes)
+- [`scrollEnabled`](Reference.md#scrollenabled)
+- [`geolocationEnabled`](Reference.md#geolocationenabled)
+- [`allowUniversalAccessFromFileURLs`](Reference.md#allowUniversalAccessFromFileURLs)
+- [`useWebKit`](Reference.md#usewebkit)
+- [`url`](Reference.md#url)
+- [`html`](Reference.md#html)
+
+## Methods Index
+
+* [`extraNativeComponentConfig`](Reference.md#extranativecomponentconfig)
+* [`goForward`](Reference.md#goforward)
+* [`goBack`](Reference.md#goback)
+* [`reload`](Reference.md#reload)
+* [`stopLoading`](Reference.md#stoploading)
+
+---
+
+# Reference
+
+## Props
+
+### `source`
+
+Loads static HTML or a URI (with optional headers) in the WebView. Note that static HTML will require setting [`originWhitelist`](Reference.md#originwhitelist) to `["*"]`.
+
+The object passed to `source` can have either of the following shapes:
+
+**Load uri**
+
+* `uri` (string) - The URI to load in the `WebView`. Can be a local or remote file.
+* `method` (string) - The HTTP Method to use. Defaults to GET if not specified. On Android, the only supported methods are GET and POST.
+* `headers` (object) - Additional HTTP headers to send with the request. On Android, this can only be used with GET requests.
+* `body` (string) - The HTTP body to send with the request. This must be a valid UTF-8 string, and will be sent exactly as specified, with no additional encoding (e.g. URL-escaping or base64) applied. On Android, this can only be used with POST requests.
+
+**Static HTML**
+
+* `html` (string) - A static HTML page to display in the WebView.
+* `baseUrl` (string) - The base URL to be used for any relative links in the HTML.
+
+| Type   | Required |
+| ------ | -------- |
+| object | No       |
+
+---
+
+### `automaticallyAdjustContentInsets`
+
+Controls whether to adjust the content inset for web views that are placed behind a navigation bar, tab bar, or toolbar. The default value is `true`.
+
+| Type | Required |
+| ---- | -------- |
+| bool | No       |
+
+---
+
+### `injectJavaScript`
+
+Function that accepts a string that will be passed to the WebView and executed immediately as JavaScript.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `injectedJavaScript`
+
+Set this to provide JavaScript that will be injected into the web page when the view loads.
+
+| Type   | Required |
+| ------ | -------- |
+| string | No       |
+
+---
+
+### `mediaPlaybackRequiresUserAction`
+
+Boolean that determines whether HTML5 audio and video requires the user to tap them before they start playing. The default value is `true`.
+
+| Type | Required |
+| ---- | -------- |
+| bool | No       |
+
+---
+
+### `nativeConfig`
+
+Override the native component used to render the WebView. Enables a custom native WebView which uses the same JavaScript as the original WebView.
+
+The `nativeConfig` prop expects an object with the following keys:
+
+* `component` (any)
+* `props` (object)
+* `viewManager` (object)
+
+| Type   | Required |
+| ------ | -------- |
+| object | No       |
+
+---
+
+### `onError`
+
+Function that is invoked when the `WebView` load fails.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `onLoad`
+
+Function that is invoked when the `WebView` has finished loading.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `onLoadEnd`
+
+Function that is invoked when the `WebView` load succeeds or fails.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `onLoadStart`
+
+Function that is invoked when the `WebView` starts loading.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `onMessage`
+
+A function that is invoked when the webview calls `window.postMessage`. Setting this property will inject a `postMessage` global into your webview, but will still call pre-existing values of `postMessage`.
+
+`window.postMessage` accepts one argument, `data`, which will be available on the event object, `event.nativeEvent.data`. `data` must be a string.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `onNavigationStateChange`
+
+Function that is invoked when the `WebView` loading starts or ends.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `originWhitelist`
+
+List of origin strings to allow being navigated to. The strings allow wildcards and get matched against _just_ the origin (not the full URL). If the user taps to navigate to a new page but the new page is not in this whitelist, the URL will be handled by the OS. The default whitelisted origins are "http://*" and "https://*".
+
+| Type             | Required |
+| ---------------- | -------- |
+| array of strings | No       |
+
+---
+
+### `renderError`
+
+Function that returns a view to show if there's an error.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `renderLoading`
+
+Function that returns a loading indicator. The startInLoadingState prop must be set to true in order to use this prop.
+
+| Type     | Required |
+| -------- | -------- |
+| function | No       |
+
+---
+
+### `scalesPageToFit`
+
+Boolean that controls whether the web content is scaled to fit the view and enables the user to change the scale. The default value is `true`.
+
+On iOS, when [`useWebKit=true`](Reference.md#usewebkit), this prop will not work.
+
+| Type | Required |
+| ---- | -------- |
+| bool | No       |
+
+---
+
+### `onShouldStartLoadWithRequest`
+
+Function that allows custom handling of any web view requests. Return `true` from the function to continue loading the request and `false` to stop loading.
+
+| Type     | Required | Platform |
+| -------- | -------- | -------- |
+| function | No       | iOS      |
+
+---
+
+### `startInLoadingState`
+
+Boolean value that forces the `WebView` to show the loading view on the first load. This prop must be set to `true` in order for the `renderLoading` prop to work.
+
+| Type | Required |
+| ---- | -------- |
+| bool | No       |
+
+---
+
+### `decelerationRate`
+
+A floating-point number that determines how quickly the scroll view decelerates after the user lifts their finger. You may also use the string shortcuts `"normal"` and `"fast"` which match the underlying iOS settings for `UIScrollViewDecelerationRateNormal` and `UIScrollViewDecelerationRateFast` respectively:
+
+* normal: 0.998
+* fast: 0.99 (the default for iOS web view)
+
+| Type   | Required | Platform |
+| ------ | -------- | -------- |
+| number | No       | iOS      |
+
+---
+
+### `domStorageEnabled`
+
+Boolean value to control whether DOM Storage is enabled. Used only in Android.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | Android  |
+
+---
+
+### `javaScriptEnabled`
+
+Boolean value to enable JavaScript in the `WebView`. Used on Android only as JavaScript is enabled by default on iOS. The default value is `true`.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | Android  |
+
+---
+
+### `mixedContentMode`
+
+Specifies the mixed content mode. i.e WebView will allow a secure origin to load content from any other origin.
+
+Possible values for `mixedContentMode` are:
+
+* `never` (default) - WebView will not allow a secure origin to load content from an insecure origin.
+* `always` - WebView will allow a secure origin to load content from any other origin, even if that origin is insecure.
+* `compatibility` - WebView will attempt to be compatible with the approach of a modern web browser with regard to mixed content.
+
+| Type   | Required | Platform |
+| ------ | -------- | -------- |
+| string | No       | Android  |
+
+---
+
+### `thirdPartyCookiesEnabled`
+
+Boolean value to enable third party cookies in the `WebView`. Used on Android Lollipop and above only as third party cookies are enabled by default on Android Kitkat and below and on iOS. The default value is `true`.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | Android  |
+
+---
+
+### `userAgent`
+
+Sets the user-agent for the `WebView`.
+
+| Type   | Required | Platform |
+| ------ | -------- | -------- |
+| string | No       | Android  |
+
+---
+
+### `allowsInlineMediaPlayback`
+
+Boolean that determines whether HTML5 videos play inline or use the native full-screen controller. The default value is `false`.
+
+> **NOTE**
+>
+> In order for video to play inline, not only does this property need to be set to `true`, but the video element in the HTML document must also include the `webkit-playsinline` attribute.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | iOS      |
+
+---
+
+### `bounces`
+
+Boolean value that determines whether the web view bounces when it reaches the edge of the content. The default value is `true`.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | iOS      |
+
+---
+
+### `contentInset`
+
+The amount by which the web view content is inset from the edges of the scroll view. Defaults to {top: 0, left: 0, bottom: 0, right: 0}.
+
+| Type                                                               | Required | Platform |
+| ------------------------------------------------------------------ | -------- | -------- |
+| object: {top: number, left: number, bottom: number, right: number} | No       | iOS      |
+
+---
+
+### `dataDetectorTypes`
+
+Determines the types of data converted to clickable URLs in the web view's content. By default only phone numbers are detected.
+
+You can provide one type or an array of many types.
+
+Possible values for `dataDetectorTypes` are:
+
+* `phoneNumber`
+* `link`
+* `address`
+* `calendarEvent`
+* `none`
+* `all`
+
+With the [new WebKit](Reference.md#usewebkit) implementation, we have three new values:
+
+* `trackingNumber`
+* `flightNumber`
+* `lookupSuggestion`
+
+| Type             | Required | Platform |
+| ---------------- | -------- | -------- |
+| string, or array | No       | iOS      |
+
+---
+
+### `scrollEnabled`
+
+Boolean value that determines whether scrolling is enabled in the `WebView`. The default value is `true`.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | iOS      |
+
+---
+
+### `geolocationEnabled`
+
+Set whether Geolocation is enabled in the `WebView`. The default value is `false`. Used only in Android.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | Android  |
+
+---
+
+### `allowUniversalAccessFromFileURLs`
+
+Boolean that sets whether JavaScript running in the context of a file scheme URL should be allowed to access content from any origin. Including accessing content from other file scheme URLs. The default value is `false`.
+
+| Type | Required | Platform |
+| ---- | -------- | -------- |
+| bool | No       | Android  |
+
+---
+
+### `useWebKit`
+
+If true, use WKWebView instead of UIWebView.
+
+| Type    | Required | Platform |
+| ------- | -------- | -------- |
+| boolean | No       | iOS      |
+
+---
+
+### `url`
+
+**Deprecated.** Use the `source` prop instead.
+
+| Type   | Required |
+| ------ | -------- |
+| string | No       |
+
+---
+
+### `html`
+
+**Deprecated.** Use the `source` prop instead.
+
+| Type   | Required |
+| ------ | -------- |
+| string | No       |
+
+## Methods
+
+### `extraNativeComponentConfig()`
+
+```javascript
+static extraNativeComponentConfig()
+```
+
+### `goForward()`
+
+```javascript
+goForward();
+```
+
+Go forward one page in the web view's history.
+
+### `goBack()`
+
+```javascript
+goBack();
+```
+
+Go back one page in the web view's history.
+
+### `reload()`
+
+```javascript
+reload();
+```
+
+Reloads the current page.
+
+### `stopLoading()`
+
+```javascript
+stopLoading();
+```
+
+Stop loading the current page.
+
+## Other Docs
+
+Also check out our [Getting Started Guide](Getting-Started.md) and [In-Depth Guide](Guide.md).