pull sinatra-contrib docs

_includes/sinatra-config-file.html

@@ -0,0 +1,106 @@
+<h1>Sinatra::ConfigFile</h1>
+<p>
+<tt>Sinatra::ConfigFile</tt> is an extension that allows you to load the
+application&#8217;s configuration from YAML files.  It automatically
+detects if the files contains specific environment settings and it will use
+the corresponding to the current one.
+</p>
+<p>
+Within the application you can access those options through
+<tt>settings</tt>.  If you try to get the value for a setting that
+hasn&#8217;t been defined in the config file for the current environment,
+you will get whatever it was set to in the application.
+</p>
+<h2>Usage</h2>
+<p>
+Once you have written your configurations to a YAML file you can tell the
+extension to load them.  See below for more information about how these
+files are interpreted.
+</p>
+<p>
+For the examples, lets assume the following config.yml file:
+</p>
+<pre>
+    greeting: Welcome to my file configurable application
+</pre>
+<h3>Classic Application</h3>
+<pre>
+    require &quot;sinatra&quot;
+    require &quot;sinatra/config_file&quot;
+
+    config_file 'path/to/config.yml'
+
+    get '/' do
+      @greeting = settings.greeting
+      haml :index
+    end
+
+    # The rest of your classic application code goes here...
+</pre>
+<h3>Modular Application</h3>
+<pre>
+    require &quot;sinatra/base&quot;
+    require &quot;sinatra/config_file&quot;
+
+    class MyApp &lt; Sinatra::Base
+      register Sinatra::ConfigFile
+
+      config_file 'path/to/config.yml'
+
+      get '/' do
+        @greeting = settings.greeting
+        haml :index
+      end
+
+      # The rest of your modular application code goes here...
+    end
+</pre>
+<h3>Config File Format</h3>
+<p>
+In its most simple form this file is just a key-value list:
+</p>
+<pre>
+    foo: bar
+    something: 42
+    nested:
+      a: 1
+      b: 2
+</pre>
+<p>
+But it also can provide specific environment configuration.  There are two
+ways to do that: at the file level and at the setting level.  They are
+illustrated, repsectively, as follows:
+</p>
+<pre>
+    development:
+      foo: development
+      bar: bar
+    test:
+      foo: test
+      bar: bar
+    production:
+      foo: production
+      bar: bar
+</pre>
+<p>
+and
+</p>
+<pre>
+    foo:
+      development: development
+      test: test
+      production: production
+    bar: bar
+</pre>
+<p>
+In either case, <tt>settings.foo</tt> will return the environment name, and
+<tt>settings.bar</tt> will return <tt>&quot;bar&quot;</tt>.
+</p>
+<p>
+Be aware that if you have a different environment, besides development,
+test and production, you will also need to adjust the <tt>environments</tt>
+setting.  For instance, when you also have a staging environment:
+</p>
+<pre>
+    set :environments, %w{development test production staging}
+</pre>

_includes/sinatra-content-for.html

@@ -0,0 +1,63 @@
+<h1>Sinatra::ContentFor</h1>
+<p>
+<tt>Sinatra::ContentFor</tt> is a set of helpers that allows you to capture
+blocks inside views to be rendered later during the request. The most
+common use is to populate different parts of your layout from your view.
+</p>
+<p>
+The currently supported engines are: Erb, Erubis, Haml and Slim.
+</p>
+<h2>Usage</h2>
+<p>
+You call <tt>content_for</tt>, generally from a view, to capture a block of
+markup giving it an identifier:
+</p>
+<pre>
+    # index.erb
+    &lt;% content_for :some_key do %&gt;
+      &lt;chunk of=&quot;html&quot;&gt;...&lt;/chunk&gt;
+    &lt;% end %&gt;
+</pre>
+<p>
+Then, you call <tt>yield_content</tt> with that identifier, generally from
+a layout, to render the captured block:
+</p>
+<pre>
+    # layout.erb
+    &lt;%= yield_content :some_key %&gt;
+</pre>
+<h3>Classic Application</h3>
+<p>
+To use the helpers in a classic application all you need to do is require
+them:
+</p>
+<pre>
+    require &quot;sinatra&quot;
+    require &quot;sinatra/content_for&quot;
+
+    # Your classic application code goes here...
+</pre>
+<h3>Modular Application</h3>
+<p>
+To use the helpers in a modular application you need to require them, and
+then, tell the application you will use them:
+</p>
+<pre>
+    require &quot;sinatra/base&quot;
+    require &quot;sinatra/content_for&quot;
+
+    class MyApp &lt; Sinatra::Base
+      register Sinatra::ContentFor
+
+      # The rest of your modular application code goes here...
+    end
+</pre>
+<h2>And How Is This Useful?</h2>
+<p>
+For example, some of your views might need a few javascript tags and
+stylesheets, but you don&#8217;t want to force this files in all your
+pages. Then you can put <tt>&lt;% yield_content :scripts_and_styles
+%&gt;</tt> on your layout, inside the <head> tag, and each view can call
+<tt>content_for</tt> setting the appropriate set of tags that should be
+added to the layout.
+</p>

_includes/sinatra-cookies.html

@@ -0,0 +1,58 @@
+<h1>Sinatra::Cookies</h1>
+<p>
+Easy way to deal with cookies
+</p>
+<h2>Usage</h2>
+<p>
+Allows you to read cookies:
+</p>
+<pre>
+  get '/' do
+    &quot;value: #{cookie[:something]}&quot;
+  end
+</pre>
+<p>
+And of course to write cookies:
+</p>
+<pre>
+  get '/set' do
+    cookies[:something] = 'foobar'
+    redirect to('/')
+  end
+</pre>
+<p>
+And generally behaves like a hash:
+</p>
+<pre>
+  get '/demo' do
+    cookies.merge! 'foo' =&gt; 'bar', 'bar' =&gt; 'baz'
+    cookies.keep_if { |key, value| key.start_with? 'b' }
+    foo, bar = cookies.values_at 'foo', 'bar'
+    &quot;size: #{cookies.length}&quot;
+  end
+</pre>
+<h3>Classic Application</h3>
+<p>
+In a classic application simply require the helpers, and start using them:
+</p>
+<pre>
+    require &quot;sinatra&quot;
+    require &quot;sinatra/cookies&quot;
+
+    # The rest of your classic application code goes here...
+</pre>
+<h3>Modular Application</h3>
+<p>
+In a modular application you need to require the helpers, and then tell the
+application you will use them:
+</p>
+<pre>
+    require &quot;sinatra/base&quot;
+    require &quot;sinatra/link_header&quot;
+
+    class MyApp &lt; Sinatra::Base
+      helpers Sinatra::Cookies
+
+      # The rest of your modular application code goes here...
+    end
+</pre>

_includes/sinatra-decompile.html

@@ -0,0 +1,43 @@
+<h1>Sinatra::Decompile</h1>
+<p>
+<tt>Sinatra::Decompile</tt> is an extension that provides a method,
+conveniently called <tt>decompile</tt>, that will generate a String pattern
+for a given route.
+</p>
+<h2>Usage</h2>
+<h3>Classic Application</h3>
+<p>
+To use the extension in a classic application all you need to do is require
+it:
+</p>
+<pre>
+    require &quot;sinatra&quot;
+    require &quot;sinatra/decompile&quot;
+
+    # Your classic application code goes here...
+</pre>
+<p>
+This will add the <tt>decompile</tt> method to the application/class scope,
+but you can also call it as <tt>Sinatra::Decompile.decompile</tt>.
+</p>
+<h3>Modular Application</h3>
+<p>
+To use the extension in a modular application you need to require it, and
+then, tell the application you will use it:
+</p>
+<pre>
+    require &quot;sinatra/base&quot;
+    require &quot;sinatra/decompile&quot;
+
+    class MyApp &lt; Sinatra::Base
+      register Sinatra::Decompile
+
+      # The rest of your modular application code goes here...
+    end
+</pre>
+<p>
+This will add the <tt>decompile</tt> method to the application/class scope.
+You can choose not to register the extension, but instead of calling
+<tt>decompile</tt>, you will need to call
+<tt>Sinatra::Decompile.decompile</tt>.
+</p>

_includes/sinatra-extension.html

@@ -0,0 +1,50 @@
+<h1>Sinatra::Extension</h1>
+<p>
+<tt>Sinatra::Extension</tt> is a mixin that provides some syntactic sugar
+for your extensions.  It allows you to call directly inside your extension
+module almost any <tt>Sinatra::Base</tt> method.  This means you can use
+<tt>get</tt> to define a route, <tt>before</tt> to define a before filter,
+<tt>set</tt> to define a setting, a so on.
+</p>
+<p>
+Is important to be aware that this mixin remembers the methods calls you
+make, and then, when your extension is registered, replays them on the
+Sinatra application that has been extended.  In order to do that, it
+defines a <tt>registered</tt> method, so, if your extension defines one
+too, remember to call <tt>super</tt>.
+</p>
+<h2>Usage</h2>
+<p>
+Just require the mixin and extend your extension with it:
+</p>
+<pre>
+    require 'sinatra/extension'
+
+    module MyExtension
+      extend Sinatra::Extension
+
+      # set some settings for development
+      configure :development do
+        set :reload_stuff, true
+      end
+
+      # define a route
+      get '/' do
+        'Hello World'
+      end
+
+      # The rest of your extension code goes here...
+    end
+</pre>
+<p>
+You can also create an extension with the <tt>new</tt> method:
+</p>
+<pre>
+    MyExtension = Sinatra::Extension.new do
+      # Your extension code goes here...
+    end
+</pre>
+<p>
+This is useful when you just want to pass a block to
+<tt>Sinatra::Base.register</tt>.
+</p>