Prototyping Rails Applications with Serve

This is tutorial is incomplete. Help us finish it!

Serve can be used as a rapid prototyping framework for Rails applications. It is designed to complement Rails development and enforce a strict separation of concerns between designer and developer. Using Serve with Rails allows the designer to happily work in their own space creating an HTML prototype of the application, while the developer works on the Rails application and copies over HTML from the prototype as needed. This allows the designer to focus on presentation and flow while the developer can focus on the implementation.

Let’s have a look at how it all works.

Installation

To get started we need to download and install the Ruby gem for Serve:

$ sudo gem install serve

After we’ve done that it’s probably a good idea to install a couple of additional gems so that Serve will play nicely with Haml, Markdown, and Textile:

$ sudo gem install haml sass BlueCloth RedCloth

Project Directory Structure

Once we have everything installed the next thing to do is setup the project directory. I like to setup my projects with the following directory structure:

artwork Logos and other identity design files go here
mockups Fireworks or Photoshop web app mockups go here
prototype The HTML prototype for the web app goes here
application The actual Rails application is here

Let’s go ahead and setup the directory for the prototype. We’ll use the serve create command to create the initial prototype directory and files:

$ serve create prototype

This should output something like this:

create  prototype
create  prototype/public
create  prototype/tmp
create  prototype/views
create  prototype/config.ru
create  prototype/LICENSE
create  prototype/.gitignore
create  prototype/compass.config
create  prototype/README.markdown
create  prototype/public/images
create  prototype/public/javascripts
create  prototype/public/stylesheets
create  prototype/stylesheets
create  prototype/stylesheets/application.scss
create  prototype/views/_layout.html.erb
create  prototype/views/hello.html.erb
create  prototype/views/view_helpers.rb
create  prototype/views/index.redirect

You’ll note that the serve create command creates a directory structure that is somewhat similar to a Rails project:

prototype/
  |
  +-- config.ru              # Rack configuration file
  |
  +-- compass.config         # Compass configuration file
  |
  +-- public/                # Directories for static assets
  |    |
  |    +-- stylesheets/      # Compiled stylesheets
  |    |
  |    +-- images/
  |    |
  |    `-- javascripts/
  |
  +-- stylesheets/           # Store Sass source files here
  |    |
  |    `-- application.scss  # Example SCSS file for application
  |
  +-- tmp/                   # Needed for Passenger (mod_passenger)
  |    |
  |    `-- restart.txt
  |
  `-- views/                 # Store your ERB, Haml, etc. here
       |
       +-- _layout.html.erb  # Example layout
       |
       +-- hello.html.erb    # Example view
       |
       `-- view_helpers.rb   # Example view helpers

Views and layouts for your prototype application belong in the “views” directory. The “public” directory is for static assets – resources like images or javascripts that don’t need server side processing. The “stylehseets” directory is the place where you should store Sass source files (if you use those). Serve will automatically compile Sass and SCSS files stored here into public/stylesheets directory.

Creating Our First Screen

Now that we have the prototype directory set up, let’s create our first page so that you can get a feel for how Serve works. This will be a simple HTML login page for our application.

In the “views” directory, create a file named “login.html.erb” and insert the following source code:

<form action="/dashboard/" method="put">
  <p>
    <label for="username">Username</label>
    <input type="text" name="username" id="username" />
  </p>
  <p>
    <label for="password">Password</label>
    <input type="password" name="password" id="password" />
  </p>
  <p>
    <input type="submit" value="Login" />
  </p>
</form>

Starting Serve

To view our login page in a Web browser, we need to start up Serve in the directory where we are building the prototype:

% cd prototype
% serve
[2008-02-23 15:19:05] INFO  WEBrick 1.3.1
[2008-02-23 15:19:05] INFO  ruby 1.8.6 (2007-09-24) [universal-darwin9.0]
[2008-02-23 15:19:05] INFO  Serve::Server#start: pid=5087 port=4000
...

Once you execute the serve command it will launch a mini Web server for the prototype and will output a noisy log of any activity. (To stop the command at any point simply switch back to the command line and press Ctrl+C.)

By default the serve command automatically serves files from the directory that it is started in over port 4000 on your local machine. To access the the prototype in your Web browser go to:

http://localhost:4000

Now navigate to the following URL:

http://localhost:4000/login

You should see the contents of the login page. Note that Serve allows you to refer to pages without their extension. This allows you to use URLs in your documents that correspond to the URLs that Rails uses by default.

Layouts

One thing to note about the source that I gave you for the login page. I intentionally left out the <html>, <head>, and <body> tags because they belong in a layout—not a view file. Let’s go ahead and define that layout now.

Replace the contents of the file named “_layout.html.erb” in the “views” directory of your prototype with the following:

<html>
  <head>
    <title><%= @title %></title>
  </head>
  <body>
    <h1><%= @title %></h1>
    <%= yield %>
  </body>
</html>

This layout includes a small amount of ERB. ERB stands for Embedded Ruby. ERB allows you to embed Ruby code into a web page to dynamically render content. In our case, we are using it in the layout to indicate the title of the web page and to insert the content of the page at the appropriate point. You can use ERB in layout or view files.

Embedded Ruby is delineated with the opening and closing sequence <% and %> respectively. Sequences that begin with an addition equals sign insert their output directly into the HTML. In this case we want to render the @title variable as the title in the head and as the first heading in the document body. The yield keyword is used to insert the content of the page at that point.

We need to make one small change to our login page before continuing. Insert the following line at the top of login.html.erb file:

<% @title = "Login" %>

This will set the @title variable for the login page. Now, switch back to your Web browser and navigate to:

http://localhost:4000/login

The page should now have a title and heading that both read “Login”.

Content regions with content_for

Let’s add a sidebar to the login page. To do this in a layout friendly way, we will use the content_for helper method to define the sidebar.

Add the following code to the bottom of login.html.erb:

<% content_for :sidebar do %>
  <h3>New Around Here?</h3>
  <p>No problem! Just <a href="/signup/">create an account</a>.</p>
<% end %>

This defines a new content region of the page that we can render wherever we want in the layout. The :sidebar symbol defines the name of the content region.

Now to modify the layout to work with this new content region. In “_layout.html.erb” replace the code:

<h1><%= @title %></h1>
<%= yield %>

With the following:

<div id="content">
  <h1><%= @title %></h1>
  <%= yield %>
</div>
<div id="sidebar">
  <%= yield :sidebar %>
</div>

This defines two new divs for the content and sidebar portions of the document. The first call to yield renders the content portion of a view (everything apart from regions defined by calls to content_for). The second call to yield passes the name of our content region as a symbol. When yield is called with a symbol, it renders the associated content region. In our case yield :sidebar causes Serve to render the content that we defined for the :sidebar region at that point in the layout.

Now add a block for inline styles to the “head” of the layout:

<style>
  #content { float: left;  width: 60%; }
  #sidebar { float: right; width: 40%; }
</style>

We could certainly put this in it’s own file (in the public/stylesheets directory), but for the purposes of this demonstration, it works just as well in the head of the document.

The full layout file should now look like this:

<html>
  <head>
    <title><%= @title %></title>
    <styles>
       #content { float: left;  width: 60%; }
       #sidebar { float: right; width: 40%; }
     </styles>
  </head>
  <body>
    <div id="content">
      <h1><%= @title %></h1>
      <%= yield %>
    </div>
    <div id="sidebar">
      <%= yield :sidebar %>
    </div>
  </body>
</html>

Now switch back to your Web browser at:

http://localhost:4000/login

And check out the new multi-column layout on the login page.

Partials

Let's add a header and a footer our page now. To keep everything self-contained, we can define the header and footer in separate files and include them into the main layout.

Create a file in the views directory called "_header.html.erb" and insert the following code:

<div id="header">
  My Web App
</div>

Create another file in the views directory called "_footer.html.erb" and insert the following code:

<div id="footer">
  Copyright © 2017, My Company. All rights reserved.
</div>

Now switch over to "_layout.html.erb" and insert this line just after the opening <body> tag:

<%= render 'header' %>

And this this line, just before the closing </body> tag:

<%= render 'footer' %>

What we've done here is added two calls to the render helper method. One for the header and one for the footer. Partials, like layouts, are prefixed with an "_", but when you refer to them inside of a view or layout, drop the "_" and the file extension. This is why we were able to write render 'header' instead of render '_header.html.erb'. Both variations will actually work, but the first is preferred because it's more concise.

To pretty things up a bit, let's add a couple of additional styles in the head portion of the layout. Insert the following code inside the twin <style> tags:

#header { background: #666; color: white; font-size: 120%; padding: 10px; }
#footer { clear: both; color: #333; }

Your "_layout.html.erb" file should now look like this:

<html>
  <head>
    <title><%= @title %></title>
    <style>
       #content { float: left;  width: 60%; }
       #sidebar { float: right; width: 40%; }
       #header { background: #666; color: white; font-size: 120%; padding: 10px; }
       #footer { clear: both; color: #333; }
     </style>
  </head>
  <body>
    <%= render 'header' %>
    <div id="content">
      <h1><%= @title %></h1>
      <%= yield %>
    </div>
    <div id="sidebar">
      <%= yield :sidebar %>
    </div>
    <%= render 'footer' %>
  </body>
</html>

Now switch back to your Web browser at:

http://localhost:4000/login

And check out the new header and footer that we've added.

View Helpers

We can

view_helpers.rb

This tutorial is incomplete. Help us finish it!