testing blockquote
This commit is contained in:
parent
ae9119393e
commit
3cb91c4828
268
README.md
268
README.md
|
@ -1344,7 +1344,7 @@ You can also hand in an array in order to disable a list of protections:
|
|||
|
||||
### Available Settings
|
||||
|
||||
____**absolute_redirects**____
|
||||
**absolute_redirects**
|
||||
|
||||
> If disabled, Sinatra will allow relative redirects, however, Sinatra will no
|
||||
longer conform with RFC 2616 (HTTP 1.1), which only allows absolute redirects.
|
||||
|
@ -1355,109 +1355,129 @@ pass in `false` as the second parameter.
|
|||
|
||||
> Disabled per default.
|
||||
|
||||
__**add_charsets**__
|
||||
**add_charsets**
|
||||
> mime types the `content_type` helper will automatically add the charset info to.
|
||||
|
||||
You should add to it rather than overriding this option:
|
||||
|
||||
settings.add_charsets << "application/foobar"
|
||||
|
||||
[app_file] Path to the main application file, used to detect project
|
||||
root, views and public folder and inline templates.
|
||||
**app_file**
|
||||
|
||||
[bind] IP address to bind to (default: 0.0.0.0).
|
||||
Only used for built-in server.
|
||||
> Path to the main application file, used to detect project root, views and public
|
||||
folder and inline templates.
|
||||
|
||||
[default_encoding] encoding to assume if unknown
|
||||
(defaults to `"utf-8"`).
|
||||
**bind**
|
||||
|
||||
[dump_errors] display errors in the log.
|
||||
> IP address to bind to (default: 0.0.0.0). Only used for built-in server.
|
||||
|
||||
[environment] current environment, defaults to `ENV['RACK_ENV']`,
|
||||
or `"development"` if not available.
|
||||
**default_encoding**
|
||||
|
||||
[logging] use the logger.
|
||||
> encoding to assume if unknown (defaults to `"utf-8"`).
|
||||
|
||||
[lock] Places a lock around every request, only running
|
||||
processing on request per Ruby process concurrently.
|
||||
**dump_errors**
|
||||
|
||||
Enabled if your app is not thread-safe.
|
||||
Disabled per default.
|
||||
> display errors in the log.
|
||||
|
||||
[method_override] use `_method` magic to allow put/delete forms in
|
||||
browsers that don't support it.
|
||||
**environment**
|
||||
|
||||
[port] Port to listen on. Only used for built-in server.
|
||||
> current environment, defaults to `ENV['RACK_ENV']`, or `"development"` if
|
||||
not available.
|
||||
|
||||
[prefixed_redirects] Whether or not to insert `request.script_name`
|
||||
into redirects if no absolute path is given. That way
|
||||
`redirect '/foo'` would behave like
|
||||
`redirect to('/foo')`. Disabled per default.
|
||||
**logging**
|
||||
> use the logger.
|
||||
|
||||
[protection] Whether or not to enable web attack protections. See
|
||||
protection section above.
|
||||
**lock**
|
||||
> Places a lock around every request, only running processing on request
|
||||
per Ruby process concurrently.
|
||||
|
||||
[public_dir] Alias for `public_folder`. See below.
|
||||
> Enabled if your app is not thread-safe. Disabled per default.
|
||||
|
||||
[public_folder] Path to the folder public files are served from. Only
|
||||
used if static file serving is enabled (see
|
||||
`static` setting below). Inferred from
|
||||
`app_file` setting if not set.
|
||||
**method_override**
|
||||
> use `_method` magic to allow put/delete forms in browsers that
|
||||
don't support it.
|
||||
|
||||
[reload_templates] whether or not to reload templates between requests.
|
||||
Enabled in development mode.
|
||||
**port**
|
||||
> Port to listen on. Only used for built-in server.
|
||||
|
||||
[root] Path to project root folder. Inferred from +app_file+
|
||||
setting if not set.
|
||||
**prefixed_redirects**
|
||||
> Whether or not to insert `request.script_name` into redirects if no
|
||||
absolute path is given. That way `redirect '/foo'` would behave like
|
||||
`redirect to('/foo')`. Disabled per default.
|
||||
|
||||
[raise_errors] raise exceptions (will stop application). Enabled
|
||||
by default when `environment` is set to
|
||||
`"test"`, disabled otherwise.
|
||||
**protection**
|
||||
> Whether or not to enable web attack protections. See protection section above.
|
||||
|
||||
[run] if enabled, Sinatra will handle starting the web server,
|
||||
do not enable if using rackup or other means.
|
||||
**public_dir**
|
||||
> Alias for `public_folder`. See below.
|
||||
|
||||
[running] is the built-in server running now?
|
||||
do not change this setting!
|
||||
**public_folder**
|
||||
> Path to the folder public files are served from. Only used if static
|
||||
file serving is enabled (see `static` setting below). Inferred from
|
||||
`app_file` setting if not set.
|
||||
|
||||
[server] server or list of servers to use for built-in server.
|
||||
defaults to ['thin', 'mongrel', 'webrick'], order
|
||||
indicates priority.
|
||||
**reload_templates**
|
||||
> Whether or not to reload templates between requests. Enabled in development mode.
|
||||
|
||||
[sessions] enable cookie-based sessions support using
|
||||
`Rack::Session::Cookie`. See 'Using Sessions'
|
||||
section for more information.
|
||||
**root**
|
||||
> Path to project root folder. Inferred from `app_file` setting if not set.
|
||||
|
||||
[show_exceptions] show a stack trace in the browser when an exception
|
||||
happens. Enabled by default when `environment`
|
||||
is set to `"development"`, disabled otherwise.
|
||||
Can also be set to `:after_handler` to trigger
|
||||
app-specified error handling before showing a stack
|
||||
trace in the browser.
|
||||
**raise_errors**
|
||||
> raise exceptions (will stop application). Enabled by default when
|
||||
`environment` is set to `"test"`, disabled otherwise.
|
||||
|
||||
[static] Whether Sinatra should handle serving static files.
|
||||
Disable when using a server able to do this on its own.
|
||||
Disabling will boost performance.
|
||||
Enabled per default in classic style, disabled for
|
||||
modular apps.
|
||||
**run**
|
||||
> if enabled, Sinatra will handle starting the web server, do not
|
||||
enable if using rackup or other means.
|
||||
|
||||
[static_cache_control] When Sinatra is serving static files, set this to add
|
||||
`Cache-Control` headers to the responses. Uses the
|
||||
+cache_control+ helper. Disabled by default.
|
||||
Use an explicit array when setting multiple values:
|
||||
`set :static_cache_control, [:public, :max_age => 300]`
|
||||
**running**
|
||||
> is the built-in server running now? do not change this setting!
|
||||
|
||||
[threaded] If set to +true+, will tell Thin to use
|
||||
`EventMachine.defer` for processing the request.
|
||||
**server**
|
||||
> server or list of servers to use for built-in server. defaults to
|
||||
['thin', 'mongrel', 'webrick'], order indicates priority.
|
||||
|
||||
[views] Path to the views folder. Inferred from `app_file`
|
||||
setting if not set.
|
||||
**sessions**
|
||||
> Enable cookie-based sessions support using `Rack::Session::Cookie`.
|
||||
See 'Using Sessions' section for more information.
|
||||
|
||||
== Environments
|
||||
**show_exceptions**
|
||||
|
||||
> Show a stack trace in the browser when an exception
|
||||
happens. Enabled by default when `environment`
|
||||
is set to `"development"`, disabled otherwise.
|
||||
|
||||
> Can also be set to `:after_handler` to trigger
|
||||
app-specified error handling before showing a stack
|
||||
trace in the browser.
|
||||
|
||||
**static**
|
||||
|
||||
> Whether Sinatra should handle serving static files.
|
||||
> Disable when using a server able to do this on its own.
|
||||
> Disabling will boost performance.
|
||||
> Enabled per default in classic style, disabled for
|
||||
modular apps.
|
||||
|
||||
**static_cache_control**
|
||||
> When Sinatra is serving static files, set this to add
|
||||
`Cache-Control` headers to the responses. Uses the
|
||||
`cache_control` helper. Disabled by default.
|
||||
Use an explicit array when setting multiple values:
|
||||
`set :static_cache_control, [:public, :max_age => 300]`
|
||||
|
||||
**threaded**
|
||||
> If set to `true`, will tell Thin to use `EventMachine.defer`
|
||||
for processing the request.
|
||||
|
||||
**views**
|
||||
> Path to the views folder. Inferred from `app_file` setting if
|
||||
not set.
|
||||
|
||||
## Environments
|
||||
|
||||
There are three predefined +environments+: `"development"`,
|
||||
`"production"` and `"test"`. Environments can be set
|
||||
through the +RACK_ENV+ environment variable. The default value is
|
||||
through the `RACK_ENV` environment variable. The default value is
|
||||
`"development"`. In the `"development"` environment all templates are reloaded between
|
||||
requests, and special `not_found` and `error` handlers
|
||||
display stack traces in your browser.
|
||||
|
@ -1470,24 +1490,26 @@ To run different environments use the `-e` option:
|
|||
You can use predefined methods: +development?+, +test?+ and +production?+ to
|
||||
check the current environment setting.
|
||||
|
||||
== Error Handling
|
||||
## Error Handling
|
||||
|
||||
Error handlers run within the same context as routes and before filters, which
|
||||
means you get all the goodies it has to offer, like `haml`,
|
||||
`erb`, `halt`, etc.
|
||||
|
||||
=== Not Found
|
||||
### Not Found
|
||||
|
||||
When a `Sinatra::NotFound` exception is raised, or the response's status
|
||||
code is 404, the `not_found` handler is invoked:
|
||||
|
||||
not_found do
|
||||
```ruby
|
||||
not_found do
|
||||
'This is nowhere to be found.'
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
=== Error
|
||||
### Error
|
||||
|
||||
The +error+ handler is invoked any time an exception is raised from a route
|
||||
The `error` handler is invoked any time an exception is raised from a route
|
||||
block or a filter. The exception object can be obtained from the
|
||||
`sinatra.error` Rack variable:
|
||||
|
||||
|
@ -1530,16 +1552,16 @@ Or a range:
|
|||
Sinatra installs special `not_found` and `error` handlers when
|
||||
running under the development environment.
|
||||
|
||||
== Rack Middleware
|
||||
## Rack Middleware
|
||||
|
||||
Sinatra rides on Rack[http://rack.rubyforge.org/], a minimal standard
|
||||
Sinatra rides on [Rack](http://rack.rubyforge.org/), 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:
|
||||
`use` method:
|
||||
|
||||
require 'sinatra'
|
||||
require 'my_custom_middleware'
|
||||
|
@ -1552,7 +1574,7 @@ Sinatra makes building Rack middleware pipelines a cinch via a top-level
|
|||
end
|
||||
|
||||
The semantics of +use+ are identical to those defined for the
|
||||
Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
|
||||
[Rack::Builder](http://rack.rubyforge.org/doc/classes/Rack/Builder.html) DSL
|
||||
(most frequently used from rackup files). For example, the +use+ method
|
||||
accepts multiple/variable args as well as blocks:
|
||||
|
||||
|
@ -1566,15 +1588,15 @@ many of these components automatically based on configuration so you
|
|||
typically don't have to +use+ them explicitly.
|
||||
|
||||
You can find useful middleware in
|
||||
{rack}[https://github.com/rack/rack/tree/master/lib/rack],
|
||||
{rack-contrib}[https://github.com/rack/rack-contrib#readme],
|
||||
with {CodeRack}[http://coderack.org/] or in the
|
||||
{Rack wiki}[https://github.com/rack/rack/wiki/List-of-Middleware].
|
||||
[rack](https://github.com/rack/rack/tree/master/lib/rack),
|
||||
[rack-contrib](https://github.com/rack/rack-contrib#readm),
|
||||
with [CodeRack](http://coderack.org/) or in the
|
||||
[Rack wiki](https://github.com/rack/rack/wiki/List-of-Middleware).
|
||||
|
||||
== Testing
|
||||
|
||||
Sinatra tests can be written using any Rack-based testing library or framework.
|
||||
{Rack::Test}[http://rdoc.info/github/brynary/rack-test/master/frames]
|
||||
[Rack::Test](http://rdoc.info/github/brynary/rack-test/master/frames)
|
||||
is recommended:
|
||||
|
||||
require 'my_sinatra_app'
|
||||
|
@ -1604,9 +1626,10 @@ is recommended:
|
|||
end
|
||||
end
|
||||
|
||||
Note: If you are using Sinatra in the modular style, replace `Sinatra::Application` above with the class name of your app.
|
||||
Note: If you are using Sinatra in the modular style, replace `Sinatra::Application`
|
||||
above with the class name of your app.
|
||||
|
||||
== Sinatra::Base - Middleware, Libraries, and Modular Apps
|
||||
## Sinatra::Base - Middleware, Libraries, and Modular Apps
|
||||
|
||||
Defining your app at the top-level works well for micro-apps but has
|
||||
considerable drawbacks when building reusable components such as Rack
|
||||
|
@ -1639,10 +1662,10 @@ available via the top-level DSL. Most top-level apps can be converted to
|
|||
|
||||
`Sinatra::Base` is a blank slate. Most options are disabled by default,
|
||||
including the built-in server. See
|
||||
{Options and Configuration}[http://sinatra.github.com/configuration.html]
|
||||
[Options and Configuration](http://sinatra.github.com/configuration.html)
|
||||
for details on available options and their behavior.
|
||||
|
||||
=== Modular vs. Classic Style
|
||||
### Modular vs. Classic Style
|
||||
|
||||
Contrary to common belief, there is nothing wrong with the classic style. If it
|
||||
suits your application, you do not have to switch to a modular application.
|
||||
|
@ -1665,7 +1688,7 @@ different default settings:
|
|||
static true false
|
||||
|
||||
|
||||
=== Serving a Modular Application
|
||||
### Serving a Modular Application
|
||||
|
||||
There are two common options for starting a modular app, actively starting with
|
||||
`run!`:
|
||||
|
@ -1694,7 +1717,7 @@ Run:
|
|||
|
||||
rackup -p 4567
|
||||
|
||||
=== Using a Classic Style Application with a config.ru
|
||||
### Using a Classic Style Application with a config.ru
|
||||
|
||||
Write your app file:
|
||||
|
||||
|
@ -1710,7 +1733,7 @@ And a corresponding `config.ru`:
|
|||
require './app'
|
||||
run Sinatra::Application
|
||||
|
||||
=== When to use a config.ru?
|
||||
### When to use a config.ru?
|
||||
|
||||
A `config.ru` file is recommended if:
|
||||
|
||||
|
@ -1719,11 +1742,11 @@ A `config.ru` file is recommended if:
|
|||
* You want to use more than one subclass of `Sinatra::Base`.
|
||||
* You want to use Sinatra only for middleware, and not as an endpoint.
|
||||
|
||||
<b>There is no need to switch to a `config.ru` simply because you
|
||||
**There is no need to switch to a `config.ru` simply because you
|
||||
switched to the modular style, and you don't have to use the modular style for running
|
||||
with a `config.ru`.</b>
|
||||
with a `config.ru`.**
|
||||
|
||||
=== Using Sinatra as Middleware
|
||||
### Using Sinatra as Middleware
|
||||
|
||||
Not only is Sinatra able to use other Rack middleware, any Sinatra application
|
||||
can in turn be added in front of any Rack endpoint as middleware itself. This
|
||||
|
@ -1759,63 +1782,70 @@ application (Rails/Ramaze/Camping/...):
|
|||
get('/') { "Hello #{session['user_name']}." }
|
||||
end
|
||||
|
||||
=== Dynamic Application Creation
|
||||
### Dynamic Application Creation
|
||||
|
||||
Sometimes you want to create new applications at runtime without having to
|
||||
assign them to a constant, you can do this with `Sinatra.new`:
|
||||
|
||||
require 'sinatra/base'
|
||||
my_app = Sinatra.new { get('/') { "hi" } }
|
||||
my_app.run!
|
||||
```ruby
|
||||
require 'sinatra/base'
|
||||
my_app = Sinatra.new { get('/') { "hi" } }
|
||||
my_app.run!
|
||||
```
|
||||
|
||||
It takes the application to inherit from as an optional argument:
|
||||
|
||||
# config.ru (run with rackup)
|
||||
require 'sinatra/base'
|
||||
```ruby
|
||||
# config.ru (run with rackup)
|
||||
require 'sinatra/base'
|
||||
|
||||
controller = Sinatra.new do
|
||||
controller = Sinatra.new do
|
||||
enable :logging
|
||||
helpers MyHelpers
|
||||
end
|
||||
end
|
||||
|
||||
map('/a') do
|
||||
map('/a') do
|
||||
run Sinatra.new(controller) { get('/') { 'a' } }
|
||||
end
|
||||
end
|
||||
|
||||
map('/b') do
|
||||
map('/b') do
|
||||
run Sinatra.new(controller) { get('/') { 'b' } }
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
This is especially useful for testing Sinatra extensions or using Sinatra in
|
||||
your own library.
|
||||
|
||||
This also makes using Sinatra as middleware extremely easy:
|
||||
|
||||
require 'sinatra/base'
|
||||
```ruby
|
||||
require 'sinatra/base'
|
||||
|
||||
use Sinatra do
|
||||
use Sinatra do
|
||||
get('/') { ... }
|
||||
end
|
||||
end
|
||||
|
||||
run RailsProject::Application
|
||||
run RailsProject::Application
|
||||
```
|
||||
|
||||
== Scopes and Binding
|
||||
## Scopes and Binding
|
||||
|
||||
The scope you are currently in determines what methods and variables are
|
||||
available.
|
||||
|
||||
=== Application/Class Scope
|
||||
### Application/Class Scope
|
||||
|
||||
Every Sinatra application corresponds to a subclass of `Sinatra::Base`.
|
||||
If you are using the top-level DSL (`require 'sinatra'`), then this
|
||||
class is `Sinatra::Application`, otherwise it is the subclass you
|
||||
created explicitly. At class level you have methods like +get+ or +before+, but
|
||||
you cannot access the +request+ or +session+ objects, as there is only a
|
||||
created explicitly. At class level you have methods like `get` or `before`, but
|
||||
you cannot access the `request` or `session` objects, as there is only a
|
||||
single application class for all requests.
|
||||
|
||||
Options created via +set+ are methods at class level:
|
||||
Options created via `set` are methods at class level:
|
||||
|
||||
class MyApp < Sinatra::Base
|
||||
```ruby
|
||||
class MyApp < Sinatra::Base
|
||||
# Hey, I'm in the application scope!
|
||||
set :foo, 42
|
||||
foo # => 42
|
||||
|
@ -1823,8 +1853,8 @@ Options created via +set+ are methods at class level:
|
|||
get '/foo' do
|
||||
# Hey, I'm no longer in the application scope!
|
||||
end
|
||||
end
|
||||
|
||||
end
|
||||
```
|
||||
You have the application scope binding inside:
|
||||
|
||||
* Your application class body
|
||||
|
|
Loading…
Reference in New Issue