Letterpress
===========

Rails plugin, uses Imagemagick to generate images for displaying text in non-web fonts.


Prerequisites
=============

ImageMagick (NOT RMagick.  It isn't used)


Configuration
=============

Absolute path to the directory to look for fonts:
    Letterpress::Config.fonts_dir
  Default:
    RAILS_ROOT/lib/fonts

Directory to output images, relative to RAILS_ROOT/public/images ():
    Letterpress::Config.images_dir
  Default:
    letterpress

File format used to render the image (can be anything ImageMagick supports):
    Letterpress::Config.image_format
  Default:
    'png'

A hash of default, site-wide parameters.  The options passed into individual calls to the
letterpress() method are merged into this, overwriting these defaults:
    Letterpress::Config.singleton_options
  Default:
    {:density => "72", :units => "PixelsPerInch"}
  Examples:
    Letterpress::Config.singleton_options[:font] = "Verdana-Regular"
    Letterpress::Config.singleton_options[:density] = "300"
    Letterpress::Config.singleton_options.merge!(:density => "100", :size => 20)

Usage
=====

letterpress(text, options = {})

The letterpress method takes two parameters: the text to be rendered as an 
image and a hash of options.  Supported options are:

  :background_color => The background color, specified in the supported ImageMagick
    formats enumerated at http://www.imagemagick.org/RMagick/doc/imusage.html#color_names.

  :font => The file name of a font found in the letterpress fonts directory.  Any font
    supported by ImageMagick will work.  If no extension is provided, .ttf is assumed.

  :color => The color of the text, specified in the supported ImageMagick formats
    enumerated at http://www.imagemagick.org/RMagick/doc/imusage.html#color_names.

  :size => The size of the text, IN POINTS

  :format => The format of the image that the text will be rendered out to.  This
    can be set as a plugin-wide setting with Letterpress::Config.image_format, or
    this can be specified in each call to letterpress.  The default is 'png'.

  :transparent => The color to make transparent within the image. Pass the same
    color here as in background_color option to make a transparent image for web use.

  :density => The horizontal and vertical resolution in pixels of the image.  Specified
    as the width ("DD") or width and height ("DDxDD").

  :units => the units of image resolution.  Choose from: Undefined, PixelsPerInch, or
    PixelsPerCentimeter.

See http://www.imagemagick.org/script/command-line-options.php for more information.

All unsupported options will be passed on to image_tag as is.  This can be 
used, for example, to provide the css class of the image:

  <%= letterpress "Le géant américain des logiciels", 
        :format => 'jpeg',
        :class => 'some_css_class' %>

The generated image will be written out to the directory configured in 
Letterpress::Config.images_dir (with a filename equal to the md5 hash of the text
and all the options passed in).  If an image with this filename already exists,
it will not be generated again (unless you are in development mode).  Add some
fragment caching and this will perform just as well as pre-generated images and
image_tag.


Examples
========

In RAILS_ROOT/lib/fonts:

  AppleGothic.ttf
  
In a view:
  
  <%= letterpress "Assertively revolutionize worldwide materials via 2.0 content.", :format => 'gif' %>

 Or...

  <%= letterpress "Compellingly harness client-based ideas whereas business schemas.", 
        :font => 'AppleGothic', 
        :size => 55, 
        :color => '#f7f7f7', 
        :background_color => 'red',
        :format => 'png' %>

 Etc.


Rake Task
=========

To clear all previously generated images, run the task provided:

  letterpress:images:clear


Copyright (c) 2008 Norbauer Inc, released under the MIT license