vanilla 1.0.2 → 1.2

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

@@ -0,0 +1,69 @@
+{tutorial-links}
+
+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 <a href="{current_snip name}.raw">this snip in raw format</a> in a new window or tab. Ready? OK.
+
+Every piece of information displayed here is stored as a {link_to 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 {link_to tutorial-basic-snip-inclusion}:
+
+    {raw tutorial-basic-snip-inclusion}
+
+When this snip is rendered, it appears like this:
+
+> {tutorial-basic-snip-inclusion}
+
+Notice the use of curly brackets to reference one snip from inside another. {link_to 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 `{current_snip extension}`, 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 {link_to 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:
+
+    {raw tutorial-basic-snip-inclusion}
+
+we can see a reference to the `link_to` snip - <tt>&#123;link\_to snip&#125;</tt>.
+
+Lets look 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. So, in the case of <tt>&#123;link\_to snip&#125;</tt>, 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: {link_to index}
+  * ... and several others.
+
+
+Anyway - that should be enough to get you started.
+
+{tutorial-links}
+
+
+:updated_at: 2011-04-28 16:21:00 +01:00

data/pristine_app/soups/tutorial/vanilla-rb.snip

@@ -0,0 +1,16 @@
+Vanilla.rb is the software powering this site. It's a sort-of wiki/bliki thing, based on {link_to vanilla}.
+
+Here's the [introductory blog post][3].
+
+It's developed on [github][1], and has a [lighthouse bug tracker][2]. 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 {link_to tutorial}).
+
+{tutorial}
+
+
+[1]: http://github.com/lazyatom/vanilla
+[2]: http://lazyatom.lighthouseapp.com/projects/11797-vanilla/tickets
+[3]: http://interblah.net/introducing-vanilla-rb
+
+:render_as: Markdown

data/pristine_app/soups/tutorial/vanilla.snip

@@ -0,0 +1,8 @@
+The bliki upon which {link_to vanilla-rb} is based, written by [Christian Langreiter][1]
+
+[Official Web HQ][2]
+
+[1]: http://www.langreiter.com
+[2]: http://www.vanillasite.at
+
+:render_as: Markdown

data/test/dynasnip_test.rb

@@ -0,0 +1,42 @@
+require "test_helper"
+require 'vanilla/dynasnip'
+
+describe Dynasnip do
+  context "when storing attributes" do
+
+    class ::TestDyna < Dynasnip
+      attribute :test_attribute, "test attribute content"
+    end
+
+    should "make the attribute available as an instance method" do
+      assert_equal "test attribute content", TestDyna.new(@app).test_attribute
+    end
+
+    should "store the attribute in the soup" do
+      @app.soup << TestDyna.snip_attributes
+      assert_equal "test attribute content", @app.soup['test_dyna'].test_attribute
+    end
+
+    should "allow the attribute to be overriden by the soup contents" do
+      @app.soup << TestDyna.snip_attributes
+      snip = @app.soup['test_dyna']
+      snip.test_attribute = "altered content"
+      snip.save
+
+      assert_equal "altered content", TestDyna.new(@app).test_attribute
+    end
+  end
+
+  context "when rendering usage" do
+    class ::ShowUsage < Dynasnip
+      usage "This is the usage"
+      def handle
+        usage
+      end
+    end
+
+    should "show the usage defined in the snip" do
+      assert_equal "This is the usage", ShowUsage.new(@app).handle
+    end
+  end
+end

data/test/dynasnips/link_to_current_snip_test.rb

@@ -0,0 +1,19 @@
+require "test_helper"
+$LOAD_PATH.unshift File.expand_path("../../../pristine_app/soups/dynasnips", __FILE__)
+require "link_to_current_snip"
+
+context "The link_to_current_snip dynasnip" do
+  setup do
+    @app.soup << LinkToCurrentSnip.snip_attributes
+    create_snip :name => "test", :content => "test {link_to_current_snip}"
+  end
+
+  should "render a link to the snip that was requested" do
+    assert_response_body %{test <a href="/test">test</a>}, "/test"
+  end
+
+  should "render a link to the snip that was requested even if it isn't the snip that included the dyna" do
+    create_snip :name => "othertest", :content => "othertest {test}"
+    assert_response_body %{othertest test <a href="/othertest">othertest</a>}, "/othertest"
+  end
+end

data/test/dynasnips/link_to_test.rb

@@ -0,0 +1,27 @@
+require "test_helper"
+$LOAD_PATH.unshift File.expand_path("../../../pristine_app/soups/dynasnips", __FILE__)
+require "link_to"
+
+context "The link_to dynasnip" do
+  setup do
+    create_snip :name => "start", :content => "hello"
+  end
+
+  should "render a link to a snip that exists" do
+    assert_equal %{<a href="/start">start</a>}, render_dynasnip(LinkTo, "start")
+  end
+
+  should "allow specification of the link text" do
+    assert_equal %{<a href="/start">the start snip</a>}, render_dynasnip(LinkTo, "start", "the start snip")
+  end
+
+  should "mark snips that are missing with a class" do
+    assert_equal %{<a class="missing" href="/missing">missing</a>}, render_dynasnip(LinkTo, "missing")
+  end
+
+  private
+
+  def render_dynasnip(klass, *args)
+    klass.new(@app).handle(*args)
+  end
+end

data/test/dynasnips/page_title_test.rb

@@ -0,0 +1,19 @@
+require "test_helper"
+$LOAD_PATH.unshift File.expand_path("../../../pristine_app/soups/dynasnips", __FILE__)
+require "page_title"
+
+context "The page_title dynasnip" do
+  setup do
+    @app.soup << PageTitle.snip_attributes
+  end
+
+  should "render as the requested snip name if that snip has no title" do
+    create_snip :name => "test", :content => "{page_title}"
+    assert_response_body %{test}, "/test"
+  end
+
+  should "render as the requested snip's page_title when that attribute is present" do
+    create_snip :name => "test", :content => "{page_title}", :page_title => "This is a test"
+    assert_response_body %{This is a test}, "/test"
+  end
+end

data/test/renderers/base_renderer_test.rb

@@ -0,0 +1,43 @@
+require "test_helper"
+
+describe Vanilla::Renderers::Base do
+  setup do
+    create_snip(:name => "test", :content => "content content", :part => "part content")
+  end
+
+  should "render the contents part of the snip as it is" do
+    assert_response_body "content content", "/test"
+  end
+
+  should "render the specified part of the snip" do
+    assert_response_body "part content", "/test/part"
+  end
+
+  should "include the contents of a referenced snip" do
+    create_snip(:name => "snip_with_inclusions", :content => "loading {test}")
+    assert_response_body "loading content content", "/snip_with_inclusions"
+  end
+
+  should "be able to render a snip attribute" do
+    create_snip(:name => "snip_with_inclusions", :content => "loading {test.part}")
+    assert_response_body "loading part content", "/snip_with_inclusions"
+  end
+
+  should "perform snip inclusion when rendering a part" do
+    create_snip(:name => "snip_with_inclusions", :content => "other content", :part => "loading {test}")
+    assert_response_body "loading content content", "/snip_with_inclusions/part"
+  end
+
+  should "include other snips using their renderers" do
+    create_snip(:name => "including_snip", :content => "lets include {another_snip}")
+    create_snip(:name => "another_snip", :content => "blah", :render_as => "Bold")
+    assert_equal "lets include <b>blah</b>", response_body_for("/including_snip").gsub(/\s+/, ' ')
+  end
+  
+  context "when trying to include a missing snip" do
+    should "return a string describing the missing snip" do
+      create_snip(:name => 'blah', :content => 'include a {missing_snip}')
+      assert_response_body "include a [snip 'missing_snip' cannot be found]", "/blah"
+    end
+  end
+end

data/test/renderers/erb_renderer_test.rb

@@ -0,0 +1,29 @@
+require "test_helper"
+
+describe Vanilla::Renderers::Erb do
+  context "when rendering" do
+    should "insert evaluated Erb content into the snip" do
+      erb_snip(:name => "test", :content => "<%= 1 + 2 %>")
+      assert_response_body "3", "/test"
+    end
+
+    should "evaluate Erb content in the snip" do
+      erb_snip(:name => "test", :content => "<% if false %>monkey<% else %>donkey<% end %>")
+      assert_response_body "donkey", "/test"
+    end
+
+    should "expose the snip as an instance variable" do
+      erb_snip(:name => "test", :content => "<%= @snip.name %>")
+      assert_response_body "test", "/test"
+    end
+
+    should "expose the app as an instance variable" do
+      erb_snip(:name => "test", :content => "<%= @app.class.name %>")
+      assert_response_body "Vanilla::App", "/test"
+    end
+  end
+
+  def erb_snip(params)
+    create_snip(params.merge(:render_as => "Erb"))
+  end
+end

data/test/renderers/haml_renderer_test.rb

@@ -0,0 +1,35 @@
+require 'test_helper'
+require 'haml'
+
+describe Vanilla::Renderers::Haml do
+  context "when rendering" do
+    should "render Haml into HTML" do
+      haml_snip(:name => "test", :content => "#hello\n  stuff")
+      assert_response_body %{<div id='hello'>\n  stuff\n</div>}, "/test"
+    end
+
+    should "insert evaluated Haml content into the snip" do
+      haml_snip(:name => "test", :content => "= 1 + 2")
+      assert_response_body "3", "/test"
+    end
+
+    should "evaluate Erb content in the snip" do
+      haml_snip(:name => "test", :content => "- if false\n  monkey\n- else\n  donkey")
+      assert_response_body "donkey", "/test"
+    end
+
+    should "expose the snip as an instance variable" do
+      haml_snip(:name => "test", :content => "= @snip.name")
+      assert_response_body "test", "/test"
+    end
+
+    should "expose the app as an instance variable" do
+      haml_snip(:name => "test", :content => "= @app.class.name")
+      assert_response_body "Vanilla::App", "/test"
+    end
+  end
+
+  def haml_snip(params)
+    create_snip(params.merge(:render_as => "Haml"))
+  end
+end

data/test/renderers/markdown_renderer_test.rb

@@ -0,0 +1,31 @@
+require "test_helper"
+
+describe Vanilla::Renderers::Markdown do
+  context "when rendering" do
+    should "return the snip contents rendered via Markdown" do
+      content = <<Markdown
+# markdown
+
+* totally
+* [rocks](http://www.example.com)!
+Markdown
+      markdown_snip(:name => "test", :content => content)
+      assert_response_body BlueCloth.new(content).to_html, "/test"
+    end
+
+    should "include other snips using their renderers" do
+      markdown_snip(:name => "test", :content => <<-Markdown
+# markdown
+
+and so lets include {another_snip}
+Markdown
+      )
+      create_snip(:name => "another_snip", :content => "blah", :render_as => "Bold")
+      assert_equal "<h1>markdown</h1> <p>and so lets include <b>blah</b></p>", response_body_for("/test").gsub(/\s+/, ' ')
+    end
+  end
+
+  def markdown_snip(attributes)
+    create_snip(attributes.merge(:render_as => "Markdown"))
+  end
+end

data/test/renderers/raw_renderer_test.rb

@@ -0,0 +1,23 @@
+require "test_helper"
+
+describe Vanilla::Renderers::Raw do
+  context "when rendering" do
+    setup do
+      @snip = create_snip(:name => "test", :content => "raw content", :part => "raw part")
+      set_main_template "<tag>{current_snip}</tag>"
+    end
+
+    should "render the contents part of the snip as it is" do
+      assert_response_body "raw content", "/test.raw"
+    end
+  
+    should "render the specified part of the snip" do
+      assert_response_body "raw part", "/test/part.raw"
+    end
+  
+    should "not perform any snip inclusion" do
+      create_snip(:name => "snip_with_inclusions", :content => "loading {another_snip}")
+      assert_response_body "loading {another_snip}", "/snip_with_inclusions.raw"
+    end
+  end
+end

data/test/renderers/ruby_renderer_test.rb

@@ -0,0 +1,59 @@
+require "test_helper"
+
+describe Vanilla::Renderers::Ruby do
+  context "when rendering normally" do
+    class ::TestDyna < Dynasnip
+      def handle(*args)
+        'handle called'
+      end
+    end
+
+    setup do
+      @app.soup << TestDyna.snip_attributes
+    end
+
+    should "render the result of the handle method" do
+      assert_response_body 'handle called', "/test_dyna"
+    end
+  end
+
+  context "when responding restfully" do
+    class ::RestishDyna < Dynasnip
+      def get(*args)
+        'get called'
+      end
+      def post(*args)
+        'post called'
+      end
+    end
+
+    setup do
+      @app.soup << RestishDyna.snip_attributes
+    end
+
+    should "render the result of the get method on GET requests" do
+      assert_response_body 'get called', "/restish_dyna"
+    end
+
+    should "render the result of the post method on POST requests" do
+      assert_response_body 'post called', "/restish_dyna?_method=post"
+    end
+  end
+
+  context "when knowing about enclosing snips" do
+    class ::Encloser < Dynasnip
+      def handle(*args)
+        "enclosing snip is #{enclosing_snip.name}"
+      end
+    end
+
+    setup do
+      @app.soup << Encloser.snip_attributes
+      create_snip(:name => "test", :content => "{encloser}")
+    end
+
+    should "know about the snip that called this dynasnip" do
+      assert_response_body 'enclosing snip is test', "/test"
+    end
+  end
+end

data/test/snip_inclusion_test.rb

@@ -0,0 +1,56 @@
+require "test_helper"
+
+context "When including snips in other snips" do
+  setup do
+    create_snip :name => "test", :content => "snip content"
+  end
+
+  should "match simple snips" do
+    assert_equal "rendering snip content", render("rendering {test}")
+  end
+
+  should "match snips with an argument" do
+    assert_equal "rendering snip content", render("rendering {test arg1}")
+  end
+
+  should "match snips with several arguments" do
+    assert_equal "rendering snip content", render("rendering {test arg1, arg2}")
+  end
+
+  should "match snips with hyphens" do
+    create_snip :name => "test-snip", :content => "snip content"
+    assert_equal "rendering snip content", render("rendering {test-snip}")
+  end
+
+  should "match snips with underscores" do
+    create_snip :name => "test_snip", :content => "snip content"
+    assert_equal "rendering snip content", render("rendering {test_snip}")
+  end
+
+  should "match snips with numbers" do
+    create_snip :name => "test1", :content => "snip content"
+    assert_equal "rendering snip content", render("rendering {test1}")
+  end
+
+  should "match snips with ruby 1.9 style hashes" do
+    create_snip :name => "test", :content => %{
+      class Blah
+        def handle(args)
+          args.inspect
+        end
+        self
+      end
+    }, :render_as => "Ruby"
+    assert_equal %{rendering {:x=>"1"}}, render("rendering {test x:1}")
+  end
+
+  should "ignore references that are rubyish" do
+    assert_equal "10.times { |x| puts x }", render("10.times { |x| puts x }")
+    assert_equal "10.times {|x| puts x }", render("10.times {|x| puts x }")
+  end
+
+  def render(content)
+    snip = create_snip :name => "test-content", :content => content
+    Vanilla::Renderers::Base.new(@app).render(snip)
+  end
+end