Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 191 lines (128 sloc) 6.765 kb
111e018 @kristianmandrup first version
authored
1 # Picturefill View helpers for Rails
2
d59d93b @kristianmandrup included srcset assets and test and updated readme
authored
3 This gem provides polyfills for 3 wys to render responsive images:
4
5 * picturefill
6 * jquery-picture
7 * srcset
8
5aa937d @kristianmandrup all specs pass
authored
9 [picturefill](https://github.com/scottjehl/picturefill) is currently the best way for rendering [Responsive Images](http://5by5.tv/webahead/25) on a web page.
111e018 @kristianmandrup first version
authored
10
11 *picturefill-rails* provides nice view helper methods to render the picturefill.
12
13 ```html
14 <div data-picture data-alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
15 <div data-src="small.jpg"></div>
16 <div data-src="small.jpg" data-media="(min-device-pixel-ratio: 2.0)"></div>
17 <div data-src="medium.jpg" data-media="(min-width: 400px)"></div>
18 <div data-src="medium_x2.jpg" data-media="(min-width: 400px) and (min-device-pixel-ratio: 2.0)"></div>
19 <div data-src="large.jpg" data-media="(min-width: 800px)"></div>
20 <div data-src="large_x2.jpg" data-media="(min-width: 800px) and (min-device-pixel-ratio: 2.0)"></div>
21 <div data-src="extralarge.jpg" data-media="(min-width: 1000px)"></div>
22 <div data-src="extralarge_x2.jpg" data-media="(min-width: 1000px) and (min-device-pixel-ratio: 2.0)"></div>
23
24 <!-- Fallback content for non-JS browsers. Same img src as the initial, unqualified source element. -->
25 <noscript>
26 <img src="external/imgs/small.jpg" alt="A giant stone face at The Bayon temple in Angkor Thom, Cambodia">
27 </noscript>
28 </div>
29 ```
30
5aa937d @kristianmandrup all specs pass
authored
31 The above can be rendered in Rails 3+ by writing the following code, using the View helpers provided by the Rails engine included:
111e018 @kristianmandrup first version
authored
32
33 ```haml
34 = picturefill 'A giant stone face at The Bayon temple in Angkor Thom, Cambodia' do
5aa937d @kristianmandrup all specs pass
authored
35 = picture_src 'small.jpg'
36 = picture_src 'small.jpg', "(min-device-pixel-ratio: 2.0)"
37 = picture_src 'medium.jpg', "(min-width: 400px)"
38 = picture_src 'medium_x2.jpg', "(min-width: 400px) and (min-device-pixel-ratio: 2.0)"
39 = picture_src 'largs.jpg', "(min-width: 800px)"
40 = picture_src 'large_x2.jpg', "(min-width: 800px) and (min-device-pixel-ratio: 2.0)"
831d2a5 @kristianmandrup added fallback example in readme
authored
41 # ...
42 = picture_fallback "external/imgs/small.jpg", alt: "A giant stone face at The Bayon temple in Angkor Thom, Cambodia"
111e018 @kristianmandrup first version
authored
43 ```
44
5aa937d @kristianmandrup all specs pass
authored
45 Note: This example uses [HAML](https://github.com/haml/haml) as the rendering engine.
111e018 @kristianmandrup first version
authored
46
5aa937d @kristianmandrup all specs pass
authored
47 ### Optimizations using conventions
111e018 @kristianmandrup first version
authored
48
5aa937d @kristianmandrup all specs pass
authored
49 Using conventions, and an extra `ratio:` option, the following shorthand is possible:
111e018 @kristianmandrup first version
authored
50
51 ```haml
52 = picturefill 'A giant stone face at The Bayon temple in Angkor Thom, Cambodia' do
5aa937d @kristianmandrup all specs pass
authored
53 = picture_src 'small.jpg', ratio: 'x2'
54 = picture_src 'medium.jpg', "400", ratio: 'x2'
55 = picture_src 'large.jpg', "800", ratio: 'x2'
831d2a5 @kristianmandrup added fallback example in readme
authored
56 # ...
57 = picture_fallback "external/imgs/small.jpg", alt: "A giant stone face at The Bayon temple in Angkor Thom, Cambodia"
111e018 @kristianmandrup first version
authored
58 ```
59
5aa937d @kristianmandrup all specs pass
authored
60 This will ouput exactly the same HTML as the previous example :)
61 See the specs for more details...
62
63 ## Usage
64
65 In your Gemfile:
66
67 `gem 'picturefill-rails'`
68
69 A number of specs are included which all pass and should ensure that the view helpers work as expected.
70
71 ## TODO
111e018 @kristianmandrup first version
authored
72
d59d93b @kristianmandrup included srcset assets and test and updated readme
authored
73 The `#picture_src` method works, but could use some heavy refactoring! I don't like methods of more than 10 lines! Reponsibilities should be off-loaded to other methods (or classes)
111e018 @kristianmandrup first version
authored
74
2bf1727 @kristianmandrup rename helpers and update readme
authored
75 Currently the gem only supports Ruby 1.9+ and has only been tested on 1.9.3.
76
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
77 ## Assets
78
2bf1727 @kristianmandrup rename helpers and update readme
authored
79 The gem includes the picturefill javascript assets that are automatically available for the asset pipeline. In your `application.js` manifest file require:
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
80
81 * `picturefill.js`
82 * `picturefill\matchemedia.js`
83
84 See [demo](http://scottjehl.github.com/picturefill/) for a full example!
85
86 ## jQuery Picture
87
88 [jquery picture](http://jquerypicture.com/) is now also partly supported. It is very similar to picturefill but with slightly different tags.
89
2bf1727 @kristianmandrup rename helpers and update readme
authored
90 The assets `jquery-picture.min.js` and `jquery-picture.js` are included in vendor/assets.
91
92 The view helper includes the helper methods:
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
93
2bf1727 @kristianmandrup rename helpers and update readme
authored
94 * `picture_tag(alt)`
95 * `source_tag(src, media, options = {})
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
96
2bf1727 @kristianmandrup rename helpers and update readme
authored
97 Usage example:
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
98
99 ```haml
2bf1727 @kristianmandrup rename helpers and update readme
authored
100 = picture_tag 'A giant stone face at The Bayon temple in Angkor Thom, Cambodia' do
101 = source_tag 'small.jpg', ratio: 'x2'
102 = source_tag 'medium.jpg', "400", ratio: 'x2'
103 = source_tag 'large.jpg', "800", ratio: 'x2'
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
104 # ...
105 = picture_fallback "external/imgs/small.jpg", alt: "A giant stone face at The Bayon
106 ```
107
2bf1727 @kristianmandrup rename helpers and update readme
authored
108 And to enable via jquery:
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
109
110 ```javascript
111 $(function(){
112 $('picture').picture();
113 });
114 ```
115
d59d93b @kristianmandrup included srcset assets and test and updated readme
authored
116 *Arcticles*
84d31c1 @kristianmandrup added vendor assets and included support for jquery picture
authored
117
118 [critique of picturefill](http://oscargodson.com/posts/picturefill-needs-to-die.html)
119
d59d93b @kristianmandrup included srcset assets and test and updated readme
authored
120 ## Img SrcSet Polyfill
121
122 See [the specification][spec] for the reference algorithm.
123
124 See [repo]: https://github.com/borismus/srcset-polyfill
125
126 ### Usage
127
128 Use the `srcset` attribute of `<img>` elements. For example:
129
130 <img alt="The Breakfast Combo"
131 src="banner.jpeg"
132 srcset="banner-HD.jpeg 2x, banner-phone.jpeg 100w,
133 banner-phone-HD.jpeg 100w 2x"/>
134
135
136 Include `srcset.min.js` in your page.
137
16f0456 @kristianmandrup bump version
authored
138 *View helper*
d59d93b @kristianmandrup included srcset assets and test and updated readme
authored
139
16f0456 @kristianmandrup bump version
authored
140 * `imgset_tag src, srcset, options = {}` (alias `imageset_tag`)
141
142 ```haml
143 = imgset_tag "banner.jpeg", "banner-HD.jpeg 2x, banner-phone.jpeg 100w,banner-phone-HD.jpeg 100w 2x", alt: "The Breakfast Combo"
144 ```
145
146 outputs the HTML code shown above.
147
148 If you leave out the srcset argument it will fallback to a single src image
149
150 ```haml
151 = imgset_tag "banner.jpeg", alt: "The Breakfast Combo"
152 ```
153
154 Same as
155
156 ```haml
157 = image_tag "banner.jpeg", alt: "The Breakfast Combo"
158 ```
d59d93b @kristianmandrup included srcset assets and test and updated readme
authored
159
160 ### Assets
161
162 The gem includes srcset javascript assets that are automatically available for the asset pipeline. In your `application.js` manifest file require:
163
164 * `srcset.min.js` (prod)
165 * `srcset.js` (dev/test)
166
167 ### Open questions
168
169 - How to reliably check for srcset support in the browser (so as to not
170 attempt to polyfill if it's not necessary?)
171 - Is it safe to use `-webkit-transform` to scale things?
172 - Is it worth falling back to `-webkit-image-set` if available?
173
174 [spec]: http://www.whatwg.org/specs/web-apps/current-work/multipage/embedded-content-1.html#processing-the-image-candidates
175
111e018 @kristianmandrup first version
authored
176 ## Contributing to picturefill-rails
177
178 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
179 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
180 * Fork the project.
181 * Start a feature/bugfix branch.
182 * Commit and push until you are happy with your contribution.
183 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
184 * 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.
185
186 ## Copyright
187
188 Copyright (c) 2012 Kristian Mandrup. See LICENSE.txt for
189 further details.
190
Something went wrong with that request. Please try again.