README

== browser_cms thumbnail extension

This extension adds a "thumbnail" view helper that takes a content_block with an attachment (an ImageBlock or a custom content_block) and creates a thumbnail according to the ImageMagick geometry you specify.

* Supports png, jpg, gif, and bmp formats. Thumbnails are output in jpg format.
* The default geometry is "100x100" - so no side larger than 100 pixels.  
* It caches these thumbnails in the directory RAILS_ROOT/public/bcms_thumbnail_cache/. We'll create this directory automatically if needed.
* Use the "bcms_thumbnail:clear" rake task to clear the thumbnail cache.
* Thumbnails are public. They are served directly off the filesystem.

== Examples

It's pretty simple. The code below demonstrates creating a thumbnail from an image block, which (naturally) has a browser_cms attachment. This code overrides the default 100x100 geometry and creates images of no larger than 125 pixels on any side, with a quality of 85.

Add a dynamic portlet and the add this to the template:
  <% image = ImageBlock.find(:first) %>
  <%= image_tag(thumbnail(image,'125x125',85)) %>

A stupidly simple image gallery? It's easier than you think! Again, in a dynamic portlet:

 <div class="gallery">
   <% ImageBlock.find(:all).each do |image| %>
     <div class="image"><%= link_to(image_tag(thumbnail(image,'100x100'), :alt => image.name),image.attachment.file_path) %></div>
   <% end %>
 </div>

The above, but only for images with a certain tag? Oh, hell yes:

 <div class="gallery">
   <% Tag.find_by_name('lol').taggings.find(:all, :conditions => ['taggable_type = ?', 'AbstractFileBlock']).collect{|img| img.taggable}.each do |image| %>
     <div class="image"><%= link_to(image_tag(thumbnail(image,'100x100'), :alt => image.name),image.attachment.file_path) %></div>
   <% end %>
 </div>

Note: The code above is yucky. But cool.

You can also create square thumbnails via the "thumbnail_square" helper. You should only pass a single integer in for geometry when create a square thumbnail.
  <% image = ImageBlock.find(:first) %>
  <%= image_tag(thumbnail_square(image,'125')) %>

So "thumbnail" and "thumbnail_square" accept three parameters:

# The object with the attachment,
# The geometry, and
# An integer representing the JPG compression level, from 1 to 100. Default is 85.

== Geometries

ImageMagick will preserve aspect ratio with all the geometries below: 

* "125" will ensure the width is no more than 125px.
* "x125" will ensure the height is no more than 125px.
* "125x125" will ensure neither side is more than 125px.
* "50%" will scale the image to half its size.

More info on ImageMagick geometry here: http://www.imagemagick.org/www/command-line-processing.html#geometry

Remember that "thumbnail_square" only requires a single integer for its geometry string.

== Gotchas

* Thumbnails are generated when the helper method is called. If you clear the thumbnail cache and don't clear the page cache right afterwards, you may have cached pages calling for thumbnails that aren't regenerated - because the helper method call creates the image.  Be sure to clear your page cache after clearing your thumbnail cache and you'll be fine.
* Speaking of caches - this does nothing to automatically clean up old cached thumbnails from images that've changed or that've been deleted. If you find that these old thumbnails are eating up too much space, Use the rake task to clear out the cache. Be sure to follow it with a page cache flush.

== Todo

* Beef up the thumbnail helper to expose more mini_magick features.
* Better error reporting and sanity checking. 

== Installation

 gem install bcms_thumbnail

and then follow the standard module installation instructions here: http://guides.browsercms.org/installing_modules.html  

== Requires

* The mini_magick gem, version >= 1.2.5
* ImageMagick, to satisfy the above.

== Author

Dan Collis-Puro, http://collispuro.com, http://github.com/djcp/

== License

This extension is licensed under the Gnu LGPL: http://www.gnu.org/licenses/lgpl.html