simple_attachments 0.1.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Tsokurov Alex <me@ximik.net>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,132 @@
+= Simple Attachments
+
+Simple Attachments is a plugin for Ruby on Rails 3 which implements complex solution for working with file attachments.
+
+== Requirements
+
+Plugin contains some CSS and JavaScript code, so Asset Pipeline should be switched on (by default).
+Also you need {jQuery library}[http://jquery.com/] to make JavaScript work.
+
+== Installation
+
+Add this to your Gemfile and run the +bundle+ command.
+
+  gem 'simple_attachments'
+
+== Getting Started
+
+Let's say you have a +User+ which has one +Avatar+ and many +Document+.
+The avatar can be change from user edit form. And the avatar data updates only after submiting the form.
+The documents are shown on the same page. They can be managed separately with auto saving all changes in background.
+You can find this app in +test+.
+
+=== Migrations
+
+  class CreateAvatars < ActiveRecord::Migration
+    def change
+      create_table :avatars do |t|
+        t.references :avatar, :null => true
+        t.attachment
+      end
+    end
+  end
+
+  class CreateDocuments < ActiveRecord::Migration
+    def change
+      create_table :documents do |t|
+        t.references :avatar, :null => true
+        t.attachment
+      end
+    end
+  end
+
+*WARNING*: it's important to permit null value for container.
+
+=== Routes
+
+  resources :avatars, :only => [:create, :show, :destroy]
+  resources :documents, :only => [:create, :show, :destroy]
+
+=== Models
+
+  class User < ActiveRecord::Base
+    has_one_attachment :avatar, :dependent => :destroy
+    has_many_attachments :books, :dependent => :destroy
+  end
+
+  class Avatar < ActiveRecord::Base
+    attached_to :user
+    validates_mimetype %w(image/png image/gif image/jpeg)
+    validates_filesize :less_than_or_equal_to => 5e4
+  end
+
+  class Document < ActiveRecord::Base
+    attached_to :user
+    validates_mimetype %w(application/pdf)
+    validates_filesize :less_than_or_equal_to => 20e6
+  end
+
+You can use a lot of options here. Just like with +has_one+, +has_many+ and +belongs_to+.
+
+=== Controllers
+
+  class AvatarsController < ApplicationController
+    attachment_controller
+  end
+
+  class DocumentsController < ApplicationController
+    attachment_controller
+  end
+
+=== View
+
+  <%= form_for @user do |f| %>
+    <%= f.file :avatar, :auto_associate => false %>
+  <% end %>
+
+  <%= files @user, :documents %>
+
+*WARNING*: you also need +csrf_meta_tags+ in your layout to work with +protect_from_forgery+ filter.
+
+=== JavaScript
+
+Plugin doesn't provide any implementation of the file appearance.
+Instead it triggers events, which are easy to handle.
+
+  //= require_self
+  //= require simple_attachments
+
+  $(function() {
+    // Div is loaded and engine is ready.
+    $(".simple_attachments_div").bind("init", function() {
+      // You can add your own init features here.
+    });
+    // New field was created.
+    // Field is a div displaying attachment information.
+    $(".simple_attachments_div").bind("new_field", function(event, field) {
+      // You have to set field in the right place and add binds.
+      field.appendTo(this);
+      // Attachment was loaded
+      // data contains attachment properties and some little support variables
+      field.bind("loaded", function(event, data) {
+        // You have to create and/or set field content here
+        data.destroy_link.appendTo(this);
+        data.attachment_link.html(data.filename).appendTo(this);
+      });
+      // Attachment upload was failed
+      // errors is an array of strings
+      field.bind("failed", function(event, errors) {
+        // You can do something here before field would be deleted
+      });
+    });
+  });
+
+*WARNING*: +simple_attachments.js+ should be required after binds.
+
+=== CSS
+
++simple_attachments.css+ contains some code to decorate default file input. So better require it, but it's not so necessary.
+
+---
+
+(c) 2012 Tsokurov Alex <{me@ximik.net}[mailto:me@ximik.net]>, released under the MIT license

data/lib/simple_attachments.rb

@@ -0,0 +1,15 @@
+# :main: README.rdoc
+
+module SimpleAttachments # :nodoc:
+  class Engine < ::Rails::Engine # :nodoc:
+  end
+end
+
+dir = File.expand_path(File.dirname(__FILE__))
+I18n.load_path << File.join(dir, '..', 'locales', 'en.yml')
+
+require File.join(dir, 'simple_attachments', 'attachment_model')
+require File.join(dir, 'simple_attachments', 'container_model')
+require File.join(dir, 'simple_attachments', 'attachments_controller')
+require File.join(dir, 'simple_attachments', 'view_helpers')
+require File.join(dir, 'simple_attachments', 'migration_helpers')

data/lib/simple_attachments/attachment_model.rb

@@ -0,0 +1,128 @@
+module SimpleAttachments::AttachmentModel
+
+  module Helpers
+
+    # Mark model as attachment and create association.
+    #
+    # Syntax is identical to +belongs_to+.
+    #
+    #   attached_to :post
+    #
+    # Do not use more than one time in one model.
+    # However you can use polymorphic associations.
+    #
+    #   attached_to :container, :polymorphic => true
+
+    def attached_to(name, options = {})
+      reflection = belongs_to name, options
+      self.class.send(:attr_accessor, :container_name)
+      self.container_name = reflection.name
+      before_save :save_file
+      after_destroy :destroy_file
+      send :extend, ClassMethods
+      send :include, InstanceMethods
+    end
+
+  end
+
+  module ClassMethods
+
+    # Validate mimetype of uploaded file.
+    #
+    #   validates_mimetype %w(image/png image/gif image/jpeg), :message => 'should be an image'
+    #
+    # :message is optional.
+
+    def validates_mimetype(types, options = {})
+      options[:message] ||= I18n.t('simple_attachments.mimetype_isnt_allowed')
+      validates :mimetype, :inclusion => { :in => types, :message => options[:message] }
+    end
+
+    # Validate filesize. Syntax is identical to numericality validator. Filesize is given in bytes.
+    #
+    #   validates_filesize :less_than_or_equal_to => 12e6, :message => 'file is too large'
+    #
+    # :message is optional.
+
+    def validates_filesize(options)
+      options[:message] ||= I18n.t('simple_attachments.file_is_too_large')
+      validates :filesize, :numericality => options
+    end
+
+  end
+
+  module InstanceMethods
+
+    # Set file for attachment.
+    # +file+ is +UploadedFile+ object
+
+    def file=(file)
+      if file.nil?
+        uploading_error
+      else
+        @file = file
+        self.mimetype = @file.content_type
+        self.filesize = @file.tempfile.size
+        self.filename = File.basename(@file.original_filename) # old browsers hack
+        self.filepath = file_path
+      end
+    end
+
+    # Generate path to file.
+    # Redefine this method if you want another naming logic.
+
+    def file_path
+      "#{Time.now.to_f}.#{filename}"
+    end
+
+    # Generate full path to file.
+    # Redefine this method if you have another place to hold files.
+
+    def full_file_path
+      Rails.root.join('uploads', filepath).to_s
+    end
+
+    # Save file in the filesystem.
+
+    def save_file
+      File.open(full_file_path, 'w') { |file| file.write @file.read } unless @file.nil?
+    rescue
+      uploading_error
+    end
+
+    # Delete file from the filesystem.
+
+    def destroy_file
+      File.delete full_file_path
+    rescue
+    end
+
+    def serializable_hash # :nodoc:
+      data = super
+      data['filepath'] = path # changing filepath to file url
+      data
+    end
+
+    # Test if attached to any container.
+
+    def attached?
+      not send(self.class.container_name).nil?
+    end
+
+    # Generate error connected to any server problems.
+
+    def uploading_error
+      errors[:base] << I18n.t('simple_attachments.uploading_error')
+    end
+
+    # Get url to the attachment.
+
+    def path
+      Rails.application.routes.url_helpers.send(self.class.to_s.underscore.concat('_path'), id)
+    end
+
+  end
+
+end
+
+ActiveRecord::Base.extend SimpleAttachments::AttachmentModel::Helpers

data/lib/simple_attachments/attachments_controller.rb

@@ -0,0 +1,100 @@
+module SimpleAttachments::AttachmentsController
+
+  module Helpers
+
+    # Mark controller as controller for attachment resource.
+    #
+    # Just put at any place of your controller.
+    #
+    #   attachment_controller
+    #
+    # Sometimes you have to specify your resource manually.
+    #
+    #   attachment_controller :resource => MyNamespace::Attachment
+
+    def attachment_controller(options = {})
+      before_filter :load_attachment, :except => :create
+      self.class.send(:attr_accessor, :attachment_model)
+      self.attachment_model = (options[:resource] or controller_path.classify.constantize)
+      send :include, InstanceMethods
+    end
+
+  end
+
+  module InstanceMethods
+
+    def create # :nodoc:
+      @attachment = self.class.attachment_model.new
+      @attachment.file = params[:file]
+      if @attachment.save and params[:container_id] != 'null'
+        begin
+          container = params[:container_model].classify.constantize.find params[:container_id]
+          associate(container, params[:method])
+          container.save
+        rescue
+          @attachment.uploading_error
+        end
+      end
+      if @attachment.errors.any?
+        succeed = false
+        data = @attachment.errors.messages.values.flatten
+        @attachment.destroy
+      else
+        succeed = true
+        data = @attachment.serializable_hash
+      end
+      render_answer(succeed, data)
+    end
+
+    def show # :nodoc:
+      send_file @attachment.full_file_path, :type => @attachment.mimetype, :filename => @attachment.filename
+    end
+
+    def destroy # :nodoc:
+      @attachment.destroy
+      render :nothing => true
+    end
+
+    private
+
+    # Before filter to load attachment resource.
+    #
+    # If you use another way to load it then just skip this filter.
+    #
+    #   skip_before_filter :load_attachment
+
+    def load_attachment # :doc:
+      @attachment = self.class.attachment_model.find params[:id]
+    rescue
+      raise ActionController::RoutingError.new('Not Found')
+    end
+
+    # Associate attachment with container.
+    # Works only if you use +:auto_associate+ option (switched on by default).
+    #
+    # Redefine it if you want to have some extra control. E.g. CanCan authorization.
+    #
+    #   def associate(container, method)
+    #     authorize! :update, container
+    #     super
+    #   end
+
+    def associate(container, method) # :doc:
+      container.add_attachment method, @attachment
+    end
+
+    # Renders answer for javascript.
+
+    def render_answer(succeed, data) # :nodoc:
+      render :text => {'succeed' => succeed, 'data' => data}.to_json
+    end
+
+    def handle_unverified_request # :nodoc:
+      render :nothing => true
+    end
+
+  end
+
+end
+
+ActionController::Base.extend SimpleAttachments::AttachmentsController::Helpers

data/lib/simple_attachments/container_model.rb

@@ -0,0 +1,73 @@
+module SimpleAttachments::ContainerModel
+
+  module Helpers
+
+    # Mark model as container and create association.
+    #
+    # Syntax is identical to +has_many+.
+    #
+    #   has_many_attachments :attachments
+
+    def has_many_attachments(name, options = {})
+      reflection = has_many name, options
+      send(:define_method, reflection.plural_name + '_=') do |attachment_ids|
+        method, model = recover_vars(__method__)
+        old_attachment_ids = send method.singularize.concat('_ids')
+        attachment_ids = attachment_ids.map { |id| id.to_i }
+        model.destroy_all :id => (old_attachment_ids - attachment_ids)
+        (attachment_ids - old_attachment_ids).each do |attachment_id|
+          find_and_add_attachment(method, model, attachment_id)
+        end
+      end
+      send :include, InstanceMethods
+    end
+
+    # Mark model as container and create association.
+    #
+    # Syntax is identical to +has_one+.
+    #
+    #   has_one_attachment :attachment
+
+    def has_one_attachment(name, options = {})
+      reflection = has_one name, options
+      send(:define_method, reflection.name.to_s + '_=') do |attachment_id|
+        method, model = recover_vars(__method__)
+        find_and_add_attachment(method, model, attachment_id)
+      end
+      send :include, InstanceMethods
+    end
+
+  end
+
+  module InstanceMethods
+
+    def add_attachment(method, attachment) # :nodoc:
+      if reflections[method.to_sym].instance_variable_get :@collection
+        send(method) << attachment
+      else
+        old_attachment = send(method)
+        old_attachment.destroy unless old_attachment.nil?
+        send (method + '='), attachment
+      end
+    end
+
+    private
+
+    def recover_vars(method) # :nodoc:
+      method = method.to_s.chomp('_=')
+      model = reflections[method.to_sym].klass
+      [method, model]
+    end
+
+    def find_and_add_attachment(method, model, attachment_id) # :nodoc:
+      attachment = model.find_by_id attachment_id
+      return if attachment.nil?
+      return if attachment.attached?
+      add_attachment method, attachment
+    end
+
+  end
+
+end
+
+ActiveRecord::Base.extend SimpleAttachments::ContainerModel::Helpers