Remove navigator comparison and redirect to Navigation guide

Libraries/Components/Navigation/NavigatorIOS.ios.js

@@ -93,10 +93,17 @@ type Event = Object;
  */
 
 /**
- * `NavigatorIOS` is a wrapper around UIKit navigation, enabling you to
- * implement back-swipe functionality in your iOS app. Take a look at
+ * `NavigatorIOS` is a wrapper around
+ * [`UINavigationController`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UINavigationController_Class/),
+ * enabling you to implement a navigation stack. It works exactly the same as it
+ * would on a native app using `UINavigationController`, providing the same
+ * animations and behavior from UIKIt.
+ *
+ * As the name implies, it is only available on iOS. Take a look at
  * [`Navigator`](/docs/navigator.html) for a similar solution for your
- * cross-platform needs.
+ * cross-platform needs, or check out
+ * [react-native-navigation](https://github.com/wix/react-native-navigation), a
+ * component that aims to provide native navigation on both iOS and Android.
  *
  * To set up the navigator, provide the `initialRoute` prop with a route
  * object. A route object is used to describe each scene that your app
@@ -106,53 +113,68 @@ type Event = Object;
  * import React, { Component } from 'react';
  * import { NavigatorIOS, Text } from 'react-native';
  *
- * class NavvyIOS extends Component {
+ * export default class NavigatorIOSApp extends Component {
  *   render() {
  *     return (
  *       <NavigatorIOS
  *         initialRoute={{
- *           component: MyView,
- *           title: 'My View Title',
+ *           component: MyScene,
+ *           title: 'My Initial Scene',
  *         }}
  *         style={{flex: 1}}
  *       />
  *     );
  *   }
  * }
  *
- * class MyView extends Component {
+ * class MyScene extends Component {
+ *   static propTypes = {
+ *     title: PropTypes.string.isRequired,
+ *     navigator: PropTypes.object.isRequired,
+ *   }
+ *
+ *   constructor(props, context) {
+ *     super(props, context);
+ *     this._onForward = this._onForward.bind(this);
+ *     this._onBack = this._onBack.bind(this);
+ *   }
+ *
+ *   _onForward() {
+ *     this.props.navigator.push({
+ *       title: 'Scene ' + nextIndex,
+ *     });
+ *   }
+ *
  *   render() {
- *     return(
- *       <Text style={{marginTop: 200, alignSelf: 'center'}}>
- *         See you on the other nav!
- *       </Text>
- *     );
+ *     return (
+ *       <View>
+ *         <Text>Current Scene: { this.props.title }</Text>
+ *         <TouchableHighlight onPress={this._onForward}>
+ *           <Text>Tap me to load the next scene</Text>
+ *         </TouchableHighlight>
+ *       </View>
+ *     )
  *   }
  * }
  * ```
  *
- * In this code, the navigator sets its title and renders `MyView`. The
- * component specified in `initialRoute` will receive a `route` prop and a
- * `navigator` prop representing the navigator.
+ * In this code, the navigator renders the component specified in initialRoute,
+ * which in this case is `MyScene`. This component will receive a `route` prop
+ * and a `navigator` prop representing the navigator. The navigator's navigation
+ * bar will render the title for the current scene, "My Initial Scene".
  *
  * You can optionally pass in a `passProps` property to your `initialRoute`.
  * `NavigatorIOS` passes this in as props to the rendered component:
  *
  * ```
  * initialRoute={{
- *   component: MyView,
- *   title: 'Foo This',
+ *   component: MyScene,
+ *   title: 'My Initial Scene',
  *   passProps: { myProp: 'foo' }
  * }}
  * ```
  *
- * You can then access the props passed in:
- *
- * ```
- * <Text style={{marginTop: 200, alignSelf: 'center'}}>
- *   See you on the other nav {this.props.myProp}!
- * </Text>
- * ```
+ * You can then access the props passed in via `{this.props.myProp}`.
  *
  * #### Handling Navigation
  *
@@ -254,6 +276,7 @@ type Event = Object;
  *
  * In the example above the navigation bar color is changed when the new route
  * is pushed.
+ *
  */
 var NavigatorIOS = React.createClass({
 

Libraries/CustomComponents/Navigator/Navigator.js

@@ -130,9 +130,10 @@ var GESTURE_ACTIONS = [
 
 /**
  * `Navigator` handles the transition between different scenes in your app.
- * You should consider using this component instead of `NavigatorIOS` if you're
- * building a cross-platform app. `Navigator` is implemented in JavaScript
- * whereas `NavigatorIOS` is a wrapper around `UINavigationController`.
+ * It is implemented in JavaScript and is available on both iOS and Android. If
+ * you are targeting iOS only, you may also want to consider using
+ * [`NavigatorIOS`](docs/navigatorios.html) as it leverages native UIKit
+ * navigation.
  *
  * To set up the `Navigator` you provide one or more objects called routes,
  * to identify each scene. You also provide a `renderScene` function that
@@ -142,13 +143,13 @@ var GESTURE_ACTIONS = [
  * import React, { Component } from 'react';
  * import { Text, Navigator } from 'react-native';
  *
- * class NavAllDay extends Component {
+ * export default class NavAllDay extends Component {
  *   render() {
  *     return (
  *       <Navigator
- *         initialRoute={{name: 'Awesome Scene'}}
+ *         initialRoute={{ title: 'Awesome Scene', index: 0 }}
  *         renderScene={(route, navigator) =>
- *           <Text>Hello {route.name}!</Text>
+ *           <Text>Hello {route.title}!</Text>
  *         }
  *         style={{padding: 100}}
  *       />
@@ -158,8 +159,8 @@ var GESTURE_ACTIONS = [
  * ```
  *
  * In the above example, `initialRoute` is used to specify the first route. It
- * contains a `name` property that identifies the route. The `renderScene`
- * prop returns a function that displays text based on the route's name.
+ * contains a `title` property that identifies the route. The `renderScene`
+ * prop returns a function that displays text based on the route's title.
  *
  * ### Additional Scenes
  *
@@ -169,8 +170,8 @@ var GESTURE_ACTIONS = [
  * ```
  * render() {
  *   const routes = [
- *     {name: 'First Scene', index: 0},
- *     {name: 'Second Scene', index: 1},
+ *     {title: 'First Scene', index: 0},
+ *     {title: 'Second Scene', index: 1},
  *   ];
  *   return (
  *     <Navigator
@@ -184,7 +185,7 @@ var GESTURE_ACTIONS = [
  *             navigator.pop();
  *           }
  *         }}>
- *         <Text>Hello {route.name}!</Text>
+ *         <Text>Hello {route.title}!</Text>
  *         </TouchableHighlight>
  *       }
  *       style={{padding: 100}}
@@ -256,6 +257,12 @@ var GESTURE_ACTIONS = [
  * This sets up a left navigator bar button that's visible on scenes after the
  * the first one. When the button is tapped the navigator is popped.
  *
+ * Another type of navigation bar, with breadcrumbs, is provided by
+ * `Navigator.BreadcrumbNavigationBar`. You can also provide your own navigation
+ * bar by passing it through the `navigationBar` prop. See the
+ * [UIExplorer](https://github.com/facebook/react-native/tree/master/Examples/UIExplorer)
+ * demo to try out both built-in navigation bars out and see how to use them.
+ *
  * ### Scene Transitions
  *
  * To change the animation or gesture properties of the scene, provide a

docs/JavaScriptEnvironment.md

@@ -4,7 +4,7 @@ title: JavaScript Environment
 layout: docs
 category: Guides
 permalink: docs/javascript-environment.html
-next: navigation
+next: navigator-comparison
 ---
 
 ## JavaScript Runtime

docs/Navigation.md → docs/Navigator-Comparison.md

@@ -1,25 +1,25 @@
 ---
-id: navigation
+id: navigator-comparison
 title: Navigation
 layout: docs
 category: Guides
-permalink: docs/navigation.html
-next: navigator-comparison
+permalink: docs/navigator-comparison.html
+next: performance
 ---
 
 Mobile apps rarely consist of just one screen or scene. As soon as you add a second scene to your app, you will have to take into consideration how the user will navigate from one scene to the other.
 
-Navigators in React Native allow you to push and pop scenes in a master/detail stack, or to pop up modal scenes. Navigators handle the transitions between scenes, and also maintain the navigational state of your application.
+Navigators in React Native allow you to push and pop scenes in a master/detail stack, or to pop up modal scenes. Navigators handle the transition between scenes, and also maintain the navigational state of your application.
 
-If you are just getting started with React Native, you will probably want to start with the `Navigator` component.
+If you are new to React Native, you will probably want to start with the Navigator component.
 
 ## Navigator
 
-`Navigator` is a cross-platform implementation of a navigation stack, so it works on both iOS and Android. It is easy to customize and includes simple navigation bars.
+[Navigator](docs/navigator.html) is a cross-platform implementation of a navigation stack, so it works on both iOS and Android. It is easy to customize and includes simple navigation bars.
 
 ```js
 <Navigator
-  initialRoute={{ title: 'My Initial Scene', index: 0}}
+  initialRoute={{ title: 'My Initial Scene', index: 0 }}
   renderScene={(route, navigator) => {
       // We'll get to this function soon.
   }}
@@ -31,28 +31,10 @@ Something you will encounter a lot when dealing with navigation is the concept o
 The `push` and `pop` functions provided by Navigator can be used to push and pop routes into the navigation stack. A more complete example that demonstrates the pushing and popping of routes could therefore look something like this:
 
 ```js
-class MyScene extends Component {
-  static propTypes = {
-    title: PropTypes.string.isRequired,
-    onForward: PropTypes.func.isRequired,
-    onBack: PropTypes.func.isRequired,
-  }
-  render() {
-    return (
-      <View>
-        <Text>Current Scene: { this.props.title }</Text>
-        <TouchableHighlight onPress={this.props.onForward}>
-          <Text>Tap me to load the next scene</Text>
-        </TouchableHighlight>
-        <TouchableHighlight onPress={this.props.onBack}>
-          <Text>Tap me to go back</Text>
-        </TouchableHighlight>
-      </View>
-    )
-  }
-}
+import React, { Component, PropTypes } from 'react';
+import { Navigator, Text, TouchableHighlight, View } from 'react-native';
 
-class SimpleNavigationApp extends Component {
+export default class SimpleNavigationApp extends Component {
   render() {
     return (
       <Navigator
@@ -78,6 +60,27 @@ class SimpleNavigationApp extends Component {
     )
   }
 }
+
+class MyScene extends Component {
+  static propTypes = {
+    title: PropTypes.string.isRequired,
+    onForward: PropTypes.func.isRequired,
+    onBack: PropTypes.func.isRequired,
+  }
+  render() {
+    return (
+      <View>
+        <Text>Current Scene: { this.props.title }</Text>
+        <TouchableHighlight onPress={this.props.onForward}>
+          <Text>Tap me to load the next scene</Text>
+        </TouchableHighlight>
+        <TouchableHighlight onPress={this.props.onBack}>
+          <Text>Tap me to go back</Text>
+        </TouchableHighlight>
+      </View>
+    )
+  }
+}
 ```
 
 In this example, the `MyScene` component is passed the title of the current route via the `title` prop. It displays two tappable components that call the `onForward` and `onBack` functions passed through its props, which in turn will call `navigator.push()` and `navigator.pop()` as needed.
@@ -86,7 +89,7 @@ While this is a very basic example, it can easily be adapted to render an entire
 
 ## NavigatorIOS
 
-If you are targeting iOS only, you may also want to consider using `NavigatorIOS`. It looks and feels just like `UINavigationController`, because it is actually built on top of it.
+If you are targeting iOS only, you may also want to consider using [NavigatorIOS](docs/navigatorios.html). It looks and feels just like [`UINavigationController`](https://developer.apple.com/library/ios/documentation/UIKit/Reference/UINavigationController_Class/), because it is actually built on top of it.
 
 ```js
 <NavigatorIOS
@@ -98,11 +101,30 @@ If you are targeting iOS only, you may also want to consider using `NavigatorIOS
 />
 ```
 
-Just like Navigator, it it uses routes to represent scenes, with some important differences. The actual component that will be rendered can be specified using the `component` key in the route, and any props that should be passed to this component can be specified in `passProps`. A navigator object is automatically passed as a prop to the component, allowing you to call `push` and `pop` as needed.
+Just like Navigator, NavigatorIOS uses routes to represent scenes, with some important differences. The actual component that will be rendered can be specified using the `component` key in the route, and any props that should be passed to this component can be specified in `passProps`. A "navigator" object is automatically passed as a prop to the component, allowing you to call `push` and `pop` as needed.
+
+As NavigatorIOS leverages native UIKit navigation, it will automatically render a navigation bar with a back button and title.
 
 Check out the [NavigatorIOS reference docs](docs/navigatorios.html) to learn more about this component.
 
 ```js
+import React, { Component, PropTypes } from 'react';
+import { NavigatorIOS, Text, TouchableHighlight, View } from 'react-native';
+
+export default class NavigatorIOSApp extends Component {
+  render() {
+    return (
+      <NavigatorIOS
+        initialRoute={{
+          component: MyScene,
+          title: 'My Initial Scene',
+        }}
+        style={{flex: 1}}
+      />
+    )
+  }
+}
+
 class MyScene extends Component {
   static propTypes = {
     title: PropTypes.string.isRequired,
@@ -112,7 +134,6 @@ class MyScene extends Component {
   constructor(props, context) {
     super(props, context);
     this._onForward = this._onForward.bind(this);
-    this._onBack = this._onBack.bind(this);
   }
 
   _onForward() {
@@ -121,41 +142,17 @@ class MyScene extends Component {
     });
   }
 
-  _onBack() {
-    this.props.navigator.pop();
-  }
-
   render() {
     return (
       <View>
         <Text>Current Scene: { this.props.title }</Text>
         <TouchableHighlight onPress={this._onForward}>
           <Text>Tap me to load the next scene</Text>
         </TouchableHighlight>
-        <TouchableHighlight onPress={this._onBack}>
-          <Text>Tap me to go back</Text>
-        </TouchableHighlight>
       </View>
     )
   }
 }
-
-class NavigatorIOSApp extends Component {
-  render() {
-    return (
-      <NavigatorIOS
-        initialRoute={{
-          component: MyScene,
-          title: 'My Initial Scene',
-          index: 0
-        }}
-        renderScene={ (route, navigator) =>
-          <MyScene title={route.title} />
-        }
-      />
-    )
-  }
-}
 ```
 
 > You may also want to check out [react-native-navigation](https://github.com/wix/react-native-navigation), a component that aims to provide native navigation on both iOS and Android.