Skip to content
This repository has been archived by the owner on Nov 23, 2018. It is now read-only.

pressly/scene-router

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

scene-Router (v2)

A complete scene routing library written in pure JavaScript for React Native. It supports iOS and Android. The api is so easy that you just have to learn only 2 simple things, scene decorator and Router component.

Description

We, at Pressly, using react-native and our app consists of large number of scenes. We wanted somthing super simple, it went through a lot of internal reversion, until we decided to open source it.

scene-router supports the following out of box:

  • url like path, which can contains params and query strings. e.g. '/user/:id'
  • passing custom props to target scene
  • storeless, you can connect to redux or mobx stores
  • reset stack of scenes
  • animating scene from all 4 direction
  • gesture enable
  • configure scene settings at scene difinition and route time
  • all animation are being configure to optimize useNativeDriver feature

Installation

npm install scene-router

Prerequisite

we recommended to use decorator. It makes the code a lot easier to maintain. If you don't want to use it, that's ok too.

in order to enable decorator in your react-native project follow the 3 steps below,

1: install babel-plugin-transform-decorators-legacy using yarn or npm and 2: configure your .babelrc file as follows

{
  "extends": "react-native/packager/react-packager/rn-babelrc.json",
  "plugins": ["transform-decorators-legacy"]
}

3: if you are using flowtype, make sure to add esproposal.decorators=ignore under [options] tags inside .flowconfig file

Usage

There are 2 things you should learn about scene-router in oreder to start using it in your project

scene decorator

scene is a decorator feature which register your component as a scene. here's an example

import React, { Component } from 'react'
import { scene } from 'scene-router'

@scene({
  path: '/scene1'
})
class MyFirstScene extends Component {
  render() {
    ...
  }
}

a little bit of explaination, what we did was adding scene as a decorator on top of our first component MyFirstScene. We were passing path. This is our path to this scene. so every time, Router wants to render this scene, all it needs a path url. scene-router will handle all coordinations and animations behind the scene.

you might ask, so what if I want to show my scene from top to bottom. As I said, scene decorator accepts many arguments. except path the rest of the arguments are optional. here's the list of all options

option type required default value route time change Description
path String Yes N/A No register a scene with this unique path
side Side No Side.FromRight Yes how the scene will animated, from which side
threshold Number No 30 Yes how far from side you have to swip to make the gesture working
gesture Boolean No true Yes enable or disable gesture
reset Boolean No false Yes all scenes prior to this scene will be destroyed
backgroundColor String No white Yes the back color of each scene

ther are 5 differant sides you can choose from

name description
FromLeft Animate the Scene From Left to Right
FromRight Animate the Scene From Right to Left
FromTop Animate the Scene From Top to Bottom
FromBottom Animate the Scene From Bottom to Top
Static No animation

There is one little thing, every component which decorated with scene will have a method called, updateSceneStatus(status: Status). This method will be called based on whether your scene is Active, InActive, MightActive or MightInActive. In other words, We are adding 4 more lifecycles to React. remember this is just a utility to help you!

import React, { Component } from 'react'
import { scene, Status } from 'scene-router'

@scene({
  path: '/scene1'
})
class MyFirstScene extends Component {
  updateSceneStatus(status) {
    switch(status) {
      case Status.Active:
        break
      case Status.InActive:
        break
      case Status.MightActive:
        break
      case Status.MightInActive:
        break
    }
  }

  render() {
    ...
  }
}

here's a little bit of description:

value Description
Active when the animation is done and scene is visible
InActive when a scene is already covered or gone
MightInActive during dragging a scene. the current scene will get this value
MightActive the previous and covered scene by current during dragging with get this value

Router component

the second thing to learn is Router. This is your entry point of your app. It has only 3 props, area, action and config.

  • area is a string which defines an area with a name. if you plan to use tabs, each individual tab must have a unique name, that name can be passed to area
  • action is a string which accepts either goto or goback. if you pass goback, the 3rd prop, config, will be ignored.
  • config is defining which path you want to go and if you want to override any scene configuration.

here's an example of Router

import React, { Component } from 'react'
import { View, Text } from 'react-native'
import { scene, Router } from 'scene-router'

@scene({
  path: '/scenes/:id'
})
class Scenes extends Component {
  render() {
    const { route: { params } } = this.props

    return (
      <View style={{ flex: 1}}>
        <Text>{params.id}</Text>
      </View>
    )
  }
}

class App extends Component {
  constructor(props: any, context: any) {
    super(props, context)

    this.state = {
      area: "default",
      action: 'goto',
      config: {
        path: '/scenes/1'
      }
    }
  }

  render() {
    const { area, action, config } = this.state

    return (
      <Router
        area={area}
        action={action}
        config={config} />
    )
  }
}

NOTE Router component also accepts one Componet as a child, This Component is being displayed and renderd first before the first route is triggered. this is a good place to put your splash screen.

Cheers.