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>.