TABLE OF CONTENTS

文档

Mojolicious - 实时 Web 框架

概述

# 应用
package MyApp;
use Mojo::Base 'Mojolicious';

# 路径选择
sub startup {
  my $self = shift;
  $self->routes->get('/hello')->to('foo#hello');
}

# 控制器
package MyApp::Foo;
use Mojo::Base 'Mojolicious::Controller';

# 动作
sub hello {
  my $self = shift;
  $self->render(text => 'Hello World!');
}

描述

在这有非常不错的文档 Mojolicious::Guides!

HOOKS

当前可以使用的 hooks 点和相关的顺序如下:

after_build_tx

这个点是工作在 HTTP 的请求还没有被解析, 但连接已经建立时.

$app->hook(after_build_tx => sub {
  my ($tx, $app) = @_;
  ...
});

这是一个非常强大的 hook 点, 但不应常使用才对. 这个地方用来实现一些非常先进的功能如: 上传进度条之类, 需要注意在内嵌的应用中不能使用. ( 默认参数送的是 transaction 和 application object )

before_dispatch

这个点是工作在静态文件调度和路由选择之前.

$app->hook(before_dispatch => sub {
  my $c = shift;
  ...
});

如果你要重写进来的请求和提前做一些处理时非常有用. ( 默认参数送的是 controller 控制器对象 )

after_static

这个工作在静态响应已经由静态文件服务生成之后.

$app->hook(after_static_dispatch => sub {
  my $c = shift;
  ...
});

主要用来做静态响应之后做些后处理 ( post-processing ),( 默认参数送的是 controller 对象 )

before_routes

这个工作在静态文件服务发现静态文件需要被服务之后和路径选择器工作之前.

$app->hook(before_routes => sub {
  my $c = shift;
  ...
});

多用于定制调度和收集度量用. ( 默认参数是 controller 对象 )

around_action

当一个 action 被调用的时候, 这个工作在调用前后, 所以在这个中, 你还想接着处理这个链条上的其它动作, 你必须手动进入下一个 hook. 默认的操作的调度操作是最在最后个 hook 点, 所以你需要运行在它之前.

$app->hook(around_action => sub {
  my ($next, $c, $action, $last) = @_;
  ...
  return $next->();
});

这也是个非常强大的 hook 点, 但并不太常用. 它可以让你传递额外的一些参数给 action 和对不同的处理方式返回不同的值. ( Passed a callback leading to the next hook, the current controller object, the action callback and a flag indicating if this action is an endpoint )

before_render

这个工作在内容被 renderer 生成之前. 注意这个 hook 可能触发失灵, 由于这个的动态性质, 嵌入式应用将只用于在呈现应用程序.

$app->hook(before_render => sub {
  my ($c, $args) = @_;
  ...
});

多用于提前处理参数给 renderer. ( 默认当前是传送参数是 controller 对象和 render 的参数 )

after_render

这个工作在内容被 renderer 生成之后, 这时分配了响应. 注册这个 hook 可能也会触发失灵, 由于这个的动态性质.

$app->hook(after_render => sub {
  my ($c, $output, $format) = @_;
  ...
});

多用于后处理动态生成的内容. ( 这当前是传送的参数 controller 对象和引用到的内容与格式 )

after_dispatch

响应渲染的内容后调用. 注意这个 hook 点会在 after_static_dispatch 之前触发.

$app->hook(after_dispatch => sub {
  my $c = shift;
  ...
});

这个主要用来重写响应的输出和其它的处理任务. (默认参数送的是 controller 对象)

around_dispatch

before_dispatch 的 hook 点之前调用, 并环绕整个调度的过程. 如果你想控制连接的整个链你可以手动地 forward 到下一个 hook 点. 在异常处理的模块 "render_exception" in Mojolicious::Controller 中, 它 hook 了开始的链并在 dispatch 之后还会调用. 你的 hook 会放在这个中间的.

$app->hook(around_dispatch => sub {
  my ($next, $c) = @_;
  ...
  $next->();
  ...
});

这个 hook 点也非常强大, 但你常使用才对. 它可以让你定制应用的异常处理之类, 你可以给这个工具看成你的工具箱中的大锤一样重要. (传送的参数是下一个 hook 点的回调和 controller 的对象)

属性

Mojolicious 是从 Mojo 继承了所有的属性, 并自己实现了一些新的.

commands

my $commands = $app->commands;
$app         = $app->commands(Mojolicious::Commands->new);

应用的命令行接口, 默认是 Mojolicious::Commands 的这个对象.

# Add another namespace to load commands from
push @{$app->commands->namespaces}, 'MyApp::Command';

controller_class

my $class = $app->controller_class;
$app      = $app->controller_class('Mojolicious::Controller');

默认的控制器使用的类是 Mojolicious::Controller.

mode

my $mode = $app->mode;
$app     = $app->mode('production');

你当前应用默认的操作模式. 默认这个模式会从 MOJO_MODE 的环境变量或 development 中取相应的参数. 也可以加入自定义的到你的应用中, 你需要给你的应用中自己的方法名定义成 ${mode}_mode . 这个会立即调用 startup 之前调用.

sub development_mode {
  my $self = shift;
  ...
}

sub production_mode {
  my $self = shift;
  ...
}

在调用 startup 和指定模式方法之前, Mojolicious 会收起当前的模式, 重命名日志文件之后会提高日志级别从 debuginfo.

moniker

my $moniker = $app->moniker;
$app        = $app->moniker('foo_bar');

应用的名字, 常常用于宣言默认的配置文件的名字和用它 "decamelize" in Mojo::Util 反驼峰化应用类.

plugins

my $plugins = $app->plugins;
$app        = $app->plugins(Mojolicious::Plugins->new);

这是插件管理, 默认是使用 Mojolicious::Plugins 对象来管理, 如果你需要使用插件, 你可以看 plugin 相关的方法.

# Add another namespace to load plugins from
push @{$app->plugins->namespaces}, 'MyApp::Plugin';

renderer

my $renderer = $app->renderer;
$app         = $app->renderer(Mojolicious::Renderer->new);

你的应用渲染内容使用的是 Mojolicious::Renderer 的对象. 渲染插件主要有二个, Mojolicious::Plugin::EPRendererMojolicious::Plugin::EPLRenderer 可以查看相关的模块.

# Add another "templates" directory
push @{$app->renderer->paths}, '/home/sri/templates';

# Add another class with templates in DATA section
push @{$app->renderer->classes}, 'Mojolicious::Plugin::Fun';

routes

my $routes = $app->routes;
$app       = $app->routes(Mojolicious::Routes->new);

路径选择器的对象是使用的 Mojolicious::Routes 的对象, 你可以使用这个来定义你的 Url 的指向, 在你调用 startup 时你的方法时就会定义.

# Add routes
my $r = $app->routes;
$r->get('/foo/bar')->to('test#foo', title => 'Hello Mojo!');
$r->post('/baz')->to('test#baz');

# Add another namespace to load controllers from
push @{$app->routes->namespaces}, 'MyApp::Controller';

secrets

my $secret = $app->secret;
$app       = $app->secrets(['passw0rd']);

使用秘密的口令用于签名 cookies 之类. 默认使用的是在应用中的名字 "moniker" 这是非常不安全的, 所以你需要修改它. 如果你在日志中使用默认的不安全的会提示你修改你的密码.

只有第一个口令是用来创建新的签名, 但它们都会进行验证, 所以你在进行口令替换的时候, 可以使用它们来提高安全性, 不会让签名失效. 只需要给最新的放到前面, 并从后面给旧的拿出来.

# Rotate passphrases
$app->secrets(['new_passw0rd', 'old_passw0rd', 'very_old_passw0rd']);

sessions

my $sessions = $app->sessions;
$app         = $app->sessions(Mojolicious::Sessions->new);

基于 session 管理来签名 cookie . 默认是使用 Mojolicious::Sessions 的对象. 更加的信息看 "session" in Mojolicious::Controller.

# Change name of cookie used for all sessions
$app->sessions->cookie_name('mysession');

static

my $static = $app->static;
$app       = $app->static(Mojolicious::Static->new);

从你的 public 的目录输出静态文件. 默认使用 Mojolicious::Static 的对象.

# Add another "public" directory
push @{$app->static->paths}, '/home/sri/public';

# Add another class with static files in DATA section
push @{$app->static->classes}, 'Mojolicious::Plugin::Fun';

types

my $types = $app->types;
$app      = $app->types(Mojolicious::Types->new);

负责控制传的文件的扩展 MIME 类型.默认是在 Mojolicious::Types 对象中控制.

$app->types->type(twt => 'text/tweet');

validator

my $validator = $app->validator;
$app          = $app->validator(Mojolicious::Validator->new);

检验参数, 默认是使用的 Mojolicious::Validator 对象.

方法

Mojolicious 是从 Mojo 中继承了全部的方法, 并实现了一些.

build_controller

my $c = $app->build_controller;
my $c = $app->build_controller(Mojo::Transaction::HTTP->new);
my $c = $app->build_controller(Mojolicious::Controller->new);

默认的 controller 对象是 "controller_class" 来定义.

# Render template from application
my $foo = $app->build_controller->render_to_string(template => 'foo');

build_tx

my $tx = $app->build_tx;

Transaction 的创建, 默认是使用的 Mojo::Transaction::HTTP 对象.

defaults

my $defaults = $app->defaults;
my $foo      = $app->defaults('foo');
$app         = $app->defaults({foo => 'bar'});
$app         = $app->defaults(foo => 'bar');

对每一次请求, 都会分配定义默认的值, 这个存在 "stash" in Mojolicious::Controller 中.

# Remove value
my $foo = delete $app->defaults->{foo};

dispatch

$app->dispatch(Mojolicious::Controller->new);

这是 Mojolicious 的应用中最重要的要点, 每个请求都会通过 Mojolicious::Controller 的对象调度到 staticroutes 中.

handler

$app->handler(Mojo::Transaction::HTTP->new);
$app->handler(Mojolicious::Controller->new);

设置默认的 controller 和每个请求的处理程序.

helper

$app->helper(foo => sub {...});

加入一个新的 helper 方法为你的控制器和应用的对象中可以来调用. 当然在 ep 的模板中也可以调用.

# Helper
$app->helper(cache => sub { state $cache = {} });

# Controller/Application
$c->cache->{foo} = 'bar';
my $result = $self->cache->{foo};

# Template
% cache->{foo} = 'bar';
%= cache->{foo}

hook

$app->hook(after_dispatch => sub {...});

通过 hooks 点来扩展 Mojolicious. 在这注册后可以让你的代码在所有请求中共享使用. 全部有关 hooks 的列表, 请看 "HOOKS".

# 如果存在定义的响应码, 这个 dispatch 是不会工作的
$app->hook(before_dispatch => sub {
  my $c = shift;
  $c->render(text => 'Skipped static file server and router!')
    if $c->req->url->path->to_route =~ /do_not_dispatch/;
});

new

my $app = Mojolicious->new;

在你调用 "startup" 的时候, 会构造一个新的 Mojolicious 应用. 这个会自动的设置你的 home 目录和根据你当前模式来设置你的日志, 渲染, 静态文件, 默认的插件的设置和 "around_dispatch" hook 点的中定义的默认异常操作.

plugin

$app->plugin('some_thing');
$app->plugin('some_thing', foo => 23);
$app->plugin('some_thing', {foo => 23});
$app->plugin('SomeThing');
$app->plugin('SomeThing', foo => 23);
$app->plugin('SomeThing', {foo => 23});
$app->plugin('MyApp::Plugin::SomeThing');
$app->plugin('MyApp::Plugin::SomeThing', foo => 23);
$app->plugin('MyApp::Plugin::SomeThing', {foo => 23});

加载插件, 全部的插件的例子请看 "PLUGINS" in Mojolicious::Plugins.

Mojolicious::Plugin::Charset

改变应用的字符.

Mojolicious::Plugin::Config

配置相关

Mojolicious::Plugin::DefaultHelpers

常用的 helper 的收集. 这个会默认自动加载.

Mojolicious::Plugin::EPLRenderer

Renderer for plain embedded Perl templates, loaded automatically.

Mojolicious::Plugin::EPRenderer

Renderer for more sophisiticated embedded Perl templates, loaded automatically.

Mojolicious::Plugin::HeaderCondition

Route condition for all kinds of headers, loaded automatically.

Mojolicious::Plugin::JSONConfig

JSON 的配置文件.

Mojolicious::Plugin::Mount

Mount 所有的 Mojolicious 应用.

Mojolicious::Plugin::PODRenderer

渲染 POD 到 HTML 文档浏览器,默认是打开 Mojolicious::Guides.

Mojolicious::Plugin::PoweredBy

Add an X-Powered-By header to outgoing responses, loaded automatically.

Mojolicious::Plugin::RequestTimer

Log timing information, loaded automatically.

Mojolicious::Plugin::TagHelpers

Template specific helper collection, loaded automatically.

Plugin Xslate

Mojolicious::Plugin::Xslate

Xslate 的扩展插件, 请直接看 Xslate 的相关语法

start

$app->start;
$app->start(@ARGV);

通过 "start" in Mojolicious::Commands 启动应用程序并从你的命令行接口中读取参数.

# Always start daemon and ignore @ARGV
$app->start('daemon', '-l', 'http://*:8080');

startup

$app->startup;

这是进入你的应用的主 hook 点, 它将会调用应用 startup.

sub startup {
  my $self = shift;
  ...
}

HELPERS

In addition to the attributes and methods above you can also call helpers on Mojolicious objects. This includes all helpers from Mojolicious::Plugin::DefaultHelpers and Mojolicious::Plugin::TagHelpers. Note that application helpers are always called with a new default controller object, so they can't depend on or change controller state, which includes request, response and stash.

$app->log->debug($app->dumper({foo => 'bar'}));

SUPPORT

Web

http://mojolicio.us

IRC

#mojo on irc.perl.org

Mailing-List

http://groups.google.com/group/mojolicious

DEVELOPMENT

Repository

http://github.com/kraih/mojo

BUNDLED FILES

The Mojolicious distribution includes a few files with different licenses that have been bundled for internal use.

Mojolicious Artwork

Copyright (C) 2010-2012, Sebastian Riedel.

Licensed under the CC-SA License, Version 3.0 http://creativecommons.org/licenses/by-sa/3.0.

jQuery

Copyright (C) 2011, John Resig.

Licensed under the MIT License, http://creativecommons.org/licenses/MIT.

prettify.js

Copyright (C) 2006, Google Inc.

Licensed under the Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0.

CODE NAMES

Every major release of Mojolicious has a code name, these are the ones that have been used in the past.

3.0, Rainbow (u1F308)

2.0, Leaf Fluttering In Wind (u1F343)

1.4, Smiling Face With Sunglasses (u1F60E)

1.3, Tropical Drink (u1F379)

1.1, Smiling Cat Face With Heart-Shaped Eyes (u1F63B)

1.0, Snowflake (u2744)

0.999930, Hot Beverage (u2615)

0.999927, Comet (u2604)

0.999920, Snowman (u2603)

PROJECT FOUNDER

Sebastian Riedel, sri@cpan.org

CORE DEVELOPERS

Current members of the core team in alphabetical order:

CREDITS

In alphabetical order:

COPYRIGHT AND LICENSE

Copyright (C) 2008-2012, Sebastian Riedel.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.