@@ -30,7 +30,7 @@ body pre body a { color: #1177DD; - text-decoration: none; } + text-decoration: none; } body a:hover { text-decoration: underline; } assets/book.css @@ -5,7 +5,7 @@ Use Sinatra's "set" option -------------------------- -external config file via the configure block +External config file via the configure block -------------------------------------------- book/Configuration.markdown @@ -9,7 +9,7 @@ available for all major platforms: * [Windows][git_win] * [Mac OS X][git_osx] * Linux and BSD users can usually acquire [Git][git] through their Package - Management System, e.g. "apt-get install git-core" on Debian systems. + Management System, e.g. `apt-get install git-core` on Debian systems. After that, cloning the Sinatra repository is as easy as typing the following into your command line: book/Contributing.markdown @@ -9,57 +9,61 @@ proxy setup using Lighttpd and Thin. 1. Install Lighttpd and Thin - # Figure out lighttpd yourself, it should be handled by your - # linux distro's package manager - - # For thin: - gem install thin + # Figure out lighttpd yourself, it should be handled by your + # linux distro's package manager + + # For thin: + gem install thin -2. Create your rackup file - the "require 'app'" line should require the actual +2. Create your rackup file -- the `require 'app'` line should require the actual Sinatra app you have written. - set :env, :production - set :port, 4567 - disable :run, :reload - - require 'app' - run Sinatra.application + require 'rubygems' + require 'sinatra' + + set :env, :production + set :port, 4567 + disable :run, :reload + + require 'app' + + run Sinatra.application 3. Setup a config.yml - change the /path/to/my/app path to reflect reality. - --- - environment: production - chdir: /path/to/my/app - address: 127.0.0.1 - user: root - group: root - port: 4567 - pid: /path/to/my/app/thin.pid - rackup: /path/to/my/app/config.ru - log: /path/to/my/app/thin.log - max_conns: 1024 - timeout: 30 - max_persistent_conns: 512 - daemonize: true + --- + environment: production + chdir: /path/to/my/app + address: 127.0.0.1 + user: root + group: root + port: 4567 + pid: /path/to/my/app/thin.pid + rackup: /path/to/my/app/config.ru + log: /path/to/my/app/thin.log + max_conns: 1024 + timeout: 30 + max_persistent_conns: 512 + daemonize: true 4. Setup lighttpd.conf - change mydomain to reflect reality. Also make sure the first port here matches up with the port setting in config.yml. - $HTTP["host"] =~ "(www\.)?mydomain\.com" { - proxy.balance = "fair" - proxy.server = ("/" => - ( - ( "host" => "127.0.0.1", "port" => 4567 ), - ( "host" => "127.0.0.1", "port" => 4568 ) - ) - ) - } + $HTTP["host"] =~ "(www\.)?mydomain\.com" { + proxy.balance = "fair" + proxy.server = ("/" => + ( + ( "host" => "127.0.0.1", "port" => 4567 ), + ( "host" => "127.0.0.1", "port" => 4568 ) + ) + ) + } 5. Start thin and your application. I have a rake script so I can just call "rake start" rather than typing this in. - thin -s 2 -C config.yml -R config.ru start + thin -s 2 -C config.yml -R config.ru start You're done! Go to mydomain.com/ and see the result! Everything should be setup now, check it out at the domain you setup in your lighttpd.conf file. @@ -67,21 +71,21 @@ now, check it out at the domain you setup in your lighttpd.conf file. *Variation* - nginx via proxy - The same approach to proxying can be applied to the nginx web server - upstream www_mydomain_com { - server 127.0.0.1:5000; - server 127.0.0.1:5001; - } - - server { - listen www.mydomain.com:80 - server_name www.mydomain.com live; - access_log /path/to/logfile.log - - location / { - proxy_pass http://www_mydomain_com; - } - - } + upstream www_mydomain_com { + server 127.0.0.1:5000; + server 127.0.0.1:5001; + } + + server { + listen www.mydomain.com:80 + server_name www.mydomain.com live; + access_log /path/to/logfile.log + + location / { + proxy_pass http://www_mydomain_com; + } + + } *Variation* - More Thin instances - To add more thin instances, change the `-s 2` parameter on the thin start command to be how ever many servers you want. @@ -99,68 +103,68 @@ You can find additional documentation at the Passenger Github repository. 1. Setting up the account in the Dreamhost interface - Domains -> Manage Domains -> Edit (web hosting column) - Enable 'Ruby on Rails Passenger (mod_rails)' - Add the public directory to the web directory box. So if you were using 'rails.com', it would change to 'rails.com/public' - Save your changes + Domains -> Manage Domains -> Edit (web hosting column) + Enable 'Ruby on Rails Passenger (mod_rails)' + Add the public directory to the web directory box. So if you were using 'rails.com', it would change to 'rails.com/public' + Save your changes 2. Creating the directory structure - domain.com/ - domain.com/tmp - domain.com/public - # a vendored version of sinatra - not necessary if you use the gem - domain.com/sinatra - -3. Creating the "Rackup file" (rack configuration file) `config.ru` + domain.com/ + domain.com/tmp + domain.com/public + # a vendored version of sinatra - not necessary if you use the gem + domain.com/sinatra - # This file goes in domain.com/config.ru - require 'sinatra/lib/sinatra.rb' # "require 'sinatra'" if installed as a gem - require 'rubygems' - - set :env, :production - disable :run +3. Creating the "Rackup file" (rack configuration file) `config.ru` -- the `require 'app'` + line should require the actual Sinatra app you have written. - require 'test.rb' # assumes your Sinatra application file is 'test.rb' - - run Sinatra.application + # This file goes in domain.com/config.ru + require 'rubygems' + require 'sinatra' + + set :env, :production + disable :run + + require 'app' + + run Sinatra.application 4. A very simple Sinatra application - # this is test.rb referred to above - get '/' do - "Worked on dreamhost" - end - - get '/foo/:bar' do - "You asked for foo/#{params[:bar]}" - end + # this is test.rb referred to above + get '/' do + "Worked on dreamhost" + end + + get '/foo/:bar' do + "You asked for foo/#{params[:bar]}" + end + And that's all there is to it! Once it's all setup, point your browser at your domain, and you should see a 'Worked on Dreamhost' page. To restart the application after making changes, you need to run `touch tmp/restart.txt`. - Please note that currently passenger 2.0.3 has a bug where it can cause Sinatra to not find the view directory. In that case, add `:views => '/path/to/views/'` to the Sinatra options in your Rackup file. Additional note: some documentation sources will have a different format for passing options to Sinatra in the Rackup file, e.g.: - - Sinatra::Application.default_options.merge!( - :run => false, - :env => :production, - :raise_errors => true - ) - - + + Sinatra::Application.default_options.merge!( + :run => false, + :env => :production, + :raise_errors => true + ) + +This is perfectly valid, however calling `set`, `disable` and `enable` is preferred. FastCGI {#deployment_fastcgi} ------- The standard method for deployment is to use Thin or Mongrel, and have a -reverse proxy (lighttpd, nginx, or even Apache) point to your -bundle of servers. +reverse proxy (lighttpd, nginx, or even Apache) point to your bundle of servers. But that isn't always possible. Cheaper shared hosting (like Dreamhost) won't let you run Thin or Mongrel, or setup reverse proxies (at least on the default @@ -182,84 +186,85 @@ Steps to deploy via FastCGI: 1. .htaccess - RewriteEngine on - - AddHandler fastcgi-script .fcgi - Options +FollowSymLinks +ExecCGI - - RewriteRule ^(.*)$ dispatch.fcgi [QSA,L] + RewriteEngine on + + AddHandler fastcgi-script .fcgi + Options +FollowSymLinks +ExecCGI + + RewriteRule ^(.*)$ dispatch.fcgi [QSA,L] 2. dispatch.fcgi - #!/usr/bin/ruby - - require 'sinatra/lib/sinatra.rb' - require 'rubygems' - - fastcgi_log = File.open("fastcgi.log", "a") - STDOUT.reopen fastcgi_log - STDERR.reopen fastcgi_log - STDOUT.sync = true - - set :logging, false - set :server, "FastCGI" - - module Rack - class Request - def path_info - @env["REDIRECT_URL"].to_s - end - def path_info=(s) - @env["REDIRECT_URL"] = s.to_s - end - end - end - - load 'test.rb' + + #!/usr/bin/ruby + + require 'rubygems' + require 'sinatra/lib/sinatra' + + fastcgi_log = File.open("fastcgi.log", "a") + STDOUT.reopen fastcgi_log + STDERR.reopen fastcgi_log + STDOUT.sync = true + + set :logging, false + set :server, "FastCGI" + + module Rack + class Request + def path_info + @env["REDIRECT_URL"].to_s + end + def path_info=(s) + @env["REDIRECT_URL"] = s.to_s + end + end + end + + load 'app.rb' 3. sinatra.rb - Replace this function with the new version here (commenting out the `puts` lines) - def run - begin - #puts "== Sinatra has taken the stage on port #{port} for #{env} with backup by #{server.name}" - require 'pp' - server.run(application) do |server| - trap(:INT) do - server.stop - #puts "\n== Sinatra has ended his set (crowd applauds)" - end - end - rescue Errno::EADDRINUSE => e - #puts "== Someone is already performing on port #{port}!" - end - end + def run + begin + #puts "== Sinatra has taken the stage on port #{port} for #{env} with backup by #{server.name}" + require 'pp' + server.run(application) do |server| + trap(:INT) do + server.stop + #puts "\n== Sinatra has ended his set (crowd applauds)" + end + end + rescue Errno::EADDRINUSE => e + #puts "== Someone is already performing on port #{port}!" + end + end Heroku ------ [Heroku] has added basic support for Sinatra applications. This is possibly the easiest deployment option as once correctly configured, -deploying to heroku becomes simply a matter of pushing to git +deploying to Heroku becomes simply a matter of pushing to git Steps to deploy to Heroku: * make a config/rackup.ru * push to git -1. an example rackup file - - set :app_file, File.expand_path(File.dirname(__FILE__) + '/../my_sinatra_app.rb') - set :public, File.expand_path(File.dirname(__FILE__) + '/../public') - set :views, File.expand_path(File.dirname(__FILE__) + '/../views') - set :env, :production - disable :run, :reload +1. An example rackup file - require File.dirname(__FILE__) + "/../my_sinatra_app" - - run Sinatra.application + set :app_file, File.expand_path(File.dirname(__FILE__) + '/../my_sinatra_app.rb') + set :public, File.expand_path(File.dirname(__FILE__) + '/../public') + set :views, File.expand_path(File.dirname(__FILE__) + '/../views') + set :env, :production + disable :run, :reload + + require File.dirname(__FILE__) + "/../my_sinatra_app" + + run Sinatra.application 2. push to git - $ git remote add heroku git@heroku.com:my-sinatra-app.git - $ git push heroku master + $ git remote add heroku git@heroku.com:my-sinatra-app.git + $ git push heroku master [Heroku]: http://www.heroku.com @@ -272,4 +277,3 @@ Poolparty and Amazon EC2 // TODO: What other deployment strategies are there? - book/Deployment.markdown @@ -17,38 +17,36 @@ By default error will catch Sinatra::ServerError Sinatra will pass you the error via the ‘sinatra.error’ in request.env - error do - 'Sorry there was a nasty error - ' + request.env['sinatra.error'].name - end - + error do + 'Sorry there was a nasty error - ' + request.env['sinatra.error'].name + end + Custom error mapping: - error MyCustomError do - 'So what happened was...' + request.env['sinatra.error'].message - end + error MyCustomError do + 'So what happened was...' + request.env['sinatra.error'].message + end then if this happens: - get '/' do - raise MyCustomError, 'something bad' - end + get '/' do + raise MyCustomError, 'something bad' + end you gets this: - So what happened was... something bad + So what happened was... something bad Additional Information ---------------------- Because Sinatra give you a default not\_found and error do :production that are secure. If you want to customize only for :production but want to keep the friendly helper screens for :development then do this: - configure :production do - - not_found do - "We're so sorry, but we don't what this is" - end - - error do - "Something really nasty happened. We're on it!" - end - - end \ No newline at end of file + configure :production do + not_found do + "We're so sorry, but we don't what this is" + end + + error do + "Something really nasty happened. We're on it!" + end + end \ No newline at end of file book/ErrorHandling.markdown @@ -5,9 +5,9 @@ before do... ------------ These are run in Sinatra::EventContext - before do - .. this code will run before each event .. - end + before do + # .. this code will run before each event .. + end Handling of Rails like nested params ------------------------------------ book/Filters.markdown @@ -3,16 +3,18 @@ Handlers Structure --------- + Handler is the generic term that Sinatra uses for the "controllers". A -handler is the initial point of entry for new http requests into your +handler is the initial point of entry for new HTTP requests into your application. To find more about the routes, head to the Routes section (right above this one) -redirect +Redirect -------- + The redirect helper is a shortcut to a common http response code (302). Basic usage is easy: @@ -56,7 +58,7 @@ Sinatra ships with basic support for cookie based sessions. To enable it, in a The downside to this session approach is that all the data is stored in the cookie. Since cookies have a fairly hard limit of 4 kilobytes, you can't store -much data. The other issue is that the cookie is not tamper proof. The user +much data. The other issue is that cookies are not tamper proof. The user can change any data in their session. But... it is easy, and it doesn't have the scaling problems that memory or database backed sessions run into. @@ -69,13 +71,14 @@ the scaling problems that memory or database backed sessions run into. ### Database Based Sessions -cookies +Cookies ------- Cookies are a fairly simple thing to use in Sinatra, but they have a few quirks. Lets first look at the simple use case: + require 'rubygems' require 'sinatra' get '/' do @@ -110,7 +113,7 @@ deserialize or split them in any way, it hands you the raw, encoded string for your parsing pleasure. -status +Status ------ If you want to set your own status response instead of the normal 200 (Success), you can use the `status`-helper to set the @@ -126,6 +129,6 @@ specified status code and string to the client. `throw` supports more options in for more info. -authentication +Authentication -------------- book/Handlers.markdown @@ -1,28 +1,27 @@ Helpers ======= -the basics +The basics ---------- It is ill-advised to create helpers on the root level of your application. They muddy the global namespace, and don't have easy access to the request, response, session or cookie variables. -Instead, use the handy helpers method to install methods on Sinatra::EventContext for use inside events and templates. +Instead, use the handy helpers method to install methods on `Sinatra::EventContext` for use inside events and templates. Example: - helpers do - def bar(name) - "#{name}bar" - end - end - - - get '/:name' do - bar(params[:name]) - end + helpers do + def bar(name) + "#{name}bar" + end + end + + get '/:name' do + bar(params[:name]) + end -implemention of rails style partials +Implemention of rails style partials ------------------------------------ Using partials in your views is a great way to keep them clean. Since Sinatra takes the hands off approach to framework @@ -33,11 +32,10 @@ Here is a really basic version: # Usage: partial :foo helpers do def partial(page, options={}) - haml page, options.merge!(:layout => false) + haml page, options.merge!(:layout => false) end end - A more advanced version that would handle passing local options, and looping over a hash would look like: # Render the page once: @@ -63,5 +61,3 @@ A more advanced version that would handle passing local options, and looping ove end end end - - book/Helpers.markdown @@ -3,7 +3,7 @@ Introduction What is Sinatra? -------------------------- -Sinatra is a Domain Specific Language(DSL) for quickly creating web-applications +Sinatra is a Domain Specific Language (DSL) for quickly creating web-applications in ruby. It keeps a minimal feature set, leaving the developer to use the tools that best suit them and their application. @@ -11,22 +11,22 @@ Installation --------------------------------- The simplest way to obtain Sinatra is through rubygems - $ sudo gem install sinatra + $ sudo gem install sinatra Sample App ----------- Sinatra is installed and you're done eating cake, how about making your first application? - # myapp.rb - require 'rubygems' - require 'sinatra' + # myapp.rb + require 'rubygems' + require 'sinatra' + + get '/' do + 'Hello world!' + end - get '/' do - 'Hello world!' - end - -Run this by doing $ ruby myapp.rb and view it at http://localhost:4567 +Run this by doing `$ ruby myapp.rb` and view it at http://localhost:4567 Living on the Edge -------------------------------- @@ -43,8 +43,8 @@ our minds--we can do the following To use this unholy power, simply add this line to your sinatra.rb file - $:.unshift File.dirname(__FILE__) + '/sinatra/lib' - require 'sinatra' + $:.unshift File.dirname(__FILE__) + '/sinatra/lib' + require 'sinatra' That is certainly life on the edge. book/Introduction.markdown @@ -1,27 +1,26 @@ Rack Middleware =============== -Sinatra rides on [Rack][rack], a minimal standard interface for Ruby web frameworks. One of Rack’s most interesting capabilities for application developers is support for “middleware” — components that sit between the server and your application monitoring and/or manipulating the HTTP request/response to provide various types of common functionality. +Sinatra rides on [Rack][rack], a minimal standard interface for Ruby web frameworks. One of Rack’s most interesting capabilities for application developers is support for "middleware" -- components that sit between the server and your application monitoring and/or manipulating the HTTP request/response to provide various types of common functionality. -Sinatra makes building Rack middleware pipelines a cinch via a top-level "use" method: +Sinatra makes building Rack middleware pipelines a cinch via a top-level `use` method: - require 'sinatra' - require 'my_custom_middleware' + require 'sinatra' + require 'my_custom_middleware' + + use Rack::Lint + use MyCustomMiddleware + + get '/hello' do + 'Hello World' + end - use Rack::Lint - use MyCustomMiddleware - get '/hello' do - 'Hello World' - end - - -The semantics of "use" are identical to those defined for the [Rack::Builder][rack_builder] DSL (most frequently used from rackup files). For example, the use method accepts multiple/variable args as well as blocks: - - use Rack::Auth::Basic do |username, password| - username == 'admin' && password == 'secret' - end +The semantics of "use" are identical to those defined for the [Rack::Builder][rack_builder] DSL (most frequently used from rackup files). For example, the use method accepts multiple/variable args as well as blocks: + use Rack::Auth::Basic do |username, password| + username == 'admin' && password == 'secret' + end Rack is distributed with a variety of standard middleware for logging, debugging, URL routing, authentication, and session handling. Sinatra uses many of of these components automatically based on configuration so you typically don’t have to use them explicitly. book/RackMiddleware.markdown @@ -1,62 +1,64 @@ Routes ====== -http methods +HTTP methods ------------ Sinatra's routes are designed to respond to the HTTP request methods. -* get -* post -* put -* delete +* GET +* POST +* PUT +* DELETE - - -basic +Basic ----- -Simple - get '/hi' do - ... - end +Simple + get '/hi' do + ... + end + With params - get '/:name' do - # matches /sinatra and the like and sets params[:name] - end + get '/:name' do + # matches /sinatra and the like and sets params[:name] + end -options +Options ------- -splats +Splats ------ - get '/say/*/to/*' do - # matches /say/hello/to/world - params["splat"] # => ["hello", "world"] - end - get '/download/*.*' do - # matches /download/path/to/file.xml - params["splat"] # => ["path/to/file", "xml"] - end + get '/say/*/to/*' do + # matches /say/hello/to/world + params["splat"] # => ["hello", "world"] + end + + get '/download/*.*' do + # matches /download/path/to/file.xml + params["splat"] # => ["path/to/file", "xml"] + end -user agent +User agent ---------- - get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do - "You're using Songbird version #{params[:agent][0]}" - end - get '/foo' do - # matches non-songbird browsers - end + get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do + "You're using Songbird version #{params[:agent][0]}" + end + + get '/foo' do + # matches non-songbird browsers + end -other methods +Other methods ------------- + Other methods are requested exactly the same as "get" routes. You simply use -the "post", "put", or "delete" functions to define the route, rather then the -"get" one. To access POSTed parameters, use params\[:xxx\] where xxx is the name +the `post`, `put`, or `delete` functions to define the route, rather then the +`get` one. To access POSTed parameters, use `params[:xxx]` where xxx is the name of the form element that was posted. post '/foo' do @@ -64,20 +66,25 @@ of the form element that was posted. end -the PUT and DELETE methods +The PUT and DELETE methods -------------------------- Since browsers don't natively support the PUT and DELETE methods, a hacky workaround has been adopted by the web community. Simply add a hidden element with the name "\_method" and the value equal to the HTTP method you want to use. The form itself is sent as a POST, but Sinatra will interpret it as the desired -method. +method. For example: + + <form method="post" action="/destroy_it"> + <input name="_method" value="delete" /> + <div><button type="submit">Destroy it</button></div> + </form> -When you want to use PUT or DELETE form a client that does support them (like +When you want to use PUT or DELETE from a client that does support them (like Curl, or ActiveResource), just go ahead and use them as you normally would, and -ignore the \_method advice above. That is only for hacking in support for +ignore the `_method` advice above. That is only for hacking in support for browsers. -how routes are looked up +How routes are looked up ------------------------ Each time you add a new route to your application, it gets compiled down into a regular expression that will match it. That is stored in an array along with @@ -86,7 +93,7 @@ the handler block attached to that route. When a new request comes in, each regex is run in turn, until one matches. Then the the handler (the code block) attached to that route gets executed. -splitting into multiple files +Splitting into multiple files ----------------------------- Because Sinatra clears out your routes and reloads your application on every request in development mode, you can't use require to load files containing @@ -98,7 +105,7 @@ your routes because these will only be loaded when the application starts require 'sinatra' get '/' do - "Hello world!" + "Hello world!" end load 'more_routes.rb' @@ -108,5 +115,5 @@ and # more_routes.rb get '/foo' do - "Bar? How unimaginative." + "Bar? How unimaginative." end book/Routes.markdown @@ -2,47 +2,47 @@ Views ===== All file-based views are looked up in: - root - | - views/ + root + | - views/ Template Languages ------------------ ### Haml - get '/' do - haml :index - end + get '/' do + haml :index + end This will render ./views/index.haml ### Sass - get '/' do - sass :styles - end + get '/' do + sass :styles + end This will render ./views/styles.sass ### Erb - get '/' do - erb :index - end + get '/' do + erb :index + end This will render ./views/index.erb ### Builder - get '/' do - builder :index - end + get '/' do + builder :index + end This will render ./views/index.builder - get '/' do - builder do |xml| + get '/' do + builder do |xml| xml.node do xml.subnode "Inner text" end end - end + end This will render the xml inline, directly from the handler. @@ -78,11 +78,12 @@ This will render the rss inline, directly from the handler. Layouts ------- + Layouts are simple in Sinatra. Put a file in your views directory named "layout.erb", "layout.haml", or "layout.builder". When you render a page, the appropriate layout will be grabbed (of the same filetype), and used. -The layout itself should call yield at the point you want the content to be +The layout itself should call `yield` at the point you want the content to be included. An example haml layout file could look something like this: @@ -94,7 +95,7 @@ An example haml layout file could look something like this: #container = yield -avoiding a layout +Avoiding a layout ----------------- Sometimes you don't want the layout rendered. In your render method just pass :layout => false, and you're good. @@ -105,23 +106,24 @@ Sometimes you don't want the layout rendered. In your render method just pass In File Views ------------- -This one is cool: - - get '/' do - haml :index - end - - use_in_file_templates! - __END__ - - @@ layout - X - = yield - X +This one is cool: - @@ index - %div.title Hello world!!!!! + get '/' do + haml :index + end + + use_in_file_templates! + + __END__ + + @@ layout + X + = yield + X + + @@ index + %div.title Hello world!!!!! Try it! book/Views.markdown 339873b750440b92f2033b75dc22107e366a6a36 Nicolas Sanguinetti contacto@nicolassanguinetti.info http://github.com/cschneid/sinatra-book/commit/14f44b311470eead8f2b51b8d83e36fd02bd701f 14f44b311470eead8f2b51b8d83e36fd02bd701f 2009-01-09T06:02:24-08:00 2009-01-09T05:57:42-08:00 Be consistent with casing and indentation. * Make sure we use 4-space indentation for markdown where we want <pre> tags in the output, and 2-space indentation for ruby/html code in those code samples. * Make all titles/subtitles start with uppercase. * Fix some minor spelling issues * Add some missing 'require "rubygems"' in the Deployment section. Signed-off-by: Scott Wisely <syd@scrimfind.org> c0fd67a5119f14631fe60b64d8b2b88d8946cd85 Scott Wisely syd@scrimfind.org