progstr-filer 0.8.1 → 0.8.2

data/README.md

@@ -0,0 +1,107 @@
+Progstr Filer is a developer-friendly file hosting platform built specifically for web apps. It lets you easily associate file attachments with your ActiveRecord models and removes the hassle of actually hosting the files yourself.
+
+### Setting up the Ruby gem
+
+Bundler makes that all too easy - add this line to your `Gemfile` to have the gem pulled into your app and required automatically.
+
+
+    gem "progstr-filer", :require => "progstr-filer"
+
+
+### Credentials
+
+Progstr Filer uses two keys similar to Amazon's cloud services. The access key is a public string that gets rendered publicly in URL's and web pages. We use it to identify your account. The secret key is used to sign and encrypt sensitive data. You should keep it, well, secret.
+
+Provisioning your add-on with Heroku gets you two environment variables: `PROGSTR_FILER_ACCESS_KEY` and `PROGSTR_FILER_SECRET_KEY`. Add those to your `config/environments/production.rb` file:
+
+    Progstr::Filer.access_key = ENV['PROGSTR_FILER_ACCESS_KEY']
+    Progstr::Filer.secret_key = ENV['PROGSTR_FILER_SECRET_KEY']
+ 
+
+### Defining an uploader
+
+Every attachment can have a specific set of options that take effect while uploading and manipulating it. Those settings get configured via your own class that will extend `Progstr::Filer::Uploader`. You could store uploader classes in your `app/uploaders` folder. Here is a sample class:
+
+    class AvatarUploader < Progstr::Filer::Uploader
+      #uploader options
+    end
+
+
+### Associating uploaders with your models
+
+Progstr Filer extends ActiveRecord models and lets you use the `has_file` method in class definitions. Here is a User model class that has an avatar image managed as a Progstr Filer attachment via its `avatar` property:
+
+    class User < ActiveRecord::Base
+        has_file :avatar, AvatarUploader
+    end
+
+
+Note: make sure your database table has an `avatar` column created already. Future versions of the `progstr-filer` gem will let you generate migrations automatically.
+
+### Feeding data to your uploaders
+
+That is easy - all you need is assign a Ruby File object to the uploader property and save the model object:
+
+    @user.avatar = uploaded_image_file
+    @user.avatar.save 
+
+
+Rails can get most of the job done for you automatically if you create a file upload form:
+
+    <div class="field">
+      <%= f.label :avatar %>
+      <%= f.file_field :avatar %>
+    </div>
+
+
+...and create your model from the params hash:
+
+    @user = User.new(params[:user])
+    @user.save
+
+
+### Generating URLs for files
+
+Just use the `url` method on your attachments, say `@user.avatar.url`. Here is a sample view that generates an `img` tag pointing to the avatar image:
+
+    <p>
+      <b>Avatar:</b><br>
+      <%= image_tag @user.avatar.url, :style => "max-width: 600px; margin: 10px 0px;" %>
+    </p>
+
+### Validation
+
+Users may upload all types of files to your application and it might be a good idea to restrict that to the set of files that your application knows how to process. For example it would not be a good idea to allow non-image file types as an avatar picture. It might be a good idea to disable executable content that might spread malware too. To help with that the `progstr-filer` gem currently supports attachment validation according to an extension whitelist through the `validates_file_extension_of` method that is available to model objects:
+
+    class User < ActiveRecord::Base
+      has_file :avatar, AvatarUploader
+      validates_file_extension_of :avatar, :allowed => ["jpg", "png"]
+    end
+
+In addition you can restrict the file size using `validates_file_size_of`:
+
+    class User < ActiveRecord::Base
+      has_file :avatar, AvatarUploader
+      validates_file_size_of :avatar, :less_than => 1 * 1024 * 1024
+    end
+
+The example above will not allow files larger than 1 MB. You can specify a lower bound using the `:greater_than` option or even pass a numeric range using the `:in` option.
+
+Of course, requiring users to always upload a file when saving a model object, use the Rails built-in `validates_presence_of` validator:
+
+    class User < ActiveRecord::Base
+      has_file :avatar, AvatarUploader
+      validates_presence_of :avatar
+    end
+
+You can pass a custom error message for all validators using the `:message` option.
+
+### Deleting stale files
+
+Every time you set a new file and save your model, the old file will get scheduled for deletion. The same happens when you `destroy` your model. Note that calling `delete` for your model will not delete any associated files.
+
+### Source code
+
+The `progstr-filer` [gem](https://rubygems.org/gems/progstr-filer) is open source and its code is hosted on [Github](https://github.com/progstr/progstr-filer-gem).
+
+All the techniques outlined in this document are available as a fully-functional Rails project on [Github](https://github.com/progstr/progstr-filer-demo) too.

data/VERSION

@@ -1 +1 @@
-0.8.1
+0.8.2

data/lib/filer/activerecord.rb

@@ -23,12 +23,6 @@ module Progstr
           def #{attribute}=(new_file)
             _set_attachment(:#{attribute}, new_file)
           end
-          def #{attribute}_file_size
-            _get_attachment(:#{attribute}).size
-          end
-          def #{attribute}_file_extension
-            _get_attachment(:#{attribute}).extension
-          end
           def upload_#{attribute}!
             _upload_attachment(:#{attribute})
           end

data/lib/filer/attachment.rb

@@ -1,7 +1,7 @@
 module Progstr
   module Filer
     class Attachment
-      attr_accessor :id, :attribute, :file
+      attr_accessor :id, :attribute, :file, :pre_validated
 
       @@id_generator = ::UUID.new
 
@@ -31,7 +31,9 @@ module Progstr
         result = Attachment.new
         result.id = generate_id
         result.attribute = attribute
+
         result.file = file
+        result.pre_validated = false
         result
       end
 
@@ -58,6 +60,8 @@ module Progstr
         result = Attachment.new
         result.id = id
         result.attribute = attribute
+
+        result.pre_validated = true
         result
       end
 

data/lib/filer/validation.rb

@@ -11,7 +11,7 @@ module Progstr
 
         message = options[:message] || "File size not between #{min} and #{max} bytes."
 
-        validates_with PropertyValidator, :attributes => [attribute],
+        validates_with AttachmentPropertyValidator, :attributes => [attribute],
           :property => :size,
           :in        => allowed_range,
           :message   => message,
@@ -23,7 +23,7 @@ module Progstr
         allowed = options[:allowed] || EverythingIncluded.new
         message = options[:message] || "File extension not allowed."
 
-        validates_with PropertyValidator, :attributes => [attribute],
+        validates_with AttachmentPropertyValidator, :attributes => [attribute],
           :property => :extension,
           :in        => allowed,
           :message   => message
@@ -35,15 +35,17 @@ module Progstr
         end
       end
 
-      class PropertyValidator < ActiveModel::Validations::InclusionValidator
+      class AttachmentPropertyValidator < ActiveModel::Validations::InclusionValidator
         def initialize(options)
           @property = options[:property]
           super(options)
         end
 
-        def validate_each(record, attribute, value)
-          property_value = value.send(@property)
-          super(record, attribute, property_value) unless value.nil? || value.blank? || property_value.nil?
+        def validate_each(record, attribute, attachment)
+          unless attachment.pre_validated
+            property_value = attachment.send(@property)
+            super(record, attribute, property_value) unless attachment.nil? || attachment.blank? || property_value.nil?
+          end
         end
       end
     end

data/test/test_validation.rb

@@ -46,6 +46,20 @@ class TestValidation < UserTest
     assert_equal u.errors[:avatar], ["Avatar image extension not allowed."]
   end
 
+  test "don't validate prevalidated attachments on record update" do
+    u = ValidatedUser.new
+    u.name = "John"
+    avatar = File.open("test/adium-green-duckling.png")
+    u.avatar = avatar
+    save_success = u.save
+    assert_true save_success, "Initially valid."
+
+    loaded = ValidatedUser.find(u.id)
+    loaded.name = "Jim"
+    save_success = loaded.save
+    assert_true save_success, "Still valid on update when attachment not modified."
+  end
+
   test "validation passes" do
     u = ValidatedUser.new
     jpg = FileLike.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: progstr-filer
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.8.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-06 00:00:00.000000000Z
+date: 2012-01-12 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
-  requirement: &24667240 !ruby/object:Gem::Requirement
+  requirement: &14664400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *24667240
+  version_requirements: *14664400
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &24665880 !ruby/object:Gem::Requirement
+  requirement: &14662460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: 3.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *24665880
+  version_requirements: *14662460
 - !ruby/object:Gem::Dependency
   name: uuid
-  requirement: &24663920 !ruby/object:Gem::Requirement
+  requirement: &14658240 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *24663920
+  version_requirements: *14658240
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &24663080 !ruby/object:Gem::Requirement
+  requirement: &14657280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *24663080
+  version_requirements: *14657280
 - !ruby/object:Gem::Dependency
   name: multi_json
-  requirement: &24659740 !ruby/object:Gem::Requirement
+  requirement: &14656740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *24659740
+  version_requirements: *14656740
 - !ruby/object:Gem::Dependency
   name: sqlite3
-  requirement: &24659000 !ruby/object:Gem::Requirement
+  requirement: &14655880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24659000
+  version_requirements: *14655880
 - !ruby/object:Gem::Dependency
   name: guard-test
-  requirement: &24658260 !ruby/object:Gem::Requirement
+  requirement: &14655200 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24658260
+  version_requirements: *14655200
 - !ruby/object:Gem::Dependency
   name: rb-inotify
-  requirement: &24657380 !ruby/object:Gem::Requirement
+  requirement: &14654400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -98,10 +98,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24657380
+  version_requirements: *14654400
 - !ruby/object:Gem::Dependency
   name: libnotify
-  requirement: &24656540 !ruby/object:Gem::Requirement
+  requirement: &14653640 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -109,10 +109,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24656540
+  version_requirements: *14653640
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &24652860 !ruby/object:Gem::Requirement
+  requirement: &14652960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -120,10 +120,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24652860
+  version_requirements: *14652960
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &24651640 !ruby/object:Gem::Requirement
+  requirement: &14652280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -131,10 +131,10 @@ dependencies:
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *24651640
+  version_requirements: *14652280
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &24648740 !ruby/object:Gem::Requirement
+  requirement: &14648520 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -142,10 +142,10 @@ dependencies:
         version: 1.6.4
   type: :development
   prerelease: false
-  version_requirements: *24648740
+  version_requirements: *14648520
 - !ruby/object:Gem::Dependency
   name: rcov
-  requirement: &24647720 !ruby/object:Gem::Requirement
+  requirement: &14647220 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -153,10 +153,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24647720
+  version_requirements: *14647220
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: &24646940 !ruby/object:Gem::Requirement
+  requirement: &14646360 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -164,7 +164,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *24646940
+  version_requirements: *14646360
 description: Progstr Filer is a developer-friendly file and attachment hosting service
   that lets you easily build apps that store and share files.
 email: hristo@deshev.com
@@ -172,7 +172,7 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
-- README.rdoc
+- README.md
 files:
 - .document
 - .rspec
@@ -180,7 +180,7 @@ files:
 - Gemfile.lock
 - Guardfile
 - LICENSE.txt
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - lib/filer/activerecord.rb
@@ -190,6 +190,7 @@ files:
 - lib/filer/uploader.rb
 - lib/filer/validation.rb
 - lib/progstr-filer.rb
+- test/adium-green-duckling.png
 - test/file_like.rb
 - test/test_attachment_url.rb
 - test/test_file_mount.rb
@@ -214,7 +215,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1683985428954431553
+      hash: 4163702518948381072
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:

data/README.rdoc

@@ -1,19 +0,0 @@
-= filer-gem
-
-Description goes here.
-
-== Contributing to filer-gem
- 
-* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
-* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
-* Fork the project
-* Start a feature/bugfix branch
-* Commit and push until you are happy with your contribution
-* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
-* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
-
-== Copyright
-
-Copyright (c) 2011 Hristo Deshev. See LICENSE.txt for
-further details.
-