diff --git a/README.md b/README.md index 1f503fb73..512838180 100644 --- a/README.md +++ b/README.md @@ -4,34 +4,38 @@ [Follow author @PAksonov](https://twitter.com/PAksonov) -Please 🌟 my proposal talk for ReactiveConf 2017 [What is RNRNF?](https://gist.github.com/aksonov/e2d7454421e44b1c4c72214d14053410) +Please 🌟 my talk proposal for [ReactiveConf 2017](https://reactiveconf.com/) - [What is RNRF?](https://gist.github.com/aksonov/e2d7454421e44b1c4c72214d14053410) -#### Go [here](https://github.com/aksonov/react-native-router-flux/tree/v3) for v3. Docs could be found [here](https://github.com/aksonov/react-native-router-flux/blob/master/README3.md) +#### NOTE: v4 (based on [React Navigation](https://reactnavigation.org/)) is in beta. See [this branch](https://github.com/aksonov/react-native-router-flux/tree/v3) and [docs](https://github.com/aksonov/react-native-router-flux/blob/master/README3.md) for v3. ___ -Define all your routes in one place... +* [Example](#try-the-example-app) +* [Motivation](https://gist.github.com/aksonov/e2d7454421e44b1c4c72214d14053410) +* [v4 Features](#v4-features) +* [API](/docs/API.md) +* [Migrating from v3](/docs/MIGRATION.md) +* [Sponsors/Backers/Contributors](#contributors) + + +Define all your routes in one React component... ```js -class App extends React.Component { - render() { - return ( - - - - - - - - ); - } -} +const App = () => ( + + + + + + + +); ``` ...and navigate from scene to scene with a simple, powerful API ```js -// login.js +// Login.js // navigate to 'home' as defined in your top-level router Actions.home(PARAMS) @@ -63,36 +67,20 @@ react-native run-ios ## v4 Features * Based on latest [React Navigation](https://reactnavigation.org) API * Separate navigation logic from presentation. You may change now navigation state directly from your business logic code - stores/reducers/etc. navigationStore -* Built-in state machine (v3 `Switch` replacement) - each ‘scene’ could have onEnter/onExit handlers. onEnter handler could be async. For successful termination of onEnter, `success` handler (if defined) will be executed (if `success` is string then router will navigation to that Scene), in case of handler's failure `failure` (if defined) will be run. It will allow to build authentication, data validation and conditional transitions in very easy way. -* MobX-powered, all used scenes are wrapped as 'observer' automatically. You may subscribe to navigationStore (former Actions), observe current navigation state, etc. If you are using Redux, skip this. -* Flexible nav bar customization, that is not allowed by react navigation right now: +* Built-in state machine (v3 `Switch` replacement) + * Each `Scene` can have `onEnter`/`onExit`/`on` handlers. + * `onEnter`/`on` handler can be async. + * For 'truthy' return of `onEnter`/`on`, `success` handler (if defined) will be executed + * if `success` is a string then router will navigate to the `Scene` with that key + * in case of handler's failure, `failure` prop (if defined) will be run. + * Combining `onEnter`, `onExit`, `success`, and `failure` makes patterns like authentication, data validation, and conditional transitions simple and intuitive. +* [MobX](https://mobx.js.org/)-friendly: all scenes are wrapped with `observer`. You may subscribe to `navigationStore` (`Actions` in v3) and observe current navigation state. Not applicable to Redux. +* Flexible nav bar customization not currently allowed by React Navigation: https://github.com/react-community/react-navigation/issues/779 -* Drawer support (provided by reactnavigation) -* Inheritance of scene attributes allow you to avoid any code/attribute duplications. If you send rightTitle it will be shown in all children. -* Access to your app navigations state as simple as `Actions.state`, use `Actions.currentScene` to get name of current scene. - -## Breaking changes (compared to v3): -* `Actions.create` (alternative syntax to define scenes) is not available (for simplicity) - just use `` as top component for your App. You may wrap it with Redux as well. -* No `duration`/`panHandlers` support - you have to implement custom navigator now instead and pass it as ‘navigator’ prop -https://reactnavigation.org/docs/navigators/custom. You could still pass `panHandlers={null}` to disable gestures or `gesturedEnabled={false}` -* No `component` support for scene containers (that contains children `Scene`) - you have to use custom navigator -* No support for partial hiding of tab bar for some tabs because of react navigation bug (react navigation issue): -https://github.com/react-community/react-navigation/issues/1584 -* No possibility to skip animation during reset/replace (react navigation issue): -https://github.com/react-community/react-navigation/issues/1493 -* `Switch` is removed - you may use onEnter/onExit handlers for more flexible logic. -* `getSceneStyle` is removed (no needed in v4, you may pass any values to Router now and they will be inherited by all scenes). -* Custom reducer is supported (`createReducer` prop for Router) but Redux actions now are passed directly from React Navigation (‘Navigation/BACK’, ‘Navigation/NAVIGATE’, etc.) -* Drawer is 'drawer' attribute Scene -* Modal is 'lightbox' attribute for Scene (used for popups, like Error) -* Container scenes (that has children) cannot have `component` (or it will be considered as child!). If you want to customize containers, use react navigation custom navigators and pass it as `navigator` prop. -* No `position` attribute is supported for custom transitions. For vertical transition add `modal` to parent `Scene`. -* No flux 'focus' actions - use onEnter/onExit handlers instead. -* tabBarSelectedItemStyle is not supported. Instead please use React Navigation TabBar params for tabs Scene: `activeTintColor`, `inactiveTintColor`, etc (https://reactnavigation.org/docs/navigators/tab) -* Possible other stuff. - -## Migrating from v3 -Coming soon +* Drawer support (provided by React Navigation) +* Inheritance of scene attributes allow you to avoid any code/attribute duplications. Adding `rightTitle` to a scene will apply to all child scenes. See example app. +* Access to your app navigations state as simple as `Actions.state`. +* Use `Actions.currentScene` to get name of current scene. ## Contributors @@ -121,5 +109,3 @@ Support this project by becoming a sponsor. Your logo will show up here with a l - - diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 000000000..23ca9706f --- /dev/null +++ b/docs/API.md @@ -0,0 +1,50 @@ +# API and Configuration + +## Available imports +- `Router` +- `Scene` +- `Actions` +- `ActionConst` + +## Router: + +| Property | Type | Default | Description | +|-------------|----------|--------------|----------------------------------------------------------------| +| children | | required | Scene root element | +| `wrapBy` | `Function` | | allows integration of state management schemes like Redux (`connect`) and Mobx (`observer`) | + +## Scene: + +| Property | Type | Default | Description | +|-----------|----------|----------|--------------------------------------------| +| `key` | `string` | required | Will be used to call screen transition, for example, `Actions.name(params)`. Must be unique. | +| `component` | `React.Component` | semi-required | The `Component` to be displayed. Not required when defining a nested `Scene`, see example. | +| `initial` | `boolean` | false | Set to `true` if this is the first scene to display among its sibling `Scene`s | +| `clone` | `boolean` | false | Scenes marked with `clone` will be treated as templates and cloned into the current scene's parent when pushed. See example. | +| `on` | `Function` | | aka `onEnter`. Called when the `Scene` is navigated to. `props` are provided as a function param | +| `onExit` | `Function` | | Called when the `Scene` is navigated away from. | +| `success` | `Function` | | If `on` returns a "truthy" value then `success` is called. | +| `failure` | `Function` | | If `on` returns a "falsey" value then `failure` is called. | +| `tabs` | `boolean` | false | load child scenes as [TabNavigator](https://reactnavigation.org/docs/navigators/tab). Other [Tab Navigator props](https://reactnavigation.org/docs/navigators/tab#TabNavigatorConfig) also apply here. | +| `hideTabBar` | `boolean` | false | hide the tab bar (only applies to scenes with `tabs` specified) | +| `drawer` | `boolean` | false | load child scenes inside [DrawerNavigator](https://reactnavigation.org/docs/navigators/drawer) | +| `contentComponent` | `React.Component` | | Component used to render the content of the drawer (e.g. navigation items). | +| `onLeft` | `boolean` | false | load child scenes as [DrawerNavigator](https://reactnavigation.org/docs/navigators/drawer) | +| `navTransparent` | `boolean` | false | nav bar background transparency | +| `hideNavBar` | `boolean` | false | hide the nav bar | +| `title` | `string` | | Text to be displayed in the center of the nav bar. | +| `onLeft` | `Function` | | Called when the left nav bar button is pressed. | +| `onRight` | `Function` | | Called when the right nav bar button is pressed. | +| `leftButtonImage` | `Image` | | Image to substitute for the left nav bar button | +| `rightButtonImage` | `Image` | | Image to substitute for the right nav bar button | +| `modal` | `boolean` | false | | +| `back` | `boolean` | false | Show a back button on the left side of the nav bar that calls `Actions.pop` on press. | +| all other props | | | Any other props not listed here will be pass on to the specified `Scene`'s `component` | + +## Actions + +| Property | Type | Default | Description | +|-----------------|----------|----------|--------------------------------------------| +| `[key]` | `Function` | | Scenes are "automagically" added as functions on the `Actions` object by `key`. To navigate to a scene, call `Actions.{key}`. The function takes an `Object` which gets passed to the Scene as React props. | +| `pop` | `Function` | | Go back to the previous scene by "popping" the current scene off the nav stack | +| `refresh` | `Function` | | "Refresh" the current scene. The function takes an `Object` which gets passed to the Scene as React props. | diff --git a/docs/MIGRATION.md b/docs/MIGRATION.md index 9dad0546a..74169b43f 100644 --- a/docs/MIGRATION.md +++ b/docs/MIGRATION.md @@ -1,13 +1,21 @@ -# Migrating from 2.x +# Migrating from 3.x -## Breaking changes comparing with 2.x version: -- React Native 0.26 is required -- `Router` is root container now and should not be nested. For nested scenes you should use `Scene` element -- `Route` became `Scene`, now unique `key` attribute is required for each scene (it was `name` attribute before) -- Define all your scenes on top-level, not within `Router` as before (see Example) -- No `Schema` element is supported for now (for simplicity), maybe later it could be added -- No ActionSheet support -- Custom scene renderers are used instead of 'custom' types (like 'modal'), so 'modal' scenes are pushed as usual, but custom renderer will render them as popup. No `dismiss`, just usual `pop` to close such popups. -- No old navigator.sceneConfig support (instead the component uses React Native NavigationAnimatedView for better transitions) -- No onPush/onPop/etc handlers because they are not needed now. If navigation state is changed, container will be re-rendered with changed navigationState property, see `Modal` as Example. -- No header/footer properties are supported for Scene currently - you may include them into Scene component. +## Breaking changes (compared to v3): +* `Actions.create` (alternative syntax to define scenes) is not available (for simplicity) - just use `` as top component for your App. You may wrap it with Redux as well. +* No `duration`/`panHandlers` support - you have to implement custom navigator now instead and pass it as ‘navigator’ prop +https://reactnavigation.org/docs/navigators/custom. You could still pass `panHandlers={null}` to disable gestures or `gesturedEnabled={false}` +* No `component` support for scene containers (that contains children `Scene`) - you have to use custom navigator +* No support for partial hiding of tab bar for some tabs because of react navigation bug (react navigation issue): +https://github.com/react-community/react-navigation/issues/1584 +* No possibility to skip animation during reset/replace (react navigation issue): +https://github.com/react-community/react-navigation/issues/1493 +* `Switch` is removed - you may use onEnter/onExit handlers for more flexible logic. +* `getSceneStyle` is removed (no needed in v4, you may pass any values to Router now and they will be inherited by all scenes). +* Custom reducer is supported (`createReducer` prop for Router) but Redux actions now are passed directly from React Navigation (‘Navigation/BACK’, ‘Navigation/NAVIGATE’, etc.) +* Drawer is 'drawer' attribute Scene +* Modal is 'lightbox' attribute for Scene (used for popups, like Error) +* Container scenes (that has children) cannot have `component` (or it will be considered as child!). If you want to customize containers, use react navigation custom navigators and pass it as `navigator` prop. +* No `position` attribute is supported for custom transitions. For vertical transition add `modal` to parent `Scene`. +* No flux 'focus' actions - use onEnter/onExit handlers instead. +* tabBarSelectedItemStyle is not supported. Instead please use React Navigation TabBar params for tabs Scene: `activeTintColor`, `inactiveTintColor`, etc (https://reactnavigation.org/docs/navigators/tab) +* Possible other stuff. diff --git a/docs/API_CONFIGURATION.md b/docs/v3/API_CONFIGURATION.md similarity index 100% rename from docs/API_CONFIGURATION.md rename to docs/v3/API_CONFIGURATION.md diff --git a/docs/DETAILED_EXAMPLE.md b/docs/v3/DETAILED_EXAMPLE.md similarity index 100% rename from docs/DETAILED_EXAMPLE.md rename to docs/v3/DETAILED_EXAMPLE.md diff --git a/docs/v3/MIGRATION.md b/docs/v3/MIGRATION.md new file mode 100644 index 000000000..9dad0546a --- /dev/null +++ b/docs/v3/MIGRATION.md @@ -0,0 +1,13 @@ +# Migrating from 2.x + +## Breaking changes comparing with 2.x version: +- React Native 0.26 is required +- `Router` is root container now and should not be nested. For nested scenes you should use `Scene` element +- `Route` became `Scene`, now unique `key` attribute is required for each scene (it was `name` attribute before) +- Define all your scenes on top-level, not within `Router` as before (see Example) +- No `Schema` element is supported for now (for simplicity), maybe later it could be added +- No ActionSheet support +- Custom scene renderers are used instead of 'custom' types (like 'modal'), so 'modal' scenes are pushed as usual, but custom renderer will render them as popup. No `dismiss`, just usual `pop` to close such popups. +- No old navigator.sceneConfig support (instead the component uses React Native NavigationAnimatedView for better transitions) +- No onPush/onPop/etc handlers because they are not needed now. If navigation state is changed, container will be re-rendered with changed navigationState property, see `Modal` as Example. +- No header/footer properties are supported for Scene currently - you may include them into Scene component. diff --git a/docs/MINI_TUTORIAL.md b/docs/v3/MINI_TUTORIAL.md similarity index 100% rename from docs/MINI_TUTORIAL.md rename to docs/v3/MINI_TUTORIAL.md diff --git a/docs/OTHER_INFO.md b/docs/v3/OTHER_INFO.md similarity index 100% rename from docs/OTHER_INFO.md rename to docs/v3/OTHER_INFO.md diff --git a/docs/REDUX_FLUX.md b/docs/v3/REDUX_FLUX.md similarity index 100% rename from docs/REDUX_FLUX.md rename to docs/v3/REDUX_FLUX.md diff --git a/docs/super_simple.gif b/docs/v3/super_simple.gif similarity index 100% rename from docs/super_simple.gif rename to docs/v3/super_simple.gif