arjanvandergaag.nl atom feed

Rails decorator patterns

2012-05-11T13:00:00Z

After spending some time refactoring a collection of decorators in a Rails app recently, I found that most of the decorator methods followed one of a small set of patterns.

These examples use code examples based on the Draper gem, but the concepts should apply to any decorator/presenter/exhibition pattern or library.

1. Linking

One scenario that keeps coming up is wanting to link to an object. Rather than constructing your own using link_to, the decorated model should know how to generate a link to itself:

post = PostDecorator.decorate(post)
post.link # => "<a href='...'>...</a>"

This does not seem all that special for regular objects, but consider nested resources or date-based archives requiring complex arguments:

class PostDecorator < ApplicationDecorator
  def link
    h.link_to title_with_comments, post_path(post, archive_params)
  end

  def title_with_comments
    "#{title} (#{comments_count})"
  end

  def archive_params
    { :month => created_at.month, :year => created_at.year }
  end
end

This logic is best kept out of your view template. It is also better suited for a decorator than a generic helper method. Compare:

post.link
archive_post_link_to(post)

This becomes extra helpful when using delegation:

class AuthorDecorator < ApplicationDecorator
  def link
    h.link_to full_name, model
  end
end

class PostDecorator < ApplicationDecorator
  decorates :post
  decorates_association :author
  delegate :link, :to => :author, :prefix => true
end

post = PostDecorator.decorate(post)
post.author_link # => '<a href="/authors/1">Arjan</a>'

It is a good convention to always have every model be able to generate a sensible link to itself.

2. Filter attribute through helper method

Most custom decorator methods apply a single helper method to the value of an attribute, like applying number_to_currency to a product.price method.

It is easy to write a simple macro for that in the base decorator:

class ApplicationDecorator < Draper::Base
  def self.filter_attributes(*args)
    options = args.extract_options!
    [*args].each do |attr|
      define_method attr do
        h.send(options.fetch(:with), model.send(attr))
      end
    end
  end
end

This allows you to write a decorator like so:

class ProductDecorator < ApplicationDecorator
  filter_attributes :price, :with => :number_to_currency
  filter_attributes :created_at,
                    :published_at,
                    :with => :relative_time_in_words
end

This pattern allows you to write generic helper modules that can be used anywhere containing the logic you wish to use. The decorator then takes care of consistently applying it.

Note that it is probably best to get rid of your ApplicationHelper and not generate any helpers for your controllers either. Its best to group your helpers in sensibly named modules rather than by controller or in one big junk drawer.

3. Translate attribute values

Attributes commonly contain values that need to be localized, like a status column (e.g. ‘published’, ‘draft’, etc.). A decorator method would then usually look like this:

class PostDecorator < ApplicationDecorator
  def state
    h.t('activerecord.attributes.post.states').fetch state.to_sym
  end
end

This is pretty tedious. A macro would help clarify intent, so we can create something like the following:

class ApplicationDecorator < Draper::Base
  def self.translate_attributes(translations = {})
    translations.each do |attribute, key|
      define_method attribute do
        h.t(key).fetch model.send(attribute).to_s.to_sym
      end
    end
  end
end

This allows us to declare that an attribute value should be translated:

class PostDecorator < ApplicationDecorator
  translate_attributes {
      :state => 'activerecord.attributes.post.states'
  }
end

With the accompanying translation file:

nl:
  activerecord:
    attributes:
      post:
        states:
          published: Gepubliceerd
          draft: Concept
          scheduled: Gepland

Mix and match

These macros do not cover all use cases and do not allow easy mixing and matching. When you find yourself wanting to combine such macros on a single attribute, you are probably better off writing an explicit method.

Introducing Rpub, a simple ePub generation library

2012-05-01T10:00:00Z

I am writing a book. A little book, but a book nonetheless. And when I started writing it, I knew I wanted to publish it as an ebook and write in Markdown. I found no easy solution to facilitate that, so I wrote my own.

Rpub is a very simple Ruby gem for converting a set of markdown input files into an ebook in .epub format. It is simple because it doesn’t do much:

it converts the markdown files to HTML using Kramdown;
it combines the HTML files together with any referenced images and fonts into a .zip archive, together with some XML boilerplate files.

Additionally, it provides some helper functions to make life a little easier:

a package task to combine the .epub file with an arbitrary number of other files (e.g. a license or README) into a single archive for online distribution;
a preview task for generating a single HTML page for easy previewing-as-you-write.
a statistics task for counting words and stuff.
it can generate a table of contents for you based on headers in your text.

Configuration

As valid .epub files require some metadata, a config.yml file is needed to generate your book. It is needed to specify book title, author, publisher, subject and all that malarkey. You can also use it to specify the cover image you want to use for the book or what files to include in the package.

The gem comes with default HTML and CSS files for layout, but you can easily override them. Using the generate task you can copy these files into your current project and tweak them to your taste.

Secret features

Because markdown files are converted using Kramdown, we get a few nice extra features:

footnotes
syntax highlighting of code samples
automatic header ids
abbreviations

Find out more about those in the Kramdown documentation.

Getting started

Rpub is distributed as a Ruby gem, so getting started is easy. Once you’ve got a working installation of Ruby and Ruby Gems set up, you can install Rpub:

$ gem install rpub

Then create a new directory for your project, write your next great novel in a .md file per chapter and set the title and author in a config.yml file:

---
creator: Arjan van der Gaag
language: en
version: 1.0.0
title: Absolutism in 18th century Cleves
publisher: Me!
subject: History
rights: copyright 2012. All rights reserved.
description: My awesome history thesis.

That should do it. Compile your ebook:

$ rpub compile

…and a new absolutism-in-the-18th-centruy-1.0.0.epub file will appear in your current directory. Open it in iBooks on your iPad or use an ebook reader on your computer and bask in your self-publishing glory.

Contribute

Take the gem for a spin and report any issues you find on the Github issues tracker. Or better yet, fork it and send it some pull request love.

Presentation: Getting started with ruby

2012-04-24T10:00:00Z

I gave a lightning talk about using the ruby program the other day at Eindhoven.rb, the Ruby user group for the Eindhoven area.

Ruby is a programming language, and ruby is the program you invoke it with. It takes some interesting arguments that enable you to use it as a general-purpose command line scripting solution – traditionally the domain of Perl.

In my slides I go over most of the options and some common use cases, so flip through them. Being a lightning talk, there wasn’t time to review these features in-depth, but Programming Ruby 1.9 is a great reference book to find out more.

The slides at Speakerdeck do not contain any presenter notes, but there is actually a video recording available. Check it out:

A Ruby gem for the bol.com developer API

2012-02-02T12:30:00Z

It has bugged me for a long time that I could not access product information from bol.com the same way I could from Amazon.com. When bol.com released their public API some time ago, I still couldn’t. Not easily. So I wrote a Ruby library for the Bol.com API.

The bol.com API allows you to fetch detailed information for common products, such as books, DVDs and toys, search for products by keyword, or list bestsellers. The API is not too complex: it’s just a handful of endpoints, a couple of available query parameters and a request signature.

I built a wrapper around this API that exposes the available operations and handles the difficult parts of request signing and XML parsing. All you, as the developer, have to do is provide the access credentials. All operations give you nice, clean Ruby objects back, such as a Bol::Product.

Getting started

You need to sign up for a developer account first. When your account has been approved, you can request an API key. The key has two parts – one public, one secret – that will be used by bol.com to make sure you really are who you say you are when you make a request.

Once you have both your access key and its secret, you can get started by installing the Ruby gem:

$ gem install bol

An example application

Let’s create a very simple Sinatra application to search the bol.com store (see the completed app in one file). Create an application file app.rb:

require 'sinatra'

get '/' do
  erb :search
end

Add a simple form view:

<form method="post" action="/search">
  <label>Query: <input type="text" name="q"></label>
  <input type="submit">
</form>

Run the app to confirm everything works:

$ ruby -rubygems app.rb

When you browse to http://localhost:4567 you can see the search page, but it doesn’t do anything yet. Let’s add a search action:

post '/search' do
  @products = []
  erb :results
end

And a view to display results:

<ol>
<% @products.each do |product| %>
  <li><%= product.title %></li>
<% end %>
</ol>

Implementing search

We’ve added a /search route that will somehow set an array of products, and then render them to an ordered list on the page. Simple enough. Now to actually search some products:

post '/search' do
  @products = Bol.search params[:q]      
  erb :results
end

Searching the bol.com website is as easy as Bol.search(params[:q]). Restart the app, and try it out. You will get an error, complaining that the gem is not properly configured. We need to provide our access key and its secret, so they can be used to sign our requests:

Bol.configure do |c|
  c.access_key = '123456789'
  c.secret     = 'abcdefghi'
end

When you restart the application, you should be able to search bol.com by keyword and get a list of titles back.

Showing product details

Let’s go one step further and add some product details. We’ll create a new route for that:

get '/product/:id' do
  @product = Bol::Product.find params[:id]
  erb :product
end

We can use Product#find to find a particular product on bol.com by its internal ID. We’ll create a link to the detail page in our search results:

<ol>
<% @products.each do |product| %>
  <li>
    <a href="/product/<%= product.id %>">
      <%= product.title %>
    </a>
  </li>
<% end %>
</ol>

We also need a view for our new action:

<h1><%= @product.title %></h1>
<dl>
  <% @product.attributes.each_pair do |k, v| %>
  <dt><%= k %></dt>
  <dd><pre><%= v %></pre></dd>
  <% end %>
</dl>

Restart the app, perform a search and click on a result. You should see all available product details. Note that there are several sizes of cover image available, and that the author attribute is an Array – there can be more than one, after all.

Scoping search results to categories

Now we want to limit our search results to a particular category of products. Bol.com products are extensively categorized and we can look up those categories and search in them. Let’s add a drop-down list of categories to search to our search form:

get '/' do
  @categories = Bol.categories
  erb :search
end

post '/search' do
  @products = Bol::Scope.new(params[:category_id])
    .search params[:q]      
  erb :results
end

And in the view:

<form method="post" action="/search">
  <select name="category_id">
    <% @categories.each do |category| %>
    <option value="<%= category.id %>">
      <%= category.name %> (<%= category.count %>)
    </option>
    <% end %>
  </select>
  <input type="text" name="q">
  <input type="submit">
</form>

Once we’ve reloaded the application, we can choose a category to search in and get results limited to that category. Categories are nested, so you can get subcategories using Bol::Scope.new(some_id).categories. And there are also refinements, such as groupings by price or brand and other attributes, but they work similarly to categories.

Referral links

Then only referral links remain. It is a good idea to link to products on bol.com, so you can get a kickback on any sales resulting from the traffic you send over. This is not strictly a feature of the developer API, but it is so commonly used, I just threw it in here. You can simply ask a product for its referral URL, given a specific referral ID:

product = Bol.find(params[:id])
product.referral_link('my-site-id')
# => "http://..."

Other features

This example application showcases the basics of the bol gem, but it includes some more:

Ordering and limiting of number of results
Automatic pagination
Joining and subtracting categories and refinements to create complex scopes
List popular or bestselling products

See the project README file for more information.

Example application and source code

That’s all you need to know to get started. You can see the entire example application in this gist. You can find the source for this Ruby gem on Github, where I also keep the API documentation and track issues. The gem is still in beta stage, so it can be field-tested before getting an actual stamp-of-approval by releasing a version 1.0. Try it out and do let me know if you make anything awesome with it!

Shell scripting to the rescue

2012-01-19T19:00:00Z

I love Ruby and tend to use it for everything I can use it for. But I’ve reading up on Unix recently, and I decided to test my newfound knowledge by using standard unix programs to solve a problem. Those who do not know Unix are doomed to re-implement it badly (or so I have been told).

I needed to copy a lot of images from a remote server to my local machine. Since images were constantly being added to the remote server, I wanted to have a repeatable script to download only those images that were listed in a YAML file from another application. So I needed to read the YAML file, find the files listed inside it, and collect those in an archive for easy downloading.

01. Reading input

My input file was in YAML, so the first step is reading that. But since the file is several thousand lines long, we pipe it into head to just print the first few lines:

$ cat images.yml | head
---
- http://host.tld/images/image1.jpg
- http://host.tld/images/image2.jpg
...

The first problem was the first line of three dashes, which I needed to get rid of. Using sed you can actually issue ex commands like in Vim, so this was easy:

$ cat images.yml | sed '1d' | head
- http://host.tld/images/image1.jpg
- http://host.tld/images/image2.jpg
- http://flickr.com/images/image3.jpg
...

This deletes line one, but there’s a saying along the lines of: “if you cat a file and immediately pipe it into something else, something’s wrong”. So, I rewrote it like so:

$ sed 'd' images.yml | head

02. “Parsing” YAML

Then, I needed to get rid of the YAML array element indicators – the dashes starting each line. I could have used sed for that, but I chose cut, which extracts fields from a line, splitting the line on a given delimited into columns. I wanted the second column with a space as delimiter:

$ sed 'd' images.yml | cut -d' ' -f 2 | head
http://host.tld/images/image1.jpg
http://host.tld/images/image2.jpg
http://flickr.com/images/image3.jpg
…

This was starting to look useful.

03. Getting just the image path

There was a problem with the images: all images contained the full URL, and I wanted to get just the path. sed to the rescue, again:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  sed 's|http://host.tld/||' |\
  head
images/image1.jpg
images/image2.jpg
http://flickr.com/images/image3.jpg

This time, I used a replacement pattern as we would in Vim, only replacing the standard / separator with a | to not have to escape every / in the search string.

04. Getting rid of externally hosted images

This left the problem of externally hosted images. I just gave up on those. Getting rid of those sounded like a task for grep, which can be used to exclude lines matching a pattern:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  sed 's|http://host.tld/||' |\
  grep -v "flickr" |\
  head
images/image1.jpg
images/image2.jpg
http://amazon.com/images/image4.jpg

This gives a new problem: there are several different external hosts in the file. I only wanted our own. I decided to rewrite the command and use grep to filter out all lines that do contain our own host, and then remove the domain:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  grep "http://host.tld" |\
  sed 's|http://host.tld/||' |\
  head
images/image1.jpg
images/image2.jpg
images/image5.jpg

05. Combining files into an archive

The next task was to zip up all those files into one big archive for easy downloading from the server to my local machine.

The first idea was to just dump the whole lot into zip, like so:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  grep "http://host.tld" |\
  sed 's|http://host.tld/||' |\
  zip dump.zip

Alas, that doesn’t work. I started investigating possible solutions, such as using xargs – which mashes a bunch of lines into a single line and feed them as arguments to another program, with some intelligence about the number of arguments a program accepts. After some fiddling, I got frustrated that zip just didn’t read filenames from standard input, so I finally decided to open the zip manual with man zip. Searching the manual for stdin, I found out zip indeed does not read input filenames from standard input by default, but On Mac OS X, there’s the --names-stdin option, while on most other systems there’s -@. There you go, it pays to RTFM.

So, the entire command now looks like this:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  grep "http://host.tld" |\
  sed 's|http://host.tld/||' |\
  zip dump.zip -@

This does what I wanted it to do quite nicely, but I figured I could do slightly better.

06. Duplicates and thumbnails

One problem was a lot of duplicate images; another was lots of different sizes of the same image – with the original one the only I care about.

Solving duplicates is easy enough using the uniq program:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  grep "http://host.tld" |\
  sed 's|http://host.tld/||' |\
  uniq |\
  zip dump.zip -@

Then, I want to only use the original image, not the generated thumbnails. I happened to know that generated thumbnails have filenames like original-filename-150x75.jpg. Removing the dimensions at the end of the filename would give me the regular file. My list could very well contain that original file already, but uniq would sort that out. So, there’s one more sed to add:

$ sed 'd' images.yml | \
  cut -d' ' -f 2 | \
  grep "http://host.tld" |\
  sed 's|http://host.tld/||' |\
  sed 's/-\d+x\d+\.jpg/.jpg/' |\
  uniq |\
  zip -9 dump.zip -@

That gave me a dump archive file containing all my images. As I was happy with the result, I tacked on a -9 to enable maximum compression for the archive, shaving a couple of percentage points of the end result file size.

Conclusion

This post might seem long, but the process of developing this command chain was actually rather quick. Feedback is almost instant and there’s a rich collection of tools to get the job done. I’m pretty sure developing a Ruby script doing the same thing would have involved more manual tweaking and looking up documentation.