jitterbug 0.3.0 → 0.4.0

data/README.markdown

@@ -1,46 +1,147 @@
 # Jitterbug: A just-in-time image creator for pretty text headers
 
-Jitterbug provides on-demand text header images using the font of your choice. On the first request, Jitterbug creates the requested header graphic and returns its image tag. On subsequent requests it returns the image tag of the already-created graphic.
+Jitterbug provides on-demand graphical text headers using the font of your choice. On the first request, Jitterbug creates the requested header graphic and returns its image tag. On subsequent requests it returns the image tag of the already-created graphic.
 
 ## 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.
 
-    <%= jitterbug 'Default' %>
-    <%= jitterbug('Forty Two', :size => 42) %>
-    <%= jitterbug(t('whole_enchilada'), :background => '#fff', :color => 'green', :font => 'Yummy.otf', :font_dir => '/fonts/', :format => 'gif', :img_path => '/images/headers/', :size => 64, :width => 240) %>
+    jitterbug 'Hello World'
+    => <img alt="Hello World" class="jitterbug" src="/content/jitterbug/72a65768cdccea18870b0cb2bdff4703.png?1258050948" />
 
-## Dependencies
+![Hello World](http://a51.flying-saucer.net/jitterbug/72a65768cdccea18870b0cb2bdff4703.png)
 
-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.
+    jitterbug t('hello_world')
+    => <img alt="¡Hola, mundo!" class="jitterbug" src="/content/jitterbug/3a395edcea566b56ed20f6c7b96aeec9.png?1258050948" />
 
-## Quick Links
+![¡Hola, mundo!](http://a51.flying-saucer.net/jitterbug/3a395edcea566b56ed20f6c7b96aeec9.png)
+
+    jitterbug 'Hello Big World', :size => 72
+    => <img alt="Hello Big World" class="jitterbug" src="/content/jitterbug/2dd5f6f98139fcdf3e671eca84671baf.png?1258050948" />
+
+![Hello Big World](http://a51.flying-saucer.net/jitterbug/2dd5f6f98139fcdf3e671eca84671baf.png)
+
+    jitterbug 'Well hello, World, how do you do?', :tag => :h1, :width => 240, :style => 'height: 110px;'
+    => <h1 class="jitterbug" style="background-image:url(/content/jitterbug/e0eb0490fcf15de125eaca6cbdffee12.png);height: 110px;">Well hello, World, how do you do?</h1>
 
- * [github.com/flyingsaucer/jitterbug](http://github.com/flyingsaucer/jitterbug)
- * [imagemagick.org](http://www.imagemagick.org/script/index.php)
+
+![Well hello, World, how do you do?](http://a51.flying-saucer.net/jitterbug/e0eb0490fcf15de125eaca6cbdffee12.png)
+
+    jitterbug 'Hello_World.gif', :fat => :h2, :format => :gif, :color => '#FFCC00', :background => 'black'
+    => <h2 class="jitterbug" style="display:block;text-indent:-9999px;margin:0;padding:0;background:url(/content/jitterbug/11686362655ca2fb3235b23a6d6c2621.gif)no-repeat;height:36px;">Hello_World.gif</h2>
+
+![Hello_World.gif](http://a51.flying-saucer.net/jitterbug/11686362655ca2fb3235b23a6d6c2621.gif)
 
 ## Installation
 
+Install the gem:
+
     sudo gem install jitterbug
 
 In your `config/environment.rb` file:
 
     Rails::Initializer.run do |config|
+      ...
       config.gem "jitterbug", :source  => 'http://gemcutter.org/'
+      ...
     end
 
-## Configuration
+In your `app\controllers\application_controller.rb` file:
+
+    class ApplicationController < ActionController::Base
+      ...
+      helper Jitterbug
+      ...
+    end
+
+Drop any fonts into your project's font directory (by default `/lib/fonts`).
+    
+## Available Options
+
+`:background` Background color for the generated header image (default `transparent`)
+
+`:class` Any additional classes to include in the generated tag (default `jitterbug`)
+
+`:color` Font color for the generated header image (default `black`)
+
+`:fat` Return the specified tag (eg. `:fat => :h1`) with full inline styles to hide a text label and show the graphic instead (see the next section)
+
+`:font_dir` Directory where fonts reside (default `/lib/fonts/`)
+
+`:font` Font to use in the generated header image (default `*`, ie. first font found in the font directory)
+
+`:format` Format to output the generated header image (default `png`)
+
+`:img_path` Image path for generated header images (default `/content/jitterbug/`)
+
+`:size` Font size for the generated header image (default `16`)
+
+`:style` Any additional inline styles to include in the generated tag
+
+`: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:
+
+    <h2 class="jitterbug" style="display:block;text-indent:-9999px;margin:0;padding:0;background:url(/content/jitterbug/a034939a8aaccd59354207b4fdff120b.png)no-repeat;height:64px;">Hello World</h2>
+
+The alternative option is `:tag => :h1`:
+
+    <%= jitterbug 'Hello World', :tag => :h1, :width => 240 %>
+
+Which generates a leaner tag:
+
+    <h1 class="jitterbug" style="background-image:url(/content/jitterbug/37cf820f2f6b018f6f4d486517ac8d20.png);">Hello World</h1>
+    
+And relies on an external stylesheet like the following:
+
+    h1.jitterbug {
+      background-repeat: no-repeat;
+      display: block;
+      height: 64px;
+      margin: 0;
+      padding: 0;
+      text-indent: -9999px;
+    }
+
+## 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.
+
+Jitterbug's currently Rails-centric, with these Rails dependencies: `RAILS_ROOT`, `content_tag`, `image_tag`. These aren't completely necessary, but we haven't had a need to remove them yet.
+
+## 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. Please rename any fonts with spaces in their filename.
+
+## Quick Links
+
+ * [github.com/flyingsaucer/jitterbug](http://github.com/flyingsaucer/jitterbug)
+ * [imagemagick.org](http://www.imagemagick.org/script/index.php)
+
+## Global Configuration
 
 Define your global configuration in `config/jitterbug.yml`. The following sample contains 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.
 
     development:   &defaults
       background:  transparent
-      color:       white
+      color:       black
       font:        *
       font_dir:    /lib/fonts/
       format:      png
       img_path:    /content/jitterbug/
-      size:        14
+      size:        16
 
     test:
       <<:          *defaults

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/jitterbug.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{jitterbug}
-  s.version = "0.3.0"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Chris Sessions", "Seth Engelhard"]
-  s.date = %q{2009-11-03}
+  s.date = %q{2009-11-12}
   s.description = %q{Jitterbug provides on-demand text header images using the font of your choice. On its first request, Jitterbug creates the requested header graphic. Then, and on subsequent requests, it returns an html image tag pointing to the header graphic file.}
   s.email = %q{contact@flying-saucer.net}
   s.extra_rdoc_files = [
@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
      "jitterbug.gemspec",
      "lib/jitterbug.rb",
      "lib/jitterbug/config.rb",
+     "lib/jitterbug/css.rb",
      "lib/jitterbug/fonts.rb",
      "spec/jitterbug_spec.rb",
      "spec/spec.opts",

data/lib/jitterbug/config.rb

@@ -7,7 +7,7 @@ module Jitterbug
                    :font_dir   => '/lib/fonts/',
                    :format     => 'png',
                    :img_path   => '/content/jitterbug/',
-                   :size       => 13 }
+                   :size       => 16 }
 
     def self.read
       config = "#{RAILS_ROOT}/config/jitterbug.yml"

data/lib/jitterbug/css.rb

@@ -0,0 +1,15 @@
+module Jitterbug
+  module Css
+
+    def self.fat(src, opts)
+      css = "display:block;text-indent:-9999px;margin:0;padding:0;background:url(#{src})no-repeat;"
+      css += "height:#{opts[:size]}px;" if opts[:width].nil?
+      "#{css}#{opts[:style].to_s}"
+    end
+
+    def self.tag(src, opts)
+      "background-image:url(#{src});#{opts[:style].to_s}"
+    end
+
+  end
+end

data/lib/jitterbug/fonts.rb

@@ -10,6 +10,6 @@ module Jitterbug
         else    raise "*** Jitterbug Error: Multiple fonts matched '#{_font}' in #{_path}:\n    + #{font.join("\n    + ")}"
       end
     end
-    
+
   end
 end

data/lib/jitterbug.rb

@@ -1,4 +1,5 @@
 require 'jitterbug/config'
+require 'jitterbug/css'
 require 'jitterbug/fonts'
 require 'md5'
 
@@ -8,7 +9,7 @@ module Jitterbug
     Jitterbug::Config.read
   end
 
-  def jitterbug(label = '<no label provided>', options = {})
+  def jitterbug(label = '<jitterbug>', options = {})
     options = Jitterbug::Config.settings.merge(options)
     hash = MD5.new("#{label}#{options.sort {|a, b| a[0].to_s <=> b[0].to_s}.to_s}")
     path = "#{RAILS_ROOT}/public/#{options[:img_path]}/#{hash}.#{options[:format]}".gsub('//', '/')
@@ -21,7 +22,13 @@ module Jitterbug
     end
     img_src   = "/#{options[:img_path]}/#{hash}.#{options[:format]}".gsub('//', '/')
     img_class = (['jitterbug'] << options[:class]).compact.join(' ')
-    %Q{<img src="#{img_src}" class="#{img_class}" alt="#{label}" />}
+    if options[:tag]
+      content_tag(options[:tag], label, :class => img_class, :style => Jitterbug::Css.tag(img_src, options))
+    elsif options[:fat]
+      content_tag(options[:fat], label, :class => img_class, :style => Jitterbug::Css.fat(img_src, options))
+    else
+      image_tag(img_src, :alt => label, :class => img_class)
+    end
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jitterbug
 version: !ruby/object:Gem::Version 
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors: 
 - Chris Sessions
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-11-03 00:00:00 -08:00
+date: 2009-11-12 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -42,6 +42,7 @@ files:
 - jitterbug.gemspec
 - lib/jitterbug.rb
 - lib/jitterbug/config.rb
+- lib/jitterbug/css.rb
 - lib/jitterbug/fonts.rb
 - spec/jitterbug_spec.rb
 - spec/spec.opts