Mojolicious::Controller(3p)

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;
    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 "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;
  $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 "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 => 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. Unspecific "Accept" request headers that contain more than one MIME type are ignored.

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

SEE ALSO
Mojolicious, Mojolicious::Guides, <http://mojolicio.us>.