Mojolicious::Lite(3pm)					User Contributed Perl Documentation				    Mojolicious::Lite(3pm)

NAME

       Mojolicious::Lite - Real-time micro web framework

SYNOPSIS

	 # Automatically enables "strict", "warnings" and Perl 5.10 features
	 use Mojolicious::Lite;

	 # Route with placeholder
	 get '/:foo' => sub {
	   my $self = shift;
	   my $foo  = $self->param('foo');
	   $self->render(text => "Hello from $foo.");
	 };

	 # Start the Mojolicious command system
	 app->start;

DESCRIPTION

       Mojolicious::Lite is a micro real-time web framework built around Mojolicious.

TUTORIAL

       A quick example driven introduction to the wonders of Mojolicious::Lite.  Most of what you'll learn here also applies to normal Mojolicious
       applications.

   Hello World
       A simple Hello World application can look like this, strict, warnings and Perl 5.10 features are automatically enabled and a few functions
       imported when you use Mojolicious::Lite, turning your script into a full featured web application.

	 #!/usr/bin/env perl
	 use Mojolicious::Lite;

	 get '/' => sub {
	   my $self = shift;
	   $self->render(text => 'Hello World!');
	 };

	 app->start;

   Generator
       There is also a helper command to generate a small example application.

	 $ mojo generate lite_app

   Commands
       All the normal Mojolicious::Commands are available from the command line.  Note that CGI and PSGI environments can usually be auto detected
       and will just work without commands.

	 $ ./myapp.pl daemon
	 Server available at http://127.0.0.1:3000.

	 $ ./myapp.pl daemon -l http://*:8080
	 Server available at http://127.0.0.1:8080.

	 $ ./myapp.pl cgi
	 ...CGI output...

	 $ ./myapp.pl
	 ...List of available commands (or automatically detected environment)...

   Start
       The app->start call that starts the Mojolicious command system can be customized to override normal @ARGV use.

	 app->start('cgi');

   Reloading
       Your application will automatically reload itself if you start it with the "morbo" development web server, so you don't have to restart the
       server after every change.

	 $ morbo myapp.pl
	 Server available at http://127.0.0.1:3000.

   Routes
       Routes are basically just fancy paths that can contain different kinds of placeholders. $self is a Mojolicious::Controller object
       containing both, the HTTP request and response.

	 # /foo
	 get '/foo' => sub {
	   my $self = shift;
	   $self->render(text => 'Hello World!');
	 };

   GET/POST parameters
       All "GET" and "POST" parameters are accessible via "param" in Mojolicious::Controller.

	 # /foo?user=sri
	 get '/foo' => sub {
	   my $self = shift;
	   my $user = $self->param('user');
	   $self->render(text => "Hello $user.");
	 };

   Stash and templates
       The "stash" in Mojolicious::Controller is used to pass data to templates, which can be inlined in the "DATA" section.

	 # /bar
	 get '/bar' => sub {
	   my $self = shift;
	   $self->stash(one => 23);
	   $self->render('baz', two => 24);
	 };

	 __DATA__

	 @@ baz.html.ep
	 The magic numbers are <%= $one %> and <%= $two %>.

       For more information about templates see also "Embedded Perl" in Mojolicious::Guides::Rendering.

   HTTP
       "req" in Mojolicious::Controller and "res" in Mojolicious::Controller give you full access to all HTTP features and information.

	 # /agent
	 get '/agent' => sub {
	   my $self = shift;
	   $self->res->headers->header('X-Bender' => 'Bite my shiny metal ass!');
	   $self->render(text => $self->req->headers->user_agent);
	 };

   Route names
       All routes can have a name associated with them, this allows automatic template detection and back referencing with "url_for" in
       Mojolicious::Controller as well as many helpers like "link_to" in Mojolicious::Plugin::TagHelpers. Nameless routes get an automatically
       generated one assigned that is simply equal to the route itself without non-word characters.

	 # /
	 get '/' => sub {
	   my $self = shift;
	   $self->render;
	 } => 'index';

	 # /hello
	 get '/hello';

	 __DATA__

	 @@ index.html.ep
	 <%= link_to Hello  => 'hello' %>.
	 <%= link_to Reload => 'index' %>.

	 @@ hello.html.ep
	 Hello World!

   Layouts
       Templates can have layouts too, you just select one with the helper "layout" in Mojolicious::Plugin::DefaultHelpers and place the result of
       the current template with the helper "content" in Mojolicious::Plugin::DefaultHelpers.

	 # /with_layout
	 get '/with_layout' => sub {
	   my $self = shift;
	   $self->render('with_layout');
	 };

	 __DATA__

	 @@ with_layout.html.ep
	 % title 'Green';
	 % layout 'green';
	 Hello World!

	 @@ layouts/green.html.ep
	 <!DOCTYPE html>
	 <html>
	   <head><title><%= title %></title></head>
	   <body><%= content %></body>
	 </html>

   Blocks
       Template blocks can be used like normal Perl functions and are always delimited by the "begin" and "end" keywords.

	 # /with_block
	 get '/with_block' => 'block';

	 __DATA__

	 @@ block.html.ep
	 % my $link = begin
	   % my ($url, $name) = @_;
	   Try <%= link_to $url => begin %><%= $name %><% end %>.
	 % end
	 <!DOCTYPE html>
	 <html>
	   <head><title>Sebastians frameworks</title></head>
	   <body>
	     %= $link->('http://mojolicio.us', 'Mojolicious')
	     %= $link->('http://catalystframework.org', 'Catalyst')
	   </body>
	 </html>

   Captured content
       The helper "content_for" in Mojolicious::Plugin::TagHelpers can be used to pass around blocks of captured content.

	 # /captured
	 get '/captured' => sub {
	   my $self = shift;
	   $self->render('captured');
	 };

	 __DATA__

	 @@ captured.html.ep
	 % layout 'blue', title => 'Green';
	 % content_for header => begin
	   <meta http-equiv="Pragma" content="no-cache">
	 % end
	 Hello World!
	 % content_for header => begin
	   <meta http-equiv="Expires" content="-1">
	 % end

	 @@ layouts/blue.html.ep
	 <!DOCTYPE html>
	 <html>
	   <head>
	     <title><%= title %></title>
	     %= content_for 'header'
	   </head>
	   <body><%= content %></body>
	 </html>

   Helpers
       You can also extend Mojolicious with your own helpers, a list of all built-in ones can be found in Mojolicious::Plugin::DefaultHelpers and
       Mojolicious::Plugin::TagHelpers.

	 # "whois" helper
	 helper whois => sub {
	   my $self  = shift;
	   my $agent = $self->req->headers->user_agent || 'Anonymous';
	   my $ip    = $self->tx->remote_address;
	   return "$agent ($ip)";
	 };

	 # /secret
	 get '/secret' => sub {
	   my $self = shift;
	   my $user = $self->whois;
	   $self->app->log->debug("Request from $user.");
	 };

	 __DATA__

	 @@ secret.html.ep
	 We know who you are <%= whois %>.

   Placeholders
       Route placeholders allow capturing parts of a request path until a "/" or "." separator occurs, results are accessible via "stash" in
       Mojolicious::Controller and "param" in Mojolicious::Controller.

	 # /foo/test
	 # /foo/test123
	 get '/foo/:bar' => sub {
	   my $self = shift;
	   my $bar  = $self->stash('bar');
	   $self->render(text => "Our :bar placeholder matched $bar");
	 };

	 # /testsomething/foo
	 # /test123something/foo
	 get '/(:bar)something/foo' => sub {
	   my $self = shift;
	   my $bar  = $self->param('bar');
	   $self->render(text => "Our :bar placeholder matched $bar");
	 };

   Relaxed Placeholders
       Relaxed placeholders allow matching of everything until a "/" occurs.

	 # /test/hello
	 # /test123/hello
	 # /test.123/hello
	 get '/#you/hello' => 'groovy';

	 __DATA__

	 @@ groovy.html.ep
	 Your name is <%= $you %>.

   Wildcard placeholders
       Wildcard placeholders allow matching absolutely everything, including "/" and ".".

	 # /hello/test
	 # /hello/test123
	 # /hello/test.123/test/123
	 get '/hello/*you' => 'groovy';

	 __DATA__

	 @@ groovy.html.ep
	 Your name is <%= $you %>.

   HTTP methods
       Routes can be restricted to specific request methods.

	 # GET /hello
	 get '/hello' => sub {
	   my $self = shift;
	   $self->render(text => 'Hello World!');
	 };

	 # PUT /hello
	 put '/hello' => sub {
	   my $self = shift;
	   my $size = length $self->req->body;
	   $self->render(text => "You uploaded $size bytes to /hello.");
	 };

	 # GET|POST|PATCH /bye
	 any [qw(GET POST PATCH)] => '/bye' => sub {
	   my $self = shift;
	   $self->render(text => 'Bye World!');
	 };

	 # * /whatever
	 any '/whatever' => sub {
	   my $self   = shift;
	   my $method = $self->req->method;
	   $self->render(text => "You called /whatever with $method.");
	 };

   Optional placeholders
       Routes allow default values to make placeholders optional.

	 # /hello
	 # /hello/Sara
	 get '/hello/:name' => {name => 'Sebastian'} => sub {
	   my $self = shift;
	   $self->render('groovy', format => 'txt');
	 };

	 __DATA__

	 @@ groovy.txt.ep
	 My name is <%= $name %>.

   Restrictive placeholders
       The easiest way to make placeholders more restrictive are alternatives, you just make a list of possible values.

	 # /test
	 # /123
	 any '/:foo' => [foo => [qw(test 123)]] => sub {
	   my $self = shift;
	   my $foo  = $self->param('foo');
	   $self->render(text => "Our :foo placeholder matched $foo");
	 };

       All placeholders get compiled to a regex internally, this process can also be easily customized.

	 # /1
	 # /123
	 any '/:bar' => [bar => qr/d+/] => sub {
	   my $self = shift;
	   my $bar  = $self->param('bar');
	   $self->render(text => "Our :bar placeholder matched $bar");
	 };

       Just make sure not to use "^" and "$" or capturing groups "(...)", because placeholders become part of a larger regular expression
       internally, "(?:...)"  is fine though.

   Under
       Authentication and code shared between multiple routes can be realized easily with the "under" statement. All following routes are only
       evaluated if the "under" callback returned a true value.

	 use Mojolicious::Lite;

	 # Authenticate based on name parameter
	 under sub {
	   my $self = shift;

	   # Authenticated
	   my $name = $self->param('name') || '';
	   return 1 if $name eq 'Bender';

	   # Not authenticated
	   $self->render('denied');
	   return;
	 };

	 # / (with authentication)
	 get '/' => 'index';

	 app->start;
	 __DATA__;

	 @@ denied.html.ep
	 You are not Bender, permission denied.

	 @@ index.html.ep
	 Hi Bender.

       Prefixing multiple routes is another good use for "under".

	 use Mojolicious::Lite;

	 # /foo
	 under '/foo';

	 # /foo/bar
	 get '/bar' => {text => 'foo bar'};

	 # /foo/baz
	 get '/baz' => {text => 'foo baz'};

	 # /
	 under '/' => {message => 'whatever'};

	 # /bar
	 get '/bar' => {inline => '<%= $message %> works'};

	 app->start;

       You can also "group" related routes, which allows nesting of multiple "under" statements.

	 use Mojolicious::Lite;

	 # Global logic shared by all routes
	 under sub {
	   my $self = shift;
	   return 1 if $self->req->headers->header('X-Bender');
	   $self->render(text => "You're not Bender.");
	   return;
	 };

	 # Admin section
	 group {

	   # Local logic shared only by routes in this group
	   under '/admin' => sub {
	     my $self = shift;
	     return 1 if $self->req->heaers->header('X-Awesome');
	     $self->render(text => "You're not awesome enough.");
	     return;
	   };

	   # GET /admin/dashboard
	   get '/dashboard' => {text => 'Nothing to see here yet.'};
	 };

	 # GET /welcome
	 get '/welcome' => {text => 'Hi Bender.'};

	 app->start;

   Formats
       Formats can be automatically detected by looking at file extensions.

	 # /detection.html
	 # /detection.txt
	 get '/detection' => sub {
	   my $self = shift;
	   $self->render('detected');
	 };

	 __DATA__

	 @@ detected.html.ep
	 <!DOCTYPE html>
	 <html>
	   <head><title>Detected</title></head>
	   <body>HTML was detected.</body>
	 </html>

	 @@ detected.txt.ep
	 TXT was detected.

       Restrictive placeholders can also be used.

	 # /hello.json
	 # /hello.txt
	 get '/hello' => [format => [qw(json txt)]] => sub {
	   my $self = shift;
	   return $self->render_json({hello => 'world'})
	     if $self->stash('format') eq 'json';
	   $self->render_text('hello world');
	 };

       Or you can just disable format detection.

	 # /hello
	 get '/hello' => [format => 0] => {text => 'No format detection.'};

	 # Disable detection and allow the following routes selective re-enabling
	 under [format => 0];

	 # /foo
	 get '/foo' => {text => 'No format detection again.'};

	 # /bar.txt
	 get '/bar' => [format => 'txt'] => {text => ' Just one format.'};

   Content negotiation
       For resources with different representations and that require truly "RESTful" content negotiation you can also use "respond_to" in
       Mojolicious::Controller.

	 # /hello (Accept: application/json)
	 # /hello (Accept: text/xml)
	 # /hello.json
	 # /hello.xml
	 # /hello?format=json
	 # /hello?format=xml
	 get '/hello' => sub {
	   my $self = shift;
	   $self->respond_to(
	     json => {json => {hello => 'world'}},
	     xml  => {text => '<hello>world</hello>'},
	     any  => {data => '', status => 204}
	   );
	 };

       MIME type mappings can be extended or changed easily with "types" in Mojolicious.

	 app->types->type(rdf => 'application/rdf+xml');

   Conditions
       Conditions such as "agent" and "host" from Mojolicious::Plugin::HeaderCondition allow even more powerful route constructs.

	 # /foo (Firefox)
	 get '/foo' => (agent => qr/Firefox/) => sub {
	   my $self = shift;
	   $self->render(text => 'Congratulations, you are using a cool browser.');
	 };

	 # /foo (Internet Explorer)
	 get '/foo' => (agent => qr/Internet Explorer/) => sub {
	   my $self = shift;
	   $self->render(text => 'Dude, you really need to upgrade to Firefox.');
	 };

	 # http://mojolicio.us/bar
	 get '/bar' => (host => 'mojolicio.us') => sub {
	   my $self = shift;
	   $self->render(text => 'Hello Mojolicious.');
	 };

   Sessions
       Signed cookie based sessions just work out of the box as soon as you start using them through the helper "session" in
       Mojolicious::Plugin::DefaultHelpers.

	 use Mojolicious::Lite;

	 get '/counter' => sub {
	   my $self = shift;
	   $self->session->{counter}++;
	 };

	 app->start;
	 __DATA__

	 @@ counter.html.ep
	 Counter: <%= session 'counter' %>

   Secret
       Note that you should use a custom "secret" in Mojolicious to make signed cookies really secure.

	 app->secret('My secret passphrase here');

   File uploads
       All files uploaded via "multipart/form-data" request are automatically available as Mojo::Upload objects. And you don't have to worry about
       memory usage, because all files above "250KB" will be automatically streamed into a temporary file.

	 use Mojolicious::Lite;

	 # Upload form in DATA section
	 get '/' => 'form';

	 # Multipart upload handler
	 post '/upload' => sub {
	   my $self = shift;

	   # Check file size
	   return $self->render(text => 'File is too big.', status => 200)
	     if $self->req->is_limit_exceeded;

	   # Process uploaded file
	   return $self->redirect_to('form')
	     unless my $example = $self->param('example');
	   my $size = $example->size;
	   my $name = $example->filename;
	   $self->render(text => "Thanks for uploading $size byte file $name.");
	 };

	 app->start;
	 __DATA__

	 @@ form.html.ep
	 <!DOCTYPE html>
	 <html>
	   <head><title>Upload</title></head>
	   <body>
	     %= form_for upload => (enctype => 'multipart/form-data') => begin
	       %= file_field 'example'
	       %= submit_button 'Upload'
	     % end
	   </body>
	 </html>

       To protect you from excessively large files there is also a limit of "5MB" by default, which you can tweak with the "MOJO_MAX_MESSAGE_SIZE"
       environment variable.

	 # Increase limit to 1GB
	 $ENV{MOJO_MAX_MESSAGE_SIZE} = 1073741824;

   User agent
       With "ua" in Mojolicious::Controller there's a full featured HTTP 1.1 and WebSocket user agent built right in. Especially in combination
       with Mojo::JSON and Mojo::DOM this can be a very powerful tool.

	 get '/test' => sub {
	   my $self = shift;
	   $self->render(data => $self->ua->get('http://mojolicio.us')->res->body);
	 };

   WebSockets
       WebSocket applications have never been this easy before.

	 websocket '/echo' => sub {
	   my $self = shift;
	   $self->on(message => sub {
	     my ($self, $message) = @_;
	     $self->send("echo: $message");
	   });
	 };

       The event "message" in Mojo::Transaction::WebSocket, which you can subscribe to with "on" in Mojolicious::Controller, will be emitted for
       every new WebSocket message that is received.

   External templates
       External templates will be searched by the renderer in a "templates" directory.

	 # /external
	 any '/external' => sub {
	   my $self = shift;

	   # templates/foo/bar.html.ep
	   $self->render('foo/bar');
	 };

   Static files
       Static files will be automatically served from the "DATA" section (even Base64 encoded) or a "public" directory if it exists.

	 @@ something.js
	 alert('hello!');

	 @@ test.txt (base64)
	 dGVzdCAxMjMKbGFsYWxh

	 $ mkdir public
	 $ mv something.js public/something.js

   Testing
       Testing your application is as easy as creating a "t" directory and filling it with normal Perl unit tests.

	 use Test::More tests => 3;
	 use Test::Mojo;

	 use FindBin;
	 require "$FindBin::Bin/../myapp.pl";

	 my $t = Test::Mojo->new;
	 $t->get_ok('/')->status_is(200)->content_like(qr/Funky/);

       Run all unit tests with the "test" command.

	 $ ./myapp.pl test

       To make your tests more noisy and show you all log messages you can also change the application log level directly in your test files.

	 $t->app->log->level('debug');

   Mode
       To disable debug messages later in a production setup you can change the Mojolicious mode, default will be "development".

	 $ ./myapp.pl -m production

   Logging
       Mojo::Log messages will be automatically written to "STDERR" or a "log/$mode.log" file if a "log" directory exists.

	 $ mkdir log

       For more control the Mojolicious object can be accessed directly.

	 app->log->level('error');
	 app->routes->get('/foo/:bar' => sub {
	   my $self = shift;
	   $self->app->log->debug('Got a request for "Hello Mojo!".');
	   $self->render(text => 'Hello Mojo!');
	 });

   More
       You can continue with Mojolicious::Guides now, and don't forget to have fun!

FUNCTIONS

       Mojolicious::Lite implements the following functions.

   "any"
	 my $route = any '/:foo' => sub {...};
	 my $route = any [qw(GET POST)] => '/:foo' => sub {...};

       Generate route with "any" in Mojolicious::Routes::Route, matching any of the listed HTTP request methods or all. See also the tutorial
       above for more argument variations.

   "app"
	 my $app = app;

       The Mojolicious::Lite application.

   "del"
	 my $route = del '/:foo' => sub {...};

       Generate route with "delete" in Mojolicious::Routes::Route, matching only "DELETE" requests. See also the tutorial above for more argument
       variations.

   "get"
	 my $route = get '/:foo' => sub {...};

       Generate route with "get" in Mojolicious::Routes::Route, matching only "GET" requests. See also the tutorial above for more argument
       variations.

   "group"
	 group {...};

       Start a new route group.

   "helper"
	 helper foo => sub {...};

       Alias for "helper" in Mojolicious.

   "hook"
	 hook after_dispatch => sub {...};

       Alias for "hook" in Mojolicious.

   "options"
	 my $route = options '/:foo' => sub {...};

       Generate route with "options" in Mojolicious::Routes::Route, matching only "OPTIONS" requests. See also the tutorial above for more
       argument variations.

   "patch"
	 my $route = patch '/:foo' => sub {...};

       Generate route with "patch" in Mojolicious::Routes::Route, matching only "PATCH" requests. See also the tutorial above for more argument
       variations.

   "plugin"
	 plugin 'SomeThing';

       Alias for "plugin" in Mojolicious.

   "post"
	 my $route = post '/:foo' => sub {...};

       Generate route with "post" in Mojolicious::Routes::Route, matching only "POST" requests. See also the tutorial above for more argument
       variations.

   "put"
	 my $route = put '/:foo' => sub {...};

       Generate route with "put" in Mojolicious::Routes::Route, matching only "PUT" requests. See also the tutorial above for more argument
       variations.

   "under"
	 my $route = under sub {...};
	 my $route = under '/:foo';

       Generate bridge with "under" in Mojolicious::Routes::Route, to which all following routes are automatically appended. See also the tutorial
       above for more argument variations.

   "websocket"
	 my $route = websocket '/:foo' => sub {...};

       Generate route with "websocket" in Mojolicious::Routes::Route, matching only "WebSocket" handshakes. See also the tutorial above for more
       argument variations.

ATTRIBUTES

       Mojolicious::Lite inherits all attributes from Mojolicious.

METHODS

       Mojolicious::Lite inherits all methods from Mojolicious.

SEE ALSO

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

perl v5.14.2							    2012-09-05						    Mojolicious::Lite(3pm)