An easy extension for Paperclip to crop your image uploads using jCrop.

Include papercrop in your Gemfile or install it by hand

gem install papercrop

You need to add the required files in your assets...

In your application.js

//= require jquery
//= require jquery.jcrop
//= require papercrop

In your application.css

*= require jquery.jcrop

You are a few steps away to start cropping attachments. Let's start with the model, a user with avatar:

has_attached_file :avatar, :styles => {:thumb => '50x50', :medium => '100x100'}
crop_attached_file :avatar

By default, the crop area and the preview box will have an aspect ratio of 1:1. You can modify that by passing a new aspect.

crop_attached_file :snapshot, :aspect => "16:9"

On the controller you can render a view after user creation, create a simple crop action, etc... whatever you like the most. Inside the form of a user with persisted avatar:

<%= form_for @user do |f| %>
  <%= f.cropbox :avatar %>
  <%= f.crop_preview :avatar %>
  <%= f.submit 'Save' %>
<% end %>

Both helpers accept a :width option to customize their dimensions. The preview box has width 100 by default but the cropbox is unlimited in size (takes the original image width), so setting the cropbox width is interesting to avoid layout breaks with huge images. :width is an alias for :box_width

<%= form_for @user do |f| %>
  <%= f.cropbox :avatar, :width => 500 %>
  <%= f.crop_preview :avatar, :width => 150 %>
  <%= f.submit 'Save' %>
<% end %>

Regardless of the width, the preview box and the cropping area will have the aspect ratio defined in the model (1:1 by default)

If you're rendering it on ajax ensure to call init_papercrop() in js after loading the crop form to make things work properly.

To allow rails to save changes in your controller, you need to permit the fields papercrop uses. For example, if your model with the attached image is named user and the attachment is named avatar:

params.require(:user).permit(
  :avatar, 
  :avatar_original_w, 
  :avatar_original_h,
  :avatar_crop_x, 
  :avatar_crop_y, 
  :avatar_crop_w, 
  :avatar_crop_h
)

Unlock aspect ratio

You can unlock the aspect ratio if you pass false as argument. :aspect is an alias for :aspect_ratio. NOTE: preview will be disabled

crop_attached_file :snapshot, :aspect => false

More Jcrop options

Regardless the model, you can always redefine/unlock aspect from the helper if you need to.

f.cropbox :snapshot, :box_width => 500, :aspect_ratio => 4.0/3.0

Or set an initial selection area.

f.cropbox :snapshot, :set_select => [50, 50, 400, 300]

See more options at JCrop official site

Chaining processors

Maybe you want to chain some custom processors to do amazing effects like crop+rotate images. Papercrop will add its processor in last place unless you declare it in the attachment definition

has_attached_file :landscape, :styles => {:big => '2000x1500'}, 
                              :processors => [:papercrop, :rotator]

We are using dummy applications to handle some of our test cases with different Gemfiles using Appraisal. You can find them in the /test_apps directory and should be able to run them as a regular Rails app (using the rails s command) if you're interested in taking a look. You may need to create mock databases for the test_apps before your tests will start to pass. This means you need to run the classics rake db:create db:migrate db:test:prepare through appraisal from the root directory.

appraisal rails_3_2 rake db:create db:migrate
appraisal rails_4 rake db:create db:migrate

Append RAILS_ENV=test to both commands to prepare each database for testing

In order to fully test our gem, we needed to use the Poltergeist gem and PhantomJS. Getting this setup is beyond the scope of this Readme.

Once you have everything setup, you should be able to execute appraisal rake from the root directory have everything run.

That's all!

• Thoughtbot's Paperclip
• Deep Liquid's JCrop
• And Ryan Bates' Railscast#182, which has inspired this gem