Skip to content

Commit

Permalink
New Documentation Structure (#673)
Browse files Browse the repository at this point in the history 
* new documentation, first file

* Update README.md

* Create getting_started.md

* Update getting_started.md

* new gif for super simple example

* Update getting_started.md

* smaller gif

* fixed gif

* Update getting_started.md

* renamed tutorial

* update docs

* Update mini_tutorial.md

* updated Docs

* update docs

* improved docs"

* Update mini_tutorial.md

* Update README.md

* Update README.md

* Update README.md

* added features list

* Update README.md

* Update README.md

* added api config

* changed headings

* Update api_configuration.md

* added example file

* split into files

* improved docs

* improved docs

* Update README.md

* Update other_info.md

* restore old readme

* uppercase file name

* new uppercase filenames

* Delete redux_flux.md

* Delete other_info.md

* Delete mini_tutorial.md

* Delete migration.md

* Delete detailed_example.md

* Delete changelog.md

* Delete api_configuration.md
  • Loading branch information
@adrianmcli @aksonov
adrianmcli authored and aksonov committed May 14, 2016
1 parent 900ba42 commit 092ef05
Show file tree
Hide file tree
Showing 10 changed files with 678 additions and 1 deletion.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -475,4 +475,4 @@ Sure it could be done using Redux, however it will require more coding and progr
+ GuavaPass.com ([iOS](https://itunes.apple.com/en/app/guavapass-one-pass-fitness/id1050491044?l=en&mt=8), Android) - offers convenient access to top classes at boutique fitness studios across Asia.

## Support
Thanks to all who submitted PRs to 2.x release. If you like the component and want to support it, feel free to donate any amount or help with issues.
Thanks to all who submitted PRs to 2.x release. If you like the component and want to support it, feel free to donate any amount or help with issues.
100 changes: 100 additions & 0 deletions docs/API_CONFIGURATION.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# API and Configuration

## Available imports
- `Router`
- `Scene`
- `Modal`
- `TabBar`
- `getInitialState`
- `Reducer`
- `DefaultRenderer`
- `Switch`
- `Actions`
- `NavBar`

## Router:
| Property | Type | Default | Description |
|---------------|----------|--------------|----------------------------------------------------------------|
| reducer | `function` | | optional user-defined reducer for scenes, you may want to use it to intercept all actions and put your custom logic |
| createReducer | `function` | | function that returns a reducer function for {initialState, scenes} param, you may wrap Reducer(param) with your custom reducer, check Flux usage section below|
| other props | | | all properties that will be passed to all your scenes |
| children | | required (if no scenes property passed)| Scene root element |
| scenes | `object` | optional | scenes for Router created with Actions.create. This will allow to create all actions BEFORE React processing. If you don't need it you may pass Scene root element as children |
| getSceneStyle | `function` | optional | Optionally override the styles for NavigationCard's Animated.View rendering the scene. |

## 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. If it is defined for 'container' scene, it will be used as custom container `renderer` |
| 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
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| 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 |

### Scene styles
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| 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
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| 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
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| 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 |
| 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 |

#### Navigation Bar: Title
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| 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
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| backTitle | `string` | | optional string to display with back button |
| 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
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| 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 |

#### Navigation Bar: Right button
| Property | Type | Default | Description |
|-----------|--------|---------|--------------------------------------------|
| rightTitle | `string` | | optional string to display on the right. `onRight` must be provided for this to appear. |
| renderRightButton | `function` | | optional closure to render the right title / buttons 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 |
| 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 |
8 changes: 8 additions & 0 deletions docs/CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# Change log
- 3.22.20 fix more ESLint errors, fix passing leftButtonStyle property for back button
- 3.22.18 fix some ESLint errors and ignore pop for root scene
- 3.22.17 allow jump & push together - now you could call Actions.tab2_2() (`tab2_2` is next scene after `tab2`) even if `tab2` is not active
- 3.22.16 simplified syntax for sub-states
- 3.22.15 introduces support for different states inside the same screen.
- 3.22.10 simplifies customization of own NavBar. From now you could import built-in NavBar from the component and customize it. You could set it globally to all scenes by setting `navBar` property for `Router` component.
For all other scenes you may pass rightButton, leftButton for custom buttons or rightTitle & onRight, leftTitle & onLeft for text buttons.
98 changes: 98 additions & 0 deletions docs/DETAILED_EXAMPLE.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
## Detailed Example
![launch](https://cloud.githubusercontent.com/assets/1321329/11692367/7337cfe2-9e9f-11e5-8515-e8b7a9f230ec.gif)

```jsx
import React, {AppRegistry, Navigator, StyleSheet, Text, View} from 'react-native'
import Launch from './components/Launch'
import Register from './components/Register'
import Login from './components/Login'
import Login2 from './components/Login2'
import {Scene, Router, TabBar, Modal, Schema, Actions, Reducer} from 'react-native-router-flux'
import Error from './components/Error'
import Home from './components/Home'
import TabView from './components/TabView'

class TabIcon extends React.Component {
render(){
return (
<Text style={{color: this.props.selected ? 'red' :'black'}}>{this.props.title}</Text>
);
}
}

const reducerCreate = params=>{
const defaultReducer = Reducer(params);
return (state, action)=>{
console.log("ACTION:", action);
return defaultReducer(state, action);
}
};

export default class Example extends React.Component {
render() {
return <Router createReducer={reducerCreate} sceneStyle={{backgroundColor:'#F7F7F7'}}>
<Scene key="modal" component={Modal} >
<Scene key="root" hideNavBar={true}>
<Scene key="register" component={Register} title="Register"/>
<Scene key="register2" component={Register} title="Register2" duration={1}/>
<Scene key="home" component={Home} title="Replace" type="replace"/>
<Scene key="launch" component={Launch} title="Launch" initial={true} style={{flex:1, backgroundColor:'transparent'}}/>
<Scene key="login" direction="vertical">
<Scene key="loginModal" component={Login} schema="modal" title="Login"/>
<Scene key="loginModal2" hideNavBar={true} component={Login2} title="Login2"/>
</Scene>
<Scene key="tabbar" tabs={true} >
<Scene key="tab1" title="Tab #1" icon={TabIcon} navigationBarStyle={{backgroundColor:'red'}} titleStyle={{color:'white'}}>
<Scene key="tab1_1" component={TabView} title="Tab #1_1" onRight={()=>alert("Right button")} rightTitle="Right" />
<Scene key="tab1_2" component={TabView} title="Tab #1_2" titleStyle={{color:'black'}}/>
</Scene>
<Scene key="tab2" initial={true} title="Tab #2" icon={TabIcon}>
<Scene key="tab2_1" component={TabView} title="Tab #2_1" onLeft={()=>alert("Left button!")} leftTitle="Left"/>
<Scene key="tab2_2" component={TabView} title="Tab #2_2"/>
</Scene>
<Scene key="tab3" component={TabView} title="Tab #3" hideTabBar={true} icon={TabIcon}/>
<Scene key="tab4" component={TabView} title="Tab #4" hideNavBar={true} icon={TabIcon}/>
<Scene key="tab5" component={TabView} title="Tab #5" icon={TabIcon} />
</Scene>
</Scene>
<Scene key="error" component={Error}/>
</Scene>
</Router>;
}
}

```

components/Launch.js (initial screen)

```jsx
import React, {View, Text, StyleSheet, TouchableHighlight} from 'react-native'
import Button from 'react-native-button'
import {Actions} from 'react-native-router-flux'

class Launch extends React.Component {
render(){
return (
<View style={styles.container}>
<Text>Launch page</Text>
<Button onPress={()=>Actions.login({data:"Custom data", title:'Custom title' })}>Go to Login page</Button>
<Button onPress={Actions.register}>Go to Register page</Button>
<Button onPress={Actions.register2}>Go to Register page without animation</Button>
<Button onPress={Actions.error('error message')}>Show error popup</Button>
<Button onPress={Actions.tabbar}>Go to TabBar page</Button>
</View>
);
}
}

var styles = StyleSheet.create({
container: {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: 'transparent',
}
});

module.exports = Launch;
```
13 changes: 13 additions & 0 deletions docs/MIGRATION.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
# Migrating from 2.x

## Breaking changes comparing with 2.x version:
- React Native 0.22 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.
125 changes: 125 additions & 0 deletions docs/MINI_TUTORIAL.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,125 @@
# Mini-Tutorial

![super_simple.gif](super_simple.gif)

In this super simple example, we will just have three files:

1. Your root index file: `index.js`
2. The first page that is loaded automatically: `PageOne.js`
3. A second page you can navigate to: `PageTwo.js`

### index.js
```jsx
import React, { Component } from 'react';
import { Router, Scene } from 'react-native-router-flux';

import PageOne from './PageOne';
import PageTwo from './PageTwo';

export default class App extends Component {
render() {
return (
<Router>
<Scene key="root">
<Scene key="pageOne" component={PageOne} title="PageOne" initial={true} />
<Scene key="pageTwo" component={PageTwo} title="PageTwo" />
</Scene>
</Router>
)
}
}
```

In `react-native-router-flux`, each route (or page) is called a `<Scene>`. Conventionally, your Scenes should be wrapped inside a root Scene before being finally wrapped inside a `<Router>` component that is returned in the `render()` function.

At the very minimum, each `<Scene>` component should have the following props:

- **key**: A unique string that can be used to refer to the particular scene.
- **component**: The component to be rendered for that `Scene` or page.
- **title**: The string to be displayed in the nav bar at the top of the screen.

Note that the first scene we wish to load has the prop `initial={true}` to indicate that it's the scene that should be initially rendered.

## From Page to Page

### PageOne.js
```jsx
import React, { Component } from 'react';
import { View, Text } from 'react-native';
import { Actions } from 'react-native-router-flux';

export default class PageOne extends Component {
render() {
return (
<View style={{margin: 128}}>
<Text onPress={Actions.pageTwo}>This is PageOne!</Text>
</View>
)
}
}
```

To navigate from one route to another, an `Action` must be called. This takes the form of:

```
Actions.SCENE_KEY(PARAMS)
```

Where `SCENE_KEY` must match the `key` prop defined in one of the Scenes of the `Router` component in the root file. And `PARAMS` refers to a javascript object that will be passed into the resulting scene as props (more on this later).

Since the PageTwo component has the key of `pageTwo`, all we need to do is to pass in the function `Actions.pageTwo` into the `<Text>` component so that it executes the page transition when the text is pressed.

## Passing Information

Now let's try to extend our example so that we can pass data from `PageOne` to `PageTwo`.

In `PageOne.js`, instead of simply passing in `Actions.pageTwo`, we can replace it with `Actions.pageTwo({text: 'Hello World!'})`. In this case, we need to wrap the Action call inside a function to prevent it from executing when this component is rendered. As a result, the render function inside `PageOne.js` should look like this:

```jsx
render() {
const goToPageTwo = () => Actions.pageTwo({text: 'Hello World!'});
return (
<View style={{margin: 128}}>
<Text onPress={goToPageTwo}>This is PageOne!</Text>
</View>
)
}
```

And in `PageTwo.js`, we can use the data being passed in by adding an additional `<Text>` component below the existing one like so:

```jsx
render() {
return (
<View style={{margin: 128}}>
<Text>This is PageTwo!</Text>
<Text>{this.props.text}</Text>
</View>
)
}
```

Now, if we navigate to the PageTwo Scene as before, we should see:

```
This is PageTwo!
Hello World!
```

## Going Forward (or backwards?)

That pretty much concludes this mini-tutorial, we've covered most of the basics here. There are a lot of things you can do to customize `react-native-router-flux`, this is only the beginning.

For example, you may want to programmatically go back to the previous Scene. The included navbar already allows you to do this by pressing on the arrow icon at the upper left corner. But you can also call this function at any point in your app for the same effect:

```js
Actions.pop()
```

And should you ever want to refresh the same Scene with new props, you can use:

```js
Actions.refresh(PARAMS)
```

Don't be afraid to explore the docs, you'll be surprised at how much you're able to customize with `react-native-router-flux`!
Loading

0 comments on commit 092ef05

Please sign in to comment.