t_bird

Straight forward file uploads for Ruby Apps

View the Project on GitHub xentek/t_bird

Uploading is... fun, fun, fun, 'til daddy takes the t_bird away.

Project Status

Installation

Add this line to your application's Gemfile:

gem 't_bird', require: false

And then execute:

$ bundle

Why?

I became frustrated by the very coupled design of the leading ruby upload libraries and wanted something that was more modular (to allow for flexibility), wasn't glued to a Model (or any other class), and fulfilled my most common use case out of the box:

Usage

First, configure t_bird with a few settings:

require 't_bird'
TBird::Configuration.configure |config|
  config.aws_key 'amazon access key id'
  config.aws_secret 'amazon secret access key'
  config.aws_bucket 'name of s3 bucket that already exists'
  config.thumbnail_size 100
end

Place this code so that it runs when your app boots.

Then, assuming you have a multipart form like this:

form enctype="multipart/form-data" method="POST"
  input type="file" name="brand[image]"
  input type="submit"

Example is using slim for clarity and terseness, but that doesn't mean you have to.

In the action the form posts to, grab the uploaded file and upload it with t_bird:

# prepended to your filename and enables you
# to create a path to your file on S3
options = { identifier: "images/brands" }

# instantiate your uploader, pass it your file
uploader = TBird::Uploader.new(params[:brand][:image], options)

# return value is the same as uploader.uploads
uploader.upload!

# returns a hash of the URL(s) to your uploads on S3
# store this in the way that makes the most sense for your app
brand.images = uploader.uploads

Options

There are three options you can pass into your TBird::Uploader instance:

Custom Uploaders

In order to define custom versions, and other advanced customization, create a subclass of TBird::Uploader:

class FileUploader < TBird::Uploader
  version :original do
    ->(file) { file.original }
  end
end

Here's a more complex example that defines several custom versions:

class ComplexUploader < TBird::Uploader

  # resizes image to a *width* of 200px, maintains aspect ratio
  version :small do
    ->(img) { img.resize '200' } 
  end

  # resizes image to a *height* of 300px, maintains aspect ratio
  version :large do
    ->(img) { img.resize 'x300' }
  end

  # resizes image to a *height* of 300px, maintains aspect ratio
  version :resized do
    ->(img) { img.resize '500x300' }
  end

  # custom thumbnail size, allowing your to ignore
  # the value of TBird::Configuration.thumbnail_size
  # on an uploader by uploader basis
  version :thumbnail do
    ->(img) { img.thumbnail 200 }
  end

  # want MOAR power?
  # use process, which gets you inside a
  # MiniMagick::Image#combine_options block
  version :complex do
    lambda do |img|
      img.process do |magick|
        magick.sample "50%"
        magick.rotate "-90>"
        magick.quality '88'
      end
    end
  end
end

For more information on MiniMagick::Image#combine_options, refer to the mini_magick docs.

:skull:TBird::Processor#process can be a very sharp stick, so carefully test your processing code with a variety of files in a non-production environment, and as usual, be wary of using values from outside of your class as input for your processing routines.

More customization options

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
  6. ???
  7. Profit!

Colophon