Acts as Markup Extended

GitHub Project: github.com/mitchmarx/acts_as_markup_extended

RDoc:

NOTE:

This is an enhanced version of Brian Landau’s acts_as_markup. It includes the “:extensions =>” option which allows you to specify methods that extend markup languages (see the samples in lib/markup_methods).

DESCRIPTION:

Allows you to specify columns of an ActiveRecord model that contain Markdown, Textile, Wiki text and RDoc. You may then use to_s to get the original markup text or to_html to get the formated HTML.

Additionally you can have a model that contains a column that has a column with markup text, and another that defines what language to process it as. If the field is listed as “markdown” “textile”, “wikitext” or “rdoc” (case insensitive) it will treat it as such, any other value for markup language will have the value pass through as a normal string.

You can use 4 different types of Markdown processing backends: BlueCloth, RDiscount, Ruby PEG or Maruku. You specify which one you want to use by setting a config value in your environment.rb file:

ActsAsMarkup.markdown_library = :bluecloth

By default RDiscount will be used.

You can specify additional options to pass to the markup library by using :markdown_options, :textile_options or :wikitext_options. RDoc does not support any useful options. The options should be given as an array of arguments. You can specify options for multiple languages when allowing more than one. See each library’s documentation for more details on what options are available.

MARKUP EXTENSION METHODS:

For any column you can specify markup extension methods by including :extensions => in any of the forms of acts_as_markup illustrated below.

Sample extensions methods are in: lib/markup_extensions. You can include methods that reside anywhere as long as they are in module MarkupExtensionMethods.

You can invoke all the methods in module MarkupExtensionMethods with :extensions => :all.

EXAMPLES:

Using acts_as_markdown:

class Post < ActiveRecord
  acts_as_markdown :body
end

@post = Post.find(:first)
@post.body.to_s     #=> "## Markdown Headline"
@post.body.to_html  #=> "<h2> Markdown Headline</h2>"

Using acts_as_textile:

class Post < ActiveRecord
  acts_as_textile :body
end

@post = Post.find(:first)
@post.body.to_s     #=> "h2. Textile Headline"
@post.body.to_html  #=> "<h2>Textile Headline</h2>"

Using acts_as_wikitext:

class Post < ActiveRecord
  acts_as_wikitext :body
end

@post = Post.find(:first)
@post.body.to_s     #=> "== Wikitext Headline =="
@post.body.to_html  #=> "<h2>Wikitext Headline</h2>"

Using acts_as_rdoc:

class Post < ActiveRecord
  acts_as_rdoc :body
end

@post = Post.find(:first)
@post.body.to_s     #=> "== RDoc Headline"
@post.body.to_html  #=> "<h2>RDoc Headline</h2>"

Using acts_as_markup:

class Post < ActiveRecord
  acts_as_markup :language => :markdown, :columns => [:body]
end

@post = Post.find(:first)
@post.body.to_s     #=> "## Markdown Headline"
@post.body.to_html  #=> "<h2> Markdown Headline</h2>"

Using acts_as_markup with :variable language:

class Post < ActiveRecord
  acts_as_markup :language => :variable, :columns => [:body]
end

@post = Post.find(:first)
@post.markup_language      # => "markdown"
@post.body.to_s            # => "## Markdown Headline"
@post.body.to_html         # => "<h2> Markdown Headline</h2>"

Using options

class Post < ActiveRecord
  acts_as_markdown :body, :markdown_options => [ :filter_html ]
end

class Post < ActiveRecord
  acts_as_textile :body, :textile_options => [ [ :filter_html ] ]
end

class Post < ActiveRecord
  acts_as_wikitext :body, :wikitext_options => [ { :space_to_underscore => true } ]
end

With markup extension methods

class Post < ActiveRecord
  acts_as_markup :language => :markdown, :columns => [:body],
     :extensions => [:method1, method2, ...].
end

class Post < ActiveRecord
  acts_as_markdown :body, :extensions => :all
end

REQUIREMENTS:

You will need the RedCloth library for processing the Textile text, and the Wikitext library for processing wikitext.

You will also need to install some type of Markdown processor. The three options currently supported are:

INSTALL:

sudo gem install acts_as_markup

Add “acts_as_markup” to your environment.rb:

config.gem "acts_as_markup"

CONTRIBUTING:

Make a fork on GitHub, make your changes and do a pull request. Good places to start are adding new Markdown libraries or new markup languages, here’s instructions for both:

Instructions for how to add a new Markdown Library:

  1. Add another item to the ActsAsMarkup::MARKDOWN_LIBS hash in the form of:

    :bluecloth => {:class_name => "BlueCloth",
               :lib_name   => "bluecloth"}

    :lib_name should be the name needed to require the library, while :class_name should be the class that we are making an instance of.

  2. If you need to modify the object in anyway (e.g. to add a to_s or to_html method), add a file to the “lib/acts_as_markup/exts/” directory.

  3. Add appropriate tests (see current tests).

Instructions for how to add a new Markup Language:

  1. Add a “when” statement to the “case” statement in acts_as_markup. The “when” statement should match with a symbol that represents the language name in some way (e.g. “:markdown”).

  2. In the “when” block you need to set the “klass” local variable and require the library and the extension file if you need one (use the special require_extensions method to require extensions).

  3. Add the same lines you added to the previous “when” statement to the “:variable” “when” statement. But replace “klass” with “language_klass” (e.g. “markdown_klass”).

  4. Add a relevant “when” statement to the class_eval block for the “:variable” language option. This should look something like:

    when /markdown/i
  markup_klasses[:markdown].new self[col].to_s

  5. Add a convenience method (e.g. “acts_as_markdown”)

  6. Add an extension file to the “lib/acts_as_markup/exts/” directory if you need to modify the object in anyway.

  7. Add appropriate tests (see current tests).