Rails 101: File Structure

December 28, 2008

When starting a project Rails automatically creates a large tree structure of folders and files, so what are they all for?

You can download a video version of this article.

Creating a Project

To create a project in Rails you need to be in your command line interface. Find an appropriate place to store your applications, for example, if you’re on a Mac, the sites folder is probably your best bet.

cd sites

You can then generate the project by simply using the rails command followed by the name of your project, for example:

rails store

Once all these files have been created. You will want open them in your editor, I recommend TextMate if you’re a Mac user, but anything that has a tree structure for files and ruby syntax highlighting will do.

cd store mate .

Now all these folders might be a little daunting to begin with but I’ll explain them one by one.

app

At the top we have our app folder, coincidently this is the folder which most of the logic behind your application will be put.

Model View Controller

As mentioned in the previous article, Rails uses a MVC format to keep your code organised by separating your code into a logical structure. Imagine a user navigates to a page on your website. Their request is first sent to the relevent controller, which picks out an action, like viewing the index, or updating an item.

The controller then loads the objects, or models it needs and maybe performs some updates on them. Models are, by default, linked to the database via ActiveRecord which means you don’t really need to write any database code (such as SQL) until you’re getting into advanced applications, so that is one less worry.

When the controller is finished detailing with the model it will pass on any information to the view, which will create the HTML, XML, RSS or whatever file format you want, before passing it back to the browser.

You might notice there is also a helpers folder within the app directory, helpers are basically small functions you can write to save you time and tidy your code up in the views.

config

The config directory contains all the files that are used during booting your application. One of the most important files is your database.yml file, which stores your database access details.

The environments folder which stores the different settings your application can run in, the defaults are development, production and test, however some people make a fourth for staging to test performance.

Initializers are used to run pieces of code during boot up of the application, such as setting up an exception notifier like Hoptoad.

Introduced in Rails 2.2.2 was internationalisation or I18n, the locales folder contains the yml configuration files for all your supported languages.

And finally the routes.rb file which basically decides what your URLs look like and maps them to the right controllers. You don’t need to worry about the others.

db

Your db directory will store any file-based databases, such as those using SQLite and the migration files which are basically Ruby-based commands which alter the database as you develop your application, ready for deployment.

doc

You can use the doc directory to store any documentation you might have for your application, or use the rake rdoc command to generate code documentation automatically.

lib

You will use the lib directory to store custom classes for repeat functionality you’ve sliced out of models and controllers.

log

One of the most important features of Rails is the log, the files store all the information you need to know while developing such as what queries are running, the performance of each page etc.

public

Your public directory is mapped to the root URL, so that means that rather than using paths prefixed with /public you can just address the file within the public directory as such: example.com/images/my-image.jpg (as apposed to example.com/public/images/my-image.jpg).

script

In the terminal you will run commands like script/server to boot up the server, these are all stored in the script directory, so you can leave that one alone for the time being.

test

You may have come across the acroynms TDD and BDD, which translate to test driven development and behaviour driven development. What these basically mean is that rather than waiting until the end of your project to test it, you test as you go along, so you will instantly pick up on any issues that might occur when you update your code. Because TDD & BDD are big in the Rails community, the test directory is an important part of the framework.

tmp

Cache files, sessions and process identifiers are stored in here – nothing to be bothered about really.

vendor

This stores any plugins you have installed, the edge version of Rails if you’re using it and any gems you have bundled into your application.

Read the next in the series: Generators »

Discussion