vanilla-rb

; updated

Vanilla.rb is the software powering this site. It’s a sort-of wiki/bliki thing, based on vanilla.

READMEish Stuff

The Skinny

Here’s the introductory blog post: introducing-vanilla-rb.

It’s developed on github, and has a lighthouse bug tracker. At the moment it’s not very well documented, since I’m exploring how the concept might work and the internals are subject to change. However, please do play around with it.

Here’s the tutorial (helpfully included from vanilla-rb-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 Couldn't find part "extension" for snip "vanilla-rb", and the render_as property of markdown_example is Markdown. Scroll to the bottom of the raw markdown_example snip in your editor, and you’ll see this being declared.

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:

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:

Anyway - that should be enough to get you started.

Basics Learn about Layouts Renderer fun More about Dynasnips Cleaning up