Introduction to Mojolicious

About this talk

I first gave this talk at Chicago.pm on Feb 28, 2013
I last updated it on April 30, 2019
The talk is hosted at http://jberger.github.io/MojoliciousIntroduction
The source is available at https://github.com/jberger/MojoliciousIntroduction
All code samples and all tests:
- are complete and run as shown
- are included in the repository

Getting Help

On with the talk...

What is Mojolicious?

An amazing real-time web framework
A powerful web development toolkit
Designed from the ground up
... based on years of experience developing Catalyst

Portable
No non-core dependencies
Batteries included
Real-time and non-blocking
"... perfect for building highly scalable web services"
8491 lines of code in lib
11237 tests (92.8% coverage)
Easy to install (secure, only takes one minute!)

curl -L https://cpanmin.us | perl - -M https://cpan.metacpan.org -n Mojolicious

Mojolicious::Lite

"Hello World"


use Mojolicious::Lite -signatures;

any '/' => sub ($c) { $c->render( text => 'Hello World' ) };

app->start;

imports strict, warnings, utf8 and v5.10
handles the '/' route
- renders the text (as text)
starts the app

Start the server

basic server: $ ./script daemon
development server, smooth auto-restarting on file change: $ morbo script
high performance preforking server, zero downtime redeployment: $ hypnotoad script
plack/psgi (no real-time features): $ plackup script or $ starman script
CGI (but why?)

Mojolicious::Lite

"Hello User"

handles all toplevel routes, including /
- /Joel becomes 'Hello Joel'
- / is special cased to /World
stashes route matches
stash some other useful values
renders from a template with layout
- stash values are localized to Perl scalars


use Mojolicious::Lite -signatures;

any '/:name' => { name => 'World' } => sub ($c) { 
  $c->stash( time => scalar localtime );
  $c->render( 'hello' );
};

app->start;

__DATA__

@@ layouts/basic.html.ep

<!DOCTYPE html>
<html>
  <head>
    <title><%= title %></title>
  </head>
  <body>
    %= content
  </body>
<html>

@@ hello.html.ep

% layout 'basic';
% title "Hello $name";

<p>Hello <%= $name %></p>

%= tag p => begin
  The time is now <%= $time %>
% end

ex/hello.pl

Testing "Hello User"


use Mojo::Base -strict;

use Test::More;
use Test::Mojo;

use FindBin '$Bin';
require "$Bin/hello.pl";

my $t = Test::Mojo->new;

$t->get_ok('/')
  ->status_is(200)
  ->content_like(qr/Hello World/)
  ->content_like(qr/\d{2}:\d{2}/);

$t->get_ok('/Joel')
  ->status_is(200)
  ->content_like(qr/Hello Joel/)
  ->content_like(qr/\d{2}:\d{2}/);

done_testing;

ex/hello1.t

Load the app into Test::Mojo

"Lite" apps must require the app
"Full" apps pass class name to Test::Mojo->new

Request content
Test status
Test response and content

... but do I really just have to regex the result???

Aside: Mojo::DOM

The power of CSS3 selectors

HTML/XML parser
CSS3 selectors (all of them)
List of supported selectors in Mojo::DOM::CSS
First: $dom->at($selector) returns a Mojo::DOM
Multiple: $dom->find($selector) returns a Mojo::Collection


use Mojo::Base -strict;
use Mojo::DOM;

my $html = <<'END';
  <div class="something">
    <h2>Heading</h2>
    Bare text
    <p>Important</p>
  </div>
  <div class="else">Ignore</div>
END

my $dom = Mojo::DOM->new($html);
say $dom->at('.something p')->text;

ex/dom_example.pl

Testing "Hello User"

With selectors

Many Test::Mojo methods support selectors
Test::Mojo has all the power of

Wraps many useful functions of Test::More


use Mojo::Base -strict;

use Test::More;
use Test::Mojo;

use FindBin '$Bin';
require "$Bin/hello.pl";

my $t = Test::Mojo->new;

$t->get_ok('/')
  ->status_is(200)
  ->text_is( p => 'Hello World' )
  ->text_like( 'p:nth-of-type(2)' => qr/\d{2}:\d{2}/ );

$t->get_ok('/Joel')
  ->status_is(200)
  ->text_is( p => 'Hello Joel' )
  ->text_like( 'p:nth-of-type(2)' => qr/\d{2}:\d{2}/ );

done_testing;

ex/hello2.t

Helpers

"helpers" are methods on the app and controller and are template functions
Helpers (and other things) can be bundled and distributed as "plugins"
Many helpers are available via plugins loaded by default
- Mojolicious::Plugin::DefaultHelpers
- Mojolicious::Plugin::TagHelpers

Sessions

Session info is signed and stored in a cookie

Login App Example


use Mojolicious::Lite -signatures;

helper validate => sub ($c, $user, $pass) {
  state $users = {
    joel => 'mypass',
  };
  return unless $users->{$user} eq $pass;
  $c->session( user => $user );
};

any '/' => sub ($c) {
  my ($user, $pass) = map {$c->param($_)} qw/user pass/;
  $c->validate($user, $pass) if $user;
  $c->render('index');
};

any '/logout' => sub ($c) {
  $c->session( expires => 1 );
  $c->redirect_to('/');
};

app->start;

__DATA__

@@ index.html.ep

% my $user = session 'user';
% title $user ? "Welcome back \u$user" : "Not logged in";
% layout 'basic';

<h1><%= title %></h1>

% unless ($user) {
  %= form_for '/' => method => 'POST' => begin
    Username: <%= input_tag 'user' %> <br>
    Password <%= password_field 'pass' %> <br>
    %= submit_button
  % end
% }

ex/login.pl

Aside: Mojo::UserAgent

Full featured user agent
Built-in cookie jar
Handles redirects
SSL and proxy support
dom and json response methods
Pluggable content generators (form/json)
Non-blocking with callback


use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua = Mojo::UserAgent->new(max_redirects => 10);

say $ua->get('api.metacpan.org/v0/release/Mojolicious')
       ->res->json->{version};

use Mojo::URL;
my $url = Mojo::URL->new('http://openlibrary.org/subjects/')
                   ->path('perl.json')
                   ->query( details => 'true' );
say $url;
say $ua->get($url)->res->json('/works/0/title');

ex/ua_example.pl

Testing Login Example

Test that the form is only shown when not authenticated
UserAgent generates form content from hash
UserAgent follows logout redirect


use Mojo::Base -strict;

use Test::More;
use Test::Mojo;

use FindBin '$Bin';
require "$Bin/login.pl";

my $t = Test::Mojo->new;
$t->ua->max_redirects( 2 );

$t->get_ok('/')
  ->status_is(200)
  ->text_is( h1 => 'Not logged in' )
  ->element_exists( 'form' );

my $login = { user => 'joel', pass => 'mypass' };
$t->post_ok( '/' => form => $login )
  ->status_is(200)
  ->text_like( h1 => qr/joel/i )
  ->element_exists_not( 'form' );

$t->get_ok('/logout')
  ->status_is(200)
  ->element_exists('form');

done_testing;

ex/login.t

Content Negotiation

RESTful apps often support many formats
the helper 'respond_to'

detects requested format
renders for that format

reply->not_found renders a 404 page
reply->exception renders a 500 page


use Mojolicious::Lite -signatures;

my %data = (
  1 => { foo => 'bar' },
  2 => { baz => 'bat' },
);

any '/:id' => sub ($c) {
  return $c->reply->not_found
    unless my $item = $data{$c->stash('id')};

  $c->respond_to(
    txt => { text => join(', ', %$item) },
    json => { json => $item },
    any  => { 
      format => 'html', 
      template => 'page', 
      foo => $item,
    },
  );
};

app->start;

__DATA__

@@ page.html.ep

% my $key = (keys %$foo)[0];
% title "You wanted $key";
% layout 'basic';

<p>
  All your <%= $key %> 
  are belong to <%= $foo->{$key} %>
</p>

ex/content.pl

Testing Content Negotiation

Test for formatted response by

default
query parameter
extension
Accept header

Test the 'not found' 404


use Mojo::Base -strict;

use Test::More;
use Test::Mojo;

use FindBin '$Bin';
require "$Bin/content.pl";

my $t = Test::Mojo->new;

$t->get_ok('/0')
  ->status_is(404);

$t->get_ok('/1')
  ->status_is(200)
  ->text_like( p => qr/foo.*?bar/ms );

$t->get_ok('/2?format=txt')
  ->status_is(200)
  ->content_is('baz, bat');

$t->get_ok('/1.json')
  ->status_is(200)
  ->json_is({foo => 'bar'});

$t->get_ok('/2', { Accept => 'application/json' })
  ->status_is(200)
  ->json_is('/baz' => 'bat');

done_testing;

ex/content.t

Still not impressed?

Let's write a POD website that

Requests module documentation from metacpan
Waits to render the response
Doesn't block while waiting

Non-blocking

UserAgent + Server


use Mojolicious::Lite -signatures;
use Mojo::UserAgent;
use Mojo::URL;

my $ua = Mojo::UserAgent->new;
my $url = Mojo::URL->new('http://api.metacpan.org/pod/')
                   ->query( 'content-type' => 'text/html' );

any '/:module' => { module => 'Mojolicious' } => sub ($c) {
  $c->render_later;

  my $module = $c->stash('module');
  my $target = $url->clone;
  $target->path($module);

  $ua->get( $target => sub {
    my ($ua, $tx) = @_;
    $c->render( 'docs', pod => $tx->res->body );
  });
};

app->start;

__DATA__

@@ docs.html.ep

% layout 'basic';
% title $module;

<h1><%= $module %></h1>

%== $pod

ex/nb_doc_server.pl

WebSockets

Client opens websocket
Server responds with data every second
Client receives data and updates plot
Real app would get some more interesting data


use Mojolicious::Lite -signatures;

any '/' => 'index';

websocket '/data' => sub ($c) {
  my $timer = Mojo::IOLoop->recurring( 1 => sub {
    state $i = 0;
    $c->send({ json => gen_data($i++) }); 
  });

  $c->on( finish => sub {
    Mojo::IOLoop->remove($timer);
  });
};

sub gen_data ($x) { 
  return [ $x, sin( $x + 2*rand() - 2*rand() ) ]
}

app->start;

__DATA__

@@ index.html.ep

% layout 'basic';

%= javascript '/jquery-1.9.1.min.js'
%= javascript '/jquery.flot.js'

<div id="plot" style="width:600px;height:300px">
</div>

%= javascript begin
  var data = [];
  var plot = $.plot($('#plot'), [ data ]);

  var url = '<%= url_for('data')->to_abs %>';
  var ws = new WebSocket( url );
  ws.onmessage = function(e){
    var point = JSON.parse(e.data);
    data.push(point);
    plot.setData([data]);
    plot.setupGrid();
    plot.draw();
  };
% end

ex/websocket.pl

Testing WebSockets

Testing is just as easy!
Send a message
Wait for a response
Test response using JSON pointer
Repeat or finish
Many other websocket test methods


use Mojo::Base -strict;

use Test::More;
use Test::Mojo;

use FindBin '$Bin';
require "$Bin/websocket.pl";

my $t = Test::Mojo->new;

$t->get_ok('/')
  ->status_is(200)
  ->element_exists( '#plot' );

$t->websocket_ok('/data')
  ->message_ok
  ->json_message_is( '/0' => 0 )
  ->json_message_has( '/1' )
  ->message_ok
  ->json_message_is( '/0' => 1 )
  ->finish_ok;

done_testing;

ex/websocket.t

Mojolicious Apps are More Than Just Web Apps

Mojolicious::Commands

Fetch, parse and extract resources from the internet

mojo get -r reddit.com/r/perl 'p.title > a.title' text

mojo get http://api.metacpan.org/v0/module/CHI /version

... or from your own app!
```
./ex/hello.pl get / p 1 text
```
Examine the routes that your app defines
```
./ex/websocket.pl routes
```

Run some ad-hoc code against your app!

./ex/websocket.pl eval -v 'app->home'

./ex/websocket.pl eval -V 'app->secrets'

Generate a new app or plugin

mojo generate lite_app

mojo generate app

mojo generate plugin

Add your own commands to Mojolicious:
```
mojo nopaste gist myfile.pl
```
... or to your own app:
```
galileo setup
```
... or import commands from CPAN:
```
./myapp.pl minion worker
```

If you liked that, see also

Mojo::Pg - The Mojolicious Postgres driver wrapper
Mojo::Redis2 - Redis driver, great for messaging
Minion - The Mojolicious job queue and plugin
Galileo - My CPAN friendly Mojolicious-based CMS
Convos - The in-browser Mojolicious-based IRC client

Mojolicious::Plugin::AssetPack - Compress and convert css, less, sass, javascript and coffeescript files
Mojo::Phantom - Easily test your app's JavaScript (YAPC)
Mojolicious::Plugin::MountPSGI - Mount a non-Mojolicious app inside a Mojolicious one
Test::Mojo::Role::PSGI - Test a non-Mojolicious app with Test::Mojo (Phantom works too!)
Mojolicious::Command::nopaste - A Mojo-based nopaste clone with some cool extras (like IRC posting)

Thanks for listening!

Now go have fun with Mojolicious!

http://mojolicio.us

curl -L https://cpanmin.us | perl - -M https://cpan.metacpan.org -n Mojolicious