paperdragon 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 36e7122d614e09b22cecbf83c3698e9d6e9343cb
-  data.tar.gz: cede5637f600b6c1121c4c7239af3a7367ed5c35
+  metadata.gz: 4c124aecf9f335b22baf9214604df964e1a965dd
+  data.tar.gz: 6328ab40a1eead17adc5b399678383cc88761a48
 SHA512:
-  metadata.gz: 5a60d0ed2a91ae998f46fa602d389fb881c384fd43735a5727c26a07539f3db76fc93cca01c3872c335b7a917054e5ef868e1f44a1596acafa0ef709918cd4b9
-  data.tar.gz: fd032e73607fb56b7e11c90b968c84f502858a465c6f6e1ea018b4901757fef14c557e4144d64a896bfa1b517c7722c86e1d9ecc7329c5f4c8e497ce2d0dcd18
+  metadata.gz: 0fc0da95f318aeab85656c5d76cc06e008e0fb2cddfac3da524501f1633f5cd04ef9fedc14ce11badc2e1a91ea3259482d9f1b95d5609523eca446163e0880ac
+  data.tar.gz: e6b9f994f29266b394c5d8c5999b40425a2808002419dea331bf628985d746a4f2bf7e331c495204441de4bbcf84c0fae753be2e021f7b74b8a77dabbc9221cc

data/README.md

@@ -1,71 +1,314 @@
 # Paperdragon
 
-TODO: Write a gem description
+_Explicit image processing._
+
+## Summary
+
+Paperdragon gives you image processing as known from [Paperclip](https://github.com/thoughtbot/paperclip, [CarrierWave](https://github.com/carrierwaveuploader/carrierwave) or [Dragonfly](https://github.com/markevans/dragonfly). It allows uploading, cropping, resizing, watermarking, maintaining different versions of an image, and so on.
+
+It provides a very explicit DSL: **No magic is happening behind the scenes, paperdragon makes _you_ implement the processing steps.**
+
+With only a little bit of more code you are fully in control of what gets uploaded where, which image version gets resized when and what gets sent to a background job.
+
+Paperdragon uses the excellent [Dragonfly](https://github.com/markevans/dragonfly) gem for processing, resizing, storing, etc.
+
+Paperdragon is database-agnostic, doesn't know anything about ActiveRecord and _does not_ hook into AR's callbacks.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'paperdragon'
+```ruby
+gem 'paperdragon'
+```
+
+
+## Example
+
+This README only documents the public DSL. You're free to use the public API [documented here](# TODO) if you don't like the DSL.
+
+### Model
+
+Paperdragon has only one requirement for the model: It needs to have a column `image_meta_data`. This is a serialised hash where paperdragon saves UIDs for the different image versions. We'll learn about this in a minute.
+
+```ruby
+class User < ActiveRecord::Base # this could be just anything.
+  include Paperdragon::Model
+
+  processable :image
+
+  serialize :image_meta_data
+end
+```
+
+Calling `::processable` advises paperdragon to create a `User#image` reader to the attachment. Nothing else is added to the class.
+
+
+## Uploading
+
+Processing and storing an uploaded image is an explicit step - you have to code it! This code usually goes to a separate class or an [Operation in Trailblazer](https://github.com/apotonick/trailblazer#domain-layer-operation), don't leave it in the controller if you don't have to.
+
+```ruby
+def create
+  file = params.delete(:image)
+
+  user = User.create(params) # this is your code.
+
+  # upload code:
+  user.image(file) do |v|
+    v.process!(:original)                                      # save the unprocessed.
+    v.process!(:thumb)   { |job| job.thumb!("75x75#") }        # resizing.
+    v.process!(:cropped) { |job| job.thumb!("140x140+20+20") } # cropping.
+    v.process!(:public)  { |job| job.watermark! }              # watermark.
+  end
+
+  user.save
+end
+```
+
+This is a completely transparent process.
+
+1. Calling `#image` usually returns the image attachment. However, passing a `file` to it allows to create different versions of the uploaded image in the block.
+2. `#process!` requires you to pass in a name for that particular image version. It is a convention to call the unprocessed image `:original`.
+3. The `job` object is responsible for creating the final version. This is simply a `Dragonfly::Job` object and gives you [everything that can be done with dragonfly](http://markevans.github.io/dragonfly/imagemagick/).
+4. After the block is run, paperdragon pushes a hash with all the images meta data to the model via `model.image_meta_data=`.
+
+For a better understanding and to see how simple it is, go and check out the `image_meta_data` field.
+
+```ruby
+ user.image_meta_data #=> {original: {uid: "original-logo.jpg", width: 240, height: 800},
+                      #    thumb:    {uid: "thumb-logo.jpg", width: 48, height: 48},
+                      #   ..and so on..
+                      #   }
+ ```
+
+
+## Rendering Images
+
+After processing, you may want to render those image versions in your app.
+
+```ruby
+user.image[:thumb].url
+```
+
+This is all you need to retrieve the URL/path for a stored image. Use this for your image tags
+
+```haml
+= img_tag user.image[:thumb].url
+```
+
+Internally, Paperdragon will call `model#image_meta_data` and use this hash to find the address of the image.
+
+While gems like paperclip often use several fields of the model to compute UIDs (addresses) at run-time, paperdragon does that once and then dumps it to the database. This completely removes the dependency to the model.
+
+
+## Reprocessing And Cropping
+
+Once an image has been processed to several versions, you might need to reprocess some of them. As an example, users could re-crop their thumbs.
+
+```ruby
+def crop
+  user = User.find(params[:id]) # this is your code.
+
+  # reprocessing code:
+  cropping = "#{params[:w]}x#{params[:h]}#"
+
+  user.image do |v|
+    v.reprocess!(:thumb, Time.now) { |job| job.thumb!(cropping) } # re-crop.
+  end
 
+  user.save
+end
+```
 
-Paperdragon is completely decoupled from ActiveRecord. Attachment-related calls are delegated to paperdragon objects, the model is solely used for persisting file UIDs.
+Only a few things have changed compared to the initial processing.
 
-Where Paperclip or Carrierwave offer you a handy DSL to configure the processing, Paperdragon comes with an API. You _program_ what you wanna do. This is only a tiny little bit more code and gives you complete control over the entire task.
+1. We do not pass a file to `#image` anymore. This makes sense as reprocessing will re-use the existing original file.
+2. Note that it's not `#process!` but `#reprocess!` indicating a surprising reprocessing.
+3. As a second argument to `#reprocess!` a fingerprint string is required. To understand what this does, let's inspect `image_meta_data` once again. (The fingerprint feature is optional but extremely helpful.)
 
 
+```ruby
+ user.image_meta_data #   ..original..
+                      #    thumb:    {uid: "thumb-logo-1234567890.jpg", width: 48, height: 48},
+                      #   ..and so on..
+                      #   }
+```
 
-The goal is to make you _understand_ what is going on.
+See how the file name has changed? Paperdragon will automatically append the fingerprint you pass into `#reprocess!` to the existing version's file name.
 
-* you control processing and storage, e.g. first thumbnails and cropping, then process the rest. easy to sidekiq.
-error handling
-UID generation handled by you. also, updating (e.g. new fingerprint)
-* only process subset, e.g. in test.
 
+## Renaming
 
-File
+Sometimes you just want to rename files without processing them. For instance, when a new fingerprint for an image is introduced, you want to apply that to all versions.
 
-All process methods return Metadata hash
-yield Job, save it from the block if you need it
-override #default_metadata_for when you wanna change it
-last arg in process method gets merged into metadata hash
+```ruby
+fingerprint = Time.now
 
-Design
-Operations in File look like scripts per design. I could have abstracted various steps into higher level methods, however, as file processing _is_ a lot scripting, I decided to sacrifice redundancy for better understandable code.
+user.image do |v|
+  v.reprocess!(:thumb, fingerprint) { |job| job.thumb!(cropping) } # re-crop.
+  v.rename!(:original, fingerprint) # just rename it.
+end
+```
 
+This will re-crop the thumb and _rename_ the original.
 
-Paperclip Compatibility
+```ruby
+ user.image_meta_data #=> {original: {uid: "original-logo-1234567890.jpg", ..},
+                      #    thumb:    {uid: "thumb-logo-1234567890.jpg", ..},
+                      #   ..and so on..
+                      #   }
+ ```
 
-1. Stores file to same location as paperclip would do.
-2. `Photo#url` will return the same URL as paperclip.
-3. P::Model image.url(:thumb) still works, your rendering code will still work.
-4. Cleaner API for generating URLs. For example, we needed to copy images from production to staging. With paperclip, it was impossible to create paths for both environments.
 
-Paperclip uses several columns to compute the UID. Once this is done, it doesn't store that UID in the database but updates the respective fields, which makes it a bit awkward to maintain.
+## Deleting
 
-Paperdragon simply dumps the image uid along with meta data into image_meta_data.
+While making images is a wonderful thing, sometimes you need to destroy to create. This is why paperdragon gives you a deleting mechanism, too.
 
-You have to take care of updating image_fingerprint etc yourself when changing stuff and still using paperclip to compute urls.
+```ruby
+user.image do |v|
+  v.delete!(:thumb)
+end
+```
 
+This will also remove the associated metadata from the model.
 
 
+## Fingerprints
 
-Original paperclip UID:
-it { pic.image(:original).should == "/system/test/pics/images/002/216/376/bc7b26d983db8ced792e38f0c34aba417f75c2e7_key/original-c5b7e624adc5b67e13435baf26e65bc8-1399980114/DSC_4876.jpg" }
+Paperdragon comes with a very simple built-in file naming.
 
-1) Uid
-     Failure/Error: should == "system/test/pics/images/002/216/376/bc7b26d983db8ced792e38f0c34aba417f75c2e7_key/original-c5b7e624adc5b67e13435baf26e65bc8-1399980114/DSC_4876.jpg" }
-       expected: "system/test/pics/images/002/216/376/bc7b26d983db8ced792e38f0c34aba417f75c2e7_key/original-c5b7e624adc5b67e13435baf26e65bc8-1399980114/DSC_4876.jpg"
-            got: "system/test/pics/images/002/216/376/bc7b26d983db8ced792e38f0c34aba417f75c2e7_key/original/DSC_4876.jpg" (using ==)
+Computing a file UID (or, name, or path) happens in the `Attachment` class. You need to provide your own implementation if you want to change things.
 
-Feel like a hacker reverse-engineering
+```ruby
+class User < ActiveRecord::Base
+  include Paperdragon::Model
 
-## Rails
+  class Attachment < Paperdragon::Attachment
+    def build_uid(style, file)
+      "/path/to/#{style}/#{obfuscator}/#{file.original_filename}"
+    end
 
+    def obfuscator
+      Obfuscator.call # this is your code.
+    end
+  end
+
+  processable :image, Attachment # use the class you just wrote.
+```
+
+The `Attachment#build_uid` method is invoked when processing images.
+
+```ruby
+user.image(file) do |v|
+  v.process!(:thumb)   { |job| job.thumb!("75x75#") }
+end
+```
+
+To create the image UID, _your_ attachment is now being used.
+
+```ruby
+ user.image_meta_data #   ..original..
+                      #    thumb:    {uid: "/path/to/thumb/ac97dnxid8/logo.jpg", ..},
+                      #   ..and so on..
+                      #   }
+```
+
+What a beautiful, cryptic and mysterious filename you just created!
+
+The same pattern applies for _re-building_ UIDs when reprocessing images.
+
+```ruby
+class Attachment < Paperdragon::Attachment
+  # def build_uid and the other code from above..
+
+  def rebuild_uid(file, fingerprint)
+    file.uid.sub("logo.png", "logo-#{fingerprint".png)
+  end
+end
+```
+
+This code is used to re-compute UIDs in `#reprocess!`.
+
+That example is stupid, I know, but it shows how you have access to the `Paperdragon::File` instance that represents the existing version of the reprocessed image.
+
+
+## Local Rails Configuration
+
+Configuration of paperdragon completely relies on [configuring dragonfly](http://markevans.github.io/dragonfly/configuration/). As an example, for a Rails app with a local file storage, I use the following configuration in `config/initializers/paperdragon.rb`.
+
+```ruby
 Dragonfly.app.configure do
   plugin :imagemagick
 
   datastore :file,
     :server_root => 'public',
     :root_path => 'public/images'
-end
+end
+```
+
+This would result in image UIDs being prefixed accordingly.
+
+```ruby
+user.image[:thumb].url #=> "/images/logo-1234567890.png"
+```
+
+
+## S3
+
+As [dragonfly allows S3](https://github.com/markevans/dragonfly-s3_data_store), using the amazon cloud service is straight-forward.
+
+All you need to do is configuring your bucket. The API for paperdragon remains unchanged.
+
+```ruby
+require 'dragonfly/s3_data_store'
+
+Dragonfly.app.configure do
+  datastore :s3,
+    bucket_name: 'my-bucket',
+    access_key_id: 'blahblahblah',
+    secret_access_key: 'blublublublu'
+end
+```
+
+Images will be stored "in the cloud" when using `#process!`, renaming, deleting and re-processing do the same!
+
+
+## Background Processing
+
+The explicit design of paperdragon makes it incredibly simple to move all or certain processing steps to background jobs.
+
+```ruby
+class Image::Processor
+  include Sidekiq::Worker
+
+  def perform(params)
+    user = User.find(params[:id])
+
+    user.image(params[:file]) do |v|
+      v.process!(:original)
+    end
+  end
+end
+```
+
+Documentation how to use Sidekiq and paperdragon in Traiblazer will be added shortly.
+
+## Validations
+
+## Paperclip compatibility
+
+I wrote paperdragon as an explicit alternative to paperclip. In the process of doing so, I step-wise replaced upload code, but left the rendering code unchanged. Paperclip has a slightly different API for rendering.
+
+```ruby
+user.image.url(:thumb)
+```
+
+Allowing your paperdragon-backed model to expose this API is piece-of-cake.
+
+```ruby
+class User < ActiveRecord::Base
+  include Paperdragon::Paperclip::Model
+```
+
+This will allow both APIs for a smooth transition.

data/lib/paperdragon/model.rb

@@ -13,8 +13,13 @@ module Paperdragon
       # Creates Avatar#image that returns a Paperdragon::File instance.
       def attachment_accessor_for(name, attachment_class)
         mod = Module.new do # TODO: abstract that into Uber, we use it everywhere.
-          define_method name do
-            attachment_class.new(self.image_meta_data, {:model => self})
+          define_method name do |file=nil, &block|
+            attachment = attachment_class.new(self.image_meta_data, {:model => self})
+
+            return attachment unless file or block
+
+            # run the task block and save the returned new metadata in the model.
+            self.image_meta_data = attachment.task(*[file], &block)
           end
         end
       end

data/lib/paperdragon/version.rb

@@ -1,3 +1,3 @@
 module Paperdragon
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/test/model_test.rb

@@ -22,14 +22,31 @@ class PaperdragonModelTest < MiniTest::Spec
 
 
   # minimum setup
-  class Image
+  class Image < OpenStruct
     include Paperdragon::Model
     processable :image
+  end
 
-    def image_meta_data
-      {:thumb => {:uid => "Avatar-thumb"}}
+  it { Image.new(:image_meta_data => {:thumb => {:uid => "Avatar-thumb"}}).image[:thumb].url.must_equal "/paperdragon/Avatar-thumb" }
+
+
+  # process with #image{}
+  let (:logo) { Pathname("test/fixtures/apotomo.png") }
+
+  it do
+    model = Image.new
+    model.image(logo) do |v|
+      v.process!(:original)
+      v.process!(:thumb) { |j| j.thumb!("16x16") }
     end
-  end
 
-  it { Image.new.image[:thumb].url.must_equal "/paperdragon/Avatar-thumb" }
+    model.image_meta_data.must_equal({:original=>{:width=>216, :height=>63, :uid=>"original-apotomo.png"}, :thumb=>{:width=>16, :height=>5, :uid=>"thumb-apotomo.png"}})
+
+
+    model.image do |v|
+      v.reprocess!(:thumb, "1") { |j| j.thumb!("8x8") }
+    end
+
+    model.image_meta_data.must_equal({:original=>{:width=>216, :height=>63, :uid=>"original-apotomo.png"}, :thumb=>{:width=>8, :height=>2, :uid=>"thumb-apotomo-1.png"}})
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paperdragon
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-26 00:00:00.000000000 Z
+date: 2014-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dragonfly