When I suggested that you write your own blog software, I had no idea that some people would actually take me seriously!

So here’s another tidbit to help you on your way: custom Textile tags.

The Feature

As a developer, it’s nice to use Textile or Markdown for text entry. Simple tags will be converted to HTML, which will save typing and automatically apply some typographic rules.

But it can go one step further if you’re using RedCloth. You can subclass RedCloth and add methods that define your own tags. This is a great way to add shortcuts for complicated sets of HTML or inject hooks for CSS and Javascript.

To create Figure A, I used a technique mentioned by Garrett Dimon in a Digital Web article. It involves a div enhanced with a few CSS classes, enclosing a caption and an image. In addition, I have the power to make it small, medium, or large. A more complete solution would even allow for alternate backgrounds and placement.

But that’s a lot to type every time I want to reference a captioned image! Instead, I wrote a custom Textile tag to do it for me.

Usage

Here’s the custom tag I use:

figure(med). RedCloth 3 Logo | redcloth3-title.jpg

Let’s break it down:

• figure is the custom tag name. It’s a hook into a textile_figure method in my application’s subclass of RedCloth.
• med is a CSS class that will be applied to the div that wraps the figure. This gives me easy control over the size of the figure, and could even be used to pass multiple classes for other effects.
• Next comes the caption. I chose to use a pipe as the delimiter between the caption and the image name.
• It ends with the name of the image.

In that single line, I have all the information I need to construct a figure. Those 50 characters will result in over 200 characters of HTML. I can also use a few lines of Ruby to assign an auto-incrementing figure letter (“Figure A”) and reuse the caption as an alt tag for the image.

Implementation

First, choose a color for your subclass. CaneSugarBrownCloth? MintJulepGreenCloth? It could take hours.

Next, create a file for your subclass. I put yellow_cloth.rb in the lib directory and required it from environment.rb.

unless RedCloth
  require 'RedCloth'
end
class YellowCloth < RedCloth
  # ...

Next, define your custom method. I have a simple ruby tag that applies a CSS class for use with my code highlighter.

def textile_ruby( tag, atts, cite, content )
  # TODO Use the arguments to build some HTML 
  #      and return a string.
end

The arguments passed in can be reused or ignored.

• tag is the name of the tag passed in (ruby in this case).
• atts is a pre-assembled string with passed CSS classes, IDs, hard-coded styles, and language identifiers. If you want to augment this, you’ll need to parse the string and append your own CSS classes (I did this for the figure tag).
• cite is rarely used.
• content This is the actual code, text, or paragraph that follows the tag. In the figure tag, I decided to parse this further and use the elements as the caption and image name.

The figure tag is more complicated.

• I add a figure class to any CSS classes passed in. In order to do this, I need to parse the atts and extract existing CSS classes.
• I split the content on the pipe and use the elements as the caption and image name. You could prepend a filepath onto the image name if all your images are stored in the same place.
• The figure letter is dynamically incremented (Figure A, Figure B, etc.).

def textile_figure(tag, atts, cite, content)
  span_class = "" 
  if atts =~ /class="([^\"]+)"/
    span_class = $1
  end
  (caption, img_url) = content.split("|").map { |w| w.strip! }
  figure_name = "Figure " + @figure_counter.chr
  figure_id   = figure_name.downcase.gsub(" ", "-")
  @figure_counter += 1
  # TODO Construct the HTML
end

Finally, here’s the code to setup the counter:

def initialize(*args)
  @figure_counter = ?A
  super
end

To use your new class, you can override the built-in textilize helper or write a before_save callback on your model to convert the text to HTML with your custom subclass.

before_save :textilize_body
def textilize_body
  self.body_html = YellowCloth.new(self.body).to_html
end

The entire code can be downloaded: yellow_cloth.rb

Bonus

If you use TextMate, you may be aware of the “Show Web Preview” menu item.

It can pipe the text of the current document through its own textile.rb script or through your custom script. I wrote a simple script that uses my subclass instead of RedCloth.

# script/textile.rb
require 'rubygems'
require 'yellow_cloth'
textile = ARGV[0] ? File.read(ARGV[0]) : STDIN.read
puts YellowCloth.new(textile).to_html

Then use the full path to this script as the argument to ‘Pipe text through’:

/Users/topfunky/repos/funkyblog/script/textile.rb

Product Placement

I’ll be speaking at both RailsConf Portland and RubyFringe.

After many requests, I’m proud to introduce the new PeepCode Unlimited plan that gives you a year of access to all PeepCode content. On sale for only $139 until March 21.

Merb is a great compliment to Rails or a capable web framework in its own right. A draft of the PeepCode PDF on Merb is now available (includes a free upgrade when the final is published in the next few weeks).

PeepCode has been growing quickly and we have a ton of new content in the works. Ryan Daigle’s Rails 2 PDF recently became the best-selling PeepCode product of all time. Cody Fauser’s ActiveMerchant PDF is already being called a must read.