> 微量的api在0.2版本有所修改
## 0.2.x的改进
- 增加了一个[askForPermission](#permission), 来帮助我们阻止一次跳转(比如在离开时， 加个通知用户是否要保存）
- 现在你可以在`enter`, `leave` 以及新增加的 `canLeave`, `canEnter` 方法中来返回Promise对象， 这对于一些异步的跳转非常有帮助
- 事件现在支持[命名空间](#event)了
- 移除了[state.async] 方法, 如果你的运行环境不支持Promise, 你仍然可以使用 `option.async` 来获得一样的效果
# StateMan 文档
为了更好的理解这不算多的API, 在文档开始前，假设我们已经配置了这样一段路由脚本.
```js
var config = {
enter: function(option){
console.log("enter: " + this.name + "; param: " + JSON.stringify(option.param))
},
leave: function(option){
console.log("leave: " + this.name + "; param: " + JSON.stringify(option.param))
},
update: function(option){
console.log("update: " + this.name + "; param: " + JSON.stringify(option.param))
},
}
function cfg(o){
o.enter = o.enter || config.enter
o.leave = o.leave || config.leave
o.update = o.update || config.update
return o;
}
var stateman = new StateMan();
stateman.state({
"app": config,
"app.contact": config,
"app.contact.detail": cfg({url: ":id(\\d+)"}),
"app.contact.detail.setting": config,
"app.contact.message": config,
"app.user": cfg({
enter: function( option ){
var done = option.async();
console.log(this.name + "is pending, 1s later to enter next state")
setTimeout(done, 1000)
},
leave: function( option ){
var done = option.async();
console.log(this.name + "is pending, 1s later to leave out")
setTimeout(done, 1000)
}
}),
"app.user.list": cfg({url: ""})
}).on("notfound", function(){
this.go('app') // if not found
}).start();
```
对象`config`用来输出navgating的相关信息, 你不需要立刻理解这个例子, 稍后文档会慢慢告诉你一切.
你可以直接通过【[在线DEMO](./example/api.html)】 访问到这个例子, 有时候试着在console中测试API可以帮助你更好的理解它们
## API
### new StateMan
__Usage__
`new StateMan(option)`
__Arguments__
|Param|Type|Detail|
|--|--|--|
|option.strict|Boolean| Default: false . 是否只有叶子节点可以被访问到 |
|option.title| String| 设置文档标题， 见 [config.title](#title)|
__Return__
[Stateman] : StateMan的实例
__Example__
```javascript
var StateMan = require("stateman");
var stateman = new StateMan({
title: "Application",
strict: true
});
// or...
var stateman = StateMan();
```
如果strict为true, 会导致上例的 `app.contact`等状态不能被直接定位(即无法成为stateman.current了). 只有像`app.contact.message` 这样的叶子节点可以被直接访问.
### stateman.state
__Usage__
`stateman.state(stateName[, config])`
stateman.state 用来增加/更新一个state, 或获取指定的state对象(假如 config 参数没有指定的话)
__Arguments__
|Param|Type|Detail|
|--|--|--|
|stateName|String Object| state名称，假如传入了一个对象，将成为一个多重设置|
|config(optional)|Function Object| 如果config没有指定，将会返回指定的state, 假如传入的是一个函数，则相当于传入了`config.enter`, 如果指定的state已经存在，原设置会被覆盖 |
__Return__ :
StateMan or State (if config is not passed)
__Example__
```js
stateman
.state("app", {
enter: function(){
console.log("enter the state: app")
},
leave: function(){
console.log("leave the state: app")
}
})
// is equals to {enter: config}
.state("app.contact", function(){
console.log("enter the app.contact state")
})
// pass in a Object for multiple operation
stateman.state({
"demo.detail": function(){
console.log("enter the demo.detail state")
},
"demo.list": {
enter: function(){}
leave: function(){}
}
})
```
诚如你所见，我们并不需要在定义`demo.detail`之前定义`demo`, stateman会帮你创建中间state
如果config参数没有传入，则会返回对应的state对象
```js
// return the demo.list state
var state = stateman.state('demo.list');
```
### > 关于`config`
所有config中的属性都会成为对应state的实例属性，但在这里, 需要对一些特殊的属性做说明
#### lifecycle related
这里有五个生命周期相关的方法可供你用来控制 路由的逻辑, 它们都是可选择实现的 , 查看[生命周期](#lifecycle)了解更多
* __config.enter(option)__: 一个函数，当状态被__进入时__会被调用
* __config.leave(option)__: 一个函数，当状态被__离开时__会被调用
* __config.update(option)__: 一个函数，当状态__更新时__会被调用, 更新的意思是，路径有变化，但是此状态仍未被退出.
* __config.canEnter(option)__: 请求是否可进入
* __config.canLeave(option)__: 请求是否可退出
#### config.url:
`url` 属性用来配置state(非全路径)的url片段
每个state对应的捕获url是所有在到此状态路径上的state的结合. 比如`app.contact.detail` 是 `app`,`app.contact` 和`app.contact.detail`的路径结合
__Example__
```js
state.state("app", {})
.state("app.contact", "users")
.state("app.contact.detail", "/:id")
```
`app.contact.detail`的完整捕获路径就是`/app/users/:id`. 当然，如你所见, 我们可以在url中定义我们的[路径参数](#param)
__ 绝对路径__
如果你不需要父级的url定义，你可以使用`^`符号来使当前状态的url
```js
state.state("app.contact.detail", "^/detail/:id");
state.state("app.contact.detail.message", "message");
```
这样`app.contact.detail`的路径会直接变成 `/detail/:id`，子状态会被影响到也变为`/detail/:id/message`
__空url__: 放弃当前这级的路径配置
如果你传入`""`, 你会放弃当前url配置, 这样你的捕获路径会与父状态一致(不过匹配优先级更高)
#### config.title
一旦跳转结束， 我们可以控制标签栏的title值(当然 你可以在enter, update, leave中来更精确的手动使用document.title来设置)
__Argument__
- config.title [String or Function]: 如果是函数，document会设置成其返回值
__Example__
```
stateman.state({
"app": {
title: "APP"
},
"app.test": {
title: "App test"
},
"app.exam": {
url: "exam/:id",
title: function(){
return "Exam " + stateman.param.id
}
},
"app.notitle": {}
})
stateman.go("app.test");
// document.title === "App test"
stateman.nav("/app/test/1");
// document.title === "Exam 1"
stateman.nav("/app/notitle");
// document.title === "App"
```
正如你所见， 如果当前状态的title没有配置，stateman会去找它父状态的title， 直到stateman本身为止.
### stateman.start
启动stateman, 路由开始
__Usage__
`stateman.start(option)`
__option__
|Param|Type|Detail|
|--|--|--|
|html5 |Boolean|(default false) 是否开启html5支持, 即使用pushState等API代替hash设置|
|root |String|(default '/') 程序根路径，影响到你使用html5模式的表现|
|prefix| String | 配置hashban, 例如你可以传入'!'来达到`#!/contact/100`的hash表现|
|autolink| Boolean | (defualt true) 是否代理所有的`#`开始的链接来达到跳转, 只对html5下有用|
__Example__
```js
stateman.start({
"html5": true,
"prefix": "!",
"root": "/blog" //the app is begin with '/blog'
})
```
__Warning__
如果你在不支持html5 pushState的浏览器开启了`html=true`, stateman会自动降级到hash的路由.
就如同上例的配置.
1. 如果我们在不支持html5(pushState相关)的浏览器访问`/blog/app`, stateman会降级到hash的路由，并自动定向到`/blog#/app`的初始状态.
2. 如果我们在__支持html5__的浏览器范围__`/blog#/app`__, stateman同样会使用history的路由路径，并自动返回到 `/blog/app`的初始状态.
### stateman.nav
跳转到指定路径，[url中匹配到的参数](#param)会合并到option, 并最终传给之前提到的`enter`, `leave`, `update`函数.
__Usage__
`stateman.nav(url[, option][, callback])`;
__Argument__
|Param|Type|Detail|
|--|--|--|
|url |String| 跳转url|
|option(optional) |Object| [路由option](#option). url参数会作为option的param参数. |
|callback(optional)|Function| 跳转结束后，此函数会被调用|
__control option__
* option.silent: 如果传入silent, 则只有url路径会发生改变，但是不触发stateman内部的状态改变, 即不会有enter, leave或updatec触发
* option.replace: 如果replace === true, 之前历史的记录会被当前替换，即你无法通过浏览器的后退，回到原状态了
__Example__
`stateman.nav("/app/contact/1?name=leeluolee", {data: 1}); `
最终传入到enter, leave与update的option参数会是
`{param: {id: "1", name:"leeluolee"}, data: 1}`.
### stateman.go
跳转到特定状态, 与 stateman.nav 非常相似，但是stateman.go 使用状态来代替url路径进行跳转
__Usage__
`stateman.go(stateName [, option][, callback])`;
__Arguments__
- stateName [String]: 目标状态
- option [Object]: [Routing Option](#option)
- option.encode:
默认是true, 如果encode是false. 则地址栏的url将不会发生变化，仅仅只是触发了内部状态的跳转. 当encode为true时， stateman会使用[encode](#encode) 函数去反推出真实的url路径显示在location中.
- option.param:
nav与go的最大区别就在于param参数
如果你的路径中带有参数，则需要传入param来帮助encode函数推算出url路径
you can use [stateman.encode](#encode) to test how stateman compute url from a state with specifed param
- option.replace: 见[stateman.nav](#nav)
- calback [Function]: 同nav
所有其它的option属性将会与param一起传入 `enter`, `leave` , `update`中.
__Example__
```
stateman.go('app.contact.detail', {param: {id:1, name: 'leeluolee'}});
```
地址会跳转到`#/app/contact/1?name=leeluolee`, 你可以发现未命名参数会直接拼接在url后方作为queryString 存在.
__Tips__:
作者始终推荐在大型项目中使用go代替nav来进行跳转， 来获得更灵活安全的状态控制.
__相对跳转__:
stateman预定义了一些符号帮助你进行相对路径的跳转
1. "~": 代表当前所处的active状态
2. "^": 代表active状态的父状态;
__example__
```js
stateman.state({
"app.user": function(){
stateman.go("~.detail") // will navigate to app.user.detail
},
"app.contact.detail": function(){
stateman.go("^.message") // will navigate to app.contact.message
}
})
```
### stateman.is
__Usage__
`stateman.is( stateName[, param] [, isStrict] )`
判断当前状态是否满足传入的stateName. 如果有param 参数传入，则除了状态，param也必须匹配. 你不必传入所有的参数， is 只会判断你传入的参数是否匹配.
__Arguments__
|Param|Type|Detail|
|--|--|--|
|stateName |String| 用测试的stateName |
|param(optional)|Object| 用于测试的参数对象|
|isStrict(optional)|Boolean| 传入状态是否要严格匹配当前状态|
__example__
```js
stateman.nav("#/app/contact/1?name=leeluolee");
stateman.is("app.contact.detail") // return true
stateman.is("app.contact", {}, true) // return false,
stateman.is("app.contact.detail", {name: "leeluolee"}, true) // return true
stateman.is("app.contact.detail", {id: "1"}) // return true
stateman.is("app.contact.detail", {id: "2"}) // return false
stateman.is("app.contact.detail", {id: "2", name: "leeluolee"}) // return false
```
### stateman.encode
根据状态名和参数获得指定url.
go函数即基于此方法
__Usage__
`stateman.encode( stateName[, param] )`
__Arguments__
|Param|Type|Detail|
|--|--|--|
|stateName |String| stateName |
|param(optional)|Object| 用于组装url的参数对象|
```js
stateman.encode("app.contact.detail", {id: "1", name: "leeluolee"})
// === "/app/contact/1?name=leeluolee"
```
### stateman.decode
解码传入的url, 获得匹配的状态，状态同时会带上计算出的参数对象
方法[__nav__](#nav) 就是基于此方法实现
__Usage__
`stateman.decode( url )`
__Example__
```js
var state = stateman.decode("/app/contact/1?name=leeluolee")
state.name === 'app.contact.detail'
state.param // =>{id: "1", name: "leeluolee"}
```
### stateman.stop
__Usage__
`stateman.stop()`
stop the stateman.
### stateman.on
为指定函数名添加监听器
__Usage__
`stateman.on(event, handle)`
StateMan内置了一个小型Emitter 来帮助实现事件驱动的开发, 在 [Routing Event](#event) 中查看内建事件
you 可以使用 `[event]:[namespace]`的格式区创建一个带有namespace的事件
__Example__
```
stateman
.on('begin', beginListener)
// there will be a multiply binding
.on({
'end': endListener,
'custom': customListener,
'custom:name1': customListenerWithNameSpace
})
```
### stateman.off
解绑一个监听器
__Usage__
`stateman.off(event, handle)`
__Example__
这里有多种参数可能
```js
// unbind listener with specified handle
stateman.off('begin', beginListener )
// unbind all listener whose eventName is custom and namespace is name1
.off('custom:name1')
// unbind listener whose name is 'custom' (ignore namespace)
.off('custom')
// clear all event bindings of stateman
.off()
```
### stateman.emit
触发一个事件，你可以传入对应的参数
__Usage__
`stateman.emit(event, param)`
与stateman.off类似， namespace会影响函数的表现， 我们用例子来说明一下
__Example__
```js
// emit all listeners named `begin` (ignore namespace)
stateman.emit('begin')
// emit all listeners named `begin`, and with namespace `name1`
.emit('custom:name1')
```
## 理解Routing
### Routing 生命周期
> 
There are three stages in one routing.
- permission
- navigation
- completion
let's talk about `navigation` first.
#### navigation: enter, leave , update:
`enter`, `update` and `leave`是生命周期中最重要的三个时期, 会在这个stata被进入、离开和更新时被调用
__Example__:
假设当前状态为`app.contact.detail.setting`, 当我们跳转到 `app.contact.message`. 完整的动作是
1. leave: app.contact.detail.setting
2. leave: app.contact.detail
3. update: app.contact
4. update: app
5. enter: app.contact.message
你可以直接在这里页面来查看完整过程： [api.html](./example/api.html);
基本上，这里没有难度去理解`enter` 和 `leave`方法，但是`update`何时被调用呢?
先看下我们文章开始的[【例子】](./example/api.html)中定义的`app.contact.detail.setting`. 当我们从 `/app/contact/3/setting`跳转到`app/contact/2/setting`时，实际上stateman的当前状态并没有变化， 都是`app.contact.detail.setting`, 但是参数id改变了，这时我们称之为update, 所有被当前状态包含的状态(但没被enter和leave)都会运行update方法.
#### permission: canEnter canLeave
有时候， 我们需要在跳转真正开始前阻止它， 一种解决方案是使用[`begin`](#event)
```js
stateman.on('begin', function(option){
if( option.current.name === 'app.user' && !isUser){
option.stop()
}
})
```
在版本0.2之后， stateman提供了一种额外的方法， 可供每个状态自己控制是否允许被跳入或跳出, 我们称之为 __"请求权限"__的过程，这个过程发生在跳转(`enter`, `leave`)之前
```js
stateman.state('app.user',{
'canEnter': function(){
return !!isUser;
}
})
```
在上面的例子中，如果`false`被返回了， 则此跳转会被，并恢复之前的url.
__你当然也可以使用[Promise](#control) 来实现异步的流程控制__
现在扩展在[navigation](#navigation)中提到的例子，当你从 `app.contact.detail.setting` 跳转到 `app.contact.message`. 现在完整的流程是
1. __canLeave: app.contact.detail.setting__
2. __canLeave: app.contact.detail__
3. __canEnter: app.contact.message__
4. leave: app.contact.detail.setting
5. leave: app.contact.detail
6. update: app.contact
7. update: app
8. enter: app.contact.message
如果任何一个过程没有被定义, 它会被忽略， 所以都是可选的， 我们只需要实现我们跳转逻辑中需要实现的方法.
### Routing 控制
Stateman 提供几种方式来帮助你实现 __异步或同步__ 的跳转控制. 你可以在[lifecyle.html](./example/lifecycle.html)查找到当前的页面.
#### [__Promise__](#Promise)
如果你的运行环境有Promise支持(浏览器或引入符合规范的Promise/A+的polyfill), 建议你使用Promise控制.
__Example__
```js
var delayBlog = false;
stateman.state('app.blog',{
// ...
'enter': function(option){
delayBlog = true;
return new Promise(function(resolve, reject){
console.log('get into app.blog after 3s')
setTimeout(function(){
delayBlog = false;
resolve();
}, 3000)
})
}
// ...
})
```
如果Promise对象被reject 或 resolve(false), 跳转会直接停止， 如果还在`askForPermission`阶段，url也会被恢复
#### 返回值控制
你可以在`enter`, `leave` 等函数中返回`false`来__同步的__阻止这次跳转
```js
stateman.state('app.blog',{
// ...
'canLeave': function(){
if(delayBlog){
return confirm('blog is pending, want to leave?')
}
}
// ...
})
```
#### `option.async`
stateman 没有与任何promise的polyfill 绑定， 如果你没有在旧版本浏览器主动引入Promise的垫片， 你也可以使用`option.async`来实现同样的功能
### Routing Option
`enter`，`leave`,`update`, `canEnter` 和 `canLeave` 都接受一个称之为 __Routing Option__ 的参数. 这个参数同时也会传递事件 `begin` 和 `end`.
这个option和你传入go 和 nav的option 是同一个引用， 不过stateman让它携带了其它重要信息
```js
stateman.state({
'app': {
enter: function( option ){
console.log(option)// routing option
}
}
})
```
__option__
|Property|Type|Detail|
|--|--|--|
|option.phase| String| 跳转所处阶段|
|option.param| Object| 捕获到的参数|
|option.previous| State| 跳转前的状态|
|option.current| State| 要跳转到的状态|
|option.async| Function| 异步跳转的一种补充方式, 建议使用Promise|
|option.stop | Function| 是否阻止这次事件|
#### 0. option.phase
代表现在跳转进行到了什么阶段. 现在跳转分为三个阶段
- permission: 请求跳转阶段
- navigation: 跳转阶段
- completion: 完成
#### 1. option.async
如果你需要在不支持Promise的环境(同时没有手动添加任何Promise的Polyfill), 你需要option.async来帮助你实现异步的跳转
__Return __
返回一个释放当前装状态的函数
```js
"app.user": {
enter: function(option){
var resolve = option.async();
setTimeout(resolve, 3000);
}
}
```
这个返回的`resolve`函数非常接近Promise中的`resolve`函数， 如果你传入false, 跳转会被终止
```js
"app.user": {
canEnter: function(option){
var resolve = option.async();
resolve(false);
}
}
```
> `false` is a special signal used for rejecting a state throughout this guide.
#### 1. option.current
目标state
#### 2. option.previous
上任state
#### 3. option.param: see [Routing Params](#param)
#### 4. option.stop
手动结束这次跳转， 一般你可能会在begin事件中使用它.
### Routing 参数
####1. 命名参数但是未指定捕获pattern.
__Example__
捕获url`/contact/:id`可以匹配路径`/contact/1`, 并得到param`{id:1}`
事实上，所有的命名参数的默认匹配规则为`[-\$\w]+`. 当然你可以设置自定规则.
####2. 命名参数并指定的规则
命名参数紧接`(RegExp)`可以限制此参数的匹配(不要再使用子匹配). 例如
now , only the number is valid to match the id param of `/contact/:id(\\d+)`
####3. 未命名的匹配规则
你可以只捕获不命名
__Example__
```sh
/contact/(friend|mate)/:id([0-9])/(message|option)
```
这个捕获路径可以匹配`/contact/friend/4/message` 并获得参数 `{0: "friend", id: "4", 1: "message"}`
如你所见，未命名参数会以自增+1的方式放置在参数对象中.
#### 4. param in search
你当然也可以设置querystring . 以 `/contact/:id`为例.
输入`/contact/1?name=heloo&age=1`, 最终你会获得参数`{id:'1', name:'heloo', age: '1'}`.
#### 5. 隐式 param
就像使用POST HTTP 请求一样， 参数不会显示在url上. 同样的, 利用一些小技巧可以让你在stateman实现隐式的参数传递. 换句话说， 你也可以传递非字符串型的参数了。
__Example__
```js
stateman.state('app.blog', {
enter: function(option){
console.log(option.blog.title)
}
})
stateman.go('app.blog', {
blog: {title: 'blog title', content: 'content blog'}
})
```
Any properties kept in option except `param` won't be showed in url.
### Routing 事件
#### begin
每当跳转开始时触发， 回调会获得一个特殊的参数`evt`用来控制跳转.
Because the navigating isn't really start, property like `previous`, `current` and `param` haven't been assigned to stateman.
__Tips__
你可以通过注册begin事件来阻止某次跳转
```js
stateman.on("begin", function(evt){
if(evt.current.name === 'app.contact.message' && evt.previous.name.indexOf("app.user") === 0){
evt.stop();
alert(" nav from 'app.user.*' to 'app.contact.message' is stoped");
}
})
```
将上述代码复制到[http://leeluolee.github.io/stateman/api.html#/app/user](./example/api.html#/app/user).并点击 `app.contact.message`. 你会发现跳转被终止了.
#### end
Emitted when a navigating is end.
```
stateman.on('end', function(option){
console.log(option.phase) // the phase, routing was end with
})
```
see [Option](#option) for other parameter on option.
#### notfound:
Emitted when target state is not founded.
__Tips__
你可以监听notfound事件，来将页面导向默认状态
__Example__
```js
stateman.on("notfound", function(){
this.go("app.contact");
})
```
## 其它属性
Some living properties.
### __stateman.current__:
The target state. the same as option.current
### __stateman.previous__:
The previous state. the same as option.previous
### __stateman.active__:
The active state, represent the state that still in pending.
Imagine that you are navigating from __'app.contact.detail'__ to __'app.user'__, __current__ will point to `app.user` and __previous__ will point to 'app.contact.detail'. But the active state is dynamic, it is changed from `app.contact.detail` to `app.user`.
__example__
```javascript
var stateman = new StateMan();
var config = {
enter: function(option){ console.log("enter: " + this.name + "; active: " + stateman.active.name )},
leave: function(option){ console.log("leave: " + this.name + "; active: " + stateman.active.name) }
}
function cfg(o){
o.enter = o.enter || config.enter
o.leave = o.leave || config.leave
o.update = o.update || config.update
return o;
}
stateman.state({
"app": config,
"app.contact": config,
"app.contact.detail": config,
"app.user": config
}).start();
```
4. __stateman.param__:
The current param captured from url or be passed to the method __stateman.go__.
__Example__
```js
stateman.nav("app.detail", {})
```
## Class: State
you can use `stateman.state(stateName)` to get the target state. each state is instanceof `StateMan.State`. the context of the methods you defined in config(`enter`, `leave`, `update`) is belongs to state.
```js
var state = stataeman.state("app.contact.detail");
state.name = "app.contact.detail"
```
__ state's properties __
1. state.async (REMOVED!) : use option.async instead
2. state.name [String]: the state's stateName
3. state.visited [Boolean]: whether the state have been entered.
4. state.parent [State or StateMan]: state's parent state.for example, the parent of 'app.user.list' is 'app.user'.
5. state.manager [StateMan]: represent the stateman instance;