Skip to content
A gem for transforming an object to a format
Ruby
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
lib
spec
.gitignore
LICENSE
README.textile
Rakefile
TODO

README.textile

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:

Make your own Formatter

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.

Something went wrong with that request. Please try again.