serve 1.0.0 → 1.1.0

data/CHANGELOG.rdoc

@@ -1,5 +1,16 @@
 = Change Log
 
+== 1.1.0 (May 25, 2010)
+
+* Use latest versions of dependencies [jlong]
+* Added support for locals in partials [heikki]
+* Added limited support for Radius [jlong]
+* Added support for LESS [jlong]
+* Added support for ERubis [jlong]
+* Rewrote the way that Serve resolves file names [jlong]
+* Incorporated Tilt so that other template languages can be added with ease. [jlong]
+* Added limited support for Slim [fleadope, jlong]
+
 == 1.0.0 (November 3, 2010)
 
 * Various tweaks and fixes [jlong]

data/Gemfile

@@ -1,19 +1,22 @@
 source "http://rubygems.org"
 
-gem 'rake',             '~> 0.8.7'
-gem 'rack',             '~> 1.2.1'
-
-# activesupport 2.x
-# gem 'activesupport', '2.3.5'
-
-# activesupport 3.0.x
-gem 'activesupport',    '~> 3.0.1'
-gem 'tzinfo',           '~> 0.3.23'
-gem 'i18n',             '~> 0.4.2'
+gem 'rake',             '~> 0.9.0'
+gem 'rack',             '~> 1.3.0'
+gem 'tilt',             '~> 1.3.1'
+gem 'activesupport',    '~> 3.0.7'
+gem 'tzinfo',           '~> 0.3.27'
+gem 'i18n',             '~> 0.6.0'
 
 group :development do
+  gem 'rspec',          '~> 2.6.0'
   gem 'jeweler',        '~> 1.4.0'
-  gem 'haml',           '~> 3.0.23'
-  gem 'compass',        '~> 0.10.6'
-  gem 'rspec',          '~> 2.0.1'
-end
+  gem 'haml',           '~> 3.1.1'
+  gem 'sass',           '~> 3.1.1'
+  gem 'compass',        '~> 0.11.1'
+  gem 'slim',           '~> 0.9.4'
+  gem 'rdiscount',      '~> 1.6.8'
+  gem 'RedCloth',       '~> 4.2.7'
+  gem 'erubis',         '~> 2.7.0'
+  gem 'less',           '~> 1.2.21'
+  gem 'radius',         '~> 0.6.1'
+end

data/Gemfile.lock

@@ -1,45 +1,72 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (3.0.1)
-    compass (0.10.6)
-      haml (>= 3.0.4)
+    RedCloth (4.2.7)
+    activesupport (3.0.7)
+    chunky_png (1.2.0)
+    compass (0.11.1)
+      chunky_png (~> 1.1)
+      fssm (>= 0.2.7)
+      sass (~> 3.1)
     diff-lcs (1.1.2)
+    erubis (2.7.0)
+    fssm (0.2.7)
     gemcutter (0.6.1)
     git (1.2.5)
-    haml (3.0.23)
-    i18n (0.4.2)
+    haml (3.1.1)
+    i18n (0.6.0)
     jeweler (1.4.0)
       gemcutter (>= 0.1.0)
       git (>= 1.2.5)
       rubyforge (>= 2.0.0)
     json_pure (1.4.6)
-    rack (1.2.1)
-    rake (0.8.7)
-    rspec (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
-      rspec-mocks (~> 2.0.1)
-    rspec-core (2.0.1)
-    rspec-expectations (2.0.1)
-      diff-lcs (>= 1.1.2)
-    rspec-mocks (2.0.1)
-      rspec-core (~> 2.0.1)
-      rspec-expectations (~> 2.0.1)
+    less (1.2.21)
+      mutter (>= 0.4.2)
+      treetop (>= 1.4.2)
+    mutter (0.5.3)
+    polyglot (0.3.1)
+    rack (1.3.0)
+    radius (0.6.1)
+    rake (0.9.0)
+    rdiscount (1.6.8)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.3)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
     rubyforge (2.0.4)
       json_pure (>= 1.1.7)
-    tzinfo (0.3.23)
+    sass (3.1.1)
+    slim (0.9.4)
+      temple (~> 0.3.0)
+      tilt (~> 1.2)
+    temple (0.3.0)
+    tilt (1.3.1)
+    treetop (1.4.9)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.27)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport (~> 3.0.1)
-  compass (~> 0.10.6)
-  haml (~> 3.0.23)
-  i18n (~> 0.4.2)
+  RedCloth (~> 4.2.7)
+  activesupport (~> 3.0.7)
+  compass (~> 0.11.1)
+  erubis (~> 2.7.0)
+  haml (~> 3.1.1)
+  i18n (~> 0.6.0)
   jeweler (~> 1.4.0)
-  rack (~> 1.2.1)
-  rake (~> 0.8.7)
-  rspec (~> 2.0.1)
-  tzinfo (~> 0.3.23)
+  less (~> 1.2.21)
+  rack (~> 1.3.0)
+  radius (~> 0.6.1)
+  rake (~> 0.9.0)
+  rdiscount (~> 1.6.8)
+  rspec (~> 2.6.0)
+  sass (~> 3.1.1)
+  slim (~> 0.9.4)
+  tilt (~> 1.3.1)
+  tzinfo (~> 0.3.27)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2010 John W. Long and Adam I. Williams
+Copyright (c) 2007-2011 John W. Long and Adam I. Williams
 Portions contributed by Robert Evans and others
 
 Permission is hereby granted, free of charge, to any person obtaining

data/QUICKSTART.rdoc

@@ -1,4 +1,4 @@
-= Getting Started with Serve
+= Serve Quickstart - Prototyping Rails Applications
 
 
 <b>This is tutorial is incomplete. Help us finish it!</b>
@@ -28,22 +28,71 @@ 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 create the directory for the prototype:
+Let's go ahead and setup the directory for the prototype. We'll use the `serve create` command to create the initial project directory and files:
+
+ $ serve create prototype
+
+This should output:
+
+ 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/sass
+ create  prototype/sass/application.sass
+ 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/
+    |
+    +-- sass/                  # Store Sass source files here
+    |    |
+    |    `-- application.sass  # Example Sass 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 "sass" 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 <tt>public/stylesheets</tt> directory.
 
- $ mkdir prototype
-
-Rails apps generally store images, javascripts, and stylesheets in the top level directories by the same name. Let's go ahead and mirror those directories for our prototype:
-
- $ cd prototype
- $ mkdir images
- $ mkdir javascripts
- $ mkdir stylesheets
 
 == 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.
 
-Insert the following HTML into an file named "login.html.erb":
+In the "views" directory, create a file named "login.html.erb" and insert the following source code:
 
  <form action="/dashboard/" method="put">
    <p>
@@ -77,28 +126,18 @@ By default the `serve` command automatically serves files from the directory tha
 
  http://localhost:4000
 
-You should see a simple directory listing. It will look similar to this:
-
- Name                          Last modified         Size
- ----------------------------------------------------------
- Parent Directory              2008/02/23 15:35      -
- images/                       2008/02/23 15:35      -
- javascripts/                  2008/02/23 15:35      -
- login.html.erb                2008/02/23 15:36      346
- stylesheets/                  2008/02/23 15:35      -
-
 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 well to the URLs that Rails uses by default.
+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 a layout---not the source file. Let's go ahead and create that layout now.
+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 a layout---not the source file. Let's go ahead and define that layout now.
 
-Insert the following HTML into a file named "_layout.html.erb" in the root directory of your prototype:
+Replace the contents of the file named "_layout.html.erb" in the "views" directory of your prototype with the following:
 
  <html>
    <head>
@@ -110,9 +149,9 @@ Insert the following HTML into a file named "_layout.html.erb" in the root direc
    </body>
  </html>
 
-This layout includes a small amount of ERB(Embedded Ruby) to indicate the title of the web page and to insert the content of the page at the appropriate point.
+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.
+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:
 
@@ -124,8 +163,79 @@ This will set the @title variable for the login page. Now, switch back to your W
 
 The page should now have a title and heading that both read "Login".
 
-== Content For
+== 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:
+
+ <styles>
+   #content { float: left;  width: 60%; }
+   #sidebar { float: right; width: 40%; }
+ </styles>
+
+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
+
+<%= render 'footer' %>
+
+== View Helpers
+
+view_helpers.rb
+
+This tutorial is incomplete. Patches are welcome!

data/README.rdoc

@@ -1,12 +1,14 @@
 = Serve - A Rapid Prototyping Framework for Web Applications
 
+link:/downloads/jlong/serve/logo-hifi-1.png
+
 Serve is a small Rack-based web server that makes it easy to serve HTML, ERB,
-or HAML from any directory.
+Haml, or Slim templates from any directory.
 
 But Serve is much more than a simple web server.
 
 Serve's primary purpose is to provide a rapid prototyping framework for Web
-applications (specifically Rails apps). It is designed to compliment web
+applications (specifically Rails apps). It is designed to complement web
 application development and enforce a strict separation of concerns between
 designer and developer. Using Serve allows the designer to work in a separate
 prototype project, while the developer can work on the actual application and
@@ -30,8 +32,8 @@ MVC stack -- the views. Serve basically allows you to have a separate project
 just for designing the views for the application. When views are ready, they
 can be copied over from the prototype to the application almost as is. This
 process is eased since Serve has full support for partials and layouts with
-either ERB or HAML. Serve can also handle SASS, Textile, and Markdown if the
-appropriate libraries are installed.
+either ERB or Haml. Serve can also handle SASS, Slim, Textile, and Markdown
+if the appropriate libraries are installed.
 
 
 == Installation
@@ -45,12 +47,12 @@ Some systems, like the Mac, may require that you type:
 
   sudo gem install serve
 
-If you are new to the command prompt see:
+If you are a Mac user and are new to the command prompt see:
 
-http://kb.iu.edu/data/amog.html
+http://wiseheartdesign.com/articles/2010/11/12/the-designers-guide-to-the-osx-command-prompt/
 
-You may also want to google "command prompt windows" if you are on a PC or
-"command prompt osx" if you are on a Mac to find a simple tutorial.
+Google "command prompt windows" if you are on a PC to find a simple
+tutorial.
 
 
 == Usage
@@ -163,18 +165,53 @@ the `compass watch` command to generate your stylesheets. Your stylesheets
 will be compiled on the fly with Serve.
 
 
-== File Types
+== Layouts
 
-Serve presently does special processing for files with following extensions:
+In Serve layouts work a little differently than they do in Rails. Because there are no
+controllers to derive layout names from, Serve relies on the directory structure to
+determine the layout associated with a specific view. Serve layouts are stored in
+"_layout.erb" or "_layout.haml" files. Serve searches for a layout file in the same
+directory as the view. If it fails to find one there, it traverses up the directory
+tree searching each parent directory until it finds the "nearest" layout.
 
-textile :: Evaluates the document as Textile (requires the Redcloth gem) 
-markdown :: Evaluates the document as Markdown (requires the Bluecloth gem)
-erb :: Experimental support for ERB
-haml :: Evaluates the document as Haml (requires the Haml gem)
-sass :: Evaluates the document as Sass (requires the Haml gem)
-scss :: Evaluates the document as SCSS (requires the Haml gem)
-email :: Evaluates the document as if it is an e-mail message; the format is identical to a plain/text e-mail message's source
-redirect :: Redirects to the URL contained in the document
+For example, assuming following directory structure:
+
+        views/
+          |
+  A)      +-- _layout.erb
+          |
+          +-- index.erb
+          |
+          `-- about/
+                |
+  B)            +-- _layout.erb
+                |
+                `-- index.erb
+
+For "views/about/index.erb" Serve will use layout B. If layout B did not exist,
+Serve would go up the directory tree and discover layout A which it would use to
+render the view.
+
+For "views/index.erb" Serve would immediately discover and use layout A because it
+is in the same directory.
+
+So Serve searches up the directory tree for the nearest layout file, and uses that
+file to render the view. This is convenient because it allows you to structure your
+Serve project in a way that allows entire "branches" of to share the same layout
+and "branches" lower down can override the layout used.
+
+
+== Partials
+
+Partials in Serve work much like they do in Rails. Prefix your partials with an
+underscore ("_") and use the <tt>render</tt> helper method in your views to render
+the partial:
+
+  <%= render "footer" %>
+
+Or,
+
+  <%= render "/shared/footer" %>
 
 
 == View Helpers
@@ -190,7 +227,62 @@ module and define your helper methods there:
   end
 
 Helpers have full access to the request and response objects so you can easily
-read and manipulate headers.
+read and manipulate headers or do other fancy tricks.
+
+Serve provides a number of stock helpers to make it easier for you to prototype
+Rails applications:
+
+  # Escape Helpers
+  html_escape(string)              # escape HTML in string
+  h(string)                        # alias for html_escape
+  json_escape(string)              # escape invalid JSON characters in string
+  j(string)                        # alias for json_escape
+  
+  # Content Helpers
+  capture(&block)                  # Capture a block inside of a view or layout
+  content_for(symbol, &block)      # Capture a block and store it by symbol
+  content_for?(symbol)             # Has content been captured for symbol?
+  get_content_for(symbol)          # Retrieve content for symbol (equivalent to `yield symbol`)
+  set_content_for(symbol, string)  # Set content for symbol to string
+  
+  # Flash Helpers
+  flash                            # fake flash for request
+  
+  # Param Helpers
+  params                           # access params for request
+  boolean_param(key)               # retrieve value of a boolean param (true/false)
+  
+  # Render Helpers
+  render(partial)                  # Render a partial
+  
+  # Tag Helpers
+  content_tag(name, content, ...)  # a double HTML tag
+  tag(name, ...)                   # a single HTML tag
+  image_tag(src, ...)              # an HTML image tag
+  image(name, ...)                 # shorthand for standard image tag
+  javascript_tag(...)              # a javascript tag
+  link_to(name, href, ...)         # a link to name at href
+  link_to_function(name, ...)      # a link to a function
+  mail_to(email_address, ...)      # a mailto link
+
+For more information, see:
+
+https://github.com/jlong/serve/blob/master/lib/serve/view_helpers.rb
+
+
+== File Types
+
+Serve does special processing for files with following extensions:
+
+textile :: Evaluates the document as Textile (requires the Redcloth gem) 
+markdown :: Evaluates the document as Markdown (requires the Bluecloth gem)
+erb :: Evaluates the document as ERB
+haml :: Evaluates the document as Haml (requires the Haml gem)
+slim :: Evaluates the document using the Slim template language (requires the Slim gem)
+sass :: Evaluates the document as Sass (requires the Haml gem)
+scss :: Evaluates the document as SCSS (requires the Haml gem)
+email :: Evaluates the document as if it is an e-mail message; the format is identical to a plain/text e-mail message's source
+redirect :: Redirects to the URL contained in the document
 
 
 == More Information
@@ -200,13 +292,13 @@ the GitHub wiki:
 
 http://wiki.github.com/jlong/serve
 
-All development takes place on GitHub:
+Have questions? Feel free to ask them on the mailing list:
 
-http://github.com/jlong/serve
+http://groups.google.com/group/serve-users
 
 
 == License
 
-Serve is released under the MIT license and is copyright (c) 2007-2010
+Serve is released under the MIT license and is copyright (c) 2007-2011
 John W. Long and Adam I. Williams. Portions have been contributed by Robert
-Evans and others. A copy of the MIT license can be found in the LICENSE file.
+Evans and others. A copy of the MIT license can be found in the LICENSE file.