tutorial
; updated James Adam
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 markdownrender_as
attribute set. For instance, the extention of this snip is
, 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:
- 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 snipraw
, which displays the raw contents of a snipindex
, 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