The rules here are the default conventions used by Rails. You can override
all of these conventions using the appropriate declarations in your Rails
classes.
We often name variables and classes using short phrases. In Ruby, the
convention is to have variable names where the letters are all lowercase,
and words are separated by
underscores. Classes and modules are named
differently: there are no underscores, and each word in the phrase (including
the first) is capitalized. (We’ll call this
mixed-case, for fairly obvious
reasons). These conventions lead to variable names such as order_status
and class names such as LineItem.
Rails takes this convention and extends it in two ways. First, it assumes
that database table names, like variable names, have lowercase letters and
underscores between the words. Rails also assumes that table names are
always plural. This leads to table names such as orders and third_parties.
On another axis, Rails assumes that files are named in lowercase with
underscores.
Rails uses this knowledge of naming conventions to convert names automatically.
For example, your application might contain a model class that
handles line items. You’d define the class using the Ruby naming convention,
calling it LineItem. From this name, Rails would automatically deduce
the following.
That the corresponding database table will be called line_items. That’s
the class name, converted to lowercase, with underscores between
the words and pluralized.
? Rails would also know to look for the class definition in a file called
line_item.rb (in the app/models directory).
Rails controllers have additional naming conventions. If our application
has a store controller, then the following happens.
? Rails assumes the class is called StoreController and that it’s in a file
named store_controller.rb in the app/controllers directory.
? It also assumes there’s a helper module named StoreHelper in the file
store_helper.rb located in the app/helpers directory.
? It will look for view templates for this controller in the app/views/store
directory.
? It will by default take the output of these views and wrap them in the
layout template contained in store.rhtml or store.rxml in the directory
app/views/layouts.
There’s one extra twist. In normal Ruby code you have to use the require
keyword to include Ruby source files before you reference the classes and
modules in those files. Because Rails knows the relationship between
filenames and class names, require is not necessary in a Rails application.
Instead, the first time you reference a class or module that isn’t known,
Rails uses the naming conventions to convert the class name to a filename
and tries to load that file behind the scenes. The net effect is that you can
Model Naming
URL
http://.../store/listFile app/views/store/list.rhtml (or .rxml)
View Naming
Helper module StoreHelper
File app/helpers/store_helper.rb
URL
http://.../store/listClass StoreController
File app/controllers/store_controller.rb
Controller Naming
Method list()
Layout app/views/layouts/store.rhtml
Figure 13.3: Naming Convention Summary
typically reference (say) the name of a model class, and that model will be
automatically loaded into your application.
As you’ll see, this scheme breaks down when your classes are stored in
sessions. In this case you’ll need to explicitly declare them. Even so, you
don’t use require. Instead, your controller would include a line such as
class StoreController < ApplicationController
model :line_item
# ...
Notice how the naming conventions are still used consistently here. The
symbol :line_item is lowercase with an underscore. It will cause the file
line_item.rb to be loaded, and that file will contain class LineItem.
Grouping Controllers into Modules
So far, all our controllers have lived in the app/controllers directory. It is
sometimes convenient to add more structure to this arrangement. For
example, our store might end up with a number of controllers performing
related but disjoint administration functions. Rather than pollute the top-
level namespace with each of these, we might choose to group them into a
single admin namespace.
Rails does this using a simple convention. If an incoming request has a
controller named (say) admin/book, Rails will look for the controller called
book_controller in the directory app/controllers/admin. That is, the final part
of the controller name will always resolve to a file called name_controller.rb,
and any leading path information will be used to navigate through subdirectories,
starting in the app/controllers directory.
Imagine that our application has two such groups of controllers (say,
admin/xxx and content/xxx) and that both groups defined a book controller.
There’d be a file called book_controller.rb in both the admin and content subdirectories
of app/controllers. Both of these controller files would define a
class named BookController. If Rails took no further steps, these two classes
would clash.
To deal with this, Rails assumes that controllers in subdirectories of the
directory app/controllers are in Ruby modules named after the subdirectory.
Thus, the book controller in the admin subdirectory would be declared as
class Admin::BookController < ApplicationController
# ...
end
The book controller in the content subdirectory would be in the Content
module.
class Content::BookController < ApplicationController
# ...
end
The two controllers are therefore kept separate inside your application.
The templates for these controllers appear in subdirectories of app/views.
Thus, the view template corresponding to the request
http://my.app/admin/book/edit/1234will be in the file
app/views/admin/book/edit.rhtml
You’ll be pleased to know that the controller generator understands the
concept of controllers in modules and lets you create them with commands
such as
myapp> ruby script/generate controller Admin::Book action1 action2 ...
This pattern of controller naming has ramifications when we start generating
URLs to link actions together. We’ll talk about this starting on
page 287.