Basics Learn about Layouts Renderer fun More about Dynasnips Cleaning up

Renderers

As well as the flexibility to combine pieces of content, another reason vanilla-rb is more interesting than simpler wiki-ish software is that each piece of content can be processed by arbitrarily complex software before it is composed.

In its simplest form, this means that some content can be written in one format (say, raw HTML) whereas other content can be written in different formats (like Textile or Markdown for richer content). You could write one blog post in Textile, and the next one in Markdown, without any issues, depending on what best suits your purpose.

This is one of the principle drivers behind vanilla-rb; you shouldn’t have to make an upfront decision about how best to structure your all of your content.

This has been covered generally in the main tutorial, but here we’ll go into a bit more detail.

Defining a renderer for a snip

The renderer used for a snip is determined in the following manner

1. Using the snip extension attribute
2. Using the snip render_as attribute
3. Using the default renderer

The snip extension is an attribute generated by the soup library, which roughly corresponds to the file extension of the snip itself. So, if your snip is stored in a file called my-schnip.markdown, the extension property will be markdown. If the filename is my-schnip.snip.markdown, the extension is still just markdown.

To determine the actual renderer from this attributes, a lookup hash is used, mapping these strings onto Ruby classes. The default is something like this:

{
  "base" => Vanilla::Renderers::Base,
  "markdown" => Vanilla::Renderers::Markdown,
  "bold" => Vanilla::Renderers::Bold,
  "erb" => Vanilla::Renderers::Erb,
  "rb" => Vanilla::Renderers::Ruby,
  "ruby" => Vanilla::Renderers::Ruby,
  "haml" => Vanilla::Renderers::Haml,
  "raw" => Vanilla::Renderers::Raw,
  "textile" => Vanilla::Renderers::Textile
}

Adding renderers

New renderers can be added as part of the application configuration:

class Application < Vanilla::App; end

Application.configure do |config|

  # other stuff..

  config.renderers[:my_format] = MyRenderer # the class
end

These will be added to the lookup, and can also used to override the defaults (changing the renderer for “markdown” snips to use RDiscount, or Redcarpet, for example).

Writing new renderers

The simplest renderer inherits from Vanilla::Renderers::Base, and reimplement the process_text method:

module Vanilla::Renderers
  class Bold < Base
    def process_text(content)
      "<b>#[snip 'content' cannot be found]</b>"
    end
  end
end

It is passed a string (either the selected snip’s “content” attribute, or some other explicitly requested attribute), and should return that content in its rendered form. The Vanilla::Renderers::Markdown renderer shows this more clearly:

module Vanilla::Renderers
  class Markdown < Base
    def process_text(content)
      BlueCloth.new(content).to_html
    end
  end
end

There are a number of other methods which can be overridden by custom renderers, but these are beyond the scope of this tutorial; the best way to learn is to look at the set of provided renderers (such as the Erb and Haml ones) and work from there.

Basics Learn about Layouts Renderer fun More about Dynasnips Cleaning up