Rails Application Structure Introduction
This article is a follow up to my rails basics article. It was originally written to be a crash course in the basics of Rails for my supervisor at the time. Due to the age of this information (it was written June 2006) it may be out of date.
All Rails applications share a defined directory structure. This document will outline the basics of this structure.
app
The app directory contains the bulk of the source code for an application. Code is divided up into models, views and controllers.
apis
This directory only appears in applications which have interfaces available to external programs. Rails is able to provide web service (SOAP or XML-RPC) interfaces so that remote applications (eg a .NET application) can interact with the Rails application.
controllers
Controllers interact with the model (adding/updating/removing/reading). For more information, see Controllers.
All controllers are Ruby code (.rb) and finish with _controller. The first part of the file name is the controller name. There is a special controller, called application.rb in the controllers directory. Methods added to this controller are available in all controllers, along with properties (such as layouts) as all controllers inheret from this one. This controller cannot be initialised by the client.
helpers
Helpers are functions which aim to simplify tasks for views. There are a large number of helpers included with Rails, such as the link_to:
link_to("list disciplines",
:controller =%gt; 'discipline',
:action => 'list')
This would create a link to the previously defined list action.
Helpers are Ruby code (.rb). Each controller generated automatically has a corresponding helper (in the format controller-name_helper.rb). Methods placed in these files are available to the views corresponding to that controller. Methods added to the application_helper are available to all views.
models
Models define the rules for each object, and how the objects interact. For a detailed description see Models.
Model files are Ruby code (.rb) with the file name being the singular name of the object (whereas the table name will be plural).
views
Views define how information is displayed. They are not Ruby code (although ruby code can be in a view. Most views are Ruby HTML (.rhtml) files. This is similar to the PHP model of a HTML file with some code to render parts of the HTML.
Views are divided into controller directories. When calling an action, Rails by default will try to render it using the view that matches the action name. Eg, for the above discipline list, the view it would use to render this action would be views\discipline\list.rhtml. This can be changed by using the render methods.
For more information, see Views
components
This is not a commonly used directory of a Rails application. Components are generally not considered a good idea. Components can be compiled c files however, which can lead to improved code protection and speed.
config
Though Rails favors convention over configuration, some configuration is neccasary. This directory contains those files.
The routes file is Ruby code which defines how actions and controllers are accessed. The default action is that urls will appear as :controller/:action/:id.
The environments directory contains the ruby code which defines how each environment operates. It is rare that you would change these files.
The environment file defines what environment is currently being used (either production or development generally) and what version of Rails is to be used.
The boot file is ruby code that sets up the application when it first runs.
The database file is a YAML file which determines the database settings. For information on how to edit this file, see Databases.
db
The db folder contains a schema of the database (schema.rb) as well as the migrations (changes to the datastructure).
migrate
Contains the database migration files, numbered in the order they were implemented. These files are ruby files. For more information, see Databases.
doc
Contains the source code documentation (in HTML form under the app directory.
This documentation is generated from comments written in the code (in RDoc format) by typing the following at the console:
rake appdoc
lib
The lib folder can contain class files that are used by the application.
log
The log folder contains log files (.log) which contain some information about errors and occurances within the application (and the server). There is one log file for each environment, plus one for the webbrick server.
public
This is the folder which drives the application interface. It is the folder the web server runs in. In addition to the server config files, there are a number of subdirectories. Using these correctly means you can use simple Rails helpers to include images, javascript and stylesheets.
images
Images used by views
javascript
Javascript (.js) files used in views
stylesheets
Stylesheets (.css) used by views
script
This directory includes scripts to run task within Ruby, including performance analysis.
test
An important part of the Rails rapid development philosophy is testing. All tests in Rails are written using Ruby::Test::Unit with many extensions to allow functional and integration testing. These tests are all ruby files and are contained within this directory (split into the types of tests they are).
Whenever a model is generated, a unit test with the same name is created. Whenever a controller is generated, a functional test with the same name is created. Test methods must be prefixed with test_.
fixtures
The fixtures directory contains test data for use during the testing process. These files can be YAML (.yml) or comma separated (.csv) files.
functional
Contains functional tests of the controllers.
integration
Contains the integration tests that test the stories.
mocks
This has not been used in the Clinic Booking System, but would contain tests of the tests.
unit
Contains the unit tests of the models.
tmp
This folder contains session information as the application is run.
vendor
The vendor directory is used to store additional plugins to extend the capabilities of Rails.
In a deployed Rails application, this folder may contain “frozen” Rails code. This ensures the application can always run with a compatible version of Rails, no matter which version is installed on the host.
10 August 2006