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
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
BlogController#index but a call to
ramaze.net/blog/entry/10 would call
All methods that are declared as public can be accessed by a user and by default
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
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".
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
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/10 and so on.
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/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
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
/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")
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:
- Validate the given URI.
- Store the controller constant.
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