Narcoleptic's Patch Mangler

    emiya-ionic2-router
    TypeScript icon, indicating that this package has built-in type declarations

    1.4.6 • Public • Published

    Emiya Ionic2 Router

    How to install

    npm install --save emiya-ionic2-router
    cordova plugin add cordova-plugin-app-version (optional but strongly recommanded)
    

    Features

    • config the route in one place
    • support url route just like what ionic1 did
    • support id route
    • support onpopstate event in browser(pop by clicking back button)
    • support android hardware back button hook to customize app exit behavior
    • intelligently route between (login/non-login/login-required/normal/guide/home) pages
    • provide push/pop event,support event prevention
    • support pop behavior customization for each page
    • manage page access based on Token
    • support app backgroud auto kill and auto restart

    >>>demo here<<<

    Usage

    route configuration
    //import all the componets you want to route 
    import {TabsPage} from '../pages/TabsPage/TabsPage';
    import {PwdLoginPage} from '../pages/PwdLoginPage/PwdLoginPage';
    import {MyFavourPage} from '../pages/MyPraisePage/MyFavourPage';
    import {AgreementPage} from '../pages/AgreementPage/AgreementPage';
    import {WelCome} from '../pages/WelCome/WelCome';
    import {HomePage} from '../pages/HomePage/HomePage';
    import {FindPage} from '../pages/FindPage/FindPage';
    
    export const Routes = {
       //homepage example
      'Tabs': {//identity for page
        page: TabsPage, //component of this page
        params: {index:1}, //optional,default page params(see ionic2/NavParams for more)
        options: {duration:0},  //optional,nav options(see ionic2 doc/navcontroller for more)
        done: function(ev){do something..},  //optional,callback after push complete
        root: true,  //is it homepage?true or false,must be unique,default is false
        url: '/tabs',  //url schema for this page(must be unique,support restful style,like /tabs/:uuid/:name),leave it null  equal to set url to "/{{pageIdentity}}"
        enable: true  //is this page enabled?true or false,default is true
        title: 'Homepage', //optional,title for this page,default is "/{{pageIdentity}}"(for now is just a descrition)
      },
      
      //login page example
      'PwdLogin': {
        page: PwdLoginPage,
        reverse: true, //optional,true or false(default),use together with option [tokens]
        tokens: ['token', 'uuid'],  //when option [reverse] = false,to access this page we need 2 tokens which call 'token' & 'uuid',the other way,we can only access the page when these 2 tokens inexist. 
        tokensLocation: ['local', 'local'], //optional,local(default)/session,the location of the token
        next: {//optional,this only works when option [reverse]=true and [tokens] has been set.Router will try to redirect to the page you config here when : ((try to access the page without meet the token condition)||(login success))&&((the router can not determine the proper next target page)||(next.force==true)) 
          name: 'TabsPage', //next page's id
          params: null,
          options: null,
          done: null,
          force:false  //optional,true or false(default),set to true tells the Router page config here has a higher prior then the target page which determine by router
        },
        url: '/PwdLoginPage',
        title: 'Password Login'
      },
      
      //logout page example
      'Logout': {
        page: LogoutPage,
        tokens: ['token', 'uuid'],  
        tokensLocation: ['local', 'local'], 
        popWhenTokenInvalid:true,  //when token become invalid,router will try to pop from this page
        url: '/LogoutPage',
        title: 'Logout'
      },
    
      //login-required page example
      'MyFavour': {
        page: MyFavourPage,
        params: null,
        options: null,
        done: null,
        tokens: ['token', 'uuid'],
        redirect: { //Router will redirect to the page you config here when you try to access the page without meet the token condition
          name: 'PwdLoginPage',
          params: null,
          options: null,
          done: null
        },
        url: '/myFavour/:userid/:catagory',
        title: 'MyFavour'
      },
    
       //normal page example
      'Agreement': {
        page: AgreementPage,
        url: '/agreementPage',
        title: 'user_agreement',
        pop: { //optional,when user try to pop from this page but there is no previous page in the navStack,router will redirect(fake pop animation) to page config here
          name: 'TabsPage',
          params: null,
          options: null,
          done: null,
          force:false //optional,true or false(default),set to true means always pop to the page config here 
        }
      },
    
    
      //guide page example
      'WelCome': {
        page: WelComePage,
        url: '/weleome',
        pop: {
          name: 'TabsPage',
          params: null,
          options: null,
          done: null
        },
        guide: { //mean it is a guide page
          always: false, //optional,true or false(default).when true,guide page will show each time you open app,when false,it only show when app first installed or updated
          duration: 6000 //optional,will leave guide page automatically after 6000 ms,default is never leave automatically
        },
        title: 'welcome',
      },
    
    
      //minimal config example
      'homeIndexTab': {
        page: HomePage,
      }
    
    }
    

    load Router Globally

    import {Router} from 'emiya-ionic2-router'
    
    @NgModule({
     providers: [Router]
    })
    

    load configuration

    import {Router} from 'emiya-ionic2-router';
    import {Routes} from 'Routes';
    
    @Component({
      template: `<ion-nav></ion-nav>`
    })
    export class MyApp {
    
    constructor(platform: Platform, router: Router,) {
        let result=router.load(Routes); //load config
        let result=router.load(Routes,'Hello World',10000); //load route config and appversion info
        result.then((ev)=>{}).catch((err)=>{}) //it's a promise which tell you whether the first page is being pushed successfully or not
        platform.ready().then(() => {
          StatusBar.styleDefault();
          Splashscreen.hide();
        });
      }
    }
    
    Important: router.load() will load home/first page automatically,so DO NOT set it in any other place!

    how to push&pop

    import {Router} from 'emiya-ionic2-router';
    import {MyFavour} from '../pages/MyFavourPage/MyFavourPage';
    
    export class TabsPage {
    
    constructor(router: Router) {
        //push via id
        router.push('MyFavour',{index:2,userid:'user001',catagory:'cata002'},{duration:500},(hasCompleted, isAsync, enteringName, leavingName, direction)=>{//stuff when completed})
        
        //push via url
        router.push('/myFavour/user001/cata002',{index:2},{duration:500})
        .then((hasCompleted, isAsync, enteringName, leavingName, direction)=>{})
        .catch((hasCompleted, isAsync, enteringName, leavingName, direction)=>{})
        
        //push via component
        router.push(MyFavourPage,{index:2,userid:'user001',catagory:'cata002'},{duration:500})
        
        //pop
        router.pop().then((hasCompleted, isAsync, enteringName, leavingName, direction)=>{})
        .catch((hasCompleted, isAsync, enteringName, leavingName, direction)=>{})
        
        router.pop({duration:0},(hasCompleted, isAsync, enteringName, leavingName, direction)=>{//stuff when completed})
        
        router.pop({duration:0})
        
        router.popSafe() //pop will fail when there is another page transition happening,it's useful for user-click pop event to avoid some transition bugs
        
      }
    }
    

    How to set and delete token

    import {Router} from 'emiya-angular2-token';
    
    export class TabsPage {
    
    constructor() {
        //set tokon
        Token.set('uuid','fasfasjfasjlk9312jkkfasjfaskl')
        Token.set('token','fasfasjfasjlk9312jkkfasjfaskl')
        //delete token
        Token.delete('uuid')
        Token.delete('token')
        //check if token exists
        Token.has('uuid')   //true or false
        Token.has('token')
      }
    }
    
    more can be found emiya-angular2-token

    route event listen&intercept example

    import {Router} from 'emiya-ionic2-router';
    import {Event} from 'emiya-angular2-event';
    
    export class MyApp {
    
    constructor(router: Router) {
        //push event
        let pushListenr=Event.subscribe('push',(ev,data)=>{})
        //pop event
        Event.subscribe('pop',(ev,data)=>{})
        
        //app exit event
        Event.subscribe('appWillExit',(ev,data)=>{})
        
        //unlisten to event
        pushListenr.unsubscribe()
      }
    }
    
    event parameters
    • ev
    preventDefault():prevent the operation
    stopPropagation():stop the event to propagate
    defaultPrevented:default is false,preventDefault() will set it to true
    propagationPrevented:default is false,stopPropagation() will set it to true
    
    • data
    fromPage:current page
    toPage:the page will transit to
    callParams:the original params of push&pop operation
    callerName:the name of method which trigger this event
    instance:the method which trigger this event
    canPush:if the push operation is permitted by router
    canGoBack:if the pop operation is permitted by router
    

    customize app exit behavior

    import {Router} from 'emiya-ionic2-router';
    
    export class MyApp {
    
    constructor(router: Router) {
        router.setExitHook(()=>{
         return true //true will exit app,otherwise prevent it
        },101 /*optional,hook prior,default is 101,only work in android runtime*/)
      }
    }
    

    global status code

    • -200 operation is prevented

    • -210 operation is not permitted because of another page transition

    • -220 app exit is prevented

    • -230 next()can not found a proper next page

    • -240 try to push a page which is disabled

    • -250 can not found page config

    • -260 can not found page config

    • -270 can not found redirect page config

    • -280 can not found redirect page config

    • -300 app exited

    • -310 attempt to enter a token inrequired page with token alreay existed

    • -320 more than one root page found

    • -330 root page not found

    • -400 fail to push first page because it's overrided by another transition

    • false throw by ionic2&angular2 stock api

    • true success

    Api Referrences(to be continued..)

    setBackgroundTimeout(number?) //unit is ms,app will kill itself after run in background for {{number}} ms,default value is -1(never kill itself)
    
    setResumeTimeout(number?) //unit is ms,app will reload and navigate to homepage when it stay in background for over {{number}} ms and resume to frontend,default value is -1(never reload)
    

    Install

    npm i emiya-ionic2-router

    DownloadsWeekly Downloads

    3

    Version

    1.4.6

    License

    MIT

    Last publish

    Collaborators

    • emiyalee