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

`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;
  say 'We are done!';
});

# Emitted when new WebSocket messages arrive
$c->on(message => sub {
  my ($c, $message) = @_;
  say "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(text => 'Hello!');
my $success = $c->render(template => 'foo/index');
my $success = $c->render(template => 'index', format => 'html');
my $success = $c->render(handler => 'something');
my $success = $c->render('foo/bar');
my $output  = $c->render('foo/bar', partial => 1);

This is a wrapper around 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 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;
$c->render_not_found('some_resource');

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');

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 Mojolicious::Static, relative to the public directories 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
$c->render_json({url => $c->req->url->to_abs->to_string});

`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 => sub {...},
  xml  => {text => 'hello!'},
  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.

$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 value 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 $c->app->ua. Usually refers to a Mojo::UserAgent object.

# 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!');

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

app

match

tx

METHODS

cookie

finish

flash

on

param

redirect_to

render

render_content

render_data

render_exception

render_json

render_later

render_not_found

render_partial

render_static

render_text

rendered

req

res

respond_to

send

session

signed_cookie

stash

ua

url_for

write

write_chunk