Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Nicer readme #639

Merged
merged 2 commits into from
May 7, 2016
Merged

Nicer readme #639

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b17d21c
better formating of jsx in .md
r0b1n May 5, 2016
19b2ced
Scene properties better formating
r0b1n May 5, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 43 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ npm i react-native-router-flux --save

## Usage
1. In top-level index.js, define your scenes using `Scene` element and pass it to `Router`:
```javascript
```jsx
import {Actions, Scene, Router} from 'react-native-router-flux';

class App extends React.Component {
Expand All @@ -60,7 +60,7 @@ class App extends React.Component {
}
```
Alternatively you could define all your scenes during compile time and use it later within `Router`:
```javascript
```jsx
const scenes = Actions.create(
<Scene key="root">
<Scene key="login" component={Login} title="Login"/>
Expand Down Expand Up @@ -109,51 +109,61 @@ class App extends React.Component {

| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| **Basic** |
| 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. If it is defined for 'container' scene, it will be used as custom container `renderer` |
| type | `string` | 'push' or 'jump' | Defines how the new screen is added to the navigator stack. One of `push`, `jump`, `replace`, `reset`. If parent container is tabbar (tabs=true), jump will be automatically set.
| tabs| `bool` | false | Defines 'TabBar' scene container, so child scenes will be displayed as 'tabs'. If no `component` is defined, built-in `TabBar` is used as renderer. All child scenes are wrapped into own navbar.
| initial | `bool` | false | Set to `true` if this is the initial scene |
| type | `string` | 'push' or 'jump' | Defines how the new screen is added to the navigator stack. One of `push`, `jump`, `replace`, `reset`. If parent container is tabbar (tabs=true), jump will be automatically set.
| clone | `bool` | | Scenes marked with `clone` will be treated as templates and cloned into the current scene's parent when pushed. See example. |
| **Animation** |
| duration | `number` | | optional. acts as a shortcut to writing an `applyAnimation` function with `Animated.timing` for a given duration (in ms). |
| direction | `string` | 'horizontal' | direction of animation horizontal/vertical |
| applyAnimation | `function` | | optional if provided overrides the default spring animation |
| title | `string` | null | The title to be displayed in the navigation bar |
| navBar | `React.Component` | | optional custom NavBar for the scene. Check built-in NavBar of the component for reference |
| hideNavBar | `bool` | false | hides the navigation bar for this scene |
| **Scene styles** |
| sceneStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | { flex: 1 } | optional style override for the Scene's component |
| getSceneStyle | `function` | optional | Optionally override the styles for NavigationCard's Animated.View rendering the scene. |
| **Tabs** |
| tabs| `bool` | false | Defines 'TabBar' scene container, so child scenes will be displayed as 'tabs'. If no `component` is defined, built-in `TabBar` is used as renderer. All child scenes are wrapped into own navbar.
| tabBarStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | optional style override for the Tabs component |
| hideTabBar | `bool` | false | hides tab bar for this scene (if built-in TabBar component is used as parent renderer)|
| **Navigation Bar** |
| hideNavBar | `bool` | false | hides the navigation bar for this scene |
| navigationBarStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | optional style override for the navigation bar |
| titleStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the title element |
| leftTitle | `string` | | optional string to display on the left if the previous route does not provide `renderBackButton` prop. `renderBackButton` > `leftTitle` > <previous route's `title`> |
| renderLeftButton | `function` | | optional closure to render the left title / buttons element |
| navBar | `React.Component` | | optional custom NavBar for the scene. Check built-in NavBar of the component for reference |
| drawerImage | [`Image source`](https://facebook.github.io/react-native/docs/image.html#source) | `'./menu_burger.png'` | Simple way to override the drawerImage in the navBar |
| backButtonImage | [`Image source`](https://facebook.github.io/react-native/docs/image.html#source) | `'./back_chevron.png'` | Simple way to override the back button in the navBar |
| **Navigation Bar: Title** |
| title | `string` | null | The title to be displayed in the navigation bar |
| getTitle | `function` | optional | Optionally closure to return a value of the title based on state |
| renderTitle | `function` | optional | Optionally closure to render the title |
| titleStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the title element |
| **Navigation Bar: Back button** |
| backTitle | `string` | | optional string to display with back button |
| backButtonTextStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the back title element |
| renderBackButton | `function` | | optional closure to render back text or button if this route happens to be the previous route |
| backButtonImage | [`Image source`](https://facebook.github.io/react-native/docs/image.html#source) | `'./back_chevron.png'` | Simple way to override the back button in the navBar |
| backButtonTextStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the back title element |
| **Navigation Bar: Left button** |
| leftTitle | `string` | | optional string to display on the left if the previous route does not provide `renderBackButton` prop. `renderBackButton` > `leftTitle` > <previous route's `title`> |
| renderLeftButton | `function` | | optional closure to render the left title / buttons element |
| onLeft | `function` | | function will be called when left navBar button is pressed |
| leftButtonImage | [`Image source`](https://facebook.github.io/react-native/docs/image.html#source) | | Image for left button |
| leftButtonIconStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | Image style for left button |
| leftButtonStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | optional style override for the container of left title / buttons |
| leftButtonTextStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the left title element |
| onLeft | `function` | | function will be called when left navBar button is pressed |
| **Navigation Bar: Right button** |
| rightTitle | `string` | | optional string to display on the right. `onRight` must be provided for this to appear. |
| onRight | `function` | | function will be called when right navBar button is pressed |
| renderRightButton | `function` | | optional closure to render the right title / buttons element |
| rightButtonStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | optional style override for the container of right title / buttons |
| rightButtonTextStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the right title element |
| onRight | `function` | | function will be called when right navBar button is pressed |
| rightButtonImage | [`Image source`](https://facebook.github.io/react-native/docs/image.html#source) | | Image for right button |
| rightButtonIconStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | Image style for right button |
| clone | `bool` | | Scenes marked with `clone` will be treated as templates and cloned into the current scene's parent when pushed. See example. |
| tabBarStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | optional style override for the Tabs component |
| sceneStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | { flex: 1 } | optional style override for the Scene's component |
| other props | | | all properties that will be passed to your component instance |
| getSceneStyle | `function` | optional | Optionally override the styles for NavigationCard's Animated.View rendering the scene. |
| getTitle | `function` | optional | Optionally closure to return a value of the title based on state
| renderTitle | `function` | optional | Optionally closure to render the title
| rightButtonStyle | [`View style`](https://facebook.github.io/react-native/docs/view.html#style) | | optional style override for the container of right title / buttons |
| rightButtonTextStyle | [`Text style`](https://facebook.github.io/react-native/docs/text.html#style) | | optional style override for the right title element |
| **...other props** | | | all properties that will be passed to your component instance |


## Example
![launch](https://cloud.githubusercontent.com/assets/1321329/11692367/7337cfe2-9e9f-11e5-8515-e8b7a9f230ec.gif)

```javascript
```jsx
import React, {AppRegistry, Navigator, StyleSheet, Text, View} from 'react-native'
import Launch from './components/Launch'
import Register from './components/Register'
Expand Down Expand Up @@ -217,7 +227,7 @@ export default class Example extends React.Component {

components/Launch.js (initial screen)

```javascript
```jsx
import React, {View, Text, StyleSheet, TouchableHighlight} from 'react-native'
import Button from 'react-native-button'
import {Actions} from 'react-native-router-flux'
Expand Down Expand Up @@ -310,7 +320,7 @@ export default combineReducers({
Create your store, wrap your routes with the redux `Provider` component and connect your Router


```js
```jsx
// app.js

import { Router } from 'react-native-router-flux';
Expand Down Expand Up @@ -348,7 +358,7 @@ export default App;

Now you can access the current scene from any connected component.

```js
```jsx
// components/MyComponent.js
import React, { PropTypes, Text } from 'react-native';
import { connect } from 'react-redux';
Expand Down Expand Up @@ -380,7 +390,7 @@ Your scene `component` class could implement _static_ renderNavigationBar(props)
New feature for 3.x release is custom scene renderer that should be used together with tabs={true} property. It allows to select `tab` scene to show depending from app state.
It could be useful for authentication, restricted scenes, etc. Usually you should wrap `Switch` with redux `connect` to pass application state to it:
Following example chooses scene depending from sessionID using Redux:
```javascript
```jsx
<Scene key="root" component={connect(state=>({profile:state.profile}))(Switch)} tabs={true}
selector={props=>props.profile.sessionID ? "main" : "signUp"}>
<Scene key="signUp" component={SignUp}/>
Expand All @@ -389,17 +399,17 @@ Following example chooses scene depending from sessionID using Redux:
```

## Split your scenes to smaller parts if needed
Scenes concept is similar to iOS storyboard where you describe all your app screens in one place. However for some large apps, you may want to split it, like iOS app could have several iOS storyboards for different areas of the app.
Scenes concept is similar to iOS storyboard where you describe all your app screens in one place. However for some large apps, you may want to split it, like iOS app could have several iOS storyboards for different areas of the app.
Luckily, you could easy split Scenes using NodeJS built-in require calls:
```
```jsx
<Router>
{require("./scenesForTabBar")}
{require("./scenesForAnotherPart")}
</Router>
```

scenesForTabBar.js:
```
```jsx
import React from 'react-native';
import {Scene} from 'react-native-router-flux';

Expand All @@ -411,7 +421,7 @@ module.exports = <Scene key="tabbar" tabs={true}>
## Drawer (side menu) integration
Example of Drawer custom renderer based on react-native-drawer. Note that the build-in NavBar component supports toggling of drawer. The Drawer implementation just needs to have a function: toggle();

```javascript
```jsx
import React from 'react-native';
import Drawer from 'react-native-drawer';
import SideMenu from './SideMenu';
Expand Down Expand Up @@ -450,7 +460,7 @@ export default class extends Component {
You could create 'sub-scene' actions by putting them as children for needed 'base' scene without `component` prop and call such action anywhere - 'base' Scene will be updated accordingly.
Example for 'My Account' screen with edit possibility (`MyAccount` component should call `Actions.editAccount()` to enable edit mode and process `save`, `editMode` properties accordingly - display edit controls, save data, etc.):

```
```jsx
<Scene key="myAccount" component={MyAccount} title="My Account">
<Scene key="viewAccount" />
<Scene key="editAccount" editMode rightTitle="Save" onRight={()=>Actions.saveAccount()} leftTitle="Cancel" onLeft={()=>Actions.viewAccount()} />
Expand Down