The mysterious ways of Ruby

Google-like Search Results Helper

2007-05-10T13:37:00.000+01:00

Representing your search results in a user-friendly way is a common task among web developers. Google's approach is dead simple but really effective. The matching text is highlighted and shown with its context. This can be implemented in less than 20 lines of code which you can include into you helper:

def highlight_text(text, words)
  tokens = strip_tags(text).split
  sections = []
  words.each do |word|
    word = word.downcase
    tokens.each_with_index do |token, i|
      if token.downcase.include? word
        section = tokens[i-10, 20].join(' ')
        words.each do |word|
          section = highlight section, word
        end
        sections << section + ' ... '
        break if sections.size > 3          
      end
    end
  end
  sections.join
end

First we remove the html tags of the text and split the text into tokens. Then we iterate over the search words and for each matching token we generate a section, which contains the highlighted word. This is done until we hav at least 4 sections, which are finally joined and ready to be included into the search result template.

DRY Up Your Url Helpers

2007-04-18T10:07:00.000+01:00

This tutorial shows you how to simplify url generation in combination with RESTful resources by extending the url_for helper. This approach will also work with nested routes and other helpers like form_tag and link_to.

One of the concepts of REST is: each resource has its own unique URI. We will enhance the url_for helper to generate this unique URI for an arbitrary record.

First we need a simple example. We have 2 models: User and Article. For our url generation to work we have to add following code to our models:

class User
  has_many :articles

  def to_params
    {:id => permalink}
  end
end

class Article
  belongs_to :user

  def to_params
    {:user_id => user.permalink, :id => permalink}
  end
end

This is necessary for nested routes to play nicely with our url generation code. We are now able to find the parameters for each record to generate an unique URL.

In a previous post I demonstrated the use of meaningful urls. We are going now the same way.

Users are identified by an URL like:

/users/matthias-georgi

Each user may write articles, which are located at:

/users/matthias-georgi/articles

If I want to write a new article, I will use this URL:

/users/matthias-georgi/articles/new

Editing an existing article would end up on this URL:

/users/matthias-georgi/articles/my-first-post;edit

For nested resources to get working you define in config/routes.rb:

map.resources :users do |user|
  user.resources :articles
end

The traditional way to generate urls is to call the resource helpers:

article_url(article.user, article)

This is redundant, as the article already knows its user.

Add following module into your lib folder and include the module in both your application controller and application helper. The most important bit is the url_for method. It will automatically generate the right url for your resource.

module ResourceHelper

  def plural_class_name(record)
    singular_class_name(record).pluralize
  end

  def singular_class_name(record)
    record.class.name.underscore.tr('/', '_')
  end

  def params_for(record)
    if record.respond_to?(:to_params)
      record.to_params
    else
      {:id => record.to_param}
    end
  end

  def collection_url(collection, record, options)
    if record
      params = params_for(record)
      params["#{singular_class_name(record)}_id".to_sym] = params.delete(:id)
      url_for options.merge(params).merge(:controller => collection)
    else
      url_for options.merge(:controller => collection)
    end
  end

  def member_url(record, options)
    url_for options.merge(params_for(record)).merge(:controller => plural_class_name(record))
  end

  def url_for(*args)
    if [String, Hash].any? {|type| args.first.is_a? type }
      super(*args)
    else
      if args[0].is_a?(Symbol)
        collection_url(args[0], args[1], :action => 'index')
      else
        member_url(args.first, :action => 'show')
      end
    end
  end

  def new_url_for(collection, record=nil)
    collection_url(collection, record, :action => 'new')
  end

  def edit_url_for(record)
    member_url(record, :action => 'edit')
  end

  def path_for(*args)
    if args[0].is_a?(Symbol)
      collection_url(args[0], args[1], :action => 'index', :only_path => true)
    else
      member_url(args.first, :action => 'show', :only_path => true)
    end
  end

  def new_path_for(collection, record=nil)
    collection_url(collection, record, :action => 'new', :only_path => true)
  end

  def edit_path_for(record)
    member_url(record, :action => 'edit', :only_path => true)
  end
end

So how can you use this stuff actually?

It is pretty easy: just pass the record instead of the url hash and the unique url will be generated automatically.

The url of a collection is treated differently. You have to pass the name of the collection, which is the controller name. For nested resources you have to pass additionally the record, the collection is belonging to.

Some examples:

new_path_for(:users)          # => '/users/new'
path_for(user)                # => '/users/harald'
edit_path_for(user)           # => '/users/harald;edit'
path_for(:articles, user)     # => '/users/harald/articles'
new_path_for(:articles, user) # => '/users/harald/articles/new'
path_for(article)             # => '/users/harald/articles/article-1'
edit_path_for(article)        # => '/users/harald/articles/article-1;edit'

# This works for helpers like url_for, form_tag or link_to.

link_to article.title, article
form_tag :articles
form_tag article, :method => 'put'

If anybody is interested I will release this stuff as plugin. I think other helpers could benefit as well as you can pass your records around and each helper may generate the appropriate url.

Pretty RESTful URLs in Rails

2007-04-10T10:36:00.000+01:00

Since Release 1.2 Rails knows to generate RESTful routes. Each resource is identified by an URI, which looks like /users/123 . It would be nice to have more readable URLs, which include the name of the user: /users/matthias-georgi. This is a short tutorial on making your urls pretty while retaining the REST approach. Assuming that you already have an user model, we add following line to our config/routes.rb:

map.resources :users

You may now run the scaffold_resource generator in case you don't have any UsersController yet. In order to remember the permalink for each user, we store it in a column named permalink in the users table. Before we save an user record, we have to infer a url-safe permalink for the user name. We do this by:

def before_save
  self.permalink = name.downcase.gsub(/[^a-z0-9]+/i, '-') if permalink.blank?
end

Each character, which is not an alphanumeric will be replaced by a dash. This is only done, if the permalink is not set already. So we have a way for users to set their permalink manually. To avoid duplicate permalinks, we validate the uniqeness of the permalink:

validates_uniqeness_of :permalink

What happens now, if we browse to a user url like /users/matthias-georgi ? Rails raises an exception, telling us that it cannot find an record with the id matthias-georgi. We'll fix now our controller to look for the permalink and not the id of the user. Just replace each call to User.find(params[:id]) with User.find_by_permalink(params[:id]). Also we have to ensure, that our user routes will be generated correctly. Therefore we overwrite the to_param method:

def to_param
 permalink
end

The effect of this little change is, that user_url(a_user) generates the right url. Nested resources and pretty urls can get tricky and for now I won't touch this topic. Remember that changing the permalink may be problematic as links to the old url will get invalid. Nevertheless have fun experimenting with pretty urls and the new wonderful world of REST.

Building a del.ico.us and flickr sidebar in 5 minutes

2007-04-08T12:37:00.000+01:00

You need a del.icio.us sidebar which shows recent bookmarks or one of these nice flickr badges? This is really is easy as the Typo weblog already includes an flickr and del.icio.us aggregator. Download the files delicous.rb and flickr.rb and drop them into your rails lib folder. Now add these two little helpers to your application_helper.rb:

require 'delicious'
require 'flickr'

def delicious(tag)
 Delicious.new("http://del.icio.us/rss/tag/#{tag}")
end

def flickr(tag)
 FlickrAggregation.new("http://api.flickr.com/services/feeds/photos_public.gne?tags=#{tag}&format=rss_200")
end

We are now able to fetch the feeds for our desired tags with a simple method call. Next step is to render a list of links for our sidebar. I use Markaby for rendering my Rails views. It is easy to type and has a clean syntax. So for rendering the del.icio.us sidebar, you need something like this:

ul {
 delicious(:ruby).items[0,10].each { |item|
   li { a(:href => item.link) { item.title } }
 }
}

This is pretty self-explanatory. We take the first ten items of the del.icio.us feed and for each item we output a list element containing a link to the item. The view for the flickr badge is similar:

ul {
 flickr(:ruby).pics[0,10].each { |pic|
   image_tag pic.square, :size => '48x48'
 }
}

We take the first ten items of the flickr feed and for each item we render an image tag which shows a square thumbnail of the size 48x48. Congratulations, you have just written a del.icio.us and flickr sidebar in 5 minutes using only 18 lines of code. Now you can spend the rest of the day pimping up your sidebar with all kinds of feeds using one of these plugins of the typo weblog.

Fast Auto-completion with Rails, Scriptaculous and JSON

2007-04-04T14:32:00.000+01:00

Inspired by the excellent Rails Recipes book , I created an improved Auto-completion helper, which uses JSON and AJAX instead of a script tag for loading the completions. What we want to achieve is a search field, which pops up immediately, showing us a list of possible completions for our search word. Look at Google Suggest to get an idea. Rails already has an auto_complete_field, which sends an AJAX request for each keystroke. This approach is quite slow, but works in most cases, especially for large datasets auto_complete_field is the better choice. Our idea, stolen from the Rails Recipes book is to fetch the array of possible completions only once. Each keystroke will trigger only a local lookup and need no further server interaction. Scriptaculous already has the right tool for this job: Autocompleter.Local . We will just pass a javascript array of possible completions to the constructor and we're done. OK, let's start. First we need the CSS used by Autocompleter.Local, which styles the choices box:

div.auto_complete {
  width: 350px;
  background: #fff;
}

div.auto_complete ul {
  border:1px solid #888;
  margin:0;
  padding:0;
  width:100%;
  list-style-type:none;
}

div.auto_complete ul li {
  margin:0;
  padding:3px;
}

div.auto_complete ul li.selected {
  background-color: #ffb;
}

div.auto_complete ul strong.highlight {
  color: #800;
  margin:0;
  padding:0;
}

Rails already has an controller macro for generating a auto completion action. We will create a similar macro, which will generate an action, which in turn generates the JSON response. Sounds complex, but the implementation is quite easy. Just add to your ApplicationController:

def self.fast_auto_complete_for(object, method, options = {})
 define_method("auto_complete_for_#{object}_#{method}") do
   render :json => object.to_s.camelize.constantize.find(:all).map(&method).to_json
  end
end

The response of the generated action will now contain a list of all values for the desired attribute. You can use it like in your controllers:

fast_auto_complete_for :sport, :name

Now let us get into the tricky part: the javascript macro helper. How will we get the completion list? Prototype includes the Ajax.Request class, which sends an Ajax Request to our generated action and fetches the array encoded as JSON. Furthermore we have to generate a div which will hold the popup list for our completion entries. Without going into detail, I'll just show you the code, which you can add to your ApplicationHelper:

def fast_auto_complete_field(field_id, options={})
 div_id = "#{field_id}_auto_complete"
 url = options.delete(:url) or raise "url required"
 options = options.merge(:tokens => ',', :frequency => 0 )
 markaby {
   div.auto_complete(:id => div_id) {}
   javascript_tag <<-end
     new Ajax.Request('#{url}', {
       method: 'get',
       onSuccess: function(transport) {
         new Autocompleter.Local('#{field_id}', '#{div_id}', eval(transport.responseText), #{options.to_json});          
       }
     });
    end
  }
end

Note, that I use my simple markaby helper, which I presented in my last post. It is just a little more convenient not to do all this string concatenation. Our helper needs the id for the text field we want to enhance. Based on this id the helper generates the div for presenting the completion entries. It is also required to pass the url of the json action, which is in our case /sports/auto_complete_for_sport_name. Usage example:

form {
 input(:type => 'text', :name => 'name', :id => 'sport_name')
 input(:type => 'submit', :value => 'Search')
}

fast_auto_complete_field :sport_name, :url => '/sports/auto_complete_for_sport_name'

Well, that's it. Now you may enjoy snappy auto-completion and feel good about using bleeding edge technology like AJAX and JSON. By the way, I'm really having a hard time formatting my code snippets here. I use this syntax-highlighter , which just works, as the styles are directly encoded into the span tags. Unfortunately every edit opertion at blogger.com swallows some whitespaces, which is quite annoying. Maybe somebody knows a better way to do this?

Rendering markaby in your helpers

2007-04-02T10:42:00.000+01:00

Generating markup in your rails helpers is a general practice in rails and is used throughout all rails helpers. Normally you use content_tag to generate markup. But often you will encounter situations, where nested tags force you to write ugly helper code like the following helper method from the rails library:

def options_for_select(container, selected = nil)
 container = container.to_a if Hash === container

 options_for_select = container.inject([]) do |options, element|
    if !element.is_a?(String) and element.respond_to?(:first) and element.respond_to?(:last)
     is_selected = ( (selected.respond_to?(:include?) && !selected.is_a?(String) ? selected.include?(element.last) : element.last == selected) )
      if is_selected
       options << "<option value=\"#{html_escape(element.last.to_s)}\" selected=\"selected\">#{html_escape(element.first.to_s)}</option>"
     else
       options << "<option value=\"#{html_escape(element.last.to_s)}\">#{html_escape(element.first.to_s)}</option>"
     end
   else
     is_selected = ( (selected.respond_to?(:include?) && !selected.is_a?(String) ? selected.include?(element) : element == selected) )
     options << ((is_selected) ? "<option value=\"#{html_escape(element.to_s)}\" selected=\"selected\">#{html_escape(element.to_s)}</option>" : "<option value=\"#{html_escape(element.to_s)}\">#{html_escape(element.to_s)}</option>")
   end
  end

 options_for_select.join("\n")
end

We will now rewrite this code with inline markaby. We need therefore the following helper method:

def markaby(&proc)
 assigns = {}
 instance_variables.each do |name|
   assigns[ name[1..-1] ] =  instance_variable_get(name)
  end
 Markaby::Builder.new(assigns, self).capture(&proc)
end

We need to collect the instance variables of the current template and pass a hash of instance variable names along with their values to the markaby builder. As second parameter we pass the current template, so that the builder can access other helper methods. Ok, let's rewrite the options_for_select helper. The method takes an array of values which should be displayed as options. Alternatively you may pass an list of pairs like [['first',1],['second',2] or an Hash, which maps from option labels to their values. One thing I did was to refactor the is_selected test into a lambda. It is cleaner to separate the test and probably more efficient. Inside the loop we are testing , if we have pairs or simple values and generate markup by sending the option method to the builder, which causes the markaby builder to generate an option tag. Tag attributes are defined with a hash, which we pass to the option method. A tag method takes an optional block, which defines the content of a tag, in our case simply the text of the option.

def options_for_select(container, selected = nil)
 container = container.to_a if Hash === container

  if selected.respond_to?(:include?) and !selected.is_a?(String)
   is_selected = lambda { |e| selected.include? e }
  else
   is_selected = lambda { |e| selected == e }
  end

 is_pair = lambda {|e| !e.is_a?(String) and e.respond_to?(:first) and e.respond_to?(:last) }

 markaby do
   container.each do |element|
      if is_pair[element]
        if is_selected[element.last]
         option(:value => element.last, :selected => 'selected') { h element.first }
       else
         option(:value => element.last) { h element.first }
       end
     else
        if is_selected[element]
         option(:value => element, :selected => 'selected') { h element }
       else
         option(:value => element) { h element }
       end
     end
   end
  end
end

Our defined markaby method is even more useful, we can accept a block for our helper method and use it inside the markaby code:

def tasks(&block)
 markaby do
   div.tasks {
     ul {
       markaby(&amp;block)
     }
   }
  end
end

If we have a common pattern like a list of tasks for many templates, we can generate the common code with the tasks method and put the actual tasks in the block:

tasks {
 task 'Back to articles'.t, articles_url
 task :edit, @article
 task :versions, @article
}

So, you can see, there is also a task helper, which is defined as follows:

def task(text, url_or_resource, html_options={})
  if text.is_a? Symbol
   task "#{text.to_s.humanize}".t, {:action => text, :id => url_or_resource}, html_options
  else
   markaby { li { link_to text, url_or_resource, html_options } }
  end
end

If the link text is a symbol, we are going to infer the url from the action name which is the first parameter and the recource, which is the second parameter in this case. Otherwise we generate a list element and delegate the arguments to the link_to helper. By using this simple abstraction, we have hidden the details of task links, which is really DRY. Instead of repeating the same pattern over and over again, we have a common place to decide, how the tasks should look like. Markaby makes it really easy to generate nested structures, as it takes advantage of ruby's block syntax. In a future post I will discuss an advanced form builder, like the one already implemented in Rails, but this time implemented with the help of Markaby. It is even possible to separate form generation and form layouting by using a separate form renderer. So step by, if you want to delve into further Markaby Magic.