cropped_paperclip 0.1.0

data/app/assets/javascripts/uploader.js.coffee

@@ -0,0 +1,3 @@
+#= require es5-shim
+#= require cropped_paperclip/filedrop
+#= require cropped_paperclip/upload_crop_scale

data/app/controllers/cropped_paperclip/application_controller.rb

@@ -0,0 +1,4 @@
+module CroppedPaperclip
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/cropped_paperclip/uploads_controller.rb

@@ -0,0 +1,40 @@
+module CroppedPaperclip
+  class UploadsController < ::ApplicationController
+    respond_to :js
+    before_filter :find_upload, :only => [:show, :edit, :destroy]
+    before_filter :build_upload, :only => [:new, :create]
+
+    def show
+      respond_with(@upload)
+    end
+
+    def new
+      render
+    end
+
+    def create
+      @upload.update_attributes(params[:upload])
+      render :partial => 'crop'
+    end
+
+    def edit
+      render :partial => 'crop'
+    end
+  
+    def destroy
+      @upload.destroy
+      respond_with(@upload)
+    end
+
+  private
+  
+    def find_upload
+      @upload = params[:id] == 'latest' || params[:id].blank? ? current_user.last_upload : Upload.find(params[:id])
+    end
+  
+    def build_upload
+      @upload = Upload.create
+    end
+    
+  end
+end

data/app/helpers/cropped_paperclip/application_helper.rb

@@ -0,0 +1,4 @@
+module CroppedPaperclip
+  module ApplicationHelper
+  end
+end

data/app/models/upload.rb

@@ -0,0 +1,119 @@
+# This is a standard upload class that should be useable for most purposes. 
+# We assume that even when the final destination is an S3 bucket, the initial upload
+# will be held locally.
+#
+class Upload < ActiveRecord::Base
+  has_attached_file :file,
+                    :path => ":rails_root/public/system/:class/:attachment/:id/:style/:filename",
+                    :url => "/system/:class/:attachment/:id/:style/:filename",
+                    :processors => lambda { |instance| instance.precrop_processors },
+                    :styles => lambda { |attachment| attachment.instance.precrop_styles }
+
+  attr_accessible :file
+
+  # To change precrop dimensions or other thumbnail properties, just monkeypatch this method.
+  #
+  def precrop_styles
+    {
+      :icon => { :geometry => "40x40#" },
+      :thumb => { :geometry => "100x100#" },
+      :precrop => { :geometry => "1600x3000" }
+    }
+  end
+
+  def precrop_processors
+    [:thumbnail]
+  end
+  
+  validates :file, :attachment_presence => true
+
+  ## Image dimensions
+  #
+  # We need to know dimensions of the precrop image in order to set up the cropping interface, so we
+  # examine the uploaded file before it is flushed.
+  #
+  after_post_process :read_dimensions
+
+  # *original_geometry* returns the discovered dimensions of the uploaded file as a paperclip geometry object.
+  #
+  def original_geometry
+    @original_geometry ||= Paperclip::Geometry.new(original_width, original_height)
+  end
+
+  # *geometry*, given a style name, returns the dimensions of the file if that style were applied. For 
+  # speed we calculate this rather than reading the file, which might be in S3 or some other distant place. 
+  # 
+  # The logic is in [lib/paperclip/geometry_tranformation.rb](/lib/paperclip/geometry_tranformation.html), 
+  # which is a ruby library that mimics the action of imagemagick's convert command.
+  #
+  def geometry(style_name='original')
+    # These calculations are all memoised.
+    @geometry ||= {}
+    begin
+      @geometry[style_name] ||= if style_name.to_s == 'original'
+        # If no style name is given, or it is 'original', we return the original discovered dimensions.
+        original_geometry
+      else
+        # Otherwise, we apply a mock transformation to see what dimensions would result.
+        style = self.file.styles[style_name.to_sym]
+        original_geometry.transformed_by(style.geometry)
+      end
+    rescue Paperclip::TransformationError => e
+      # In case of explosion, we always return the original dimensions so that action can continue.
+      original_geometry
+    end
+  end
+
+  # *width* returns the width of this image in a given style.
+  #
+  def width(style_name='original')
+    geometry(style_name).width.to_i
+  end
+
+  # *height* returns the height of this image in a given style.
+  #
+  def height(style_name='original')
+    geometry(style_name).height.to_i
+  end
+
+  # *square?* returns true if width and height are the same.
+  #
+  def square?(style_name='original')
+    geometry(style_name).square?
+  end
+
+  # *vertical?* returns true if the image, in the given style, is taller than it is wide.
+  #
+  def vertical?(style_name='original')
+    geometry(style_name).vertical?
+  end
+
+  # *horizontal?* returns true if the image, in the given style, is wider than it is tall.
+  #
+  def horizontal?(style_name='original')
+    geometry(style_name).horizontal?
+  end
+
+  # *dimensions_known?* returns true we have managed to discover the dimensions of the original file.
+  #
+  def dimensions_known?
+    original_width? && original_height?
+  end
+  
+private
+
+  # *read_dimensions* is called after post processing to record in the database the original width, height 
+  # and extension of the uploaded file. At this point the file queue will not have been flushed but the upload
+  # should be in place. We grab dimensions from the temp file and calculate thumbnail dimensions later, on demand.
+  #
+  def read_dimensions
+    if file = self.file.queued_for_write[:original]
+      geometry = Paperclip::Geometry.from_file(file)
+      self.original_width = geometry.width
+      self.original_height = geometry.height
+      self.original_extension = File.extname(file.path)
+    end
+    true
+  end
+
+end

data/config/routes.rb

@@ -0,0 +1,3 @@
+Rails.application.routes.draw do
+  resources :uploads, :controller => 'cropped_paperclip/uploads'
+end

data/cropped_paperclip.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "cropped_paperclip/version"
+
+Gem::Specification.new do |s|
+  s.name        = "cropped_paperclip"
+  s.version     = CroppedPaperclip::VERSION
+  s.authors     = ["William Ross"]
+  s.email       = ["will@spanner.org"]
+  s.homepage    = ""
+  s.summary     = %q{A simple but specific way to attach croppable uploads to any model}
+  s.description = %q{Provides a mechanism for uploading, cropping and reusing images in any of your models.}
+
+  s.rubyforge_project = "cropped_paperclip"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency "rails", "~> 3.2.0"
+  s.add_dependency('paperclip', '~> 3.1.0')
+  s.add_dependency('delayed_job_active_record')
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "rspec-rails"
+  s.add_development_dependency "shoulda-matchers"
+  s.add_development_dependency "capybara"
+  s.add_development_dependency "acts_as_fu"
+  s.add_development_dependency "sqlite3"
+  
+end

data/db/migrate/20120510103921_uploads.rb

@@ -0,0 +1,11 @@
+class Uploads < ActiveRecord::Migration
+  def change
+    create_table :uploads do |t|
+      t.has_attached_file :file
+      t.string :original_extension
+      t.integer :original_width
+      t.integer :original_height
+      t.timestamps
+    end
+  end
+end

data/init.rb

@@ -0,0 +1,4 @@
+require File.join(File.dirname(__FILE__), "lib", "cropped_paperclip")
+require 'cropped_paperclip/railtie'
+
+CroppedPaperclip::Railtie.insert

data/lib/cropped_paperclip.rb

@@ -0,0 +1,170 @@
+require "paperclip"
+require "paperclip/validators/attachment_height_validator"
+require "paperclip/validators/attachment_width_validator"
+require "paperclip/geometry_transformation"
+require "paperclip_processors/offset_thumbnail"
+require "cropped_paperclip/engine"
+require 'cropped_paperclip/glue'
+
+module CroppedPaperclip
+  mattr_accessor :attachment_path
+  mattr_accessor :attachment_url
+  attachment_path = ":rails_root/public/system/:class/:attachment/:id/:style/:filename"
+  attachment_url = "/system/:class/:attachment/:id/:style/:filename"
+  
+  # CroppedPaperclip::ClassMethods is included into ActiveRecord::Base in the same way as the Paperclip module. 
+  # It adds a `has_upload` class method that defines an attachment and adds several instance methods 
+  # that will return the values that determine its cropping. Those values are usually but not  
+  # necessarily given by the user.
+  #
+
+  module ClassMethods
+    ## Defining upload columns
+    #
+    # *has_upload* brings in the whole machinery of receiving and cropping an uploaded file. eg.
+    #
+    #   class User < ActiveRecord::Base
+    #     has_upload :avatar, :size => '120x120#'
+    #
+    # The geometry string will always be treated as though it ended in '#'.
+    #
+    # Set the :cropped option to false if you want the file-upload-sharing mechanism but no cropping step. 
+    # In that case any geometry string can be used and it will be passed through intact.
+    #
+    #   class Group < ActiveRecord::Base
+    #     has_upload :icon, :size => '40x40#', :crop => false
+    #
+    def has_upload(attachment_name=:image, options={})
+      unless !table_exists? || column_names.include?("#{attachment_name}_upload_id")
+        raise RuntimeError, "has_upload(#{attachment_name}) called on class #{self.to_s} but we have no #{attachment_name}_upload_id column"
+      end
+
+      options.reverse_merge!(:geometry => "640x960#", :cropped => true, :whiny => true)
+      options[:geometry].sub!(/\D*$/, '') if options[:cropped]
+      # raise here if geometry is not useable
+
+      class_variable_set(:"@@#{attachment_name}_cropped", options[:cropped])
+
+      # The essential step is present in this style definition. It specifies the OffsetThumbnail processor, 
+      # which is similar to the usual thumbnailer but has a more flexible scaling and cropping procedure,
+      # and passes through a couple of callback procs that will return the scaling and cropping arguments
+      # it requires.
+      #
+      crop_style = options[:cropped] == false ? geometry : {
+        :geometry => "#{options[:geometry]}#",
+        :processors => [:offset_thumbnail],
+
+        # The processor will first scale the image to the width that is specified by the scale_width property of the instance
+        :scale => lambda { |att| 
+          width = att.instance.send :"#{attachment_name}_scale_width"
+          "#{width || 0}x"
+        },
+
+        # ...then perform the crop described by the width, height, offset_top and offset_left properties of the instance.
+        :crop_and_offset => lambda { |att| 
+          width, height = options[:geometry].split('x')
+          left = att.instance.send :"#{attachment_name}_offset_left" || 0
+          top = att.instance.send :"#{attachment_name}_offset_top"
+          "%dx%d%+d%+d" % [width, height, -(left  || 0), -(top || 0)]
+        }
+      }
+
+      options[:styles] ||= { :icon => "48x48#" }
+      options[:styles].merge!({:cropped => crop_style})
+
+      ### Upload association
+      #
+      # [uploads](/app/models/upload.html) are the raw image files uploaded by this person. 
+      # They are held separately as the basis for repeatable (and shareable) image assignment.
+      #
+      belongs_to :"#{attachment_name}_upload", :class_name => "Upload"
+      before_save :"read_#{attachment_name}_upload"
+
+      ### Attachment
+      #
+      # Image attachments work in the usual Paperclip way except that the :cropped style is applied differently to each instance.
+      # The editing interface allows the user to upload a picture (which creates an upload object) and choose how it is scaled 
+      # and cropped (which stores values here).
+      # 
+      # The cropped image is created by a [custom processor](/lib/paperclip_processors/offset_thumbnail.html) very similar to 
+      # Paperclip::Thumbnail, but which looks up the scale and crop parameters to calculate the imagemagick transformation.
+      #
+      has_attached_file attachment_name, options
+
+      ## Maintenance
+      #
+      # *read_[name]_upload* is called before_save. If there is a new upload, or any of our scale and crop values are changed, it will assign 
+      # the uploaded file. Even if it's the same file as before, the effect is to trigger post-processing again and apply the current crop and scale values.
+      #
+      define_method :"read_#{attachment_name}_upload" do
+        if self.send(:"reprocess_#{attachment_name}?") && upload = self.send(:"#{attachment_name}_upload")
+          self.send :"#{attachment_name}=", upload.file  
+        end
+      end
+
+      # *reprocess_[name]?* returns true if there have been any changes to the upload association that would necessitate a new crop.
+      #
+      cols = [:upload_id]
+      cols += [:upload_id, :scale_width, :offset_top, :offset_left] if options[:cropped]
+      define_method :"reprocess_#{attachment_name}?" do
+        cols.any? {|col| send(:"#{attachment_name}_#{col}_changed?") }
+      end
+
+      # * [name]_cropped? returns true if the named attachment is cropped on assignment. It can be useful in a form partial.
+      #
+      define_method :"#{attachment_name}_cropped?" do
+        STDERR.puts ">>  #{attachment_name}_cropped?"
+        !!class_variable_get(:"@@#{attachment_name}_cropped")
+      end
+
+      define_method :"#{attachment_name}_for_cropping" do
+        if upload = send(:"#{attachment_name}_upload")
+          # here we introduce a convention that might not stand up
+          STDERR.puts ">>  #{attachment_name}_for_cropping"
+          upload.url(:"#{attachment_name}")
+        end
+      end
+
+    end
+
+    ## Delay post-processing
+
+    def delay_post_processing(attachment_name=:image)
+      send(:"before_#{attachment_name}_post_process", :"defer_#{attachment_name}_post_processing")
+      after_save(:"resume_#{attachment_name}_post_processing")
+
+      # There are too many thumbnail styles in this class. We can't make the user wait while they are processed,
+      # so the whole job of thumbnailing is spun off into a delayed_job. Since the main publication page displays
+      # the :original style, we can show the user her public page while the rest of the thumbnails are still being
+      # processed.
+      #
+      # The usual post_processing routine is abandoned when we return false from this call.
+      #
+      define_method :"defer_#{attachment_name}_post_processing" do
+        if send(:"reprocess_#{attachment_name}?") && !send(:"awaiting_#{attachment_name}_processing?")
+          send(:"awaiting_#{attachment_name}_processing", true)
+          false
+        end
+      end
+
+      # The delayed job is created just by interposing the `delay` method in a call to `process_image_styles!`. The effect
+      # is to serialize this object and that call to the database and resume it later when the job runner picks it up. 
+      # We can't do  that until the publication object has an id, so the call is made from an after_save handler.
+      #
+      define_method :"resume_#{attachment_name}_post_processing" do
+        if send(:"reprocess_#{attachment_name}?") && send(:"awaiting_#{attachment_name}_processing?")
+          self.delay.send(:"process_#{attachment_name}_styles!")
+        end
+      end
+
+      # This is the eventual processing step, to which the delayed job object is just a sort of pointer.
+      # It retrieves the original image from S3 and applies the processing styles.
+      #
+      define_method :"process_#{attachment_name}_styles!" do
+        send(attachment_name).reprocess! 
+        update_column(:"awaiting_#{attachment_name}_processing", false)
+      end
+      
+    end
+  end
+end

data/lib/cropped_paperclip/engine.rb

@@ -0,0 +1,7 @@
+module CroppedPaperclip
+  class Engine < Rails::Engine
+    initializer "cropped_paperclip.integration" do
+      ActiveRecord::Base.send(:include, CroppedPaperclip::Glue)
+    end
+  end
+end

data/lib/cropped_paperclip/glue.rb

@@ -0,0 +1,20 @@
+require 'cropped_paperclip/schema'
+
+module CroppedPaperclip
+  module Glue
+    def self.included base #:nodoc:
+      
+      # Extend ActiveRecord::Base with CroppedPaperclip::ClassMethods, as defined in cropped_paperclip.rb.
+      #
+      base.extend ClassMethods
+
+      # Load migration helpers into all the right places.
+      #
+      if defined?(ActiveRecord)
+        ActiveRecord::ConnectionAdapters::AbstractAdapter.send(:include, CroppedPaperclip::Schema)
+        ActiveRecord::ConnectionAdapters::Table.send(:include, CroppedPaperclip::Schema)
+        ActiveRecord::ConnectionAdapters::TableDefinition.send(:include, CroppedPaperclip::Schema)
+      end
+    end
+  end
+end

data/lib/cropped_paperclip/schema.rb

@@ -0,0 +1,35 @@
+module CroppedPaperclip
+  # Provides helpers that can be used in migrations. 
+  # Copied from, and often makes calls on, the equivalent file in Paperclip.
+  #
+  module Schema
+    UPLOAD_COLUMNS = {
+      :file_name    => :string,
+      :content_type => :string,
+      :file_size    => :integer,
+      :updated_at   => :datetime,
+      :upload_id    => :integer,
+      :scale_width  => :integer,
+      :scale_height => :integer,
+      :offset_left  => :integer,
+      :offset_top   => :integer
+    }
+
+    def self.included(base)
+      ActiveRecord::ConnectionAdapters::Table.send :include, TableDefinition
+      ActiveRecord::ConnectionAdapters::TableDefinition.send :include, TableDefinition
+    end
+
+    module TableDefinition
+      def uploadable_attachment(*attachment_names)
+        attachment_names.each do |attachment_name|
+          UPLOAD_COLUMNS.each_pair do |column_name, column_type|
+            column("#{attachment_name}_#{column_name}", column_type)
+          end
+        end
+      end
+    end
+
+  end
+end
+