From a111a564f916fe7240abe65a2517bb15ff7d6c7e Mon Sep 17 00:00:00 2001 From: Christine Abernathy Date: Thu, 23 Jun 2016 12:47:36 -0700 Subject: [PATCH] Update NavigatorIOS component doc Summary: Reference: #8203 Changes made: - Added more to the intro section and updated the intro examples to ES6 - Added more details to prop explanations - Added parameter descriptions for methods **Test plan (required)** Ran the website locally and checked: http://localhost:8079/react-native/docs/navigatorios.html ![component_navigatorios_2](https://cloud.githubusercontent.com/assets/691109/16315939/1501ba2a-3939-11e6-8ec0-54b43e03b323.png) Closes https://github.com/facebook/react-native/pull/8334 Differential Revision: D3476066 Pulled By: JoelMarcey fbshipit-source-id: 9fcefe3f9d59008d8c72683c57cb004d1f185f62 --- .../Components/Navigation/NavigatorIOS.ios.js | 314 ++++++++++++------ 1 file changed, 215 insertions(+), 99 deletions(-) diff --git a/Libraries/Components/Navigation/NavigatorIOS.ios.js b/Libraries/Components/Navigation/NavigatorIOS.ios.js index f9d74e961..66ea9ee3e 100644 --- a/Libraries/Components/Navigation/NavigatorIOS.ios.js +++ b/Libraries/Components/Navigation/NavigatorIOS.ios.js @@ -93,86 +93,179 @@ type Event = Object; */ /** - * NavigatorIOS wraps UIKit navigation and allows you to add back-swipe - * functionality across your app. + * `NavigatorIOS` is a wrapper around UIKit navigation, enabling you to + * implement back-swipe functionality in your iOS app. Take a look at + * [`Navigator`](/docs/navigator.html) for a similar solution for your + * cross-platform needs. * - * > **NOTE**: This Component is not maintained by Facebook - * > - * > This component is under community responsibility. - * > If a pure JavaScript solution fits your needs you may try the `Navigator` - * > component instead. + * > **NOTE**: This component is not maintained by Facebook and is the + * > community's responsibility. * - * #### Routes - * A route is an object used to describe each page in the navigator. The first - * route is provided to NavigatorIOS as `initialRoute`: + * 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 + * navigates to. `initialRoute` represents the first route in your navigator. * * ``` - * render: function() { - * return ( - * - * ); - * }, + * import React, { Component } from 'react'; + * import { NavigatorIOS, Text } from 'react-native'; + * + * class NavvyIOS extends Component { + * render() { + * return ( + * + * ); + * } + * } + * + * class MyView extends Component { + * render() { + * return( + * + * See you on the other nav! + * + * ); + * } + * } * ``` * - * Now MyView will be rendered by the navigator. It will receive the route - * object in the `route` prop, a navigator, and all of the props specified in - * `passProps`. + * 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. * - * See the initialRoute propType for a complete definition of a route. - * - * #### Navigator - * - * A `navigator` is an object of navigation functions that a view can call. It - * is passed as a prop to any component rendered by NavigatorIOS. + * You can optionally pass in a `passProps` property to your `initialRoute`. + * `NavigatorIOS` passes this in as props to the rendered component: * * ``` - * var MyView = React.createClass({ - * _handleBackButtonPress: function() { + * initialRoute={{ + * component: MyView, + * title: 'Foo This', + * passProps: { myProp: 'foo' } + * }} + * ``` + * + * You can then access the props passed in: + * + * ``` + * + * See you on the other nav {this.props.myProp}! + * + * ``` + * + * #### Handling Navigation + * + * To trigger navigation functionality such as pushing or popping a view, you + * have access to a `navigator` object. The object is passed in as a prop to any + * component that is rendered by `NavigatorIOS`. You can then call the + * relevant methods to perform the navigation action you need: + * + * ``` + * class MyView extends Component { + * _handleBackPress() { * this.props.navigator.pop(); - * }, - * _handleNextButtonPress: function() { + * } + * + * _handleNextPress(nextRoute) { * this.props.navigator.push(nextRoute); - * }, - * ... - * }); + * } + * + * render() { + * const nextRoute = { + * component: MyView, + * title: 'Bar That', + * passProps: { myProp: 'bar' } + * }; + * return( + * this._handleNextPress(nextRoute)}> + * + * See you on the other nav {this.props.myProp}! + * + * + * ); + * } + * } * ``` * - * Navigator functions are also available on the NavigatorIOS component: + * You can also trigger navigator functionality from the `NavigatorIOS` + * component: * * ``` - * var MyView = React.createClass({ - * _handleNavigationRequest: function() { - * this.refs.nav.push(otherRoute); - * }, - * render: () => ( - * - * ), - * }); + * class NavvyIOS extends Component { + * _handleNavigationRequest() { + * this.refs.nav.push({ + * component: MyView, + * title: 'Genius', + * passProps: { myProp: 'genius' }, + * }); + * } + * + * render() { + * return ( + * this._handleNavigationRequest(), + * }} + * style={{flex: 1}} + * /> + * ); + * } + * } * ``` * - * Props passed to the NavigatorIOS component will set the default configuration + * The code above adds a `_handleNavigationRequest` private method that is + * invoked from the `NavigatorIOS` component when the right navigation bar item + * is pressed. To get access to the navigator functionality, a reference to it + * is saved in the `ref` prop and later referenced to push a new scene into the + * navigation stack. + * + * #### Navigation Bar Configuration + * + * Props passed to `NavigatorIOS` will set the default configuration * for the navigation bar. Props passed as properties to a route object will set * the configuration for that route's navigation bar, overriding any props - * passed to the NavigatorIOS component. + * passed to the `NavigatorIOS` component. * + * ``` + * _handleNavigationRequest() { + * this.refs.nav.push({ + * //... + * passProps: { myProp: 'genius' }, + * barTintColor: '#996699', + * }); + * } + * + * render() { + * return ( + * + * ); + * } + * ``` + * + * In the example above the navigation bar color is changed when the new route + * is pushed. */ var NavigatorIOS = React.createClass({ propTypes: { /** - * NavigatorIOS uses "route" objects to identify child views, their props, - * and navigation bar configuration. "push" and all the other navigation - * operations expect routes to be like this: + * NavigatorIOS uses `route` objects to identify child views, their props, + * and navigation bar configuration. Navigation operations such as push + * operations expect routes to look like this the `initialRoute`. */ initialRoute: PropTypes.shape({ /** @@ -181,144 +274,159 @@ var NavigatorIOS = React.createClass({ component: PropTypes.func.isRequired, /** - * The title displayed in the nav bar and back button for this route + * The title displayed in the navigation bar and the back button for this + * route. */ title: PropTypes.string.isRequired, /** - * If set, the image will appear instead of the text title + * If set, a title image will appear instead of the text title. */ titleImage: Image.propTypes.source, /** - * Specify additional props passed to the component. NavigatorIOS will - * automatically provide "route" and "navigator" components + * Use this to specify additional props to pass to the rendered + * component. `NavigatorIOS` will automatically pass in `route` and + * `navigator` props to the comoponent. */ passProps: PropTypes.object, /** - * If set, the left header button image will appear with this source. Note - * that this doesn't apply for the header of the current view, but the - * ones of the views that are pushed afterward. + * If set, the left navigation button image will be displayed using this + * source. Note that this doesn't apply to the header of the current + * view, but to those views that are subsequently pushed. */ backButtonIcon: Image.propTypes.source, /** - * If set, the left header button will appear with this name. Note that - * this doesn't apply for the header of the current view, but the ones - * of the views that are pushed afterward. + * If set, the left navigation button text will be set to this. Note that + * this doesn't apply to the left button of the current view, but to + * those views that are subsequently pushed */ backButtonTitle: PropTypes.string, /** - * If set, the left header button image will appear with this source + * If set, the left navigation button image will be displayed using + * this source. */ leftButtonIcon: Image.propTypes.source, /** - * If set, the left header button will appear with this name + * If set, the left navigation button will display this text. */ leftButtonTitle: PropTypes.string, /** - * Called when the left header button is pressed + * This function will be invoked when the left navigation bar item is + * pressed. */ onLeftButtonPress: PropTypes.func, /** - * If set, the right header button image will appear with this source + * If set, the right navigation button image will be displayed using + * this source. */ rightButtonIcon: Image.propTypes.source, /** - * If set, the right header button will appear with this name + * If set, the right navigation button will display this text. */ rightButtonTitle: PropTypes.string, /** - * Called when the right header button is pressed + * This function will be invoked when the right navigation bar item is + * pressed. */ onRightButtonPress: PropTypes.func, /** - * Styles for the navigation item containing the component + * Styles for the navigation item containing the component. */ wrapperStyle: View.propTypes.style, /** - * A Boolean value that indicates whether the navigation bar is hidden + * Boolean value that indicates whether the navigation bar is hidden. */ navigationBarHidden: PropTypes.bool, /** - * A Boolean value that indicates whether to hide the 1px hairline shadow + * Boolean value that indicates whether to hide the 1px hairline + * shadow. */ shadowHidden: PropTypes.bool, /** - * The color used for buttons in the navigation bar + * The color used for the buttons in the navigation bar. */ tintColor: PropTypes.string, /** - * The background color of the navigation bar + * The background color of the navigation bar. */ barTintColor: PropTypes.string, /** - * The text color of the navigation bar title + * The text color of the navigation bar title. */ titleTextColor: PropTypes.string, /** - * A Boolean value that indicates whether the navigation bar is translucent + * Bboolean value that indicates whether the navigation bar is + * translucent. */ translucent: PropTypes.bool, }).isRequired, /** - * A Boolean value that indicates whether the navigation bar is hidden by default + * Boolean value that indicates whether the navigation bar is hidden + * by default. */ navigationBarHidden: PropTypes.bool, /** - * A Boolean value that indicates whether to hide the 1px hairline shadow by default + * Boolean value that indicates whether to hide the 1px hairline shadow + * by default. */ shadowHidden: PropTypes.bool, /** * The default wrapper style for components in the navigator. - * A common use case is to set the backgroundColor for every page + * A common use case is to set the `backgroundColor` for every scene. */ itemWrapperStyle: View.propTypes.style, /** - * The default color used for buttons in the navigation bar + * The default color used for the buttons in the navigation bar. */ tintColor: PropTypes.string, /** - * The default background color of the navigation bar + * The default background color of the navigation bar. */ barTintColor: PropTypes.string, /** - * The default text color of the navigation bar title + * The default text color of the navigation bar title. */ titleTextColor: PropTypes.string, /** - * A Boolean value that indicates whether the navigation bar is translucent by default + * Boolean value that indicates whether the navigation bar is + * translucent by default */ translucent: PropTypes.bool, /** - * A Boolean value that indicates whether the interactive pop gesture is enabled. Useful - * for enabling/disabling the back swipe navigation gesture. If this prop is not provided, - * the default behavior is for the back swipe gesture to be enabled when the navigation bar - * is shown and disabled when the navigation bar is hidden. Once you've provided - * the interactivePopGestureEnabled prop, you can never restore the default behavior. + * Boolean value that indicates whether the interactive pop gesture is + * enabled. This is useful for enabling/disabling the back swipe navigation + * gesture. + * + * If this prop is not provided, the default behavior is for the back swipe + * gesture to be enabled when the navigation bar is shown and disabled when + * the navigation bar is hidden. Once you've provided the + * `interactivePopGestureEnabled` prop, you can never restore the default + * behavior. */ interactivePopGestureEnabled: PropTypes.bool, @@ -493,7 +601,8 @@ var NavigatorIOS = React.createClass({ }, /** - * Navigate forward to a new route + * Navigate forward to a new route. + * @param route The new route to navigate to. */ push: function(route: Route) { invariant(!!route, 'Must supply route to push'); @@ -518,7 +627,8 @@ var NavigatorIOS = React.createClass({ }, /** - * Go back N pages at once. When N=1, behavior matches `pop()` + * Go back N scenes at once. When N=1, behavior matches `pop()`. + * @param n The number of scenes to pop. */ popN: function(n: number) { if (n === 0) { @@ -542,7 +652,7 @@ var NavigatorIOS = React.createClass({ }, /** - * Go back one page + * Pop back to the previous scene. */ pop: function() { this.popN(1); @@ -551,8 +661,9 @@ var NavigatorIOS = React.createClass({ /** * Replace a route in the navigation stack. * - * `index` specifies the route in the stack that should be replaced. - * If it's negative, it counts from the back. + * @param route The new route that will replace the specified one. + * @param index The route into the stack that should be replaced. + * If it is negative, it counts from the back of the stack. */ replaceAtIndex: function(route: Route, index: number) { invariant(!!route, 'Must supply route to replace'); @@ -583,29 +694,32 @@ var NavigatorIOS = React.createClass({ }, /** - * Replace the route for the current page and immediately + * Replace the route for the current scene and immediately * load the view for the new route. + * @param route The new route to navigate to. */ replace: function(route: Route) { this.replaceAtIndex(route, -1); }, /** - * Replace the route/view for the previous page. + * Replace the route/view for the previous scene. + * @param route The new route to will replace the previous scene. */ replacePrevious: function(route: Route) { this.replaceAtIndex(route, -2); }, /** - * Go back to the top item + * Go back to the topmost item in the navigation stack. */ popToTop: function() { this.popToRoute(this.state.routeStack[0]); }, /** - * Go back to the item for a particular route object + * Go back to the item for a particular route object. + * @param route The new route to navigate to. */ popToRoute: function(route: Route) { var indexOfRoute = this.state.routeStack.indexOf(route); @@ -619,6 +733,7 @@ var NavigatorIOS = React.createClass({ /** * Replaces the previous route/view and transitions back to it. + * @param route The new route that replaces the previous scene. */ replacePreviousAndPop: function(route: Route) { // Make sure all previous requests are caught up first. Otherwise reject. @@ -638,7 +753,8 @@ var NavigatorIOS = React.createClass({ }, /** - * Replaces the top item and popToTop + * Replaces the top item and pop to it. + * @param route The new route that will replace the topmost item. */ resetTo: function(route: Route) { invariant(!!route, 'Must supply route to push');