encoded_attachment 0.1.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Nick Ragaz
+
+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.md

@@ -0,0 +1,107 @@
+EncodedAttachment
+=================
+
+This is the bestest and certainly the easiest way to handle file uploads/downloads to [Paperclip](http://github.com/thoughtbot/paperclip)-using Active Record-backed resources using Active Resource.
+
+Rather than trying to create a multipart form submission, it just embeds the file's binary data in the Active Record model's <tt>to_xml</tt>. You can also embed binary data into XML to POST or PUT using Active Resource. These tags will automatically be parsed by Active Record and Active Resource to create files.
+
+
+Usage
+-----
+
+In a Rails application:
+
+    # Gemfile
+    gem "encoded_attachment", :git => "git://github.com/nragaz/encoded_attachment"
+    
+This will load the class methods into both ActiveRecord and ActiveResource. Nothing will really "happen" unless you use the methods described below in your models.
+
+Note that the ActiveRecord code is designed to be used with [Paperclip](http://github.com/thoughtbot/paperclip).
+
+Outside of Rails, the gem can be required directly. It will load itself into ActiveRecord::Base and/or ActiveResource::Base if they have already been loaded. (You can manually include the needed methods using <tt>EncodedAttachment.setup_activerecord</tt> and <tt>EncodedAttachment.setup_activeresource</tt> if you really want to require this gem first.)
+
+
+Functionality
+=============
+
+Active Record
+-------------
+
+Adds a class method called <tt>encode_attachment_in_xml</tt> to Active Record that can be used alongside Paperclip's <tt>has_attached_file</tt> to automatically generate useful and usable binary XML tags for the attachment's original file by wrapping <tt>to_xml</tt>.
+
+These tags will not be generated on new or destroyed records (because the Paperclip file needs to be saved to disk before it is encoded). You can disable file generation at any time using <tt>to_xml(:include_attachments => false)</tt>.
+
+Note that by default, the XML will *not* include Paperclip attributes such as <tt>attachment_file_name</tt>, <tt>attachment_file_size</tt>, <tt>attachment_content_type</tt> and <tt>attachment_updated_at</tt>. The file name and content type are in the XML tag as attributes. Using <tt>to_xml(:include_attachments => false)</tt> will restore these attributes to your XML.
+
+
+Active Resource
+---------------
+
+Adds a class method called <tt>has_encoded_attachment</tt> to Active Resource that generates a schema for the file's attributes and then embeds the file's binary content in <tt>to_xml</tt> if the file has been changed or the record is new.
+
+You can force embedding using <tt>to_xml(:include_attachments => true)</tt>. File setters include <tt>file=</tt> and <tt>file_path=</tt>. MIME types are detected based on the file name.
+
+
+Downloading Files using URLs
+----------------------------
+
+To avoid transmitting huge XML files (particularly in index actions), you can choose to have Active Record send the URL of the file instead of the encoded path using:
+
+    encode_attachment_in_xml :attachment_name, :send_urls => true, :root_url => "http://yourdomain"
+    
+<tt>:root_url</tt> is optional.
+
+You can force the file's binary data to be embedded using <tt>to_xml(:encode_attachments => true)</tt>.
+
+The URL will be downloaded separately by the Active Resource object using the same protocol settings as its native connection (e.g. authentication will be preserved).
+
+There are some limitations to this: your file URL must be on the same domain as the resource's base URL, and the URL must include the file name and extension (e.g. "/images/*rails.png*") for MIME type and file name detection.
+
+There is no support for Active Resource submitting a file URL back to Active Record. Using the <tt>file=</tt> or <tt>file_path=</tt> methods on your Active Resource object will obliterate the <tt>file_url</tt> attribute so that it doesn't appear in your PUT.
+
+Potential use cases include:
+
+    class MyModel < ActiveRecord::Base
+        encode_attachment_in_xml :my_file, :send_urls => true, :root_url => "http://yourdomain"
+    end
+    
+    class MyModelsController < ActionController::Base
+        def index
+            MyModel.all.to_xml # sends URLs
+        end
+    
+        def show
+            MyModel.find(params[:id]).to_xml(:encode_attachments => true) # sends encoded files
+        end
+    end
+
+
+Example
+=======
+
+In Active Record:
+
+    class MyModel < ActiveRecord::Base
+        has_attached_file        :pdf
+        encode_attachment_in_xml :pdf
+    end
+
+    my_model = MyModel.create(:pdf => File.open('example.pdf'))
+    my_model.to_xml => '<my-model>\n<pdf type="file" name="example.pdf" content-type="application/pdf">[binary data]</pdf>\n</my-model>'
+
+
+In Active Resource:
+
+    class MyModelResource < ActiveResource::Base
+        self.element_name = "my_model"
+
+        has_encoded_attachment :pdf
+    end
+
+    my_model_resource = MyModelResource.new.from_xml(my_model.to_xml)
+    my_model_resource.pdf # => <StringIO> containing binary data
+    my_model_resource.save_pdf_as("my_downloaded_file.pdf")
+
+    my_model_resource.pdf = File.open('example-downloaded.pdf')
+    my_model_resource.pdf_file_name # => "example_downloaded.pdf"
+    my_model_resource.pdf_content_type # => "application/pdf"

data/lib/activerecord/base.rb

@@ -0,0 +1,63 @@
+module EncodedAttachment
+  module ActiveRecordClassMethods
+    def encode_attachment_in_xml(name, attachment_options={})
+      attachment_options[:send_urls] = false unless attachment_options[:send_urls]
+      
+      @_attachment_handling ||= {}
+      @_attachment_handling[name] = {}
+      @_attachment_handling[name][:send_urls] = attachment_options[:send_urls]
+      @_attachment_handling[name][:root_url] = attachment_options[:root_url] || nil
+      
+      if attachment_options[:send_urls]
+        # Placeholder method to avoid MethodMissing exceptions on Model.from_xml(Model.to_xml)
+        define_method "#{name}_url=" do |file_url|
+          nil
+        end
+      end
+      
+      define_method "to_xml_with_encoded_#{name}" do |*args|
+        # You can exclude file tags completely by using :include_files => false
+        # If :send_urls => true, force file encoding using :encode => true
+        options, block = args
+        
+        options ||= {}
+        options[:include_attachments] = true unless options.has_key?(:include_attachments)
+        options[:encode_attachments] = false unless options.has_key?(:encode_attachments)
+        options[:procs] ||= []
+        if options[:include_attachments]
+          # strip Paperclip methods
+          options[:except] ||= []
+          options[:except] = (options[:except] + [:"#{name}_file_name", :"#{name}_file_size",
+                                                  :"#{name}_content_type", :"#{name}_updated_at"]).uniq
+          
+          # get URL handling variables if :send_urls => true               
+          send_urls = send(:class).instance_variable_get("@_attachment_handling")[name][:send_urls]
+          root_url = send(:class).instance_variable_get("@_attachment_handling")[name][:root_url] if send_urls
+          
+          options[:procs] << Proc.new { |options, record|
+            file_options = { :type => 'file'}
+            if !(new_record? || frozen?) && send(name).file? && (!(send_urls) || options[:encode_attachments])
+              file_options.merge! :name => send("#{name}_file_name"), :"content-type" => send("#{name}_content_type")
+              options[:builder].tag!(name, file_options) { options[:builder].cdata! EncodedAttachment.encode(send(name)) }
+            elsif !(new_record? || frozen?) && send(name).file? && send_urls
+              file_options.merge! :type => :string
+              url = root_url ? URI.join(root_url, send(name).url(:original, false)) : send(name).url(:original, false)
+              options[:builder].tag! "#{name}_url", url, file_options
+            elsif send_urls && (new_record? || frozen? || !(send(name).file?))
+              file_options.merge! :type => :string, :nil => true
+              options[:builder].tag! "#{name}_url", nil, file_options
+            else
+              # the file can't be included if the record is not persisted yet, because of how Paperclip works
+              file_options.merge! :nil => true
+              options[:builder].tag! name, "", file_options
+            end
+          }
+        end
+        
+        send("to_xml_without_encoded_#{name}", options, &block)
+      end
+      
+      alias_method_chain :to_xml, :"encoded_#{name}"
+    end
+  end
+end

data/lib/activeresource/base.rb

@@ -0,0 +1,118 @@
+module EncodedAttachment
+  module ActiveResourceClassMethods
+    def has_encoded_attachment(name)
+      schema do
+        string    "#{name}_file_name", "#{name}_content_type"
+        integer   "#{name}_file_size"
+        attribute "#{name}_updated_at", "string"
+        attribute name, "string"
+      end
+      
+      define_method "#{name}_updated_at" do
+        Time.parse(attributes["#{name}_updated_at"]) if attributes["#{name}_updated_at"].is_a?(String)
+      end
+      
+      define_method "to_xml_with_encoded_#{name}" do |*args|
+        # Normally, the file's XML is only included if the file has been changed in the resource
+        # using file= or file_path= or file_url=
+        # You can force file tag generation (i.e. even if the file has not changed) by using to_xml(:include_files => true)
+        options, block = args
+        
+        options ||= {}
+        options[:except] ||= []
+        options[:except] = (options[:except] + [:"#{name}", :"#{name}_updated_at", :"#{name}_file_size"]).uniq
+        options[:except] = (options[:except] + [:"#{name}_file_name", :"#{name}_content_type"]).uniq unless send("#{name}_changed?")
+        options[:procs] ||= []
+        
+        options[:procs] << Proc.new { |options, record|
+          file_options = { :type => 'file'}
+          if send("#{name}_changed?") || options[:include_files] || (new_record? && !(send("#{name}").nil?))
+            file_options.merge!   :name => send("#{name}_file_name"), :"content-type" => send("#{name}_content_type")
+            options[:builder].tag!(name, file_options) { options[:builder].cdata! EncodedAttachment.encode_io(send(name)) }
+          elsif send("#{name}_changed?") || options[:include_files]
+            file_options.merge!     :nil => true
+            options[:builder].tag!  name, "", file_options
+          end
+        }
+        
+        send "to_xml_without_encoded_#{name}", options, &block
+      end
+      alias_method_chain :to_xml, :"encoded_#{name}"
+      
+      define_method "load_with_attached_#{name}" do |attrs|
+        attrs = attrs.stringify_keys
+        if attrs.has_key?("#{name}")
+          send "#{name}=", attrs.delete("#{name}"), @attributes.has_key?(name)
+        elsif attrs.has_key?("#{name}_url")
+          send "#{name}_url=", attrs.delete("#{name}_url"), @attributes.has_key?(name)
+        end
+        send "load_without_attached_#{name}", attrs
+      end
+      alias_method_chain :load, :"attached_#{name}"
+
+      # Prevents someone from assigning the attachment attributes directly and skipping the handling methods
+      define_method "attributes=" do |attrs|
+        send :load, attrs
+      end
+
+      define_method "#{name}_changed=" do |bool|
+        instance_variable_set("@#{name}_changed", bool)
+      end
+            
+      define_method "#{name}_changed?" do
+        instance_variable_get("@#{name}_changed") || false
+      end
+      
+      define_method "#{name}_path=" do |file_path|
+        send "#{name}=",              File.open(file_path)
+        send "#{name}_file_name=",    File.basename(file_path)
+        send "#{name}_content_type=", MIME::Types.type_for(File.basename(file_path)).first.content_type
+      end
+      
+      define_method "#{name}_url=" do |*args|
+        file_url, changed = args
+        changed = (changed.nil? || changed) ? true : false
+        if file_url
+          url = URI.parse(file_url.to_s)
+          send "#{name}=",              StringIO.new(connection.get_attachment(url.path,
+                                          'Accept' => send("#{name}_content_type")).body), changed
+          send "#{name}_file_name=",    File.basename(url.path)
+          send "#{name}_content_type=", MIME::Types.type_for(File.basename(url.path)).first.content_type
+        else
+          send "#{name}=",              nil, changed
+        end
+      end
+      
+      define_method "#{name}=" do |*args|
+        io, changed = args
+        changed = (changed.nil? || changed) ? true : false
+        attributes[name] = io
+        if io.respond_to?(:original_filename)
+          send "#{name}_file_name=",    io.original_filename
+          send "#{name}_content_type=", MIME::Types.type_for(io.original_filename).first.content_type
+        elsif io.nil?
+          send "#{name}_file_name=",    nil
+          send "#{name}_content_type=", nil
+        end
+        attributes.delete "#{name}_url"
+        attributes.delete "#{name}_file_size"
+        attributes.delete "#{name}_updated_at"
+        send "#{name}_changed=", changed
+      end
+      
+      define_method "save_#{name}_as" do |*args|
+        raise "File not set - cannot be saved" if attributes[name].nil? || !(attributes[name].respond_to?(:read))
+        path, overwrite = args
+        overwrite = true if overwrite.nil?
+        unless !(overwrite) && File.exist?(path)
+          send(name).pos = 0
+          File.open(path, 'w') { |f| f << send(name).read }
+          return true
+        else
+          raise "File not saved - file already exists at #{path}"
+        end
+      end
+    end
+    
+  end
+end

data/lib/activeresource/connection.rb

@@ -0,0 +1,8 @@
+module EncodedAttachment
+  module ActiveResourceConnectionMethods
+    def get_attachment(path, headers = {})
+      request_headers = build_request_headers(headers, :get, self.site.merge(path))
+      with_auth { request(:get, path, request_headers) }
+    end
+  end
+end

data/lib/encoded_attachment/version.rb

@@ -0,0 +1,3 @@
+module EncodedAttachment
+  VERSION = "0.1.4"
+end

data/lib/encoded_attachment.rb

@@ -0,0 +1,41 @@
+require 'base64'
+
+module EncodedAttachment
+  class << self
+    def encode(attachment, style = :original)
+      encode_io( File.open(attachment.path(style)) )
+    end
+    
+    def encode_io(io)
+      io.pos = 0
+      Base64.encode64(io.read)
+    end
+    
+    def setup_activerecord
+      require File.dirname(__FILE__) + '/activerecord/base'
+      ActiveRecord::Base.extend ActiveRecordClassMethods
+    end
+    
+    def setup_activeresource
+      require File.dirname(__FILE__) + '/activeresource/base'
+      require File.dirname(__FILE__) + '/activeresource/connection'
+      ActiveResource::Base.extend ActiveResourceClassMethods
+      ActiveResource::Connection.send :include, ActiveResourceConnectionMethods
+    end
+  end
+end
+
+# Initialization
+if defined?(Rails::Railtie)
+  ActiveSupport.on_load(:active_record) do
+    EncodedAttachment.setup_activerecord
+  end
+  
+  ActiveSupport.on_load(:active_resource) do
+    EncodedAttachment.setup_activeresource
+  end
+else
+  # Load right away if required outside of Rails initialization
+  EncodedAttachment.setup_activerecord if defined?(ActiveRecord)
+  EncodedAttachment.setup_activeresource if defined?(ActiveResource)
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: encoded_attachment
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 4
+  version: 0.1.4
+platform: ruby
+authors: 
+- Nick Ragaz
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-06-06 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mime-types
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+description: Adds methods to ActiveRecord::Base and ActiveResource::Base to transmit file attachments via REST, either as binary tags in XML or via a separate URL
+email: 
+- nick.ragaz@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/activerecord/base.rb
+- lib/activeresource/base.rb
+- lib/activeresource/connection.rb
+- lib/encoded_attachment/version.rb
+- lib/encoded_attachment.rb
+- LICENSE
+- README.md
+has_rdoc: true
+homepage: http://github.com/nragaz/encoded_attachment
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: encoded_attachment
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Handles downloading and uploading Paperclip attachments using Active Record and Active Resource
+test_files: []
+