Mojolicious::Controller(3pm) User Contributed Perl Documentation Mojolicious::Controller(3pm)
NAME
Mojolicious::Controller - Controller base class
SYNOPSIS
use Mojo::Base 'Mojolicious::Controller';
DESCRIPTION
Mojolicious::Controller is the base class for your Mojolicious controllers. It is also the default controller class for Mojolicious unless
you set "controller_class" in your application.
ATTRIBUTES
Mojolicious::Controller inherits all attributes from Mojo::Base and implements the following new ones.
"app"
my $app = $c->app;
$c = $c->app(Mojolicious->new);
A reference back to the application that dispatched to this controller, defaults to a Mojolicious object.
# Use application logger
$c->app->log->debug('Hello Mojo!');
"match"
my $m = $c->match;
$c = $c->match(Mojolicious::Routes::Match->new);
Router results for the current request, defaults to a Mojolicious::Routes::Match object.
# Introspect
my $foo = $c->match->endpoint->pattern->defaults->{foo};
"tx"
my $tx = $c->tx;
$c = $c->tx(Mojo::Transaction::HTTP->new);
The transaction that is currently being processed, usually a Mojo::Transaction::HTTP or Mojo::Transaction::WebSocket object.
# Check peer information
my $address = $c->tx->remote_address;
METHODS
Mojolicious::Controller inherits all methods from Mojo::Base and implements the following new ones.
"cookie"
my $value = $c->cookie('foo');
my @values = $c->cookie('foo');
$c = $c->cookie(foo => 'bar');
$c = $c->cookie(foo => 'bar', {path => '/'});
Access request cookie values and create new response cookies.
# Create response cookie with domain
$c->cookie(name => 'sebastian', {domain => 'mojolicio.us'});
"finish"
$c->finish;
$c->finish('Bye!');
Gracefully end WebSocket connection or long poll stream.
"flash"
my $foo = $c->flash('foo');
$c = $c->flash({foo => 'bar'});
$c = $c->flash(foo => 'bar');
Data storage persistent only for the next request, stored in the "session".
# Show message after redirect
$c->flash(message => 'User created successfully!');
$c->redirect_to('show_user', id => 23);
"on"
my $cb = $c->on(finish => sub {...});
Subscribe to events of "tx", which is usually a Mojo::Transaction::HTTP or Mojo::Transaction::WebSocket object.
# Emitted when the transaction has been finished
$c->on(finish => sub {
my $c = shift;
$c->app->log->debug('We are done!');
});
# Emitted when new WebSocket messages arrive
$c->on(message => sub {
my ($c, $message) = @_;
$c->app->log->debug("Message: $message");
});
"param"
my @names = $c->param;
my $foo = $c->param('foo');
my @foo = $c->param('foo');
$c = $c->param(foo => 'ba;r');
$c = $c->param(foo => qw(ba;r ba;z));
Access GET/POST parameters, file uploads and route captures that are not reserved stash values.
# Only GET parameters
my $foo = $c->req->url->query->param('foo');
# Only GET and POST parameters
my $foo = $c->req->param('foo');
# Only file uploads
my $foo = $c->req->upload('foo');
"redirect_to"
$c = $c->redirect_to('named');
$c = $c->redirect_to('named', foo => 'bar');
$c = $c->redirect_to('/path');
$c = $c->redirect_to('http://127.0.0.1/foo/bar');
Prepare a 302 redirect response, takes the exact same arguments as "url_for".
# Conditional redirect
return $c->redirect_to('login') unless $c->session('user');
# Moved permanently
$c->res->code(301);
$c->redirect_to('some_route');
"render"
my $success = $c->render;
my $success = $c->render(controller => 'foo', action => 'bar');
my $success = $c->render({controller => 'foo', action => 'bar'});
my $success = $c->render(template => 'foo/index');
my $success = $c->render(template => 'index', format => 'html');
my $success = $c->render(data => $bytes);
my $success = $c->render(text => 'Hello!');
my $success = $c->render(json => {foo => 'bar'});
my $success = $c->render(handler => 'something');
my $success = $c->render('foo/index');
my $output = $c->render('foo/index', partial => 1);
This is a wrapper around "render" in Mojolicious::Renderer exposing pretty much all functionality provided by it. It will set a default
template to use based on the controller and action name or fall back to the route name. You can call it with a hash or hash reference of
options which can be preceded by an optional template name.
"render_content"
my $output = $c->render_content;
my $output = $c->render_content('header');
my $output = $c->render_content(header => 'Hello world!');
my $output = $c->render_content(header => sub { 'Hello world!' });
Contains partial rendered templates, used for the renderers "layout" and "extends" features.
"render_data"
$c->render_data($bytes);
$c->render_data($bytes, format => 'png');
Render the given content as raw bytes, similar to "render_text" but data will not be encoded.
"render_exception"
$c->render_exception('Oops!');
$c->render_exception(Mojo::Exception->new('Oops!'));
Render the exception template "exception.$mode.$format.*" or "exception.$format.*" and set the response status code to 500.
"render_json"
$c->render_json({foo => 'bar'});
$c->render_json([1, 2, -3], status => 201);
Render a data structure as JSON.
"render_later"
$c->render_later;
Disable automatic rendering, especially for long polling this can be quite useful.
# Delayed rendering
$c->render_later;
Mojo::IOLoop->timer(2 => sub {
$c->render(text => 'Delayed by 2 seconds!');
});
"render_not_found"
$c->render_not_found;
Render the not found template "not_found.$mode.$format.*" or "not_found.$format.*" and set the response status code to 404.
"render_partial"
my $output = $c->render_partial('menubar');
my $output = $c->render_partial('menubar', format => 'txt');
my $output = $c->render_partial(template => 'menubar');
Same as "render" but returns the rendered result.
"render_static"
my $success = $c->render_static('images/logo.png');
my $success = $c->render_static('../lib/MyApp.pm');
Render a static file using "serve" in Mojolicious::Static, usually from the "public" directory or "DATA" section of your application.
"render_text"
$c->render_text('Hello World!');
$c->render_text('Hello World', layout => 'green');
Render the given content as Perl characters, which will be encoded to bytes. See "render_data" for an alternative without encoding. Note
that this does not change the content type of the response, which is "text/html;charset=UTF-8" by default.
# Render "text/plain" response
$c->render_text('Hello World!', format => 'txt');
"rendered"
$c = $c->rendered;
$c = $c->rendered(302);
Finalize response and run "after_dispatch" plugin hook.
# Stream content directly from file
$c->res->content->asset(Mojo::Asset::File->new(path => '/etc/passwd'));
$c->res->headers->content_type('text/plain');
$c->rendered(200);
"req"
my $req = $c->req;
Alias for "$c->tx->req". Usually refers to a Mojo::Message::Request object.
# Extract request information
my $userinfo = $c->req->url->userinfo;
"res"
my $res = $c->res;
Alias for "$c->tx->res". Usually refers to a Mojo::Message::Response object.
# Force file download by setting a custom response header
$c->res->headers->content_disposition('attachment; filename=foo.png;');
"respond_to"
$c->respond_to(
json => {json => {message => 'Welcome!'}},
html => {template => 'welcome'},
any => sub {...}
);
Automatically select best possible representation for resource from "Accept" request header, "format" stash value or "format" GET/POST
parameter, defaults to rendering an empty 204 response. Unspecific "Accept" request headers that contain more than one MIME type are
currently ignored, since browsers often don't really know what they actually want.
$c->respond_to(
json => sub { $c->render_json({just => 'works'}) },
xml => {text => '<just>works</just>'},
any => {data => '', status => 204}
);
"send"
$c = $c->send({binary => $bytes});
$c = $c->send({text => $bytes});
$c = $c->send([$fin, $rsv1, $rsv2, $rsv3, $op, $payload]);
$c = $c->send('Hi there!');
$c = $c->send('Hi there!', sub {...});
Send message or frame non-blocking via WebSocket, the optional drain callback will be invoked once all data has been written.
# Send JSON object as text frame
$c->send({text => Mojo::JSON->new->encode({hello => 'world'})});
# Send "Ping" frame
$c->send([1, 0, 0, 0, 9, 'Hello World!']);
For mostly idle WebSockets you might also want to increase the inactivity timeout, which usually defaults to 15 seconds.
# Increase inactivity timeout for connection to 300 seconds
Mojo::IOLoop->stream($c->tx->connection)->timeout(300);
"session"
my $session = $c->session;
my $foo = $c->session('foo');
$c = $c->session({foo => 'bar'});
$c = $c->session(foo => 'bar');
Persistent data storage, stored "JSON" serialized in a signed cookie. Note that cookies are generally limited to 4096 bytes of data.
# Manipulate session
$c->session->{foo} = 'bar';
my $foo = $c->session->{foo};
delete $c->session->{foo};
# Delete whole session
$c->session(expires => 1);
"signed_cookie"
my $value = $c->signed_cookie('foo');
my @values = $c->signed_cookie('foo');
$c = $c->signed_cookie(foo => 'bar');
$c = $c->signed_cookie(foo => 'bar', {path => '/'});
Access signed request cookie values and create new signed response cookies. Cookies failing signature verification will be automatically
discarded.
"stash"
my $stash = $c->stash;
my $foo = $c->stash('foo');
$c = $c->stash({foo => 'bar'});
$c = $c->stash(foo => 'bar');
Non persistent data storage and exchange, application wide default values can be set with "defaults" in Mojolicious. Many stash values have
a special meaning and are reserved, the full list is currently "action", "app", "cb", "controller", "data", "extends", "format", "handler",
"json", "layout", "namespace", "partial", "path", "status", "template" and "text".
# Manipulate stash
$c->stash->{foo} = 'bar';
my $foo = $c->stash->{foo};
delete $c->stash->{foo};
"ua"
my $ua = $c->ua;
Alias for "ua" in Mojo.
# Blocking
my $tx = $c->ua->get('http://mojolicio.us');
my $tx = $c->ua->post_form('http://kraih.com/login' => {user => 'mojo'});
# Non-blocking
$c->ua->get('http://mojolicio.us' => sub {
my ($ua, $tx) = @_;
$c->render_data($tx->res->body);
});
# Parallel non-blocking
my $delay = Mojo::IOLoop->delay(sub {
my ($delay, @titles) = @_;
$c->render_json(@titles);
});
for my $url ('http://mojolicio.us', 'https://metacpan.org') {
$delay->begin;
$c->ua->get($url => sub {
my ($ua, $tx) = @_;
$delay->end($tx->res->dom->html->head->title->text);
});
}
"url_for"
my $url = $c->url_for;
my $url = $c->url_for(name => 'sebastian');
my $url = $c->url_for('test', name => 'sebastian');
my $url = $c->url_for('/perldoc');
my $url = $c->url_for('http://mojolicio.us/perldoc');
Generate a portable Mojo::URL object with base for a route, path or URL.
# "/perldoc?foo=bar" if application is deployed under "/"
$c->url_for('/perldoc')->query(foo => 'bar');
# "/myapp/perldoc?foo=bar" if application is deployed under "/myapp"
$c->url_for('/perldoc')->query(foo => 'bar');
You can also use the helper "url_with" in Mojolicious::Plugin::DefaultHelpers to inherit query parameters from the current request.
# "/list?q=mojo&page=2" if current request was for "/list?q=mojo&page=1"
$c->url_with->query([page => 2]);
"write"
$c->write;
$c->write('Hello!');
$c->write(sub {...});
$c->write('Hello!', sub {...});
Write dynamic content non-blocking, the optional drain callback will be invoked once all data has been written.
# Keep connection alive (with Content-Length header)
$c->res->headers->content_length(6);
$c->write('Hel', sub {
my $c = shift;
$c->write('lo!')
});
# Close connection when finished (without Content-Length header)
$c->write('Hel', sub {
my $c = shift;
$c->write('lo!', sub {
my $c = shift;
$c->finish;
});
});
For Comet ("long polling") you might also want to increase the inactivity timeout, which usually defaults to 15 seconds.
# Increase inactivity timeout for connection to 300 seconds
Mojo::IOLoop->stream($c->tx->connection)->timeout(300);
"write_chunk"
$c->write_chunk;
$c->write_chunk('Hello!');
$c->write_chunk(sub {...});
$c->write_chunk('Hello!', sub {...});
Write dynamic content non-blocking with "chunked" transfer encoding, the optional drain callback will be invoked once all data has been
written.
# Make sure previous chunk has been written before continuing
$c->write_chunk('He', sub {
my $c = shift;
$c->write_chunk('ll', sub {
my $c = shift;
$c->finish('o!');
});
});
You can call "finish" at any time to end the stream.
2
He
2
ll
2
o!
0
HELPERS
In addition to the attributes and methods above you can also call helpers on Mojolicious::Controller objects. This includes all helpers
from Mojolicious::Plugin::DefaultHelpers and Mojolicious::Plugin::TagHelpers.
$c->layout('green');
$c->title('Welcome!');
SEE ALSO
Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.
perl v5.14.2 2012-09-05 Mojolicious::Controller(3pm)