h1. Imaginable

Imaginable is a gem for Rails, which allows easy integration with the Imagination image-upload and scaling server.

h2. Compatibility

Imaginable is currently only compatible with Rails 3

h2. Installation

Simply add Imaginable to your Gemfile and bundle it up:

<pre>
  gem 'imaginable'
</pre>

Then run the generator to copy some javascript and a configuration initializer into your application:

<pre>
  $ rails generate imaginable:install 
</pre>

h2. Usage

It is really easy to make a model Imaginable.

If you are creating a new model, there are even some handy migration helpers.

<pre>
  class CreateArticles < ActiveRecord::Migration
    def self.up
      create_table :articles do |t|
        t.string :title
        t.text :body
        t.imaginable :photo
        t.timestamps
      end
    end

    def self.down
      drop_table :articles
    end
  end
</pre>

The @t.imaginable@ helper above, will create two columns: @photo_uuid@ and @photo_token@ which Imaginable needs to keep track of the images used by this model.

We then need to mark our model as Imaginable

<pre>
  class Article < ActiveRecord::Base
    has_imagination :photo
  end
</pre>

Finally we just need to add a field to our form, which let's the user upload a photo. This is also really easy thanks to the form helper:

<pre>
  <%= form_for(@article) do |f| %>
    <div class="field">
      <%= f.label :title %><br />
      <%= f.text_field :title %>
    </div>
    <div class="field">
      <%= f.label :body %><br />
      <%= f.text_area :body %>
    </div>
    <div class="field">
      <%= f.label :photo %><br />
      <%= f.image_field :photo %>
    </div>
    <div class="actions">
      <%= f.submit %>
    </div>
  <% end %>
</pre>

Please note, that you need to include the Imaginable javascripts in your layout, or by other means.
Here is an example of what you could do, if you had a @yield(:head)@ in the @head@ section of your layout:

<pre>
  <% content_for(:head) do %>
    <%= javascript_include_tag 'plupload.full.min' %>
    <%= javascript_include_tag 'imaginable' %>
  <% end %>
</pre>

That's all there is to it!

h2. Validation

If you require the user to upload an image, you can use this handy validation helper.

<pre>
  class Article < ActiveRecord::Base

    has_imagination :photo

    validates_presence_of :title
    validates_presence_of :body
    validates_imagination

  end
</pre>

h2. Showing images

To show an image, you simply call the imaginable method of your model.
The method will have the name that you have configured in your model.
In the above examples, this would be @@article.photo@.

<pre>
  <%= image_tag @article.photo.url(:width => 500) %>
</pre>