tutorial

Basics Learn about Layouts Renderer fun More about Dynasnips Cleaning up

Snips - the basic concept

Firstly, open the raw contents of this snip - either in your editor (search for vanilla-rb-tutorial.snip), or by opening this snip in raw format in a new window or tab. Ready? OK.

Every piece of information displayed here is stored as a snip. Snips, within their contents, can also reference other snips. When you request a snip, it will render into a page (or another kind of response), and also render any snips that it internally references.

For example, consider the snip tutorial-basic-snip-inclusion:

This is a snip, which includes another {link_to snip}: {tutorial-another-snip}

When this snip is rendered, it appears like this:

This is a snip, which includes another snip: this is another snip!

Notice the use of curly brackets to reference one snip from inside another. vanilla-rb finds these references to snips, then renders that snip and replaces it in the first snip. Neat!

Renderers

The way that a snip is rendered depends on whether or not it has an extension, or a render_as attribute set. For instance, the extention of this snip is

markdown

This means that the content of this snip will be passed through Vanilla::Renderers::Markdown before it is then rendered to the page. There are several different renders provided by Vanilla.rb at the moment:

• Markdown - as described above
• Textile - which performs similarly for Textile. This means that you can mix how you write the content of snips!
• Raw - which simply returns the content of the snip, as-is. If you attach a .raw extension to this url, you’ll see it in action
• Bold - simply wraps the content in bold. It’s a demo, essentially.
• Erb - passes the snip contents through Ruby’s Erb library. It also makes some information available for use by ruby code within the snip’s contents
• Ruby - parses the snips content as Ruby itself.

You can see a lot of these renderers being exercised in the test snip.

It’s using this last renderer that a second concept of Vanilla is implemented - dynasnips.

Dynasnips

Because the curly braces simply cause a snip to be rendered, we can use this in conjunction with the Ruby renderer to run actual code. For instance, in the snip above:

This is a snip, which includes another {link_to snip}: {tutorial-another-snip}

we can see a reference to the link_to snip - snip.

Lets look at the raw content of link_to:

class LinkTo < Vanilla::Dynasnip
  usage %|
The link_to dyna lets you create links between snips: 

  {link_to blah} 

would insert a link to the blah snip.|

  def handle(name=nil, link_text=name, part=nil)
    return usage if requesting_this_snip?
    return "You must provide a snip name" unless name
    if app.soup[name]
      %{<a href="#{url_to(name, part)}">#{link_text}</a>}
    else
      %{<a class="missing" href="#{url_to(name, part)}">#{link_text}</a>}
    end
  end

  self
end

As you can see, it simply refers to the Ruby class LinkTo, which is contained within the vanilla-rb codebase. When the Ruby renderer is called, expects the given code to evaulate to a Ruby class. It then instantiates the class, and calls a handle method on the instance, passing it any other arguments from the snip inclusion. So, in the case of snip, the only argument is snip.

Included Dynasnips

Vanilla.rb includes a number of dynasnips by default. Here are a couple:

• link_to, to produce a link to another snip
• raw, which displays the raw contents of a snip
• index, which shows all of the available snips: index
• … and several others.

Anyway - that should be enough to get you started.

Basics Learn about Layouts Renderer fun More about Dynasnips Cleaning up