Pierlis est une agence parisienne spécialisée dans le développement de web applications, et d’applications de bureau pour MacOSX et iPhone;

Nous recherchons un développeur avec 2 à 10 ans d’expérience pour rejoindre notre équipe de passionnés. Contrat en CDI. Rémunération selon expérience.

• Vous aimez l’autonomie, mais pas l’isolement ?
• Vous aimez la veille technologique et l’innovation ?
• Vous pensez que la carrière d’un développeur expérimenté ne passe par forcément par la case chef de projet ?

N’hésitez pas à nous envoyer un CV. (list at pierlis.com)

Vos compétences

• Vous maîtrisez la conception orientée objet.
• Vous connaissez SQL.
• Vous avez utilisé en production au moins l’un des langages suivant : Ruby, Python, Objective-C,
 C++, Java, C#, Haskell, Erlang.
• Vous avez l’habitude d’utiliser un framework.
• Vous avez une bonne culture générale informatique.
• Vous maîtrisez l’anglais.

Idéalement, vous pratiquez Ruby, ROR (Ruby On Rails), éventuellement Javascript. A défaut, vous avez envie de vous y mettre.

Vos responsabilités

• Développement des projets en cours, en équipe ou de façon autonome selon les cas.
• Qualité du code produit
• Veille technologique
• (...)

Nous sommes basé à Paris dans le 10e arrondissement. Environnement de travail agréable et stimulant. Clients / Projets – Prestigieux / Innovants.

When it comes to image manipulation, most Web Applications make use of ImageMagick, through a connector. (In the ruby world, RMagick). ImageMagick is a decent graphic framework, though it can be quite a time-consuming and error-prone process to go beyond the classical crop/scale/reformat image manipulations. And it is a pain to install, too. In today’s post we’ll build a captcha system. Not that we like captchas at all, but it is quite a good example to enlight our purpose: the use of the Cocoa API from a Ruby On Rails web application. Indeed, we’ll delegate all the graphic code to a brave soldier: Quartz Composer. As you will see, it will drastically lower the lines of code required for our service, and, as usual, the less code, the less bugs.

Important: As you would have guessed, you will need a mac with Leopard and the developer tools installed. No big deal however for most Rails developers.

Setup a Rails application.

From your terminal, type rails captcha to create a new rails Application. We now want to give our Rails Application access to the Quartz Composer API. To do that, add the following at the end of your config/environment.rb file:

Mime::Type.register "image/jpeg", :jpg
# Include your application configuration below
# May Cocoa be with us
require 'osx/cocoa'
include OSX
OSX.require_framework 'Quartz'

Thanks to RubyCocoa bridge (new with Leopard), all Cocoa API is now available to you using the Ruby language. We’ve included the Quartz Framework, that will be necessary for the rendering of our composition.

We have also registered the image/jpeg Mime-type, as we will use that in a respond_to block in our controller.

Create a Quartz Composition for your captcha.

Open Quartz Composer, it should be in /Developer/Applications/ if you installed the developer tools in the standard location. Create your captcha, for example using the “Image With String” generator.

Publish an input by right-clicking on the “String” input of the “Image With String” generator. Name it “Captcha”. This step is important, because we will then be able to pass a hash of parameters to the Quartz composition from our Rails application. “Captcha” will be the key in the parameters hash.

• If you are new to Quartz Composer, read the doc, play with it, it is an awesome “noodle-oriented” development tool.
• If you are lazy, just download our ready-to-run project from the top of the pink sidebar on the right of this page.

Save the composition as RAILS_ROOT/qtz/captcha.qtz.

Now, move on to the code.

Create a Composition model

Create a new file composition.rb in RAILS_ROOT/app/models, and let’s start with the Cocoa fun:

class Composition
  # creates a composition from a .qtz file whose path is qtz_path
  def initialize(qtz_path, width = 350, height = 100)
    @qtz = QCComposition.compositionWithFile(qtz_path)
    raise "Can't find a valid composition at “#{qtz_path}”." if @qtz.nil?
    @renderer = QCRenderer.alloc.initOffScreenWithSize_colorSpace_composition(
                        [width, height],
                        CGColorSpaceCreateWithName(KCGColorSpaceGenericRGB),
                        @qtz)
  end

QCComposition and QCRenderer are two classes defined in the Quartz Framework. If you wan’t to know more, open Xcode, and open the Documentation window from the Help menu.

Have a look at the initOffScreenWithSize_colorSpace_composition method name: pretty long, huh ? Objective-C, the native language of Cocoa, uses named parameters in methods. As ruby does not support that, a convention has been established by the language bridge: replace all colons (:) for underscores (_) in the Objectice-C method signature, to get the Ruby method name. And pass the parameters in the order of the signature. (You can omit the last _). Refer to the Apple Documentation to learn more.

Now move on to rendering :

# renders the composition at time, with parameters, and return the jpeg data.
def render(time = 0, parameters = {})
  # Only pass in parameters expected by the Qtz composition
  input_keys = @qtz.inputKeys
  parameters.each do |key, value|
    @renderer.setValue_forInputKey(value, key) if input_keys.include? key
  end
  # And render the composition
  rendering_ok = @renderer.renderAtTime_arguments(time, nil)
  raise "Unable to render Quartz Composition" unless rendering_ok == 1
  # now convert the result to jpeg
  bitmapRep = @renderer.createSnapshotImageOfType('NSBitmapImageRep')
  jpegimagedata = bitmapRep.representationUsingType_properties(NSJPEGFileType, 
    {NSImageCompressionFactor => 0.8}
    ).rubyString 
end

The language bridge makes a very good work in letting you swap any Objective-C basic structure by its ruby counterpart (and vice-versa). In the above code, we first filter the parameters to make sure the composition accepts them. So we first read the inputKeys dictionary (Objective-C word for Hash) from the composition, and then we fill the hash provided that inputKeys includes the keys from the parameters hash. include? is defined in Ruby’s Hash, but it is ok to call it on an NSDictionary. Thanks, RubyCocoa !

Wrap it up !

Now, we need a resource to wrap-up our stuff. It will generate a jpeg image on the fly with the captcha. Create captchas_controller.rb under RAILS_ROOT/app/controllers/, and write the following:

class CaptchasController < ApplicationController
  def show
    # Read the captcha composition
    captcha = Composition.new(File.join(RAILS_ROOT, 'qtz', 'captcha.qtz'))
    # encode our string (rot13 used here to keep our sample concise:. 
    # think to something robust for any public use - left as an exercise)
    captcha_string = params[:id].tr "A-Za-z", "N-ZA-Mn-za-m"
    # render the captcha
    respond_to do |format|
      format.text { render :text => captcha_string }
      format.jpg  { send_data captcha.render(0, {'Captcha' => captcha_string}), :disposition => 'inline' }
    end
  end
end

As you can see in the source code, you would need some kind of obfuscation to prevent automatic “guessing” of the captcha, but that is out of scope of this tutorial. (We use rot13 here, do not do that for production code !)

Add a map.resources :captchas in config/routes.rb, and edit RAILS_ROOT/public/index.html to make a form with a captcha. For the captcha image, just write: <img src="http://0.0.0.0:3000/captchas/sometext.jpg" alt="captcha" /> and replace sometext with something randomly generated.

You’re done !

Final thoughts

• All graphic code has been delegated to Quartz Composer. Once you get used to it, you’ll appreciate the power of this fantastic tool. Moreover, you can train your favorite graphic designer to use it. It will be easier to generate a new look for each client, without changing your project, as it does not include any single line related to the captcha appearance. And it will look a lot nicer !
• Quartz Composer relies on OpenGL and the graphic card for most of its work, so it is very efficient. Incredibly more than ImageMagick.
• OK, perhaps you don’t host your web apps on a mac. But what about a spare mac that would host several services, like this one, or some other that could be written in just a few lines of Cocoa-Ruby ? Cocoa is a very rich framework, have a look at it ! Examples that come to my mind are: URL-to-PDF service (a dozen of lines), Image filters (QC again)... Tell us what you’ve done with it ! and… Happy new Year !

  Download the complete sample code: captcha.zip

ActiveRecord and high-level model concepts, round 1

When we’re accessing our models, we’re always going through several layers of abstraction. The latest European RailsConf provided us with two sessions, by speakers from prestigious companies, related to that subject. In brief: ActiveRecord is short of one abstraction layer.

Imagine you are developping a CMS, a web site displaying articles. You would have to take care about the content you put online: some articles are not fully written yet, others are waiting for the publishing director’s agreement, etc.

ActiveRecord does not provide you with a standardized way to cope with this “online article” concept. Instead, it helps¹ you to stick at the column level, to think about “those articles whose publication date has been set in some date in the past, and flagged as reviewed by the publishing director, etc. etc.”.

That’s a real pity, since “online article” is a very good concept: it is stable and it is able to hide its actual implementation. Online articles are the only articles that your website will ever display, this is their very essence. And should suddenly Rupert Murdoch’s agreement be required, only the implementation of “online article” would change.

Our own RailsConf Europe 2006 talk focused on an early Pierlis technology named “ModelSearch”. Its purpose was, already, to let you declare Search APIs.

ModelSearch was keen, but Rails has evolved since its birth, we realized that our baby library would not fit well into the directions taken by our favorite framework. It was reluctant to integrate transparently into ActiveRecord, it did not play well with associations, scopes, and definitely wasn’t fancy. It was time to step back a little.

Round 2: SearchAPI

We’re now proud to release the SearchAPI plugin. It’s available on RubyForge, placed under the MIT license, fully documented, tested², and installed via the classic command:

$ script/plugin install svn://rubyforge.org/var/svn/searchapi

SearchAPI extends the expressivity of ActiveRecord’s conditions hashes.

Since Rails 1.2, ActiveRecord’s find method accepts condition hashes, in which all keys are columns.

Article.find(:all,
  :conditions => {
    :author_id => 1,
    :validated_by_publishing_director => true })
# => all articles whose author_id is 1, and validated_by_publishing_director is true

SearchAPI let you extend conditions hashes powers, by defining your own keys.

Article.find(:all, :conditions => { :online => true })
# => all online articles, the SearchAPI way

The cool thing here is that there is no such “online” column.

SearchAPI integrates really nicely with ActiveRecord

SearchAPI allows you to mix conditions:

Article.find(:all,
  :conditions => {
    :online => true,
    :tagged_as => 'rails',
    :author_id => 1 })

Or to use your Search API with associations (or to mix conditions and associations, etc.):

Author.find(:first).articles.find(:all, :conditions => { :online => true })

Declaring a Search API, an example

As usual in computer science, there’s no magic here, but a few lines of code instead. SearchAPI allows you to independently declare the actual ActiveRecord conditions for each one of your own, high-level, search keys.

class Article < ActiveRecord::Base
  belongs_to :author
  has_many :taggings, :dependent => :delete_all
  has_many :tags, :through => :taggings

  # Allows declaration of high-level Search API
  has_search_api

  # Define the online search key
  search :online do |search|
    if search.online
      { :conditions => ["published_on <= ? AND validated_by_publishing_director = ?", Time.now, true]}
    else
      { :conditions => ["published_on > ? OR validated_by_publishing_director = ?", Time.now, false]}
    end
  end

  # Define the tagged_as search key
  search :tagged_as do |search|
    { :include => :tags,
      :conditions => ["tags.name = ?", search.tagged_as]}
  end
end

Let’s dig a little into the code above.

class Article < ActiveRecord::Base
  belongs_to :author
  has_many :taggings, :dependent => :delete_all
  has_many :tags, :through => :taggings

This is the setup of our Article class. It’s designed to let me demonstrate SearchAPI features, especially its integration with associations.

  # Allows declaration of high-level Search API
  has_search_api

As the plugin does not automatically decorate all ActiveRecord classes, the line above is required to declare the article Search API.

  # Define the online condition
  search :online do |search|
    if search.online
      { :conditions => ["published_on <= ? AND validated_by_publishing_director = ?", Time.now, true]}
    else
      { :conditions => ["published_on > ? OR validated_by_publishing_director = ?", Time.now, false]}
    end
  end

This is our first piece of meat: the declaration of the :online parameter of the article Search API.

The search method is added to your class by has_search_api. Its first parameter is the name of the search key that will be implemented in the block.

The block has to return a standard³ ActiveRecord find hash, with its usual :conditions, :include, :join, :order, etc. parameters. This find hash will be merged with others by SearchAPI, and given to ActiveRecord that will process it as it has always done.

Somehow, SearchAPI is a merger of find hashes, nothing more. ActiveRecord is, and remains, the only Rails’ ORM.

Now let’s have a look at the :tagged_as search key:

  # Define the tagged_as condition
  search :tagged_as do |search|
    { :include => :tags,
      :conditions => ["tags.name = ?", search.tagged_as]}
  end

:tagged_as demonstrates how to get the support of associations to define search keys. Using a :join parameter would have been just as correct.

In case you would like to play with above code, you may download a sample application that defines the above models. The console will be your playground, though.

A word about the plugin design

Despite the fact that in the former examples, SearchAPI seems deeply integrated to ActiveRecord, it is not. SearchAPI is definitely one layer above ActiveRecord.

SearchAPI is, actually, built on three components: one that defines what’s a Search API, another that makes such an API able to talk to ActiveRecord through a dedicated bridge, and the last one, which is hardly a component, does nothing more that modifying ActiveRecord so that SearchAPI looks deeply integrated into it – but that’s just an illusion.

Digging around the documentation is not sufficient, but should help you understanding SearchAPI.

Why a public release?

Fame!

There are many discussions about the nature of a Restful search.

In the Rails community, there seem to be a need for a convention upon that subject. This may be caused by the focus on convention over configuration, and the excitement around the edgy ActiveResource.

Honestly, I’m not sure such a convention will eventually emerge.

As a matter of fact, since an ActiveResource server is unlikely to expose directly its database, it has to define, in a way or another, a Search API for its searchable resources. Some people say:

A Restful design pre-defines the useful collections URLs the clients will subscribe to.

This is surely a great design guideline, and no one would complaining if required to download http://server.com/people/ceo.xml, or http://server.com/titles/ceo/people.xml, in order to fetch a list of all CEOs.

Nevertheless, I think that this Restful design may, sometimes, be hard to maintain. Especially if your server should allow its clients to dig into data using several dimensions. Is there any possible convention upon the URL of all 34-years-old female CEOs ?

Maybe http://server.com/people.xml?title=CEO&sex=female&age=34 is not the worse candidate, even if it does not look Restful.

It is, at least, rest-savvy. The SearchAPI plugin, through its ability to define high-level search keys, is able to directly process the parameters of this URL. That’s why it is our contribution to the “restification” of Rails.

Thank you for reading.

Footnotes

¹ The bravest of you will define some class methods or constants that will encapsulate that concept. By doing this, they will still have to fight against ActiveRecord when high level features like associations get involved.

² Testing the plugin requires a host application, in order to setup the test database with test data. SearchAPI has been tested on Rails 1.2.5, 1.2.6 and 2.0.1.

³ Well, not quite standard. We’ve added two features, the first because it’s handy, the last because we needed it.

First, the ["sanitize ?", 'this'] syntax is allowed for all parameters, not only :conditions.

We also introduced the :having parameter. The usual practice is to put SQL HAVING conditions in the :group parameter. But since SearchAPI allows you to define several search keys, it’s possible that several groupings, declared independently, are activated at the same time, and will eventually be merged. This merging wouldn’t be possible without splitting the GROUP BY clause from the HAVING conditions. I hope I’ll be able to publish an example test case that will proove the need for that :having key.

“Super rescue” is not a superhero, it’s a trick for Ruby on Rails developers that, indeed, may rescue you when you’re in trouble.

It involves models’ methods defined like:

class BlogPost < AR::Base
  def language
    super rescue 'en'
  end
end

Yes, that’s actual Ruby.

Generally speaking, it means “attempt to get language in the way of my super class, and if it fails, let’s assume it’s English”.

In practice, Super Rescue is handy when Rails’ rake db:migrate won’t run throughout. The main theme is:

Compatibility with former versions of the database schema

There’s a quite common situation in a Ruby on Rails application that undergoes many iterations : the application code is in sync with the last version of your migrations, not with former ones.

The OMG scenario is the following:

• In a recent migration, you added a brand new model, or a column to another, and you source code reflected this changes by updating a validation, or adding a callback like after_save that does some important stuff.
• In a former migration, you actually fill in the database with initial data (like an initial admin user, or an initial greeting post, whatever).
• You deploy a brand new copy of your application, and trustfully rake db:migrate to setup your brand new empty database.

You see the pattern: as migrations run through from the beginning, they’ll eventually trigger parts of your present code that references columns or models that do not exist yet.

An exception abruptly wakes you up: you encounter the incompatibility-with-former-versions-of-the-database-schema syndrome.

Super rescue to the rescue!

You think your migration complains because a column does not exist (yet)?

That’s not quite the case.

Database columns do help Rails building getter and setter methods in your ActiveRecord subclasses. These methods are the indirect way column values are usually accessed.

So, what really do not exist are ruby methods.

So, let’s fool Rails. The language column does not exist yet in the blog_posts table, er, the language method does not exist yet in the BlogPost class? Take that, Rails!

class BlogPost < AR::Base
  def language
    super rescue 'en'
  end
end

Precisely speaking, it means: “let ActiveRecord handle the database access as usual, but should the column not exit, assume a default value”.

And now your

class BlogPost < AR::Base
  validates_presence_of :language
end

will succeed, even if the column is still to be created by a future migration.

Super rescue getter/setter

The getter/setter pair can be implemented as:

class BlogPost < AR::Base
  def language
    super rescue (@language ||= 'en')
  end
  def language=(value)
    super rescue (@language = value)
  end
end

And now your

class Blog < AR::Base
  has_many :blog_posts
  def after_create
    blog_posts.create(:content => 'This is your first post', :language => 'en')
  end
end

will work like a charm, despite the lack of the language column.

That’s the trick. Simple, effective, and harmless.

It’s not a panacea. It’s unable to handle complex situations. The incompatibility-with-former-versions-of-the-database-schema syndrome lost a battle, not the war.

Thank you for reading.