Imagine yourself just starting out in learning Model-View-Controller (MVC) web development. Your goal is a web service that authenticates a user before allowing them into the main site. You've looked at the Mojolicious::Lite Tutorial and Glen Hinkle's Mojocasts and getting the hang of routes and rendering, but you feel your project might need to Grow from a prototype into a structured application. The Mojolicious documentation is great, but there's a lot of it to sift through and concepts to get your head around.
Wouldn't it be nice if someone in your situation left you some notes of how problems were solved,
questions answered on the
maillist
(or the official
IRC channel
#mojo on irc.perl.org)
and gathered it into one place? This is what I've learnt so far.
In this tutorial, each step builds on the previous step.
These instructions are written as if you are entering the commands
and adding code to the files that are generated.
The completed app is a single example that resides in
the directory session_tutorial (which you will have already if you clone the
git repository
along with other supporting material).
All the instructions given assume that you are starting
from scratch and tell you how to generate the final example
shown in session_tutorial.
If you want to start in the middle, have a look in the Snapshots directory of the repo.
More about that at the end of this page.
I assume that you're comfortable with running commands in Linux from a terminal window and that you have Mojolicious installed.
Let's get started.
At the command line, type
mojo generate app SessionTutorial
This will create the directory session_tutorial and auto-generate a set of files which
we'll start from.
cd session_tutorial
morbo script/session_tutorial
open your browser at localhost:3000 and see the Welcome page.
morbo is one of the built-in webservers that ships with Mojolicious.
It's portable and self-restart capable, making it perfect for development and testing.
TODO - Link to documentation on morbo
We will include test files to verify the application works as described in the t/ directory. You can run any test with
prove -Ilib t/filename
The prove program runs the test harness and the -Ilib argument adds the application library directory to your path. You will need to have Test::Mojo installed to run these tests.
TODO - Link to documentation on prove
To verify that your Mojolicious will start up successfully (other than by using a browser), run
prove -Ilib t/basic.t
which checks the welcome page and the perldoc pages are there.
To run the whole test suite, use the app with the test option like so
script/session_tutorial test
Mojolicious ships with all its documentation available through the browser
when morbo is running.
Use
localhost:3000/perldoc
to access the Guide.
To access the command line help for the mojo command, use
mojo --help
Having created the framework for your app, the next step is to create a login page following the instructions in Login
I've taken a snapshot of the app as it is right now,
which you can find in Snapshots/Getting_Started.
If at any time you want to go back to an earlier step,
simply stop the server, cd to the step in the Snapshots directory
and start the server there using morbo script/session_tutorial.
In many places, I've assumed that you have already seen some of the copious Mojolicious documentation. Here is a list of Concepts you need to know for growing as a web programmer.