Controllers
When developing web applications controllers are the elements that are called by a browser. When visiting a page a request is made that is processed by Rack and sent to Ramaze. Ramaze in turn will determine what controller to call.
To make understanding controllers a bit easier will use a real world example. Let's say we're in a restaurant and want to order some food. The waiter of the restaurant can be seen as a controller. We'll talk to it and tell him what we want to have for dinner but the waiter itself won't actually prepare our dinner, instead it will merely tell the cooks to make the dinner and bring it to you once it's done. The waiter is our controller, the cook is our model and our meal can be seen as the view.
In a typical application the entire flow of a request is as following:
Request --> Server (Thin, Unicorn, etc) --> Rack --> Ramaze --> Controller
Ramaze & Controllers
In Ramaze controllers are plain Ruby classes that extend Ramaze::Controller. The most basic controller looks like the following:
class ControllerName < Ramaze::Controller
map '/uri'
def index
end
end
Let's walk through this snippet step by step. The first line declares a new
class that extends Ramaze::Controller. Extending this base class is very
important, without it we won't be able to call controller specific methods such
as the map()
method. This method, which is called on line 2, is used to instruct
Ramaze what controller is bound to what URI (Uniform Resource Identifier). The
argument of this method should be a string starting with a /. The reason for
this is that the URIs are relative to URL the application is running on. For
example, if our application was running at ramaze.net a URI of "/blog" would
mean the controller can be found at ramaze.net/blog.
Let's move to the next lines of code. The next lines of code define a new method
called "index". By default Ramaze will try to call this method if no URI after
the mapped URI is given. In our /blog example a call to ramaze.net/blog would
call BlogController#index
but a call to ramaze.net/blog/entry/10
would call
BlogController#entry(10)
.
All methods that are declared as public can be accessed by a user and by default
the index()
method is called if no other method is specified. Don't like the
index()
method? No problem, you can specify a different default method to call
as following:
class ControllerName < Ramaze::Controller
trait :default_action_name => 'default'
def default
end
end
We're not going to cover Traits too much in this chapter as there's a dedicated
chapter for them but in short they're a way of setting configuration options. In
this case we're using the trait default_action_name
to specify what the name
of the default method should be. By default this is set to "index" but in the
above example it was changed to "default".
Method Arguments
As mentioned above methods are bound to URLs given they're declared as public methods. The same applies to the arguments of such methods, if the method is public these arguments can be set from the URL. This means that you don't have to use a special DSL just to bind methods to certain URLs while taking various parameters into account. An example is the following:
class Pages < Ramaze::Controller
map '/pages'
def index
# Overview of all pages
end
def edit(id)
# Edit the page for the given ID
end
end
This controller would allow users to navigate to /pages/edit/10
which would
invoke Pages#edit("10")
. There's no restriction on the values of parameters
(as long as they don't include slashes), they are however always passed as
strings to the method.
One thing to keep in mind is that if a method takes a set of required parameters that are not specified Ramaze will not call the method, it will instead show a message that the request could not be executed due to a missing method/controller (unless your application has a custom handler for this).
Using the code above navigating to /pages/edit/10
would work but navigating to
/pages/edit
would not since the "id" parameter is specified as a required
parameter but wasn't given in the URL. Don't worry, working around this is as
easy as specifying a default value for your parameters:
class Pages < Ramaze::Controller
map '/pages'
def index
# Overview of all pages
end
def edit(id = nil)
# Edit the page for the given ID
end
end
With this modification the edit
method will be called for URLs such as
/pages/edit
, /pages/edit/10
and so on.
Catch-all Methods
Sometimes you want to create a controller in which a single method handles all
the requests. This can be done by creating an index
method that takes a
variable amount of parameters:
class Pages < Ramaze::Controller
map '/pages'
def index(*args)
end
end
In this example Pages#index
would be called for URLs such as /pages
,
/pages/example
, /pages/edit/10
and so on. The exception to this is URLs that
point to existing methods. An example:
class Pages < Ramaze::Controller
map '/pages'
def index(*args)
return 'index'
end
def example
return 'example'
end
end
If a user were to browse to /pages/hello
the index method would be called and
"index" would be displayed, when the user instead goes to /pages/example
the
text "example" would be displayed as there's an existing method for this URI.
However, if the user would request /pages/example/10
the index method would
again be called, this is because the example method does not take any
parameters. Below is a list of various URLs and what method calls they'd result
in.
/pages # => Pages#index
/pages/index # => Pages#index
/pages/edit/10 # => Pages#index("edit", "10")
/pages/example # => Pages#example
/pages/example/10 # => Pages#index("example", "10")
Registering Controllers
By now you might be thinking "How does Ramaze know what controller to call? I didn't initialize the controller!". It's true, you don't have to manually initialize the controller and save it in a hash or somewhere else. The entire process of registering a controller is done by the map() method and thus is one of the most important methods available. When calling this method it will store the name of the class that invoked it and bind it to the given URI. Whenever a request is made Ramaze simply creates an instance of the matching controller for a given URI.
The basic process of the map() method is as following:
- Call
map()
. - Validate the given URI.
- Store the controller constant.
- Done.
Base Controllers
In many applications you'll have separate areas such as an admin panel and the frontend. Usually you want to authenticate users for certain controllers, such as those used for an admin panel. An easy way of doing this is by putting the authentication call in a controller. By creating a base controller and extending it you don't have to call the method that authenticates the user over and over again. Because Ramaze is just Ruby all you have to do to achieve this is the following:
class AdminController < Ramaze::Controller
end
class Users < AdminController
end
If your base controller has an initialize() method defined you should always call the parent's initialize() method to ensure everything is working properly. This can be done by calling super():
class AdminController < Ramaze::Controller
def initialize
# Calls Ramaze::Controller#initialize
super
# Custom calls can be placed here...
# ...
end
end