Zero to Mojolicious with Zurb Foundation in Five Minutes

Tags:

A short tutorial.

Let's run through creating a Perl web application with Mojolicious and styling by Zurb Foundation. We will create this first as a full "application" and then as a "Lite" version.

Installing (Perlbrew and) Mojolicious

While perlbrew is not strictly required, the latest versions of Perl have a number of features and optomizations that help Mojolicious. There are two ways to install all this: Globally for all users (I recommend this if you are administering the entire server, and want to keep just one set of software) or in your home directory (best if you share a server).

  1. *Installing in your home directory *Following the instructions here [perlbrew.pl], install Perlbrew into your home directory: something like this:

    \curl -L http://install.perlbrew.pl | bash
nice perlbrew -j 5 install perl-5.20.2

    Note the 'nice' (to reduce impact on a running system) and the "-j 5" (to use up to five concurrent compilation threads) − although on an active server, you might want to just use the default single thread. Observe the final output of perlbrew: You will almost certainly have to edit ~/.bash_profile as it suggests, logout, and then log back in to enable the perlbrew command.

    Now permanently switch to the new Perl, and install Mojolicious:

    perlbrew switch perl-5.20.2
sudo sh -c "curl get.mojolicio.us | sh"

  2. *Installing globally *Assuming a brand new machine (possibly a Linode virtual machine), first we install the latest Mojolicious under /local/bin ... if you don't do this as root this way, I recommend you probably get a cpanminus version somewhere in your user home directory.

    sudo sh -c "curl get.mojolicio.us | sh"

Creating a Mojo "app"

OK now we can go into a working directory somewhere and type:

mojo generate app Test

which will create an entire tree of default files under the subdirectory 'test' for a program called 'Test.'

At this point you should be able to start your example program:

cd Test
morbo script/test

and view the default text at http://localhost:3000

Adding Zurb Foundation to your "app"

Next we get the latest Foundation distribution from their website. At the time of writing, this gave me foundation-5.3.1.zip. Create a subdirectory called foundation under the public directory and unzip into there. This will create subdirectories css and js among a few others.

wget <em>latest_foundation_link_from_above
</em>cd public
mkdir foundation
cd foundation
unzip ../../foundation*.zip
cd ..          <em># back to Mojo project's public</em>

We are going to leave those files in a pristine tree so we can replace them later, and create symbolics links to them. Note the slightly curious use of relative paths in the symbolic links below. The multiple ../ are needed because symlinks are relative to the destination file, not the directory where our shell happens to be when they are created. Also, if only the destination directory and not a filename is given, the destination filename is copied from the source (linked-to) file.

# Assuming the latest Foundation framework code
# is downloaded into the 'foundation' directory,
# and that we are currently in the 'public'
# directory in your generated mojo application,
# here we make symlinks from our document root
# into there, only for the files we actually use.
mkdir css
mkdir -p js/vendor
ln -s ../foundation/css/normalize.css css/
ln -s ../foundation/css/foundation.min.css css/
ln -s ../foundation/js/foundation.min.js js/
ln -s ../../foundation/js/vendor/jquery.js js/vendor/
ln -s ../../foundation/js/vendor/modernizr.js js/vendor/

It is worth a reminder that the syntax here is:

<tt>ln -s</tt> <em><small>{source (real file)} {destination (new link name)}</small></em>

Building the HTML for Foundation

Starting with the basic HTML from here:

http://foundation.zurb.com/docs/css.html

We copy some of the code from the original default.html.ep and create the new templates/layouts/zurbish.html.ep as follows:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <!-- Zurb Foundation stuff -->
    <meta name="viewport" content=
       "width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="css/normalize.css">
    <link rel="stylesheet" href="css/foundation.min.css">
    <script src="js/vendor/modernizr.js"></script>
    <!-- end Zurb -->
    <title><%= title %></title>
  </head>
  <body>
    <script src="js/vendor/jquery.js"></script>
    <script src="js/foundation.min.js"></script>
    <script>
      $(document).foundation();
    </script>
<%= content %>
  </body>
</html>

Then in templates/example/welcome.html.ep we change the content to be as follows:

% layout 'zurbish';
% title 'Welcome';
<h2><%= $msg %></h2>
This page was generated from the template "templates/example/welcome.html.ep"
and the layout "templates/layouts/zurbish.html.ep",
<a href="<%== url_for %>">click here</a> to reload the page or
<a href="/index.html">here</a> to move forward to a static page.
<div class="row">
  <div class="small-2 columns">2 columns</div>
  <div class="small-10 columns">10 columns</div>
</div>
<div class="row">
  <div class="small-3 columns">3 columns</div>
  <div class="small-9 columns">9 columns</div>
</div>

Now, http://localhost:3000 should give you the example text in a very, very basic Foundation based layout. From here, you might want to follow one of the excellent Mojolicious tutorials out there. Here is Zurb's official guide to the Grid, for example.

Also useful is this from "Zurb U" which explains the small/medium/large grids. The one-line gist is:

If you don't specify small-# to a column, Foundation will assume you mean "go full-width on small screens."

As a "Lite App"

For simplicity, here is basically the same program as a single file, in the form of a boilerplate Mojolicious "Lite app":

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

get '/' => sub {
  my $c = shift;
  $c->render('index',
         msg => 'Welcome to the Mojolicious real-time web framework!');
};

app->start;
__DATA__

@@ index.html.ep
% layout 'zurb';
% title 'Welcome';
<div class="row">
  <h2><%= $msg %></h2>
  <div class="small-2 columns">2 columns</div>
  <div class="small-10 columns">10 columns</div>
</div>
<div class="row">
  <div class="small-3 columns">3 columns</div>
  <div class="small-9 columns">9 columns</div>
</div>

@@ layouts/zurb.html.ep
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <!-- Zurb Foundation stuff -->
    <meta name="viewport" content=
       "width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="css/normalize.css">
    <link rel="stylesheet" href="css/foundation.min.css">
    <script src="js/vendor/modernizr.js"></script>
    <!-- end Zurb -->
    <title><%= title %></title>
  </head>
  <body>
    <script src="js/vendor/jquery.js"></script>
    <script src="js/foundation.min.js"></script>
    <script>
      $(document).foundation();
    </script>
<%= content %>
  </body>
</html>

If you save the above as example.pl for example, then the command

morbo example.pl

should permit you to view the generated one-page site at http://localhost:3000

Next steps

In the next installment, we will see how to better use Mojo's template system with Foundation.

Additional Resources