From 655b46b60b78455f1bf6998cc497157846ccf27e Mon Sep 17 00:00:00 2001 From: Kevin Cooper Date: Tue, 25 Apr 2017 05:48:54 -0400 Subject: [PATCH] Improve the Redux docs (#1172) * [ReduxExample] Programmatically generate initial state * [ReduxExample] Return original state if nextState is null * [Docs] Add getStateForAction to redux integration example * [Docs] Add link to ReduxExample app * [Docs] Give each example a 'DRY' README linking to real docs * [Docs] Clean up the Contributors guide a bit * [Docs] Remove numbers from sections in Contributors guide They don't seem very meaningful, and don't need to be done in order --- docs/guides/Contributors.md | 22 ++++++++-------- docs/guides/Redux-Integration.md | 14 ++++++++--- examples/NavigationPlayground/README.md | 7 ++++++ examples/NavigationPlayground/ReadMe.md | 17 ------------- examples/ReduxExample/README.md | 5 ++++ examples/ReduxExample/src/reducers/index.js | 28 ++++++++++++--------- 6 files changed, 50 insertions(+), 43 deletions(-) create mode 100644 examples/NavigationPlayground/README.md delete mode 100644 examples/NavigationPlayground/ReadMe.md create mode 100644 examples/ReduxExample/README.md diff --git a/docs/guides/Contributors.md b/docs/guides/Contributors.md index 0a93157..416d45a 100644 --- a/docs/guides/Contributors.md +++ b/docs/guides/Contributors.md @@ -6,21 +6,20 @@ React navigation was initially developed on macOS 10.12, with node 7+, and react ## Development -### 0. Fork the repo +### Fork the repo - Fork [`react-navigation`](https://github.com/react-community/react-navigation) on GitHub -- Run these commands in the terminal: +- Run these commands in the terminal to download locally and install it: ``` -git clone https://github.com//react-navigation.git` +git clone https://github.com//react-navigation.git cd react-navigation git remote add upstream https://github.com/react-community/react-navigation.git npm install ``` - -### 1. Run the native playground +### Run the example app ``` cd examples/NavigationPlayground @@ -30,17 +29,20 @@ npm start # In a seperate terminal tab: npm run run-playground-android +# OR: npm run run-playground-ios ``` -### 2. Run the website +You can also simply run e.g. `react-native run-android` from within the example app directory (instead of `npm run run-playground-android` from the root `react-navigation` directory); both do the same thing. + +### Run the website For development mode and live-reloading: ``` cd website npm install -npm run start +npm start ``` To run the website in production mode with server rendering: @@ -49,7 +51,7 @@ To run the website in production mode with server rendering: npm run prod ``` -### 3. Run tests, run flow +### Run tests and type-checking ``` jest @@ -60,14 +62,12 @@ Tests must pass for your changes to be accepted and merged. Flow is not yet passing, but your code should be flow checked and we expect that your changes do not introduce any flow errors. - -### 4. Developing Docs +### Developing Docs The docs are indexed in [App.js](https://github.com/react-community/react-navigation/blob/master/website/src/App.js), where all the pages are declared alongside the titles. To test the docs, follow the above instructions for running the website. Changing existing markdown files should not require any testing. The markdown from the `docs` folder gets generated and dumped into a json file as a part of the build step. To see updated docs appear in the website, re-run the build step by running `npm run build-docs` from the `react-navigation` root folder. - ## Submitting Contributions ### New views or unique features diff --git a/docs/guides/Redux-Integration.md b/docs/guides/Redux-Integration.md index 406d387..8fe4edc 100644 --- a/docs/guides/Redux-Integration.md +++ b/docs/guides/Redux-Integration.md @@ -9,9 +9,13 @@ import { addNavigationHelpers } from 'react-navigation'; const AppNavigator = StackNavigator(AppRouteConfigs); -const navReducer = (state, action) => { - const newState = AppNavigator.router.getStateForAction(action, state); - return (newState ? newState : state) +const initialState = AppNavigator.router.getStateForAction(AppNavigator.router.getActionForPathAndParams('Login')); + +const navReducer = (state = initialState, action) => { + const nextState = AppNavigator.router.getStateForAction(action, state); + + // Simply return the original `state` if `nextState` is null or undefined. + return nextState || state; }; const appReducer = combineReducers({ @@ -65,6 +69,10 @@ const AppNavigator = StackNavigator({ In this case, once you `connect` `AppNavigator` to Redux as is done in `AppWithNavigationState`, `MyTabNavigator` will automatically have access to navigation state as a `navigation` prop. +## Full example + +There's a working example app with redux [here](https://github.com/react-community/react-navigation/tree/master/examples/ReduxExample) if you want to try it out yourself. + ## Mocking tests To make jest tests work with your react-navigation app, you need to change the jest preset in the `package.json`, see [here](https://facebook.github.io/jest/docs/tutorial-react-native.html#transformignorepatterns-customization): diff --git a/examples/NavigationPlayground/README.md b/examples/NavigationPlayground/README.md new file mode 100644 index 0000000..0627570 --- /dev/null +++ b/examples/NavigationPlayground/README.md @@ -0,0 +1,7 @@ +# Navigation Playground Example + +A playground for experimenting with react-navigation in a pure-JS React Native app. + +## Usage + +Please see the [Contributors Guide](https://github.com/react-community/react-navigation/blob/master/docs/guides/Contributors.md#development) for instructions on running these example apps. diff --git a/examples/NavigationPlayground/ReadMe.md b/examples/NavigationPlayground/ReadMe.md deleted file mode 100644 index e3be7e7..0000000 --- a/examples/NavigationPlayground/ReadMe.md +++ /dev/null @@ -1,17 +0,0 @@ -# Navigation Playground Example - -A playground for experimenting with react-navigation in a pure-JS React Native app. - -## Setup: - -``` -cd react-navigation -npm install -cd examples/NavigationPlayground -npm install -cd ../.. -react-native start -cd examples/NavigationPlayground -react-native run-ios # ignore packager starting error -react-native run-android # ignore packager starting error -``` diff --git a/examples/ReduxExample/README.md b/examples/ReduxExample/README.md new file mode 100644 index 0000000..bc98a31 --- /dev/null +++ b/examples/ReduxExample/README.md @@ -0,0 +1,5 @@ +# Redux example + +## Usage + +Please see the [Contributors Guide](https://github.com/react-community/react-navigation/blob/master/docs/guides/Contributors.md#development) for instructions on running these example apps. diff --git a/examples/ReduxExample/src/reducers/index.js b/examples/ReduxExample/src/reducers/index.js index f701aea..6eeb3b6 100644 --- a/examples/ReduxExample/src/reducers/index.js +++ b/examples/ReduxExample/src/reducers/index.js @@ -4,27 +4,31 @@ import { NavigationActions } from 'react-navigation'; import { AppNavigator } from '../navigators/AppNavigator'; // Start with two routes: The Main screen, with the Login screen on top. -const initialNavState = { - index: 1, - routes: [ - { key: 'InitA', routeName: 'Main' }, - { key: 'InitB', routeName: 'Login' }, - ], -}; - -const initialAuthState = { isLoggedIn: false }; +const firstAction = AppNavigator.router.getActionForPathAndParams('Main'); +const tempNavState = AppNavigator.router.getStateForAction(firstAction); +const secondAction = AppNavigator.router.getActionForPathAndParams('Login'); +const initialNavState = AppNavigator.router.getStateForAction(secondAction, tempNavState); function nav(state = initialNavState, action) { + let nextState; switch (action.type) { case 'Login': - return AppNavigator.router.getStateForAction(NavigationActions.back(), state); + nextState = AppNavigator.router.getStateForAction(NavigationActions.back(), state); + break; case 'Logout': - return AppNavigator.router.getStateForAction(NavigationActions.navigate({ routeName: 'Login' }), state); + nextState = AppNavigator.router.getStateForAction(NavigationActions.navigate({ routeName: 'Login' }), state); + break; default: - return AppNavigator.router.getStateForAction(action, state); + nextState = AppNavigator.router.getStateForAction(action, state); + break; } + + // Simply return the original `state` if `nextState` is null or undefined. + return nextState || state; } +const initialAuthState = { isLoggedIn: false }; + function auth(state = initialAuthState, action) { switch (action.type) { case 'Login':