README.md in artwork-0.6.1 vs README.md in artwork-0.7.0

- old
+ new

@@ -1,14 +1,29 @@ # Artwork -Automated user-resolution-based image size choosing for your Rails views, but -done at the backend. Works for any browser. Delivers the information needed for -the calculations (browser window's dimentions and device's pixel ratio) via a -cookie. Supports only Paperclip attachments. +The Artwork gem provides simple server-side responsive images support for Rails +which is similar in concept to the `<picture>` tag spec but requires no +JavaScript, doesn't make extra requests and works in all browsers. +Currently it supports only Paperclip attachments, but that can be changed +failry easily. + The gem should be thread-safe and should work with Rails 2.3 or newer. +## How it works + +To do this "magic", the gem needs some information from the browser. Two pieces +of knowledge travel from the browser to the server via a cookie: + +- the browser window's dimentions (width in pixels) +- the device's pixel ratio + +These values are set in a cookie as early as possible during the first page +load and then the page is reloaded with JavaScript. If these values change +later on, for example if the user resizes their browser, no automatic reloading +is performed. + ## An example Say you've declared a default (base) resolution of 1440px. You design based on that resolution. You want to show the user an image which is half of the width of the user's browser. You then add the following to your view: @@ -54,11 +69,12 @@ Or install it yourself as: $ gem install artwork -Add the following line at the top of your `<head>` section: +Add the following line at the top of your `<head>` section, as early as +possible, but **after** any `<meta viewport>` tags: <%= activate_resolution_independence %> This will add a script which will set the cookie with the dimentions and reload the current page. If the dimentions need updating, it will do the same thing. @@ -67,10 +83,15 @@ so you could prevent this if you add (*ABOVE* the top script): <style> .artwork-reload-splash body { display: none; } </style> <%= activate_resolution_independence %> +### When you have a viewport meta tag + +If you have `<meta viewport>` tags, place them **before** the +`activate_resolution_independence` call. + ### Usage in frames The client-side code which checks for the current browser's resolutions will be disabled by default when the site is not the topmost frame, ie. when loaded from an iframe. @@ -84,11 +105,11 @@ ## Configuration Set the following variables in an app initializer: - `Artwork.supported_resolutions_list` -- `Artwork.default_resolution` +- `Artwork.base_resolution` Name your Paperclip attachment styles using the following convention: :'320x' :'320x_2x' @@ -106,11 +127,11 @@ ## Usage Example Configure the gem by putting the following code in `config/initializers/artwork.rb`: - Artwork.default_resolution = 1440 + Artwork.base_resolution = 1440 Artwork.supported_resolutions_list = [1024, 1280, 1440, 1600, 1920, 2048, 3200, 3840] Include `Artwork::Model` in your models which have artworks. Include `Artwork::Controller` in your `ApplicationController` or wherever you @@ -120,16 +141,50 @@ the `artwork_tag` view helper. Example: <%= artwork_tag @film, :board, :'1440x', :image => {:class => 'poster'} %> <%= artwork_tag @gallery, :cover, :'900x' %> +### Base (default) resolution + +The base resolution defeined by `Artwork.base_resolution` is there to assist +in development and to make calculating the image width percentage in relation +to the viewport width easier. + +For example, to define a half-width image in a setting where your base +resolution is 1600 px, you can use: + + <%= artwork_tag @record, :cover, :'800x' %> + +In general, it's convenient to set the base resolution to what your dev team's +screen width is. + +### Custom base resolutions + +The gem supports per-tag base resolutions via the following syntax: + + <%= artwork_tag @record, :cover, :'800x@1200' %> + +This effectively means "size the image as 2/3 of the viewport width". + +### Different image sizes based on different browser widths + +There is basic media query-like support built into +`Artwork::Model.artwork_thumb_for(name, size, alternative_sizes = nil)`. + +For example, to request a full width image if the current browser's viewport +is 480px or less wide, you can use the following code: + +```ruby +<%= artwork_tag @recrod, :cover, '800x', {480 => '320x@320'} %> +``` + ## Thumb Selection Algorithm The following criteria are taken into account for picking up the appropriate thumb name: -- The `default_resolution` specified in the Artwork configuration file. +- The `base_resolution` specified in the Artwork configuration file. - The current resolition, approximated to the nearest supported resolution which is larger than the current user's one. - Whether or not the screen is retina. - The width of the requested thumb size (e.g. `400` for `400x300_crop`). - The label of the requested thumb (e.g. `crop` for `400x300_crop`); the label @@ -151,10 +206,9 @@ specified in the request, aspect ratio checks will not be performed. - If the current device is a retina device, a retina thumb will be preferred. If no retuna thumb exists, a non-retina one will be selected. If no such thumb exist, the largest one will match. - ## Contributing 1. [Fork it](https://github.com/mitio/artwork/fork) 2. Create your feature branch (`git checkout -b my-new-feature`)