Domain Specific

Sample Application Using Edge Merb and DataMapper

2008-08-12T05:51:00.001-07:00

Okay, now that you have edge Merb and DataMapper installed, let's create our first app. Pick a directory where you want to put your app, and try the following:

$ merb-gen app sample

You should see "Generating with app generator:" followed by a list of the new directories and files Merb added for you. Change into that directory:

cd sample

and edit the config/init.rb file. Uncomment the DataMapper ORM line:

use_orm :datamapper

and also add a dependencies on merb_helpers and merb-assets:

# ==== Dependencies

# These are some examples of how you might specify dependencies.
# Dependency loading is delayed to a later Merb app
# boot stage, but it may be important when
# another part of your configuration relies on libraries specified
# here.
#
dependencies "merb_helpers", "merb-assets"

Finally, if you want to add query logging from DataMapper, add this to the 'after_app_loads' block:

Merb::BootLoader.after_app_loads do

DataObjects::Mysql.logger = DataObjects::Logger.new('log/dm.log', 0)

end

Now, let's set up our databases:

$ rake dm:db:database_yaml

Rename (or move) the generated config/database.yml.sample file to config/database.yml. Then go ahead and enter the correct values for the setup you want. Here's how I have mine:


development: &defaults
# These are the settings for repository :default
adapter:  mysql
database: sample_development
username: root
password:
host:     localhost

test:
<<:       *defaults        
database: sample_test            

production:        
<<:       *defaults         
database: sample_production

Next, let's create a resource:

merb-gen resource Post title:string body:text created_at:date_time

(NOTE: Run merb-gen with no arguments to see a complete list of generators.)

Make sure that you use 'date_time' and not 'datetime' as you would with ActiveRecord. Otherwise, the created_at field will be assigned the type 'Datetime' (which is wrong), and not the correct 'DateTime'. One other potential gotcha - DataMapper strings will generate a varchar(50) field in MySQL, not varchar(255) like in ActiveRecord.

The merb-gen command will generate a Post model at app/models/post.rb, among other files. Take a look at the file now:

class Post
include DataMapper::Resource

property :title, String
property :body, Text
property :created_at, DateTime

end

You will need to add a property (I put it above the other properties):

property :id, Integer, :serial => true

because DataMapper requires you to explicitly declare the primary key. Next, go ahead and run the migration:

rake dm:db:automigrate

Note that the dm:db:automigrate task is destructive. If you create any posts, then run the task again, the table will be dropped and recreated, causing you to lose your data.

You will also need to edit config/router.rb, because Merb doesn't add the Post resource to the routes automatically:


Merb::Router.prepare do |r|
# RESTful routes
r.resources :posts
end

Now let's take a look at the views (the posts controller at app/controllers/posts.rb should have everything you need from the merb-gen resource command). I modified my app/views/posts/new.html.erb file to look like this:

<h1>New Post</h1>
<%= error_messages_for :post %>

<% form_for(:post, :action => url(:posts) do %>
<%= partial('form', :button_text => 'Create') %>
<% end %>

<%= link_to 'Back', url(:posts) %>

I moved the form elements into a form partial at app/views/posts/_form.html.erb:


<p>
<label for="post_title">Title: </label><br/>
<%= text_control :title %>
</p>
<p>
<label for="post_body">Body: </label><br/>
<%= text_area_control :body %>
</p>
<p>
<%= submit_button button_text %>
</p>

You can probably guess what the edit view looks like.

Let's fire up merb and take a look in the browser:

$ merb

(NOTE: enter 'merb --help' to see a complete list of options to the 'merb' command).

Now open up your favorite browser and navigate to 'http://localhost:4000/posts'. You should see something very like this:

Now go ahead and create your first post!

Edge Merb and DataMapper on Leopard

2008-08-11T13:19:00.001-07:00

After doing this a few times, I decided I'd document my steps for getting edge Merb with DataMapper up and running on a Leopard box. Be forewarned: when working with edge Merb and DataMapper, be prepared to deal with things breaking, at least until Merb gets to 1.0.

First, install the gems that Merb depends on:

$ sudo gem install english erubis hpricot json_pure mime-types rack

Next, install Git. You can try installing Git from source if you want, but MacPorts worked fine for me.

$ sudo port install git-core

Once you have Git installed, head on over to Github to start cloning the various repositories you'll need. I suggest creating one directory where you keep all your Merb-related repositories - I keep mine in ~/dev/merb.

$ git clone git://github.com/sam/extlib.git
$ git clone git://github.com/wycats/merb-core.git
$ git clone git://github.com/wycats/merb-more.git
$ git clone git://github.com/wycats/merb-plugins.git

These are the four main repositories for Merb. As the names suggest, if you wanted to just do barebones Merb hacking, you could get by with just merb-core and skip merb-more and merb-plugins. But in my experience, you're going to want them eventually, so I advise just installing them now.

Now we'll install each gem:

$ cd extlib
$ sudo rake install
$ cd ../merb-core
$ sudo rake install
$ cd ../merb-more
$ sudo rake install
$ cd ../merb-plugins
$ sudo rake install
$ cd ..

Congratulations, you now have edge Merb installed!

Next, let's install edge DataMapper. First, install the addressable gem, a dependency of data_objects:

sudo gem install addressable

Next, change directories back into your top-level Merb directory, if you haven't already by following the instructions above, and clone the necessary repositories.

$ git clone git://github.com/sam/do.git
$ git clone git://github.com/sam/dm-core.git
$ git clone git://github.com/sam/dm-more.git

Now go ahead and install the DataMapper dependencies and gems (NOTE - I got an error related to the PostgresSQL install here, but I don't use it. It may affect you however.):

$ cd do
$ sudo rake install
$ cd ../dm-core
$ sudo rake install
$ cd ../dm-more
$ sudo rake install
$ cd ..

Excellent, now you're ready to create a Merb app on the edge!

5 Rails Tips

2008-05-01T06:52:00.000-07:00

Here's my entry for the Railscasts 100th Episode Contest - hope you find these tips useful.

1. Create SEO friendly URLs for multi-word resources with edge Rails

Let's say you're creating a web application that documents various aspects of computers. Naturally, you're going to want to be like all the cool kids and make your application RESTful. Let's go ahead and create a resource for operating systems:

$ ruby script/generate resource OperatingSystem

When running the app locally, by default you'll find this resource at localhost:3000/operating_systems. But in order to get the best bang for your SEO buck, you should use hyphens in your URLs (http://www.searchenginejournal.com/google-underscores-hyphens/6010/). The solution for edge Rails is to use the :as option to map.resources in config/routes.rb. First, freeze edge Rails into your app:

$ rake rails:freeze:edge

Then, update config/routes.rb with the following:

map.resources :operating_systems, :as => 'operating-systems'

Voila! Now you can browse to your operating system resource at localhost:3000/operating-systems.

2. ActiveResource != ActiveRecord

The team that has worked on ActiveResource has done a great job of making using it as painless as possible. On the surface, consuming a RESTful service seems very similar to using ActiveRecord with a database. It's easy to assume that everything works the same way. Don't fall into that trap.

Make sure you're aware of what's going on behind the scenes. Tail your logs and take a look at the calls that ActiveResource is making. Let's say you write an app that displays the weather, and you have a Forecast model. At first, your app is built using ActiveRecord. You may have a place in your code that calls Forecast.find(:first). This will generate the following call:

SELECT * FROM forecasts LIMIT 1;

After a while, you get tired of typing in the forecast, so you decide to switch to using a web service that does it for you. The only problem is that the same Forecast.find(:first) will generate the following service call:

GET http://url_for_web_service.com/forecasts

That means you're getting all the forecasts, and then ActiveResource is selecting the first one for you. That could be a big problem if there's 10,000 forecasts.

So keep an eye on your logs and be aware of the subtle differences.

3. Working with collections in views

When iterating through a collection in a view, one underused helper is cycle. cycle takes an array parameter with an optional name parameter. The first example in the official Rails documentation suggests using to alternate CSS classes for tables rows:

# Alternate CSS classes for even and odd numbers...
@items = [1,2,3,4]
<table>
<% @items.each do |item| %>
<tr class="<%= cycle("even", "odd") -%>">
<td>item</td>
</tr>
<% end %>
</table>

Another solution for the same problem (if you have an array of numbers) is to make use of ActiveSupport's odd? and even? helpers:

# Alternate CSS classes for even and odd numbers...
@items = [1,2,3,4]
<table>
<% @items.each do |item| %>
<tr class="<%= item.even ? "even" : "odd" -%>">
<td>item</td>
</tr>
<% end %>
</table>

When I need to keep track of the items in the collection, I most often end up using the each_with_index method from Ruby's Enumerable module:

# Alternate CSS classes for even and odd numbers...
@items = [1,2,3,4]
<table>
<% @items.each_with_index do |item, index| %>
<tr class="<%= index.even? ? "even" : "odd" -%>">
<td>item</td>
</tr>
<% end %>
</table>

This technique has the advantage of giving you the index of each item in the collection. This can come in handy when making Ajax calls - you can give the wrapping element an id that corresponds to the item's index:

# Give each table row an id that uses the item's index in the collection
@items = [1,2,3,4]
<table>
<% @items.each_with_index do |item, index| %>
<tr id="item-<%= index %>">
<td>item</td>
</tr>
<% end %>
</table>

You now have the hook you need if you want to delete that table row with a subsequent Ajax call.

4. Keep your gems local, without Edge Rails

Edge Rails has added the ability to explicitly declare your app's gem dependencies in config/environment.rb with the config.gem syntax. See Ryan Daigle's write-up at http://ryandaigle.com/articles/2008/4/1/what-s-new-in-edge-rails-gem-dependencies for a good description of the new functionality. Freeze Edge Rails into your apps and you'll see the following new Rake commands available:

$ rake -D gem

rake gems
List the gems that this rails application depends on

rake gems:build
Build any native extensions for unpacked gems

rake gems:install
Installs all required gems for this application.

rake gems:unpack
Unpacks the specified gem into vendor/gems.

rake rails:freeze:gems
Lock this application to the current gems (by unpacking them into vendor/rails)

Even if you're not ready to use Edge Rails, you can ensure that your app will always have the gem code it depends on available. It's certainly not as clean, and it does take a little more work. Move into your vendor/plugins directory, and for each gem your app depends on, just do:

$ sudo gem unpack <gem name>

This will unpack the given gem into vendor/plugins and ensure that the gem's code will be loaded when your app starts app. It's a nice way to ensure that your app will have everything it needs when, for example, you deploy on a shared host.

5. Keep a summary of your model schema inside the model

One of the nice things about the DataMapper ORM (http://datamapper.org/) is having the model's schema laid out right in the model code. When working with ActiveRecord models, I sometimes find myself returning to old code and forgetting what the schema was. Naturally, you could jump into script/console and do:

>> ModelName.new.attributes

to see what's available. But that doesn't give you the full schema. The solution is Dave Thomas' annotate_models plugin.

$ ruby script/plugin install http://repo.pragprog.com/svn/Public/plugins/annotate_models/

The plugin adds a new rake task for you to generate the model annotations:

$ rake annotate_models

Here's a sample of what the plugin adds to your model:

# Schema version: 3
#
# Table name: programs
#
# id :integer(11) not null, primary key
# title :string(255)
# description :text
# asset_url :string(255)
# link :string(255)
# language :string(255)
# author :string(255)
#

class Program<ActiveRecord::Base
end

Please note that the annotate_models plugin has been enhanced and released as a gem by Cuong Tran, among others. Source code is available at http://github.com/ctran/annotate_models/tree/master, and installation is as simple as:

$ sudo gem install annotate-models

Okay, I said it would be only five tips, but here's one more: get local documentation.

Just about everywhere you go these days, you can find an Internet connection. But just in case, I like to have both Ruby and Rails documentation on my laptop. Download the Ruby documentation here: http://www.ruby-doc.org/downloads and the Rails documentation here: http://www.railsbrain.com.

That's it for this post. Good luck with your next Rails app!