++ed by:
EXC HRUPP NGLENN AWNCORP WOLLMERS

116 PAUSE user(s)
144 non-PAUSE user(s).

Sebastian Riedel

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.

  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 => 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 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);
  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.