Dancer::Introduction - A gentle introduction to Dancer

DESCRIPTION--->简介

Dancer is a free and open source micro web application framework written in Perl.

Dancer 是一个免费的开源的基于perl编程语言的微小web应用框架。

INSTALL --->安装

Installation of Dancer is simple:

使用cpanm来安装Dancer 模块

cpanm Dancer

安装非常的方便，并且cpanm的安装也非常的方便

借鉴 http://www.php-oa.com/2010/05/05/perl-cpanminus-cpan.html

SETUP--->设置

Create a web application using the dancer script:

使用dancer脚本创建一个web应用

dancer -a MyApp

执行完后会在本路径下生成一个目录MyApp

Run the web application:

运行创建的web应用

cd MyAppbin/bin

./app.pl

You can read the output of bin/app.pl --help to change any settings such as the port number.

如果想对app.pl有更多的了解，可以使用命令来查看帮助文档

./app.pl --help

这样你就可以了解到怎么来修改默认的端口，怎么转换到其他的web应用中去，并且也会懂得怎么样将dancer脚本与终端分离放置在background中运行。当然，输出的帮助信息不止这些。

最后，当dancer脚本成功运行后，会返回一个连接地址，然后你就可以通过这个连接地址去访问刚才搭建的web应用了。

View the web application at:

http://0.0.0.0:3000

USAGE--->使用方法

When Dancer is imported to a script, that script becomes a webapp, and at this point, all the script has to do is declare a list of routes. A route handler is composed by an HTTP method, a path pattern and a code block. strict and warnings pragmas are also imported with Dancer.

The code block given to the route handler has to return a string which will be used as the content to render to the client.

当dancer被引入到一个脚本后，这个脚本就变成了一个webapp（web应用），之后，脚本所要做的是声明一系列的ruotes（路由）。一个路由处理由三部分组成，分别是：

1）http 方法 （比如：通过http访问web时使用get还是post等方法）

2）路径样式（路径匹配）（比如：具体要访问web中的哪个目录下的哪个页面）

3）代码块 （比如：如果一切正常，那么web server将怎么处理这个web request，也就是web server需要对web request进行的操作,最后将什么内容附加返回给client端）。

当然，随着dancer被引入了脚本中，与之俱来的还有warnings 和 strict指令。

Routes are defined for a given HTTP method. For each method supported, a keyword is exported by the module.

对于每个给出的http方法，都有一条定义的路由，为了对每一个方法都支持，每个方法都对应一个关键字作为处理该请求的标示。

The following is an example of a route definition. The route is defined for the method 'get', so only GET requests will be honoured by that route:

下面是一个对get方法进行的route定义。

get '/' => sub {

# do something

return 'Hello world';

};

也只有get request才能通过该route handler来处理。

HTTP METHODS----->http 方法

Here are some of the standard HTTP methods which you can use to define your route handlers.

GET The GET method retrieves information (when defining a route handler for the GET method, Dancer automatically defines a route handler for the HEAD method, in order to honour HEAD requests for each of your GET route handlers). To define a GET action, use the get keyword.

POST The POST method is used to create a resource on the server. To define a POST action, use the post keyword.

PUT The PUT method is used to update an existing resource. To define a PUT action, use the put keyword.

DELETE The DELETE method requests that the origin server delete the resource identified by the Request-URI. To define a DELETE action, use the del keyword.

一些标准的可以在用来定定义route处理的http方法：

get（检索信息）：当你为一个GET mothod定义了一个route处理的时候，dancer会自动的为HEAD method定义一个route handler，为什么？为了每个get route handler执行HEAD 请求。如果要定义一个Get 操作，需要使用get 关键字。

post（在server上创建一个资源）如果要定义一个POST操作，需要使用post关键字。

put （更新一个已经存在的资源），如果要定义一个put操作，需要使用put关键字。

delete （delete方法请求server删除uri请求中指定的资源），如果要定义一个delete操作，需要使用del关键字。

To define a route for multiple methods you can also use the special keyword any. This example illustrates how to define a route for both GET and POST methods:

如果想为多个方法定义一个路由，那么可以使用any关键字来组合，下面的例子说明了怎么为get和post方法来创建一个路由。

any ['get', 'post'] => '/myaction' => sub {

# code

};

Or even, a route handler that would match any HTTP methods:

更甚者，可以使用一个路由handler来处理任何的http方法

any '/myaction' => sub {

# code

};

ROUTE HANDLERS----->路由处理

The route action is the code reference declared. It can access parameters through the 'params' keyword, which returns a hashref. This hashref is a merge of the route pattern matches and the request params.

路由行为是声明过的代码引用（code reference），她可以通过'params'关键字访问参数，关键字'params'返回的是一个hashref（hash引用），该hashref融合了路由模式匹配（该路由模式匹配-->是不是就是上面说的路径匹配呢？和请求参数）。

You can have more details about how params are built and how to access them in the Dancer::Request documentation.

如果想了解有关params的更多知识请查看Dancer::Request documentation.

NAMED MATCHING----->命名匹配

A route pattern can contain one or more tokens (a word prefixed with ':'). Each token found in a route pattern is used as a named-pattern match. Any match will be set in the params hashref.

一个路由匹配可包含一个或者多个标志（单词前需要':'作前缀）。在一个路由匹配中的每个标志都被用作命令模式匹配。每个匹配会在params hashref中被设置。

get '/hello/:name' => sub {    'Hey '.param('name').', welcome here!';};

Tokens can be optional, for example:

标志也可以是选择性的（可选可不选=or）：比如

get '/hello/:name?' => sub {    'Hello there ' . (param->{name} || "whoever you are!");};

WILDCARDS MATCHING----->通配符匹配

A route can contain a wildcard (represented by a '*'). Each wildcard match will be returned in an arrayref, accessible via the 'splat' keyword.

一个路由可以包含通配符（通过'*'来呈现）。每个通配符的匹配会保存到一个数组引用中，该数组引用可以通过关键字'splat'来访问。例如：

get '/download/*.*' => sub {    my ($file, $ext) = splat;    # do something with $file.$ext here};

REGULAR EXPRESSION MATCHING----->正则表达式匹配

A route can be defined with a Perl regular expression.

一个路由可以通过perl正则表达式来定义。

In order to tell Dancer to consider the route as a real regexp, the route must be defined explicitly with qr{}, like the following:

为了能通知并让dancer理解该路由是通过perl的正则表达式来定义的，该路由必须通过qr{}来准确的表达，否则不好使。例如：

get qr{/hello/([\w]+)} => sub {    my ($name) = splat;    return 'Hello $name';};

这样dancer在处理路由的时候，会将'([\w]+)'这部分通过perl的正则表达式来赋值，然后再继续处理。

CONDITIONAL MATCHING----->条件匹配

Routes may include some matching conditions (on the useragent and the hostname at the moment):

路由也可以包含一些匹配条件（用在用户代理和主机名方面）。

get '/foo', {agent => 'Songbird (\d\.\d)[\d\/]*?'} => sub {  'foo method for songbird'}

get '/foo' => sub {  'all browsers except songbird'}

PREFIX----->前缀

A prefix can be defined for each route handler, like this: