Cerise provides a very flexible method for mapping URLs to request
handlers. When an HTTP request comes in, the path is compared to the
base_path of each application, which is a String defined in
app.cfg. If the base_path
matches the requested path then the request and response are dispatched to
the application.
Cerise adds several methods to the basic HTTP request:
| method | description |
|---|---|
| session(create = true) |
gets the user's session, creating one if
there is none and create is true
|
| user | gets the User object corresponding to this user, if they have been authenticated |
Once the application receives a request it goes through the
handler_map, a hash defined in
app.cfg that maps regexp paths to request
handlers. Each regexp is compared to the request path and if a match is
found, the handler's handle(request, response) method
is called with the request and response objects. Note that the app.cfg
file is reloaded whenever it is changed.
When no matching handler is found, Cerise will interpret the request path
as a request for a file and search for a matching file rooted in the
application's content directory. If a file is found, it
will be served via Cerise::FileHandler. Care must be taken
to avoid using handler_map regexps that also match
static files, or the handler will be called.
If the matching handler responds to application= then it is
passed a reference to the application. This is easily accomplished by
extending the base Cerise::RequestHandler
class which defines an attribute accessor for application.
The Cerise::Application class provides the following
functionality
| method | description |
|---|---|
| get_file(path) |
retrieves a File object for the resource at the application relative
location specified in path. This prevents handlers from
becoming tied to a specific application and isolates changes to the
server directory layout.
|
| forward(to, request, response) |
forwards the request to another handler. If to is a
Class object then the class is expected to be a handler and is called
directly.
If to is a String it is considered a path and handled
identically to a client request, iterating through the
handler_map to
find the appropriate handler. Note that forward does not
update the URL in a user's browser and so presents a poor user
experience if used to step the user through a set of pages. Consider
using redirect instead.
|
| log |
retrieves the logger associated with this application. The log class
responds to debug(), info(),
warn(), error(), etc. All logs are
currently written to cerise/log/server.log.
|
| redirect(to, request, response) | sets an HTTP redirect in the response to redirect the user to another location when the response is sent. This is the preferred method for automatically moving a user from page to page, since it updates the URL displayed the user's browser. |
The following methods are mixins from Cerise::ResourceManagement
in util.rb. You can include this module in your own code if
@server is defined as a reference to the server
instance.
| method | description |
|---|---|
| with_db_connection(location, &block) |
looks up a DBI connection pool located at location and
passes an open connection to the supplied block. After the block
terminates, the connection is returned to the pool. Connection pools
are defined in database.cfg.
|
| with_mail_connection(location, &block) |
looks up a MailConnection
located at location and passes an open connection
to the supplied block. Mail servers are defined in
mailserver.cfg.
|
A request handler is any class that responds to the
handle(request, response) method. The most convenient way to
create one is to subclass Cerise::RequestHandler. Request
handlers are placed in Ruby source files located in
cerise/apps/<application>/content They are reloaded
whenever the source file is changed.
Request handlers typically inspect the request and write the
appropriate response to response.body. The exception
is template handlers which return data
models for the template and should not modify the response unless
doing a redirect.
Most request handlers should extend Cerise::RequestHandler
to take advantage of the following functionality
| method | description |
|---|---|
| application | a reference to the current application |
| parameters | a hash of parameters passed to this handler. These parameters are defined in app.cfg |