File: README — Documentation for retina

Retina Rails

Makes your life easier optimizing an application for retina displays.

Still using version 1.0.x?

Check upgrading to upgrade or the version 1.0.x readme.

How it works

Retina Rails makes your application use high-resolution images by default. It automatically optimizes uploaded images (CarrierWave or Paperclip) for retina displays by making them twice the size and reducing the quality.

Good source on setting up image quality: http://www.netvlies.nl/blog/design-interactie/retina-revolution

Resources

Installation
Migrations
Carrierwave
Paperclip
Displaying a retina image
Upgrading

Installation

Add gem 'retina_rails', '~> 2.0.0' to your Gemfile.
Run bundle install.

Migrations

Add a text column named retina_dimensions. This column is used to store original dimensions of the images.

class AddRetinaDimensionsToUsers < ActiveRecord::Migration
  def self.change
    add_column :users, :retina_dimensions, :text
  end
end

CarrierWave

Simply add retina! to your uploader.

class ExampleUploader < CarrierWave::Uploader::Base

  retina!

  version :small do
    process :resize_to_fill => [30, 30]
    process :retina_quality => 80
  end

  version :large, :retina => false do
    process :resize_to_fill => [1000, 1000]
  end

end

By default it sets the retina image quality to 60 which can be overriden with process :retina_quality => 80. To disable the creation of a retina version simply call version :small, :retina => false.

Custom resize processors

You can also use your custom resize processors like so:

class ExampleUploader < CarrierWave::Uploader::Base

  retina!

  version :small, :retina => false do
    process :resize_to_fill_with_gravity => [200, 200, 'North', :jpg, 75]
    process :store_retina_dimensions
  end

end

Make sure you double the image size yourself in your processor. In this example the image will be displayed with a size of 100x100.

Paperclip

Simply add retina! to your model.

class ExampleUploader < ActiveRecord::Base

  retina!

  has_attached_file :image,
    :styles => {
       :original => ["800x800", :jpg],
       :small => ["125x125#", :jpg]
     },
     :retina => { :quality => 80 }

end

By default it sets the retina image quality to 60 which can be overriden by adding a quality option. To disable the creation of a retina version set the retina option to false :retina => false.

Displaying a retina image

retina_image_tag(@user, :image, :small, :default => [50, 40])
# or
retina_image_tag(@user, :image, :small, :default => { :width => 50, :height => 40 })

If no image is uploaded (yet) it will display the default image defined with CarrierWave or Paperclip and set the width and height attributes specified in the default option.

Voila! Now you're using Retina Rails.

Supported Ruby Versions

This library is tested against Travis and aims to support the following Ruby and Rails implementations:

Ruby 2.1
Ruby 2.2
Ruby 2.3
Ruby 2.4
Rails 4.2
Rails 5.0
Rails 5.1

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request