vanilla 1.0.2 → 1.2

data/pristine_app/soups/extras/comments.rb

@@ -0,0 +1,78 @@
+require 'vanilla/dynasnip'
+require 'date'
+
+class Comments < Dynasnip
+  usage %|
+    Embed comments within snips!
+
+    {comments <false>}
+
+    This will embed a list of comments, and a comment form, in a snip
+    If the snip is being rendered within another snip, it will show a link to the snip,
+    with the number of comments. Add a parameter to disable new comments.
+  |
+
+  def get(disable_new_comments=false)
+    return usage if self.class.snip_name == app.request.snip_name
+    comments = app.soup.with(:commenting_on => enclosing_snip.name)
+    comments_html = if app.request.snip_name == enclosing_snip.name
+      rendered_comments = render_comments(comments)
+      rendered_comments += comment_form.gsub('SNIP_NAME', enclosing_snip.name) unless disable_new_comments
+      rendered_comments
+    else
+     %{<a href="#{url_to(enclosing_snip.name)}">#{comments.length} comments for #{enclosing_snip.name}</a>}
+    end
+    return comments_html
+  end
+
+  def post(*args)
+    snip_name = app.request.params[:snip]
+    existing_comments = app.soup.with(:commenting_on => snip_name)
+    comment = app.request.params.reject { |k,v| ![:author, :email, :website, :content].include?(k) }
+
+    return "You need to add some details!" if comment.empty?
+    return "No spam today, thanks anyway" unless app.request.params[:human] == 'human'
+
+    app.soup << comment.merge({
+     :name => "#{snip_name}-comment-#{existing_comments.length + 1}",
+     :commenting_on => snip_name,
+     :created_at => Time.now
+    })
+    "Thanks for your comment! Back to {link_to #{snip_name}}"
+  end
+
+  def render_comments(comments)
+    "<h2>Comments</h2><ol class='comments'>" + comments.map do |comment|
+      rendered_comment = comment_template.gsub('COMMENT_CONTENT', app.render(comment)).
+                                          gsub('COMMENT_DATE', comment.created_at.to_s)
+      author = comment.author
+      author = "Anonymous" unless author && author != ""
+      if comment.website && comment.website != ""
+        rendered_comment.gsub!('COMMENT_AUTHOR', "<a href=\"#{comment.website}\">#{author}</a>")
+      else
+        rendered_comment.gsub!('COMMENT_AUTHOR', author)
+      end
+      rendered_comment
+    end.join + "</ol>"
+  end
+
+  attribute :comment_template, %{
+    <li>
+      <p>COMMENT_AUTHOR (COMMENT_DATE)</p>
+      <div>COMMENT_CONTENT</div>
+    </li>
+  }
+
+  attribute :comment_form, %{
+    <form class="comments" action="/comments?snip=SNIP_NAME" method="POST">
+      <label>Name: <input type="text" name="author"></input></label>
+      <label>Email: <input type="text" name="email"></input></label>
+      <label>Website: <input type="text" name="website"></input></label>
+      <textarea name="content"></textarea>
+      <label class="human">Type 'human' if you are one: <input type="text" name="human"></input></label>
+      <button>Submit</button>
+    </form>
+  }
+
+  self
+end

data/{lib/vanilla/dynasnips → pristine_app/soups/extras}/kind.rb

@@ -5,41 +5,43 @@ require 'date'
 class Kind < Dynasnip
   def handle(kind, limit=10, as=:html)
     as = as.to_sym
-    snips = Soup.sieve(:kind => kind)
-    entries = snips.sort_by { |s| s.created_at || '' }.reverse[0...limit.to_i].map do |snip|
+    snips = app.soup.with(:kind => kind)
+    entries = snips.sort_by { |s| s.created_at || Time.at(0) }.reverse[0...limit.to_i].map do |snip|
       render_entry_in_template(snip, as, kind)
     end
     render_entry_collection(snips, entries, as, kind)
   end
-  
+
   def render_entry_in_template(snip, as, kind)
-    rendered_contents = prepare_snip_contents(snip)
+    rendered_contents = externalise_links(prepare_snip_contents(snip))
     case as
     when :html
       snip_template.
         gsub('SNIP_KIND', kind).
         gsub('SNIP_NAME', snip.name).
-        gsub('CREATED_AT', snip.created_at || '').
+        gsub('CREATED_AT', snip.created_at.to_s || '').
         gsub('SNIP_CONTENT', rendered_contents)
     when :xml
       Atom::Entry.new do |e|
-        e.published = DateTime.parse(snip.created_at)
-        e.updated = DateTime.parse(snip.updated_at || snip.created_at)
+        e.published = snip.created_at
+        e.updated = snip.updated_at || snip.created_at
         e.content = Atom::Content::Html.new(rendered_contents)
         e.title = snip.name
         e.authors = [Atom::Person.new(:name => snip.author || domain)]
-        e.links << Atom::Link.new(:href => "http://#{domain}#{Vanilla::Routes.url_to(snip.name)}")
-        e.id = "tag:#{domain},#{(snip.created_at || Date.today.to_s).split[0]}:/#{snip.name}"
+        e.links << Atom::Link.new(:href => "http://#{domain}#{url_to(snip.name)}")
+        e.id = "tag:#{domain},#{(snip.created_at.to_s || Date.today.to_s).split[0]}:/#{snip.name}"
       end
     end
   end
-  
+
   def prepare_snip_contents(snip)
-    rendered_snip = app.render(snip)
-    # make all the links absolute
-    rendered_snip.gsub(/href="\//, "href=\"http://#{domain}/")
+    app.render(snip)
+  end
+
+  def externalise_links(content)
+    content.gsub(/href="\//, "href=\"http://#{domain}/").gsub(/src="\//, "src=\"http://#{domain}/")
   end
-  
+
   def render_entry_collection(snips, entries, as, kind)
     case as
     when :html
@@ -47,19 +49,19 @@ class Kind < Dynasnip
     when :xml
       Atom::Feed.new do |f|
         f.title = feed_title
-        f.updated = DateTime.parse(snips[0].updated_at)
+        f.updated = snips[0].updated_at
         f.id = "tag:#{domain},2008-06-01:kind/#{kind}"
         f.entries = entries
       end.to_xml
     end
   end
-  
+
   attribute :feed_title, "Your Blog"
   attribute :domain, "yourdomain.com"
   attribute :snip_template, %{
     <div class="snip SNIP_KIND">
       <div class="details">
-        #{Vanilla::Routes.link_to '#', 'SNIP_NAME'}
+        {link_to_current_snip}
         <p class="created_at">CREATED_AT</p>
       </div>
       <div class="content">

data/{lib/vanilla/dynasnips → pristine_app/soups/extras}/rand.rb

@@ -24,4 +24,6 @@ class RandomNumber < Dynasnip
     max = max.to_i
     (rand(max-min) + min)
   end
+
+  self
 end

data/pristine_app/soups/extras/url_to.rb

@@ -0,0 +1,7 @@
+require 'vanilla/dynasnip'
+
+class UrlTo < Dynasnip
+  def handle(snip_name)
+    app.soup[snip_name] ? url_to(snip_name) : "[Snip '#{snip_name}' not found]"
+  end
+end

data/pristine_app/soups/tutorial/bad_dynasnip.snip

@@ -0,0 +1,8 @@
+class BadDynasnip
+  def get(*args)
+    raise "Oh no"
+  end
+end
+BadDynasnip
+
+:render_as: Ruby

data/pristine_app/soups/tutorial/hello_world.snip

@@ -0,0 +1,20 @@
+class HelloWorld
+  # although the name doesn't need to match the snip name,
+  # it's simple to follow that convention where appropriate
+
+  def handle(name=nil)
+    if name
+      "Hey #{name} - Hello World!"
+    else
+      "Hello World!"
+    end
+  end
+
+  # note that this code must evaluate to a class. One way of achieving that is by 
+  # putting 'self' at the end of the class definition.
+  self
+end
+# Another way is by referring to the class at the end of the content. Either works fine.
+HelloWorld
+
+:render_as: Ruby

data/pristine_app/soups/tutorial/markdown_example.snip

@@ -0,0 +1,13 @@
+
+# testing header
+
+so, how are you?
+
+- item one
+- item two
+- item three
+
+
+what the *hell* are looking at, [beyotch](http://example.com)?
+
+:render_as: Markdown

data/pristine_app/soups/tutorial/snip.snip

@@ -0,0 +1,9 @@
+A snip is the basic building block of information for {link_to vanilla-rb}. Essentially, it is a piece of content with arbitrary attributes. Vanilla anticipates the presence of some key attributes:
+
+ * `name` - the name of the snip, which is how it will be referred to. The `name` of this snip is _snip_.
+ * `content` - the default part of the snip to render. You can see the `content` of this snip <a href="/snip/content.raw">here</a>.
+ * `render_as` - the name of the renderer to use when rendering the content. The `render_as` of this snip is {snip.render_as}.
+
+One implementation of the snip store is {link_to soup}.
+
+:render_as: Markdown

data/pristine_app/soups/tutorial/soup.snip

@@ -0,0 +1,3 @@
+Soup is a data store supporting the {link_to snip}-space that {link_to vanilla-rb} expects.
+
+It's hosted on github <a href="http://github.com/lazyatom/soup">here</a>.

data/pristine_app/soups/tutorial/test.snip

@@ -0,0 +1,30 @@
+Linking is good: {link_to bold}
+Here's a bold snip: {bold}
+
+- Here's a random number between 5 and 15: {rand 5,15}
+- Here's a random number between 1 and 90 (the default min): {rand 90}
+- Here's a random number between 1 and 100 (the default range): {rand}
+
+And lets include some textile: 
+
+{textile_example}
+
+The source for that was 
+
+{pre textile_example}
+
+And lets include some markdown!: 
+
+{markdown_example}
+
+The source for that was 
+
+{pre markdown_example}
+
+How about some {link_to debug} information: {debug}
+
+What about a missing snip? Lets try to include one: {monkey}
+
+And an error when running? {bad_dynasnip}
+
+:render_as: Markdown

data/pristine_app/soups/tutorial/textile_example.snip

@@ -0,0 +1,11 @@
+
+# testing lists
+# because lists are common things
+
+monkey
+
+what the *hell* are __you__ looking at?
+
+"Beyotch":http://example.com
+
+:render_as: Textile

data/pristine_app/soups/tutorial/tutorial-another-snip.snip

@@ -0,0 +1 @@
+this is another snip!

data/pristine_app/soups/tutorial/tutorial-basic-snip-inclusion.snip

@@ -0,0 +1 @@
+This is a snip, which includes another {link_to snip}: {tutorial-another-snip}

data/pristine_app/soups/tutorial/tutorial-dynasnips.snip.markdown

@@ -0,0 +1,56 @@
+{tutorial-links}
+
+Dynasnips
+=========
+
+As mentioned in the general {link_to tutorial}, dynamic content is built in vanilla using "dynasnips". These are snips who content depends on more than just their content.
+
+Typically they are rendered by the `Vanilla::Renderers::Ruby` renderer. Lets look again at the raw content of `link_to`:
+
+    {raw link_to}
+
+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.
+
+You can pass arguments to dynasnips in a number of ways. All of the following are valid:
+
+* {dynasnip apple}
+* {dynasnip apple, banana}
+* {dynasnip apple, big banana, cherry}
+* {dynasnip apple, big banana, "lovely lucious cherry"}
+* {dynasnip apple => true, banana => false}
+* {dynasnip apple: true, banana: false}
+
+Where a simple list of arguments is given, these will be passed to the `handle` method as an array. If a ruby-hash-like syntax is used, a hash of these options will be passed.
+
+Of course, it depends entirely on the implementation of the dynasnip what arguments it expects and accepts; some may require a flat list, while others may require hash-like named arguments.
+
+
+Writing your own Dynasnips
+--------------------------
+
+While dynasnip classes can be provided as part of the vanilla codebase, it's envisioned that much of these will be created by end users in their own sites, either by refering to local classes, or defining the classes directly as the content. Here's an example of that, as the raw content of `hello_world`:
+
+    {raw hello_world}
+
+It's important that the contents of the snip evaluate to a Ruby class; this is easy to achieve by placing `self` as the last statement in the class definition, or referencing the class at the end of the snip; both are shown above.
+
+If we include the dynasnip here as <tt>&#123;hello\_world&#125;</tt>, gives:
+
+> {hello_world}
+
+Note that the `handle` method can take one (optional) argument. Lets try including it with <tt>&#123;hello\_world Dave&#125;</tt>:
+
+> {hello_world Dave}
+
+
+HTTP Verbs
+----------
+
+By default, the Ruby renderer will attempt to call `handle` on a dynasnip instance, but if the instance responds to methods corresponding to the HTTP Verbs - `get`, `post`, `put`, or `delete` - then these methods will be called instead.
+
+This means you can have a single dynasnip which responds differently when receiving a `POST` request - quite useful if you want to write dynasnips that generate and respond to forms, like the `comments` dynasnip in your `extras` soup directory.
+
+There's really no limit to what you can do with dynasnips - only what you can imagine.
+
+
+{tutorial-links}

data/pristine_app/soups/tutorial/tutorial-layout.snip

@@ -0,0 +1,56 @@
+{tutorial-links}
+
+Layouts
+=======
+
+Since you almost certainly want your site to look good, one of the first things you'll want to change in your vanilla site is the layout.
+
+When the browser requests a snip, normally vanilla will present it within a _layout_ template. This would typically include a header, a footer, and any other peripheral markup that shouldn't be within the content of the snip itself. If you're familiar with the construction of web applications, this will be exactly as you expect.
+
+Layouts are just like any other snip - they can be sent through a renderer, and include other snips. The default layout snip is called, predictable, `layout.snip`, and here's the content:
+
+    {raw layout}
+
+When you request `/start`, this is the snip that's actually rendered first. If this snip was just text, that's all that would be returned; however, there are some dynasnip calls in here which help us actually return the content that the user requested.
+
+
+`current_snip`
+--------------
+
+The most significant is the call to `current_snip`. This figures out what snip was actually requested (e.g. if the url is `/start`, it's the {link_to start} snip), and renders it in place.
+
+Here's the source of `current_snip`:
+
+    {raw current_snip}
+
+The default case, as in our layout, is `app.render(app.request.snip, app.request.part)` - it delegates rendering back to the application, which then takes care of processing `start` using the right renderer and so on. This method call returns the fully rendered string, and vanilla replaces the call to the dynasnip with that output, placing our snip in the appropriate place in the layout.
+
+
+Other dynas
+-----------
+
+Of course, you can put other plain content in your layout, and other dynasnips too. In the provided layout there are calls to two other dynasnips.
+
+The first is `page_title`, which simply places a (hopefully) meaningful string in the title element of the page. Snips can set the title to be used by defining a `:page_title` attribute. As usual, the source explains it more clearly:
+
+    {raw page_title}
+
+The second dynasnip used is `link_to_current_snip`, which returns an HTML link to the snip that's currently being rendered. I'll let you figure out how to view the source yourself.
+
+
+Other layouts
+-------------
+
+Vanilla looks for a snip called `layout` by default, but this can be changed by passing in a `:default_layout` option to `Vanilla::App.new`, e.g.
+
+    Vanilla::App.new(:default_layout => "my_layout")
+
+
+You can also override the layout on a per-snip basis, simply by setting the `:layout` attribute of the snip to the name of the layout snip to use instead.
+
+Finally, if you implement a custom renderer class (see {link_to tutorial-renderers, "the renderers tutorial"}), you can also specify a layout to be used when the requested snip invokes that renderer. This can be useful if you have a particular kind of content that requires a different layout entirely.
+
+{tutorial-links}
+
+:render_as: Markdown
+:page_title: Tutorial - Layout

data/pristine_app/soups/tutorial/tutorial-links.snip

@@ -0,0 +1,4 @@
+{link_to tutorial}
+{link_to tutorial-layout}
+{link_to tutorial-renderers}
+{link_to tutorial-dynasnips}

data/pristine_app/soups/tutorial/tutorial-renderers.snip.markdown

@@ -0,0 +1,77 @@
+{tutorial-links}
+
+Renderers
+=========
+
+As well as the flexibility to combine pieces of content, another reason {link_to 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 {link_to 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 {link_to tutorial, 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 {link_to 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:
+
+    Vanilla::App.new(:renderers => {
+      "rdoc" => MyRenderers::RDoc
+    })
+
+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>#{content}</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.
+
+{tutorial-links}