README.markdown

Jitterbug: A just-in-time image creator for pretty text headers

Jitterbug is a gem that provides on-demand graphical text headers using the font of your choice. Use wherever large collections of rich text headers are necessary — especially useful in i18n projects.

On the initial request, Jitterbug creates the specified header graphic and returns its image or header tag. On subsequent requests it references the already-created graphic and returns the requested valid xhtml tag.

Usage

jitterbug(label, options = {})

Pass the jitterbug helper a string to convert into a header graphic. Optionally pass in any other parameters that differ from the defaults.

:tag Return the specified tag (eg. :tag => :h1) with only the background-image declared inline (see the next section)

:width Maximum width for the generated header image (text will wrap to a new line to stay within the specified width)

Using the :fat and :tag Options

Jitterbug provides two easy ways to display a header graphic within HTML header tags. The first and simplest is by passing :fat => :h1 in with the options (replacing :h1 with whatever tag you need). For example:

<%= jitterbug 'Hello World', :size => 64, :fat => :h2 %>

generates the following HTML with all the necessary styles defined inline:

Global Configuration

You can optionally define a global configuration in config/jitterbug.yml. The following sample mirrors Jitterbug's built in defaults. Note that the asterisk default for the font causes Jitterbug to use the first font that it finds in the font_dir folder.

Jitterbug 0.6.0 uses a new configuration format, breaking compatibility with older versions. The initial root-level block defines the default values. You can include tag-specific cascading definitions. In the config below, H1 tags are 24pt black text, H2 tags are 16pt black text in the DinMedium font, and H2 tags with class small specified are 8pt red text in the DinMedium font.

Dependencies

Jitterbug uses Imagemagick to build the header images. It needs to be installed on your development and production machines, as do any fonts that you're using. The default location for fonts is /lib/fonts in your project.

Compatibility and Font Types

Jitterbug has been tested on OSX and Linux.

The following font formats have successfully passed through the Jitterbug: OpenType (PostScript flavored), OpenType (TrueType flavored), PostScript (Type1), TrueType (Mac), and TrueType (PC). When processing Postscript fonts, Jitterbug (or rather Imagemagick) only uses the font outline file. Note that you should remove any spaces from your font filenames.

If you're using older Mac PostScript fonts you'll need to copy the font definitions from the resource fork to the data fork (see here for more information). In OSX you'd do this: