Transfigr

A simple, pluggable plugin to transfigure an object into a format. It can be used as a simple markup transfigurer, i.e. textile or markdown. It can also be used as a general purpose presenter if you define it as such.

Example

  Transfigr.format!(:textile, "h1. I am a textile string")
  Transfigr.format!(:markdown, "I _am_ a markdown string")

Using options You can configure your formatters to take an options hash to customize the format based on options.

  Transfigr.add(:xml) do
    def format!(opts)
      target.to_xml(opts)
    end
  end
  
  Transfigr.format!(:xml, @person_list, :fields => [:name, :age])

This is especially useful when using it as a presenter in merb.

Using it as a Presenter

  Transfigr.presenter(@article).to_xml # requires an :xml format be setup

This is especially useful when using something like Merb’s display method.

All active formats have a method added to the presenter to_<format>

Options in the presenter.

Sometimes you need to customize the format of an object based on the current environment or state of the application.

Transfigr presenters allow options to be passed into the format! method.

As an example, in merb you may use:

  display Transfigr.presenter(@user, :fields => [:name, :age])

When you define the formats, you can make use of any options passed it.

Pluggable Back End

The architecture is pluggable so that you can add your own custom formatters.

By default there are currently:

• :textile – Via RedCloth (you need to install redcloth)
• :markdown – Via RDiscount or as a fallback Bluecloth. RDiscount is much faster http://tomayko.com/writings/ruby-markdown-libraries-real-cheap-for-you-two-for-price-of-one

Make your own store

To define your own format is really simple. Lets look at the textile one.

  Transfigr.add(:textile)
      after_activation do
        require 'redcloth'
      end

      def format!(options = {})
        RedCloth.new(target).to_html
      end
    end
  end

You can define any helpers inline. You can also edit existing formats. Replace formats by simply adding a new one with the same name.

The after_activation block in the add methodis called when the formatter is activated. It is a good place to put any dependencies the formatter may require.

The format!(options = {}) method is the work horse. This is the method that is called to actually transform a string to the new format.

Activation

You must activate a format in order to use it. It is not secure to simply automatically load them.

You can activate existing formats like this:

  Transfigr.activate!(:textile, :markdown, :xml, :html, :pdf, :foo)

You must have these formats defined. Check like Transfigr.defined?(:foo)

That’s basically it.