IronRouter中文指南（精品） .doc

Guide指南2Quick Start2Concepts概念4Server Only服务端4Client Only客户端4Client and Server 服务端和客户端4Reactivity响应式5Route Parameters路由参数5Rendering Templates 渲染模板7Rendering Templates with Data渲染含数据的模板7Layouts布局8Rendering Templates into Regions with JavaScript含JavaScript的区域渲染模板9Setting Region Data Contexts设置区域数据上下文10Rendering Templates into Regions using contentFor在contenFor区域渲染模板11Client Navigation客户端导航12Using Links使用链接12Using JavaScript使用JavaScript14Using Redirects使用redirects14Using Links to Server Routes使用服务端Links15Named Routes命名路由15Getting the Current Route获取当前路由16Template Lookup模板查找16Path and Link Template Helpers路径和链接模板助手17pathFor17urlFor18linkTo18Route Options路由选项19Route Specific Options特殊的选项19Global Default Options默认全局选项22Subscriptions订阅22Wait and Ready22The subscriptions Option(选项)23The waitOn Option(选项)24Server Routing服务端路由25Creating Routes创建路由25Restful Routes (Rest架构式路由)25404s and Client vs Server Routes 404s和客户端 vs 服务端路由26Plugins插件26Applying Plugins to Specific Routes特定的路由应用插件26Creating Plugins创建插件27Hooks钩子27Using Hooks使用钩子27Applying Hooks to Specific Routes特定的路由应用钩子28Using the Iron.Router.hooks Namespace使用Iron.Router.hooks命名空间29Available Hook Methods可用的钩子方法29Server Hooks and Connect服务端钩子和Connect中间件30Route Controllers路由控制器31Creating Route Controllers创建路由控制器32Inheriting from Route Controllers来自路由控制器的继承33Accessing the Current Route Controller访问当前路由控制器34Setting Reactive State Variables设置响应状态变量35Getting Reactive State Variables获取响应状态变量35Custom Router Rendering定制路由器渲染36Legacy Browser Support传统浏览器支持36补充37Rest架构37路由、路由器、路由控制器的区别37yeild 与 contentFor之间的区别37Guide指南A router that works on the server and the browser, designed specifically for Meteor.iron router是为Meteor设计的一套在服务器和浏览器端工作的路由器。Quick StartYou can install iron:router using Meteor's package management system:首先，你需要使用Meteor的扩展包管理系统安装iron:router> meteor add iron:routerTo update iron:router to the latest version you can use the meteor update command:若需升级iron:router,则使用Meteor的更新命令> meteor update iron:routerStart by creating a route in your JavaScript file. By default, routes are created for the client and will run in the browser.首先在JavaScript文件中创建一个路由，默认情况是为客户端创建的路由只在浏览器端运行。Router.route('/', function () this.render('Home'););When the user navigates to the url "/", the route above will render the template named "Home" onto the page.上述代码是指：当用户导航栏地址为URL根目录，则在该页面执行模板名为“Home”的代码块。Router.route('/items');This second route will automatically render a template named "Items" or "items" to the page. In simple cases like this, you don't even need to provide a route function.上述代码是指：在页面中自动执行模板名"Items"或"items"的代码块。在这种情况下，你甚至不需要提供一个路由函数。So far, we've only created routes that will be run directly in the browser. But we can also create server routes. These hook directly into the HTTP request and are used to implement REST endpoints.到目前为止，我们只创建了在浏览器中直接运行的路由。但我们也可以创建服务器端路由。这些钩子直接进入HTTP请求和用于实现REST端点。Router.route('/item', function () var req = this.request; var res = this.response; res.end('hello from the servern');, where: 'server');The where: 'server' option tells the Router this is a server side route.这个where:'server'选项告诉路由器，这是服务器端路由。Concepts概念Server Only服务端In a typical Web app, you make an http request to a server at a particular url, like "/items/5", and a router on the server decides which function to invoke for that particular route. The function will most likely send some html back to the browser and close the connection.在一个典型的web应用中，一个特殊的url地址会向服务器发送一个http请求，如”/items/5”，服务器上的路由器决定了该特定路由的调用功能。这个功能很可能向浏览器发送一些html并关闭连接。Client Only客户端In some more modern Web apps you'll use a "client side" router like pagejs or Backbone router. These routers run in the browser, and let you navigate around an application without making trips to the server by taking advantage of browser HTML5 features like pushState or url hash fragments. 在一些流行的web应用中，你会像pagejs 和 Backbone路由一样使用一个“客户端”路由。这些路由器运行在浏览器中，并让你在不访问服务器的情况下，通过获取高级的浏览器hmtl5功能，导航周边应用，如pushState(无刷新更新)、url 哈希片段。Client and Server 服务端和客户端Iron.Router runs on the client and the server. You can define a route that only should run on the server, or a route that should only run on the client. Most of the time you'll create routes on the client. This makes your app really fast once it's loaded, because as you navigate around the application, you don't need to load an entirely new html page.Iron.Router运行于客户端和服务端。你可以定义一个路由，只在服务端运行或只在客户端运行。大多数情况会在客户端创建路由。使得你的应用一旦加载很快响应，因为在你浏览周边应用时，不需要加载一个全新的HTML页面。The router is aware of all the routes on the client and the server. This means you can click a link that takes you to a server route, or it might take you to a client route. It also means that on the server, if there is no client route defined, we can send a 404 response to the client instead of loading up the Meteor application.路由器知道所有在客户端和服务端的路由。这意味着你可以点击一个链接，便会带你到一个服务端路由，也有可能带你到客户端路由。这也意味着在服务器上，如果没有定义客户端路由，我们可以向客户端发送404响应，而不是加载的Meteor应用。Reactivity响应式Your route functions and most hooks are run in a reactive computation. This means they will rerun automatically if a reactive data source changes. For example, if you call Meteor.user() inside of your route function, your route function will rerun each time the value of Meteor.user() changes.你的route函数和大多数钩子是在响应计算周期内运行的。这意味着如果反应数据源发生改变，它们将自动重新运行。例如，如果在路由函数内调用Meteor.user()，你的路由函数将返回每次Meteor.user()的值变化。Route Parameters路由参数Routes can have variable parameters. For example, you can create one route to show any post with an id. The id is variable depending on the post you want to see such as "/posts/1" or "/posts/2". To declare a named parameter in your route use the : syntax in the url followed by the parameter name. When a user goes to that url, the actual value of the parameter will be stored as a property on this.params in your route function.路由可以有可变参数。例如，创建一个路由，用于显示任意带有id的post。这个id变量依赖于你想看到关于post是什么值；如"/posts/1" 或 "/posts/2"。在你的路由中声明一个被命名的参数：是在URL的语法后跟着参数名。当用户调转到该URL时，该参数的实际值将被存储在你的路由函数this.params属性中。In this example we have a route parameter named _id. If we navigate to the /post/5 url in our browser, inside of the route function we can get the actual value of the _id from this.params._id. In this case this.params._id => 5.在下面的例子中，我们定义一个命名为_id的路由参数。如果在浏览器中导航到”/post/5”地址，在路由函数内部，我们可以通过”this.params._id”获取”_id”的实际值。在这种情况下this.params._id=>5。/ 获取一个像 "/post/5"的地址Router.route('/post/:_id', function () var params = this.params; / _id: "5" var id = params._id; / "5");You can have multiple route parameters. In this example, we have an _id parameter and a commentId parameter. If you navigate to the url /post/5/comments/100 then inside your route function this.params._id => 5 and mentId => 100.可以添加多个路由参数。在下面的例子中，我们有”_id” 和”commentId”两个参数。假设你的跳转(导航)地址是/post/5/comments/100，然后在你的路由函数中this.params._id=>5 和entId=>100/ 获取一个像 "/post/5/comments/100"的地址Router.route('/post/:_id/comments/:commentId', function () var id = this.params._id; / "5" var commentId = mentId; / "100");If there is a query string or hash fragment in the url, you can access those using the query and hash properties of the this.params object.如果在url地址中有查询字符串或哈希片段，你可以通过this.params对象获取查询和哈希属性。/ given the url: "/post/5?q=s#hashFrag"Router.route('/post/:_id', function () var id = this.params._id; var query = this.params.query; / query.q -> "s" var hash = this.params.hash; / "hashFrag");Note: If you want to rerun a function when the hash changes you can do this:注意：如果当hash改变时，你想返回一个函数。你可以这样做:/ get a handle for the controller. in a template helper this would be /var controller = Iron.controller();获取控制器句柄，在模板Helper中这将是var controller = this;/ reactive getParams method which will invalidate the comp if any part of the params change including the hash.如果参数部分有任何改变(包括hash),响应性的getParams方法将失效。var params = controller.getParams();/var params = Iron.controller.getParams()By default the router will follow normal browser behavior. If you click a link with a hash frag it will scroll to an element with that id. If you want to use controller.getParams() you can put that in either your own autorun if you want to do something procedural, or in a helper.默认情况下，路由器会遵循标准浏览器行为。如果你点击一个带有Hash片段的链接,它将滚动到一个含有id的元素上。如果你想写一个程序或一个helper，你可以使用controller.getParams()赋予自运行.Rendering Templates 渲染模板Usually we want to render a template when the user goes to a particular url. For example, we might want to render the template named Post when the user navigates to the url /posts/1.通常当用户跳转到一个特定url地址时，我们想渲染一个模板。例如，当用户导航到”url/posts/1”地址,我们可能需要渲染名称为”post”的模板。<template name="Post"> <h1>Post: title</h1></template>Router.route('/post/:_id', function () this.render('Post'););We can render a template by calling the render method inside of our route function. The render method takes the name of a template as its first parameter.在路由函数内，通过调用render方法可以渲染一个模板。模板名称作为第一个参数被这个render方法获取。Rendering Templates with Data渲染含数据的模板In the above example the title value is not defined. We could create a helper on the Post template called title or we can set a data context for the template directly from our route function. To do that, we provide a data option as a second parameter to the render call.在上面的例子中”title”值没有定义。我们将在Post模板中创建一个Helper调用title,或我们直接从路由函数中设置一个数据上下文模板。要做到这一点,我们为渲染调用提供一个数据选项作为第二个参数。Router.route('/post/:_id', function () this.render('Post', data: function () return Posts.findOne(_id: this.params._id); ););Layouts布局Layouts allow you to reuse a common look and feel in multiple pages in your application so you don't have to duplicate the html and logic on every single page template.在您的应用程序中,布局允许重复使用通用的外观，所以没必要将Html和业务逻辑复制到每个页面中。Layouts are just templates. But, inside of a layout you can use a special helper called yield. You can think of yield as a placeholder for content. The placeholder is called a region. The content will be "injected" into the region when we actually run our route. This lets us reuse the layout on many different pages, only changing the content of the yield regions.布局就是模板。但是在布局中可以使用特殊的helper调用<code>yield</code>。你可以将<code>yield</code>作为一个内容占位符，占位符被称为<em>区域</em>。当我们实际运行路由时，内容将被”注入”到该区域。这让我们只要改变<em>yield区域</em>内容，就可在不同页面重用该布局。<template name="ApplicationLayout"> <header> <h1>title</h1> </header> <aside> > yield "aside" </aside> <article> > yield </article> <footer> > yield "footer" </footer></template>We can tell our route function which layout template to use by calling the layout method.我们可以告诉路由函数，调用layout方法使用哪一套布局模板。Router.route('/post/:_id', function () this.layout('ApplicationLayout'););If you want to use a default layout template for all routes you can configure a global Router option.如果你想为所有路由使用一个默认的布局模板，你可以配置一个全局路由器选项。Router.configure( layoutTemplate: 'ApplicationLayout');Rendering Templates into Regions with JavaScript含JavaScript的区域渲染模板Inside of our route function we can tell the router which templates to render into each region. 在路由函数内部，我们告知路由器每一个区域需要渲染哪些模板。<template name="Post"> <p> post_content </p></template><template name="PostFooter"> Some post specific footer content.</template><template name="PostAside"> Some post specific aside content.</template>Let's say we're using the ApplicationLayout and we want to put the templates defined above into their respective regions for the /post/:_id route. We can do this directly in our route function using the to option of the render method.比方说，我们使用ApplicationLayout，并想要为“/post/:_id”路由将上面定义的模板放在它们各自的区域中。在路由函数中我们可以直接使用render方法的to选项。Router.route('/post/:_id', function () / use the template named ApplicationLayout for our layout/使用模板命名ApplicationLayout布局 this.layout('ApplicationLayout'); / render the Post template into the "main" region/在主体区域里渲染Post模板 / > yield this.render('Post'); / render the PostAside template into the yield region named "aside" /在名为”aside”的yield区域中渲染”PostAside”模板 / > yield "aside" this.render('PostAside', to: 'aside'); / render the PostFooter template into the yield region named "footer" / > yield "footer" this.render('PostFooter', to: 'footer'););Setting Region Data Contexts设置区域数据上下文You can set the data contexts for regions by providing a data option to the render method. You can also set a data context for the entire layout.你可以通过为render方法提供一个data选项，设置区域的数据上下文。还可以对整个布局设置一个数据上下文。Router.route('/post/:_id', function () this.layout('ApplicationLayout', data: function () return Posts.findOne(_id: this.params._id) ); this.render('Post', / we don't really need this since we set the data context for the / the entire layout above. But this demonstrates how you can set / a new data context for each specific region./我们真的不需要这样,因为我们在整个布局之上设置数据上下文。但这里演示如何为每个特定区域设置一个新的数据上下文。 data: function () return Posts.findOne(_id: this.params._id) ); this.render('PostAside', to: 'aside', data: function () return Posts.findOne(_id: this.params._id) ); this.render('PostFooter', to: 'footer', data: function () return Posts.findOne(_id: this.params._id) ););Rendering Templates into Regions using contentFor在contenFor区域渲染模板Rendering templates into region from our route function can be useful, especially if we need to run some custom logic or if the template names are dynamic. But often an easier way to provide content for a region is to use the contentFor helper directly from our main template. Let's say we're using the same ApplicationLayout from the previous example. But this time, instead of defining a new template for each region, we'll provide the content inline in our Post template.来自路由函数中的区域模板渲染有用的，特别是在运行一些自定义逻辑或者模板名称是动态的情况。通常一个简单的方法是通过主模板使用contentFor helper为区域提供内容。从前面的例子中看，我们使用了一些ApplicationLayout,但是这次，我们在Post模板中提供一个内容链接，替代为每个区域定义一个新模板。<template name="Post"> <p> post_content </p> #contentFor "aside" Some post specific aside content. /contentFor #contentFor "footer" Some post specific footer content. /contentFor</template>Now we can simply specify our layout and render the Post template instead of each individual region.现在我们简单的指定布局和渲染Post模板，而不是每个区域。Router.route('/post/:_id', function () this.layout('ApplicationLayout', data: function () return Posts.findOne(_id: this.params._id) ); / this time just render the template named "Post" into the main / region这一次只是为主区域渲染名为”post”模板 this.render('Post'););You can even provide a template option to the contentFor helper instead of providing in-line block content.你甚至可以为contentFor助