The Trellis Framework Blog :

Trellis and Heroku

Fri, 09 Apr 2010 11:26:00 -0400

Currently, Trellis v0.1.1 requires Ruby 1.8.7 due to my usage of blocks as parameters (for the filters feature). This prevents Trellis applications to be deployed to Heroku using the default stack.

To migrate applications to 1.8.7 see http://blog.heroku.com/archives/2010/3/5/public_beta_deployment_stacks/

To create a new Heroku app for Trellis use heroku create –stack bamboo-ree-1.8.7

Trellis Tutorial #3 - Creating a Stateless Component

Wed, 10 Feb 2010 14:31:00 -0500

Creating a Stateless Component

A component-driven framework would be pretty pointless if you couldn’t create your own components. Component creation is how developers can encapsulate a complex and/or repetitive piece of functionality and provide a clear API to access that functionality.

In Trellis, components wrap both logic and presentation in a small manageable package. A Trellis component provides a template to be rendered and logic that can be used to respond to external events.

In the first installment of the Trellis tutorial series we got to use some of the simple components made available through the core library. The core components provide very basic functionality expected in a component-driven web framework. But things only get interesting when you get to build your own components. Whether they are general purpose, domain specific or application specific components, a well-crafted set of components can truly improve the understanding of an application, ease maintenance and improve testability.

In this tutorial we’ll walk through the development of a simple stateless component to display images using the Flickr API. This example is included in the Trellis distribution under examples/flickr

Project Setup

Setting up a Trellis project is quite simple. We’ll start with the simple directory structure shown in Figure 1. I’ve named the root directory of the application ‘flickr’. The ruby file flickr.rb will contain our application and the file spec/flickr_spec.rb will contain our RSpec specifications.

Figure 1 - Flickr Application Directory Structure

Test Driven Development with Trellis with RSpec

In this tutorial we’ll work in a more realistic way that in previous tutorials. We’ll developed the Flickr example in a test-driven/test-first fashion. We’ll start with a bare bones skeleton for a Trellis application, as shown next (flickr.rb):

require 'rubygems'
require 'trellis'

include Trellis

module Flickr
  class FlickrApp < Application
  end
end

RSpec

For our TDD efforts we’ll use RSpec, “the original Behavior Driven Development framework for Ruby”. With RSpec you create “specifications” which are tests that describe the behavior of the system under certain conditions. We will try to follow the red-green-refactor mantra as close as possible:

Writing a Test that describes a particular behavior of interest in the system.
Running the Test (Red): Since the behavior hasn’t been implemented the test will fail.
Implement: Writing enough code to pass the test
Re-Running the Test (Green): With the implementation in place the test should now pass
Refactor: With a basic foundation of how to fulfill the behavior and a test to prove the implementation we can now “refactor without fear”.

In the /spec directory we’ll add simple RSpec spec as follows (flickr_spec.rb):

require 'rubygems'
require 'spec'
require 'rack'
require 'rack/test'
require File.dirname(__FILE__) + '/../flickr.rb'

describe Flickr::FlickrApp do
  include Rack::Test::Methods

  def app
    Flickr::FlickrApp.new
  end

  it "should have a home page declared" do
    Flickr::FlickrApp.homepage == :home
  end
end

Let’s talk about the spec we’ve just created. At the top, besides requiring rubygems, we need the RSpec library (spec), Rack (rack) and Rack::Test (rack/test). We will also need to make the file under test, flickr.rb available.

Rack::Test enables you to test a Rack-based application without having a running server. Rack::Test mocks HTTP requests and provides a DSL to test against the response.

The describe block, “describes” an scenario. In RSpec an scenario consists of one or more examples. Each example describes a discrete behavior of the class under test.

In the scenario above we have only one example so far which states that our application should have a home page named “home”. With the bare bones application code and the spec in place we can now run it to get our TDD going.

Figure 2 - Failed Spec (no home page)

As expected the test fails. We got to the “red” stage. To pass the test and get to “green” we can simply declare the home page as shown next:

module Flickr
  class FlickrApp < Application
    home :home
  end
end

Running the tests again shows that we’ve accomplish what we set out to do in this simple example.

Figure 3 - Passed Spec (after adding a home page)

Testing with Rack::Test

With an understanding of the basic mechanics of TDD we can now move onto fleshing out the rest of the application. Our next example will make use of Rack::Test to make sure that our application returns an HTTP status code of 200 (OK). Previously we provided the spec with an #app method which returned an instance of the Flickr application. The #app method is required by Rack::Test and it enables the use of a simple DSL to interact with the application in a mocked HTTP server environment. Rack::Test provides a way to issue a mock HTTP request to the application, inspect the response, follow redirects and maintain cookies across requests.

it "should return an OK HTTP status" do
  get "/"
  last_response.status.should be(200)
end

This test requests the root url of the application, which should redirect to a home page and then checks that the last response has a status of 200.

Figure 4 - Failed Spec (no OK response)

To pass this next example we need to provide a bare bones implementation of the Home page. The Home page provides a simple html template as shown next:

class Home < Page
  template %[
    <html xml:lang="en" lang="en" 
          xmlns:trellis="http://trellisframework.org/schema/trellis_1_0_0.xsd" 
          xmlns="http://www.w3.org/1999/xhtml">
      <body>
        Some Interesting Pictures...
      </body>
    </html>
  ], :format => :html
end

Let’s run the spec again and confirm that we get a 200 response.

Figure 5 - Passed Spec (after barebones home page impl)

Running what we have so far

At this point we do have enough of the application in place so that we can also run it and visually inspect the progress so far.

To be able to launch the application self-contained we need an instance of the application on which we can invoke the #start method. Add the two following lines at the end of the Flick module in flickr.rb:

web_app = FlickrApp.new
web_app.start 3006 if __FILE__ == $PROGRAM_NAME

To launch the application run the flickr.rb ruby script like:

ruby flickr.rb

Figure 6 - Launching the Flickr Trellis App

Open a browser and point it to http://localhost:3006 and you should see:

Figure 7 - Bare bones Flickr Trellis App

The Flickr Interestingness Component

The Flickr Interestingess Trellis Component will use the Flickr API to make a call to the “interestiness” XML-RPC web service method which returns one or more random images from Flick that have been deemed “interesting” (warning to the easily offended).

We’ll start with a simple test to get the component to render something (anything really!). Our basic test will simply expect to find an html DIV with and id attribute of “flickr_viewer” and with text content equals to “Hello”:

it "should render the flickr component" do
  get '/'
  last_response.body.should include(%[Hello])
end

Figure 8 - Failed Component Test

To pass this test we can provide the bare bones implementation of a Trellis stateless component. Inside the Flickr module in flickr.rb we declare the FlickrInterestingness component which descends from Trellis::Component:

class FlickrInterestingness < Component
   tag_name "flickr_interestingness"

   render do |tag|
     %[Hello]
   end
end

A Trellis component has a tag_name, which by default is just the name of the component underscored and lower-cased. To provide the template or content for the component the Trellis::Component class provides the #render method which takes a block that expects a “tag” object as a parameter. We’ll go into more detail about the “tag” soon.

Next we’ll use the component in the page template via the tag, prefixed with the namespace ‘trellis’:

class Home < Page
  template %[
    <html xml:lang="en" lang="en" 
          xmlns:trellis="http://trellisframework.org/schema/trellis_1_0_0.xsd" 
          xmlns="http://www.w3.org/1999/xhtml">
      <body>
        Some Interesting Pictures...
        <trellis:flickr_interestingness/>
      </body>
    </html>
  ], :format => :html
end

The return value of the render method is expected to be a string value that will be rendered on the page using the component. In our simple case we simply hardcoded a return value with the expected HTML snippet.

Figure 9 - Passed Render Component Test

As you can see a Trellis stateless component is simply a way to produce content; a tag that it is available to a Trellis template.

Trellis Tutorial #2 - Routing in Trellis

Fri, 29 Jan 2010 17:13:00 -0500

Routing in Trellis

Trellis provides a per page routing scheme heavily based on Sinatra’s routing with a few more additions and magic of its own. In this short article I’ll cover the most common usages of routing. For more examples check out the included routing example in the Trellis distribution (examples/routing) and the RSpec specs for the routing classes (test/router_spec.rb)

Absolute Routes

Routing in Trellis works at the page level. Each page in an application has a base default route which is the page class name lowercased and underscored. For example, if you have a page class called ChuckNorrisIsTheMan:

class ChuckNorrisIsTheMan < Trellis::Page
  template do html { body { text %[Chuck can kick you before you blink] }} end
end

Then the page would be accessible at /chuck_norris_is_the_man. For more complex routing needs Trellis provides the “route” class method available on the Page class. The route method takes a routing pattern. The simplest routing pattern is just an absolute route:

class WhoaPage < Trellis::Page
  route '/whoa'

  template do html { body { text %[whoa!] }} end
end

With an absolute route is easy to add route spaces like /admin and the like.

Parameterized Routes

But things only get interesting when we start passing values via our URLs. Let’s say that we wanted to have a page that can be take a routing pattern representing a date. Trellis routing patterns can take named parameters so we could have a page with a complex route in a format like /day_of_the_year/2009/11/21. The page RoutedDifferentlyWithParams below shows how to create such a route:

class RoutedDifferentlyWithParams < Trellis::Page
  route '/day_of_the_year/:year/:month/:day'

  def parse_date
    Date.parse("#{@month}/#{@day}/#{@year}").strftime("%e %B, %Y")
  end

  def on_select
    self
  end

  template %[
    
     @{parse_date}@ is the @{Date.parse(@month + '/' + @day + '/' + @year).yday.ordinalize.to_s}@ day of the year!
     

     Refresh
    
  ], :format => :eruby
end

A route pattern can take named parameters using the colon + ruby identifier syntax. Any matched parameters are available as instance variables to the page. For example in the parse_date method we are taking the 3 incoming parameters turning them into a String in the format mm/dd/year, parsing the String into a Date object and finally formatting it with strftime. In the template we then print the parsed date and what day of the year it corresponds to as shown in Figure 1.

Figure 1 - Date Route Example

Optional Parameters

Trellis routes can also take optional parameters which should be pre and post-fixed with a question mark (?). For example, you could create a route such as:

route '/?:foo?/?:bar?'

The route above will match ‘/chuck/norris’, ‘/chuck’ and ‘/’ and both ‘foo’ and ‘bar’ will be available to the page as @foo and @bar respectively. In the case of the pattern ‘/chuck/norris’, @foo will be ‘chuck’ and @bar will be ‘norris’. For ‘/chuck’, @foo will be ‘chuck’ and @bar will be nil. While for ‘/’ both @foo and @bar will be nil.

Wildcard Parameters

Trellis page routes also support wildcard parameters via using and asterisk (*). For example a simple catch-all pattern could be expressed as:

route '/*'

Any values captured by the ‘*’ are available in the @splat instance variable which is an array of all captured anonymous parameters. Wildcard parameters can also be mixed with named parameters and absolute paths, for example all the routes below are valid routes:

route '/awesomeness/*/foo/*/*'
route '/mixed/:foo/*'

Also parameters do not need to be delimited only by a forward slash, for example the following pattern is also valid:

route '/downloads/:file.:ext'

Route Sorting

In frameworks with powerful routing capabilities, the order of the route declarations is typically used to determine how they are matched against an incoming request. I felt that this was a somewhat goofy convention. In Trellis routes are sorted according to their complexity. For example, let’s take a look at one of specs for the Trellis router class:

it "should be able to be sorted by 'matchability'" do
  route_1 = Trellis::Router.new(:path => '/hello/:one/:two') 
  route_2 = Trellis::Router.new(:path => '/hello/jim/:last')
  route_3 = Trellis::Router.new(:path => '/hello/*')
  route_4 = Trellis::Router.new(:path => '/hello/*/:foo/*')

  routes = [ route_1, route_2, route_3, route_4 ].sort {|a,b| b.score <=> a.score }

  routes[0].should be(route_4)
  routes[1].should be(route_2)
  routes[2].should be(route_1)
  routes[3].should be(route_3)
end

As you can see route patterns are compiled inside a Router object. Router objects have a score. For the routes above when sorted by score the order ends up being:

'/hello/*/:foo/*'
'/hello/jim/:last'
'/hello/:one/:two'
'/hello/*'

The score value represents the matching power of a route and it is used to try the more specific routes first. For example in any list of routes, the ‘catch all’ route ‘/*’ is always evaluated next to last. The default Trellis route /page[.event[_source]][/value][?query_params] is always evaluated last.

Conclusions

This short article shows the flexibility of Trellis’ page routing scheme. As I mentioned before it is a port of the great work done by the Sinatra framework with some additions of our own. In future installments we will exploit this flexibility to create robust applications with clean “pretty” routes.

Trellis at RubyNation 2010

Wed, 20 Jan 2010 14:55:00 -0500

Brian Sam-Bodden (me) will be giving a presentation on the Trellis Framework at RubyNation this coming April (9-10) in Reston, VA. Check out RubyNation at http://www.rubynation.org

Trellis Tutorial #1 - The HiLo Web Application

Tue, 06 Oct 2009 15:08:00 -0400

Trellis HiLo Game

The Trellis Hilo Game is a simple application where the user guesses a number between one and ten. This example was ‘borrowed’ from the Apache Tapestry project and ported to Trellis.

The simple diagram shows the application’s page flow, which consists of three pages: Start, Guess and Game over.

Figure 1 - Hilo Application Page Flow

The Start page simply provides a link to start guessing. The guessing happens in the Guess page. The Guess page presents the user with ten links for the numbers from 1 to 10. When the user selects incorrectly the page responds with an appropriate message such as “Guess X is too low” or “Guess X is too high”. If the user selects the correct number the application navigates to the GameOver page, which reports how many guesses it took to find the correct answer.

The Application Structure

The HiLo web application structure consists of 1 Ruby file and possibly 3 XHTML templates:

Figure 2 - Trellis Hilo Directory Structure

It is not required that you organized your application as shown but if you want to avoid having to specify your view template locations, Trellis will assume the structure above when searching for a template.

Installing Trellis

gem install trellis

The Trellis Application Class

Let’s start at the beginning and create a Trellis application. Let’s call it HiLoGame and tuck it in a module named Hilo. At the top we’ll require the RubyGems and Trellis Gems and to simplify the code we’ll include the Trellis module:

require 'rubygems'
require 'trellis'

include Trellis

module HiLo
  class HiLoGame < Application
    home :start
  end
end

The class HiLoGame extends Trellis::Application which represents a Web Application composed of one or more pages. Inside the class body the ‘home’ class method is used to declare the home page of the application. That is, the entry point and what the URI ‘/’ will be resolved to. In the case of the HiLoGame application the entry point is indicated by the symbol :start. The Trellis convention is that there will be a Trellis Page class named Start.

The Start Page

The Start page will provide a simple welcome message and a link for the users to start guessing numbers. Let’s start with the view and show the HTML markup:

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
        <title>Hi/Lo Game Start Page</title>
    </head>
    <body>
      <h1>Hi/Lo Guess</h1>
      <p>I'm thinking of a number between one and ten ... </p>
      <p>
        <trellis:action_link>Start guessing</trellis:action_link>
      </p>
    </body>
</html>

Everything in the markup above should be familiar except for the <trellis:action_link> tag. The tag represents one of Trellis’ core components, the ActionLink component. ActionLink is a simple stateless component that provides a hyperlink to trigger an action. The URI produced represents the creation of an event. Events in Trellis have names. The name of the event generated by the ActionLink component is called “select”. Now that we have a template, let’s create the Trellis page class that will serve that template. The Start page is a simple class that extends the Trellis Page class.

  class Start < Page
  end

Launching the Application

Next, let’s add a bit of code so that we can launch the application. In order to run the application we need an instance of HiLoGame for which we will invoke the start() method, as follows:

  web_app = HiLoGame.new
  web_app.start if __FILE__ == $PROGRAM_NAME

Note: The HiLoGame and all page classes are contained inside the HiLo module as well as the two lines above to instantiate and run the application.

With the skeleton page in place and its corresponding template we can now run the application like:

ruby hilo.rb

At the console you should see output similar to (Trellis uses Mongrel by default):

091005 19:51:51 INFO: Starting Trellis Application HiLo::HiLoGame on port 3000 
091005 19:51:51 INFO: watching /Users/bsbodden/Documents/projects/trellis/examples/test/source/../html/ for template changes...

Launch your browser and point it to http://localhost:3000 and you should see the home page of our Hilo application as shown next:

Figure 3 - Trellis Hilo Start Page

On the console we can see the GET request for the root “/” URI:

090921 15:30:22 INFO: 127.0.0.1 - - [21/Sep/2009 15:30:22] "GET / HTTP/1.1" 200 558 0.0025

By now, you probably have already clicked on the “Start Guessing” link and the application has appropriately blown chunks and showed you an error page describing the problem such as:

Figure 4 - Trellis Error Page

Events

The error page indicates that the application could not find a method named on_select(). If you remember I mentioned that the ActionLink component generates an event called ‘select’. When a page gets an event with a name “bacon”, it looks for an event handler method named on_bacon().

Figure 5 - Start Guessing Link

The return value of an event handler method determines where the application will navigate to next. Inside of a page for example, returning ‘self’ will make the application navigate to the same page.

Let’s add a place holder on_select() event handler to the start page and for now let’s just make it navigate back to the start page.

    def on_select
      self
    end

Go back to / or /start to refresh the page. If you hover over the link on the page you can see the URI generated by the ActionLink component. As you can see a page has an /events namespace in which we can ‘drop’ and event. In this case ‘select’. You can see the pattern now: /page/events/event

Component	Event Produced	Event Handler
ActionLink	select	on_select()

Clicking on the “Start Guessing” link again should now take you back to the start page.

By now you have probably noticed that it wasn’t necessary to restart the application after each change. Trellis will detect changes to your application’s code and templates and automatically reload them. We can now navigate to the same page but what we really want to do is navigate to the not-yet-existent Guess page.

Navigating To Other Pages

Trellis pages need to declare any other pages that they might redirect to. To declare the possible page transitions we use the class method ‘pages’. Since the Start page can only navigate to the Guess page, we declare that using the :guess symbol referring to a Guess page that we’ll develop next.

  class Start < Page
    pages :guess

    def on_select
      self
    end
  end

Injected pages such as :guess get their own instance variables (@guess) available to the page. We can change the on_select() event handler to return an instance of the Guess page and also perform some work along the way as shown below:

    def on_select
      @guess.initialize_target
    end

Obviously we haven’t yet implemented the initialize_target() method, hell we don’t even have a Guess page yet!

Stand In Pages

Yet, if you refresh the start page and click the “Start Guessing” link you should see something like:

Figure 6 - Trellis Stand-In Page for Guess

In development mode (which is the default) Trellis will generate synthetic pages or “Stand-In” pages for any injected pages for which it cannot find an implementation. Invoking any method on a stand in page returns the page object itself. In the case of the on_select() method, the return value is the guess page itself, since calling the initialize_target() method will just return the guess page object.

Stand-In pages enable incremental development, you can think of them as virtual scaffolding that automatically fades away as you provide a page’s implementation.

LoneStar RubyConf Presentation PDF

Sat, 29 Aug 2009 11:59:00 -0400

Here’s the PDF for my LoneStar RubyConf session on Trellis http://lonestarrubyconf.com/

trellis.pdf

Trellis 0.0.1 on GitHub

Sat, 29 Aug 2009 11:37:00 -0400

The experimental code base for the Trellis framework is now on GitHUb at

http://github.com/bsbodden/trellis

git://github.com/bsbodden/trellis.git

It is rough around the edges but it embodies the general principles of what I want in a Ruby Component-based Web Framework. It is by no means production ready.

Pivotal Tracker

http://www.pivotaltracker.com/projects/24696

RubyForge Page

http://rubyforge.org/projects/trellis/

Install

gem install trellis

HelloWorld

The simple Hello World example consists of one Application and one Page. The Application defines its home page as the symbol :hello which is resolved to the Home page class. The Home page provides its markup via the template class method which takes a block of Markaby. Finally the application is launched by instantiating the Application object and using the start method (runs on port 3000 by default)

require 'rubygems'
require 'trellis'

module Hello
  class HelloWorld < Trellis::Application
    home :home
  end

  class Home < Trellis::Page
    template do html { body { h1 "Hello World!" }} end
  end
end

Hello::HelloWorld.new.start if __FILE__ == $PROGRAM_NAME