Mojoliciousドキュメント日本語訳

名前

Mojolicious::Plugin::DefaultHelpers - デフォルトヘルパープラグイン

使い方

# Mojolicious
$self->plugin('DefaultHelpers');

# Mojolicious::Lite
plugin 'DefaultHelpers';

説明

Mojolicious::Plugin::DefaultHelpersはMojoliciousの レンダラのヘルパーの集合です。 これはコアのプラグインで、いつでも有効になっており、 そのコードは新しいプラグインを構築する ことを学ぶための良いサンプルです。

デフォルトで利用可能なプラグインの一覧はMojolicious::Pluginsのプラグインの項目を見てください。

ヘルパー

accepts

my $formats = $c->accepts;
my $format  = $c->accepts('html', 'json', 'txt');

Mojolicious::Rendererのacceptsを使って Acceptリクエストヘッダー、スタッシュのformatの値、 あるいはから、リソースのためにもっともよい可能な表現 を選択します。GET/POSTパラメーターのformatの値 デフォルトでは優先順位が検知できなかった場合は、最初の拡張子が返却されます。

# JSONが受け入れかのうかチェック
$c->render(json => {hello => 'world'}) if $c->accepts('json');

# JSONが明確にリクエストされたかどうかのチェック
$c->render(json => {hello => 'world'}) if $c->accepts('', 'json');

# サポートしない表現
$c->render(data => '', status => 204)
  unless my $format = $c->accepts('html', 'json');

# 選択するための表現を検知
my @formats = @{$c->accepts};

app

%= app->secrets->[0]

Mojolicious::Controllerのappのエイリアス。

b

%= b('Joel is a slug')->slugify

文字列をMojo::ByteStreamオブジェクトに変換。

c

%= c('a', 'b', 'c')->shuffle->join

リストをMojo::Collectionオブジェクトに変換。

config

%= config 'something'

Mojoのconfigのエイリアス。

content

%= content foo => begin
  test
% end
%= content bar => 'Hello World!'
%= content 'foo'
%= content 'bar'
%= content

名前つきのバッファの中に、部分的に描画されたコンテンツを保存し、取得します。 一般的にはlayoutとextendsを描画するために利用されます。 新しいコンテンツは名前つきバッファがすでに利用されていた場合は、 無視されることに注意してください。

content_for

% content_for foo => begin
  test
% end
%= content_for 'foo'

contentと同じですが、すでに使用中であれば名前つきバッファにコンテンツを追加します。

% content_for message => begin
  Hello
% end
% content_for message => begin
  world!
% end
%= content 'message'

content_with

% content_with foo => begin
  test
% end
%= content_with 'foo'

contentと同じですが、使用されていれば置き換えます。

% content message => begin
  world!
% end
% content_with message => begin
  Hello <%= content 'message' %>
% end
%= content 'message'

continue

$c->continue;

Mojolicious::Routesのcontinueでディスパッチチェーンを継続します。

csrf_token

%= csrf_token

sessionからCSRFトークンを取得します。 もしなけえれば、生成します。

current_route

% if (current_route 'login') {
  Welcome to Mojolicious!
% }
%= current_route

現在のルート名をチェック、あるいは取得します。

dumper

%= dumper {some => 'data'}

Mojo::Utilのdumperを使ってPerlのデータ構造をダンプします。 デバッグに便利です。

extends

% extends 'blue';
% extends 'blue', title => 'Blue!';

テンプレートを拡張します。すべての追加のキーと値のペアは、「stash」にマージされます。

flash

my $foo = $c->flash('foo');
$c      = $c->flash({foo => 'bar'});
$c      = $c->flash(foo => 'bar');
%= flash 'foo'

Mojolicious::Controllerのflashのエイリアス。

次のリクエストだけに持続するデータストレージ。「session」に保存されます。

# リダイレクトの後にメッセージを表示
$c->flash(message => 'User created successfully!');
$c->redirect_to('show_user', id => 23);

inactivity_timeout

$c->inactivity_timeout(3600);

Mojo::IOLoopのstreamを使って、 現在の接続を見つけ、可能であれば、タイムアウトを増やします。

# 長いバージョン
Mojo::IOLoop->stream($c->tx->connection)->timeout(3600);

include

%= include 'menubar'
%= include 'menubar', format => 'txt'

Mojolicious::Controllerのrender_to_stringのエイリアスです。

is_fresh

my $bool = $c->is_fresh;
my $bool = $c->is_fresh(etag => 'abc');
my $bool = $c->is_fresh(last_modified => $epoch);

Mojolicious::Staticのis_freshを使って If-None-Match、If-Modified-Sinceリクエストヘッダを ETag、Last-Modifiedレスポンスヘッダと比較することによって リクエストの新鮮さをチェックします。

# ETag/Last-Modifiedヘッダーを追加し、描画の前に新鮮さを確認する
$c->is_fresh(etag => 'abc', last_modified => 1424985708)
  ? $c->rendered(304)
  : $c->render(text => 'I ♥ Mojolicious!');

layout

% layout 'green';
% layout 'green', title => 'Green!';

layoutスタッシュの値を設定します。 キーと値のペアは、stashにマージされます。

param

%= param 'foo'

Mojolicious::Controllerのparamのエイリアス。

redirect_to

$c = $c->redirect_to('named', foo => 'bar');
$c = $c->redirect_to('named', {foo => 'bar'});
$c = $c->redirect_to('/index.html');
$c = $c->redirect_to('http://example.com/index.html');

302リダイレクトレスポンスを準備します。url_forと同じ引数を受け取ります。

# 永続的な移動
$c->res->code(301);
$c->redirect_to('some_route');

# 一時的なリダイレクト
$c->res->code(307);
$c->redirect_to('some_route');

reply->asset

$c->reply->asset(Mojo::Asset::File->new);

Mojolicious::Staticのserve_assetを使って、 Mojo::Asset::FileあるいはMojo::Asset::Memoryオブジェクトで応答し、 Range, If-Modified-Since,If-None-Matchヘッダで、 コンテンツネゴシエーションを実行します。

# カスタムの修正時刻でアセットをサーブ
my $asset = Mojo::Asset::Memory->new;
$asset->add_chunk('Hello World!')->mtime(784111777);
$c->res->headers->content_type('text/plain');
$c->reply->asset($asset);

# 存在するならば、静的ファイルをサーブ
if (my $asset = $c->app->static->file('images/logo.png')) {
  $c->res->headers->content_type('image/png');
  $c->reply->asset($asset);
}

reply->exception

$c = $c->reply->exception('Oops!');
$c = $c->reply->exception(Mojo::Exception->new('Oops!'));

例外テンプレートexception.$mode.$format.*あるいはexception.$format.* を描画し、レスポンスステータスコードを500に設定します。 スタッシュの値のexceptionには、Mojo::Exceptionオブジェクトが設定され snapshotには、テンプレートで使用されているstashのコピーへのが設定されます。

reply->file

$c->reply->file('/etc/passwd');

Mojoliciousの「static」を使って、ファイルシステムの絶対パスから静的ファイルを返答します。

# 長いバージョン
$c->reply->asset(Mojo::Asset::File->new(path => '/etc/passwd'));

# カスタムコンテントタイプで絶対パスからファイルをサーブ
$c->res->headers->content_type('application/myapp');
$c->reply->file('/home/sri/foo.txt');

# 秘密のアプリケーションディレクトリからファイルをサーブ
$c->reply->file($c->app->home->child('secret', 'file.txt'));

reply->not_found

$c = $c->reply->not_found;

Not Foundテンプレートnot_found.$mode.$format.*かnot_found.$format.* を描画し、レスポンスステータスコードを404に設定します。 スタッシュの値snapshotには、テンプレートで利用されているstashの コピーが設定されます。

reply->static

my $bool = $c->reply->static('images/logo.png');
my $bool = $c->reply->static('../lib/MyApp.pm');

Mojoliciousのstaticを使って 静的なファイルで応答します。 通常は、publicディレクトリかアプリケーションのDATAセクションが基点です。 このヘルパーは、親ディレクトリへのトラバーサルを防がないことに注意してください。

# カスタムコンテントタイプでファイルを応答する
$c->res->headers->content_type('application/myapp');
$c->reply->static('foo.txt');

respond_to

$c->respond_to(
  json => {json => {message => 'Welcome!'}},
  html => {template => 'welcome'},
  any  => sub {...}
);

Acceptリクエストヘッダ、formatのスタッシュの値、formatのGET/POSTパラメーターから、自動的に可能である最適なリソースの表現を選択します。デフォルトで空の204レスポンスを描画します。 ブラウザは実際にほしいものを知らないことがときどきあるので、 X-Requested-Withヘッダが値に設定されていない場合は、 ひとつ以上のMIMEタイプが含まれたAcceptリクエストヘッダは無視されます。

# "json"と"xml"以外のすべては204レスポンスを得る
$c->respond_to(
  json => sub { $c->render_json({just => 'works'}) },
  xml  => {text => '<just>works</just>'},
  any  => {data => '', status => 204}
);

より発展的なネゴシエーションのためには、 Mojolicious::Plugin::DefaultHelpersのacceptsを使用することができます。

session

%= session 'foo'

Mojolicious::Controllerのsessionのエイリアス。

stash

%= stash 'foo'
% stash foo => 'bar';

Mojolicious::Controllerのstashのエイリアス。

%= stash('name') // 'Somebody'

timing->begin

$c->timing->begin('foo');

"timing->elapsed"のために、名前付きのタイムスタンプを生成します。

timing->elapsed

my $elapsed = $c->timing->elapsed('foo');

「timing->begin」で名前付きtimstampが生成されてからの経過時間を秒単位で返します。 生成されたタイムスタンプがない場合は、undefを返します。

# 長いタイミング情報
$c->timing->begin('database_stuff');
...
my $elapsed = $c->timing->elapsed('database_stuff');
$c->app->log->debug("Database stuff took $elapsed seconds");

timing->rps

my $rps = $c->timing->rps('0.001');

すべての単独のリクエストが1秒の間に費やした時間があれば、1秒間に実行できるリクエストの小数部を返します。 数が少なすぎる場合は、undefを返します。

# 多くのタイミング情報をログに出力
$c->timing->begin('web_stuff');
...
my $elapsed = $c->timing->elapsed('web_stuff');
my $rps     = $c->timing->rps($elapsed);
$c->app->log->debug("Web stuff took $elapsed seconds ($rps per second)");

timing->server_timing

$c->timing->server_timing('metric');
$c->timing->server_timing('metric', 'Some Description');
$c->timing->server_timing('metric', 'Some Description', '0.001');

オプションの説明と期間を使って、Server-Timingヘッダを生成します。

# "Server-Timing: miss"
$c->timing->server_timing('miss');

# "Server-Timing: dc;desc=atl"
$c->timing->server_timing('dc', 'atl');

# "Server-Timing: db;desc=Database;dur=0.0001"
$c->timing->begin('database_stuff');
...
my $elapsed = $c->timing->elapsed('database_stuff');
$c->timing->server_timing('db', 'Database', $elapsed);

# "Server-Timing: miss, dc;desc=atl"
$c->timing->server_timing('miss');
$c->timing->server_timing('dc', 'atl');

title

%= title
% title 'Welcome!';
% title 'Welcome!', foo => 'bar';

titleスタッシュの値を、取得、設定します。 すべてのキーと値のペアはスタッシュにマージされます。

ua

%= ua->get('mojolicio.us')->res->dom->at('title')->text

Mojoのuaのエイリアス。

url_for

%= url_for 'named', controller => 'bar', action => 'baz'

Mojolicious::Controllerのurl_forのエイリアス。

%= url_for('/index.html')->query(foo => 'bar')

url_with

%= url_with 'named', controller => 'bar', action => 'baz'

url_forと同じですが、現在のリクエストから クエリ文字列を受け継ぎます。

%= url_with->query({page => 2})

validation

my $validation = $c->validation;

GETとPOSTパラメーターを検証するための現在のリクエストのための Mojolicious::Validator::Validationオブジェクトです。 リクエストボディの部分は、POSTパラメーターを解析するために、 メモリ上にロードされる必要があります。 そのために大きくなりすぎないように注意してください、 デフォルトは16MBの制限があります。

# GET/POSTパラメーターを検証
my $v = $c->validation;
$v->required('title', 'trim')->size(3, 50);
my $title = $v->param('title');

# ファイルアップロードを検証
my $v = $c->validation;
$v->required('tarball')->upload->size(1, 1048576);
my $tarball = $v->param('tarball');

メソッド

Mojolicious::Plugin::DefaultHelpersは Mojolicious::Pluginからすべてのメソッドを継承しており、 次の新しいメソッドを実装しています。

register

$plugin->register;

Mojoliciousアプリケーションにヘルパーを登録します。

参考

Mojolicious, Mojolicious::Guides, http://mojolicio.us.

(Mojolicious 8.12を反映。2019年6月12日更新)

関連情報

Perlクラブ