emiya-ionic2-router
v1.4.6
Published
An ionic2 based router which include url route and intelligent login&route management and many other features..
Downloads
20
Maintainers
Keywords
Readme
#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
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)