1 Guide Assumptions
This guide is designed for beginners who want to get started with creating a Railsapplication from scratch. It does not assume that you have any prior experiencewith Rails.
Rails is a web application framework running on the Ruby programming language.If you have no prior experience with Ruby, you will find a very steep learningcurve diving straight into Rails. There are several curated lists of online resourcesfor learning Ruby:
Be aware that some resources, while still excellent, cover older versions ofRuby, and may not include some syntax that you will see in day-to-daydevelopment with Rails.
2 What is Rails?
Rails is a web application development framework written in the Ruby programming language.It is designed to make programming web applications easier by making assumptionsabout what every developer needs to get started. It allows you to write lesscode while accomplishing more than many other languages and frameworks.Experienced Rails developers also report that it makes web applicationdevelopment more fun.
Rails is opinionated software. It makes the assumption that there is a "best"way to do things, and it's designed to encourage that way - and in some cases todiscourage alternatives. If you learn "The Rails Way" you'll probably discover atremendous increase in productivity. If you persist in bringing old habits fromother languages to your Rails development, and trying to use patterns youlearned elsewhere, you may have a less happy experience.
The Rails philosophy includes two major guiding principles:
- Don't Repeat Yourself: DRY is a principle of software development whichstates that "Every piece of knowledge must have a single, unambiguous, authoritativerepresentation within a system". By not writing the same information over and overagain, our code is more maintainable, more extensible, and less buggy.
- Convention Over Configuration: Rails has opinions about the best way to do manythings in a web application, and defaults to this set of conventions, rather thanrequire that you specify minutiae through endless configuration files.
3 Creating a New Rails Project
The best way to read this guide is to follow it step by step. All steps areessential to run this example application and no additional code or steps areneeded.
By following along with this guide, you'll create a Rails project calledblog
, a (very) simple weblog. Before you can start building the application,you need to make sure that you have Rails itself installed.
The examples below use $
to represent your terminal prompt in a UNIX-like OS,though it may have been customized to appear differently. If you are using Windows,your prompt will look something like C:\source_code>
.
3.1 Installing Rails
Before you install Rails, you should check to make sure that your system has theproper prerequisites installed. These include:
- Ruby
- SQLite3
3.1.1 Installing Ruby
Open up a command line prompt. On macOS open Terminal.app; on Windows choose"Run" from your Start menu and type cmd.exe
. Any commands prefaced with adollar sign $
should be run in the command line. Verify that you have acurrent version of Ruby installed:
$ ruby --versionruby 2.7.0
Rails requires Ruby version 2.7.0 or later. It is preferred to use the latest Ruby version.If the version number returned is less than that number (such as 2.3.7, or 1.8.7),you'll need to install a fresh copy of Ruby.
To install Rails on Windows, you'll first need to install Ruby Installer.
For more installation methods for most Operating Systems take a look atruby-lang.org.
3.1.2 Installing SQLite3
You will also need an installation of the SQLite3 database.Many popular UNIX-like OSes ship with an acceptable version of SQLite3.Others can find installation instructions at the SQLite3 website.
Verify that it is correctly installed and in your load PATH
:
$ sqlite3 --version
The program should report its version.
3.1.3 Installing Rails
To install Rails, use the gem install
command provided by RubyGems:
$ gem install rails
To verify that you have everything installed correctly, you should be able torun the following in a new terminal:
$ rails --versionRails 7.1.0
If it says something like "Rails 7.1.0", you are ready to continue.
3.2 Creating the Blog Application
Rails comes with a number of scripts called generators that are designed to makeyour development life easier by creating everything that's necessary to startworking on a particular task. One of these is the new application generator,which will provide you with the foundation of a fresh Rails application so thatyou don't have to write it yourself.
To use this generator, open a terminal, navigate to a directory where you haverights to create files, and run:
$ rails new blog
This will create a Rails application called Blog in a blog
directory andinstall the gem dependencies that are already mentioned in Gemfile
usingbundle install
.
You can see all of the command line options that the Rails applicationgenerator accepts by running rails new --help
.
After you create the blog application, switch to its folder:
$ cd blog
The blog
directory will have a number of generated files and folders that makeup the structure of a Rails application. Most of the work in this tutorial willhappen in the app
folder, but here's a basic rundown on the function of eachof the files and folders that Rails creates by default:
File/Folder | Purpose |
---|---|
app/ | Contains the controllers, models, views, helpers, mailers, channels, jobs, and assets for your application. You'll focus on this folder for the remainder of this guide. |
bin/ | Contains the rails script that starts your app and can contain other scripts you use to set up, update, deploy, or run your application. |
config/ | Contains configuration for your application's routes, database, and more. This is covered in more detail in Configuring Rails Applications. |
config.ru | Rack configuration for Rack-based servers used to start the application. For more information about Rack, see the Rack website. |
db/ | Contains your current database schema, as well as the database migrations. |
Dockerfile | Configuration file for Docker. |
Gemfile Gemfile.lock | These files allow you to specify what gem dependencies are needed for your Rails application. These files are used by the Bundler gem. For more information about Bundler, see the Bundler website. |
lib/ | Extended modules for your application. |
log/ | Application log files. |
public/ | Contains static files and compiled assets. When your app is running, this directory will be exposed as-is. |
Rakefile | This file locates and loads tasks that can be run from the command line. The task definitions are defined throughout the components of Rails. Rather than changing Rakefile , you should add your own tasks by adding files to the lib/tasks directory of your application. |
README.md | This is a brief instruction manual for your application. You should edit this file to tell others what your application does, how to set it up, and so on. |
storage/ | Active Storage files for Disk Service. This is covered in Active Storage Overview. |
test/ | Unit tests, fixtures, and other test apparatus. These are covered in Testing Rails Applications. |
tmp/ | Temporary files (like cache and pid files). |
vendor/ | A place for all third-party code. In a typical Rails application this includes vendored gems. |
.dockerignore | This file tells Docker which files it should not copy into the container. |
.gitattributes | This file defines metadata for specific paths in a git repository. This metadata can be used by git and other tools to enhance their behavior. See the gitattributes documentation for more information. |
.gitignore | This file tells git which files (or patterns) it should ignore. See GitHub - Ignoring files for more information about ignoring files. |
.ruby-version | This file contains the default Ruby version. |
4 Hello, Rails!
To begin with, let's get some text up on screen quickly. To do this, you need toget your Rails application server running.
4.1 Starting Up the Web Server
You actually have a functional Rails application already. To see it, you need tostart a web server on your development machine. You can do this by running thefollowing command in the blog
directory:
$ bin/rails server
If you are using Windows, you have to pass the scripts under the bin
folder directly to the Ruby interpreter e.g. ruby bin\rails server
.
JavaScript asset compression requires youhave a JavaScript runtime available on your system, in the absenceof a runtime you will see an execjs
error during asset compression.Usually macOS and Windows come with a JavaScript runtime installed.therubyrhino
is the recommended runtime for JRuby users and is added bydefault to the Gemfile
in apps generated under JRuby. You can investigateall the supported runtimes at ExecJS.
This will start up Puma, a web server distributed with Rails by default. To seeyour application in action, open a browser window and navigate tohttp://localhost:3000. You should see the Rails default information page:
When you want to stop the web server, hit Ctrl+C in the terminal window whereit's running. In the development environment, Rails does not generallyrequire you to restart the server; changes you make in files will beautomatically picked up by the server.
The Rails startup page is the smoke test for a new Railsapplication: it makes sure that you have your software configured correctlyenough to serve a page.
4.2 Say "Hello", Rails
To get Rails saying "Hello", you need to create at minimum a route, acontroller with an action, and a view. A route maps a request to acontroller action. A controller action performs the necessary work to handle therequest, and prepares any data for the view. A view displays data in a desiredformat.
In terms of implementation: Routes are rules written in a Ruby DSL(Domain-Specific Language).Controllers are Ruby classes, and their public methods are actions. And viewsare templates, usually written in a mixture of HTML and Ruby.
Let's start by adding a route to our routes file, config/routes.rb
, at thetop of the Rails.application.routes.draw
block:
Rails.application.routes.draw do get "/articles", to: "articles#index" # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.htmlend
The route above declares that GET /articles
requests are mapped to the index
action of ArticlesController
.
To create ArticlesController
and its index
action, we'll run the controllergenerator (with the --skip-routes
option because we already have anappropriate route):
$ bin/rails generate controller Articles index --skip-routes
Rails will create several files for you:
create app/controllers/articles_controller.rbinvoke erbcreate app/views/articlescreate app/views/articles/index.html.erbinvoke test_unitcreate test/controllers/articles_controller_test.rbinvoke helpercreate app/helpers/articles_helper.rbinvoke test_unit
The most important of these is the controller file,app/controllers/articles_controller.rb
. Let's take a look at it:
class ArticlesController < ApplicationController def index endend
The index
action is empty. When an action does not explicitly render a view(or otherwise trigger an HTTP response), Rails will automatically render a viewthat matches the name of the controller and action. Convention OverConfiguration! Views are located in the app/views
directory. So the index
action will render app/views/articles/index.html.erb
by default.
Let's open app/views/articles/index.html.erb
, and replace its contents with:
<h1>Hello, Rails!</h1>
If you previously stopped the web server to run the controller generator,restart it with bin/rails server
. Now visit http://localhost:3000/articles,and see our text displayed!
4.3 Setting the Application Home Page
At the moment, http://localhost:3000 still displays a page with the Ruby on Rails logo.Let's display our "Hello, Rails!" text at http://localhost:3000 as well. To doso, we will add a route that maps the root path of our application to theappropriate controller and action.
Let's open config/routes.rb
, and add the following root
route to the top ofthe Rails.application.routes.draw
block:
Rails.application.routes.draw do root "articles#index" get "/articles", to: "articles#index"end
Now we can see our "Hello, Rails!" text when we visit http://localhost:3000,confirming that the root
route is also mapped to the index
action ofArticlesController
.
To learn more about routing, see Rails Routing from the Outside In.
5 Autoloading
Rails applications do not use require
to load application code.
You may have noticed that ArticlesController
inherits from ApplicationController
, but app/controllers/articles_controller.rb
does not have anything like
require "application_controller" # DON'T DO THIS.
Application classes and modules are available everywhere, you do not need and should not load anything under app
with require
. This feature is called autoloading, and you can learn more about it in Autoloading and Reloading Constants.
You only need require
calls for two use cases:
- To load files under the
lib
directory. - To load gem dependencies that have
require: false
in theGemfile
.
6 MVC and You
So far, we've discussed routes, controllers, actions, and views. All of theseare typical pieces of a web application that follows the MVC (Model-View-Controller) pattern.MVC is a design pattern that divides the responsibilities of an application tomake it easier to reason about. Rails follows this design pattern by convention.
Since we have a controller and a view to work with, let's generate the nextpiece: a model.
6.1 Generating a Model
A model is a Ruby class that is used to represent data. Additionally, modelscan interact with the application's database through a feature of Rails calledActive Record.
To define a model, we will use the model generator:
$ bin/rails generate model Article title:string body:text
Model names are singular, because an instantiated model represents asingle data record. To help remember this convention, think of how you wouldcall the model's constructor: we want to write Article.new(...)
, notArticles.new(...)
.
This will create several files:
invoke active_recordcreate db/migrate/<timestamp>_create_articles.rbcreate app/models/article.rbinvoke test_unitcreate test/models/article_test.rbcreate test/fixtures/articles.yml
The two files we'll focus on are the migration file(db/migrate/<timestamp>_create_articles.rb
) and the model file(app/models/article.rb
).
6.2 Database Migrations
Migrations are used to alter the structure of an application's database. InRails applications, migrations are written in Ruby so that they can bedatabase-agnostic.
Let's take a look at the contents of our new migration file:
class CreateArticles < ActiveRecord::Migration[7.1] def change create_table :articles do |t| t.string :title t.text :body t.timestamps end endend
The call to create_table
specifies how the articles
table should beconstructed. By default, the create_table
method adds an id
column as anauto-incrementing primary key. So the first record in the table will have anid
of 1, the next record will have an id
of 2, and so on.
Inside the block for create_table
, two columns are defined: title
andbody
. These were added by the generator because we included them in ourgenerate command (bin/rails generate model Article title:string body:text
).
On the last line of the block is a call to t.timestamps
. This method definestwo additional columns named created_at
and updated_at
. As we will see,Rails will manage these for us, setting the values when we create or update amodel object.
Let's run our migration with the following command:
$ bin/rails db:migrate
The command will display output indicating that the table was created:
== CreateArticles: migrating ===================================-- create_table(:articles) -> 0.0018s== CreateArticles: migrated (0.0018s) ==========================
To learn more about migrations, see Active Record Migrations.
Now we can interact with the table using our model.
6.3 Using a Model to Interact with the Database
To play with our model a bit, we're going to use a feature of Rails called theconsole. The console is an interactive coding environment just like irb
, butit also automatically loads Rails and our application code.
Let's launch the console with this command:
$ bin/rails console
You should see an irb
prompt like:
Loading development environment (Rails 7.1.0)irb(main):001:0>
At this prompt, we can initialize a new Article
object:
irb> article = Article.new(title: "Hello Rails", body: "I am on Rails!")
It's important to note that we have only initialized this object. This objectis not saved to the database at all. It's only available in the console at themoment. To save the object to the database, we must call save:
irb> article.save(0.1ms) begin transactionArticle Create (0.4ms) INSERT INTO "articles" ("title", "body", "created_at", "updated_at") VALUES (?, ?, ?, ?) [["title", "Hello Rails"], ["body", "I am on Rails!"], ["created_at", "2020-01-18 23:47:30.734416"], ["updated_at", "2020-01-18 23:47:30.734416"]](0.9ms) commit transaction=> true
The above output shows an INSERT INTO "articles" ...
database query. Thisindicates that the article has been inserted into our table. And if we take alook at the article
object again, we see something interesting has happened:
irb> article=> #<Article id: 1, title: "Hello Rails", body: "I am on Rails!", created_at: "2020-01-18 23:47:30", updated_at: "2020-01-18 23:47:30">
The id
, created_at
, and updated_at
attributes of the object are now set.Rails did this for us when we saved the object.
When we want to fetch this article from the database, we can call findon the model and pass the id
as an argument:
irb> Article.find(1)=> #<Article id: 1, title: "Hello Rails", body: "I am on Rails!", created_at: "2020-01-18 23:47:30", updated_at: "2020-01-18 23:47:30">
And when we want to fetch all articles from the database, we can call allon the model:
irb> Article.all=> #<ActiveRecord::Relation [#<Article id: 1, title: "Hello Rails", body: "I am on Rails!", created_at: "2020-01-18 23:47:30", updated_at: "2020-01-18 23:47:30">]>
This method returns an ActiveRecord::Relation object, whichyou can think of as a super-powered array.
To learn more about models, see Active Record Basics and Active Record Query Interface.
Models are the final piece of the MVC puzzle. Next, we will connect all of thepieces together.
6.4 Showing a List of Articles
Let's go back to our controller in app/controllers/articles_controller.rb
, andchange the index
action to fetch all articles from the database:
class ArticlesController < ApplicationController def index @articles = Article.all endend
Controller instance variables can be accessed by the view. That means we canreference @articles
in app/views/articles/index.html.erb
. Let's open thatfile, and replace its contents with:
<h1>Articles</h1><ul> <% @articles.each do |article| %> <li> <%= article.title %> </li> <% end %></ul>
The above code is a mixture of HTML and ERB. ERB is a templating system thatevaluates Ruby code embedded in a document. Here, we can see two types of ERBtags: <% %>
and <%= %>
. The <% %>
tag means "evaluate the enclosed Rubycode." The <%= %>
tag means "evaluate the enclosed Ruby code, and output thevalue it returns." Anything you could write in a regular Ruby program can goinside these ERB tags, though it's usually best to keep the contents of ERB tagsshort, for readability.
Since we don't want to output the value returned by @articles.each
, we'veenclosed that code in <% %>
. But, since we do want to output the valuereturned by article.title
(for each article), we've enclosed that code in<%= %>
.
We can see the final result by visiting http://localhost:3000. (Remember thatbin/rails server
must be running!) Here's what happens when we do that:
- The browser makes a request:
GET http://localhost:3000
. - Our Rails application receives this request.
- The Rails router maps the root route to the
index
action ofArticlesController
. - The
index
action uses theArticle
model to fetch all articles in the database. - Rails automatically renders the
app/views/articles/index.html.erb
view. - The ERB code in the view is evaluated to output HTML.
- The server sends a response containing the HTML back to the browser.
We've connected all the MVC pieces together, and we have our first controlleraction! Next, we'll move on to the second action.
7 CRUDit Where CRUDit Is Due
Almost all web applications involve CRUD (Create, Read, Update, and Delete) operations. Youmay even find that the majority of the work your application does is CRUD. Railsacknowledges this, and provides many features to help simplify code doing CRUD.
Let's begin exploring these features by adding more functionality to ourapplication.
7.1 Showing a Single Article
We currently have a view that lists all articles in our database. Let's add anew view that shows the title and body of a single article.
We start by adding a new route that maps to a new controller action (which wewill add next). Open config/routes.rb
, and insert the last route shown here:
Rails.application.routes.draw do root "articles#index" get "/articles", to: "articles#index" get "/articles/:id", to: "articles#show"end
The new route is another get
route, but it has something extra in its path::id
. This designates a route parameter. A route parameter captures a segmentof the request's path, and puts that value into the params
Hash, which isaccessible by the controller action. For example, when handling a request likeGET http://localhost:3000/articles/1
, 1
would be captured as the value for:id
, which would then be accessible as params[:id]
in the show
action ofArticlesController
.
Let's add that show
action now, below the index
action inapp/controllers/articles_controller.rb
:
class ArticlesController < ApplicationController def index @articles = Article.all end def show @article = Article.find(params[:id]) endend
The show
action calls Article.find
(mentionedpreviously) with the ID capturedby the route parameter. The returned article is stored in the @article
instance variable, so it is accessible by the view. By default, the show
action will render app/views/articles/show.html.erb
.
Let's create app/views/articles/show.html.erb
, with the following contents:
<h1><%= @article.title %></h1><p><%= @article.body %></p>
Now we can see the article when we visit http://localhost:3000/articles/1!
To finish up, let's add a convenient way to get to an article's page. We'll linkeach article's title in app/views/articles/index.html.erb
to its page:
<h1>Articles</h1><ul> <% @articles.each do |article| %> <li> <a href="/articles/<%= article.id %>"> <%= article.title %> </a> </li> <% end %></ul>
7.2 Resourceful Routing
So far, we've covered the "R" (Read) of CRUD. We will eventually cover the "C"(Create), "U" (Update), and "D" (Delete). As you might have guessed, we will doso by adding new routes, controller actions, and views. Whenever we have such acombination of routes, controller actions, and views that work together toperform CRUD operations on an entity, we call that entity a resource. Forexample, in our application, we would say an article is a resource.
Rails provides a routes method named resourcesthat maps all of the conventional routes for a collection of resources, such asarticles. So before we proceed to the "C", "U", and "D" sections, let's replacethe two get
routes in config/routes.rb
with resources
:
Rails.application.routes.draw do root "articles#index" resources :articlesend
We can inspect what routes are mapped by running the bin/rails routes
command:
$ bin/rails routes Prefix Verb URI Pattern Controller#Action root GET / articles#index articles GET /articles(.:format) articles#index new_article GET /articles/new(.:format) articles#new article GET /articles/:id(.:format) articles#show POST /articles(.:format) articles#createedit_article GET /articles/:id/edit(.:format) articles#edit PATCH /articles/:id(.:format) articles#update DELETE /articles/:id(.:format) articles#destroy
The resources
method also sets up URL and path helper methods that we can useto keep our code from depending on a specific route configuration. The valuesin the "Prefix" column above plus a suffix of _url
or _path
form the namesof these helpers. For example, the article_path
helper returns"/articles/#{article.id}"
when given an article. We can use it to tidy up ourlinks in app/views/articles/index.html.erb
:
<h1>Articles</h1><ul> <% @articles.each do |article| %> <li> <a href="<%= article_path(article) %>"> <%= article.title %> </a> </li> <% end %></ul>
However, we will take this one step further by using the link_tohelper. The link_to
helper renders a link with its first argument as thelink's text and its second argument as the link's destination. If we pass amodel object as the second argument, link_to
will call the appropriate pathhelper to convert the object to a path. For example, if we pass an article,link_to
will call article_path
. So app/views/articles/index.html.erb
becomes:
<h1>Articles</h1><ul> <% @articles.each do |article| %> <li> <%= link_to article.title, article %> </li> <% end %></ul>
Nice!
To learn more about routing, see Rails Routing from the Outside In.
7.3 Creating a New Article
Now we move on to the "C" (Create) of CRUD. Typically, in web applications,creating a new resource is a multi-step process. First, the user requests a formto fill out. Then, the user submits the form. If there are no errors, then theresource is created and some kind of confirmation is displayed. Else, the formis redisplayed with error messages, and the process is repeated.
In a Rails application, these steps are conventionally handled by a controller'snew
and create
actions. Let's add a typical implementation of these actionsto app/controllers/articles_controller.rb
, below the show
action:
class ArticlesController < ApplicationController def index @articles = Article.all end def show @article = Article.find(params[:id]) end def new @article = Article.new end def create @article = Article.new(title: "...", body: "...") if @article.save redirect_to @article else render :new, status: :unprocessable_entity end endend
The new
action instantiates a new article, but does not save it. This articlewill be used in the view when building the form. By default, the new
actionwill render app/views/articles/new.html.erb
, which we will create next.
The create
action instantiates a new article with values for the title andbody, and attempts to save it. If the article is saved successfully, the actionredirects the browser to the article's page at "http://localhost:3000/articles/#{@article.id}"
.Else, the action redisplays the form by rendering app/views/articles/new.html.erb
with status code 422 Unprocessable Entity.The title and body here are dummy values. After we create the form, we will comeback and change these.
redirect_towill cause the browser to make a new request,whereas renderrenders the specified view for the current request.It is important to use redirect_to
after mutating the database or application state.Otherwise, if the user refreshes the page, the browser will make the same request, and the mutation will be repeated.
7.3.1 Using a Form Builder
We will use a feature of Rails called a form builder to create our form. Usinga form builder, we can write a minimal amount of code to output a form that isfully configured and follows Rails conventions.
Let's create app/views/articles/new.html.erb
with the following contents:
<h1>New Article</h1><%= form_with model: @article do |form| %> <div> <%= form.label :title %><br> <%= form.text_field :title %> </div> <div> <%= form.label :body %><br> <%= form.text_area :body %> </div> <div> <%= form.submit %> </div><% end %>
The form_withhelper method instantiates a form builder. In the form_with
block we callmethods like labeland text_fieldon the form builder to output the appropriate form elements.
The resulting output from our form_with
call will look like:
<form action="/articles" accept-charset="UTF-8" method="post"> <input type="hidden" name="authenticity_token" value="..."> <div> <label for="article_title">Title</label><br> <input type="text" name="article[title]" id="article_title"> </div> <div> <label for="article_body">Body</label><br> <textarea name="article[body]" id="article_body"></textarea> </div> <div> <input type="submit" name="commit" value="Create Article" data-disable-with="Create Article"> </div></form>
To learn more about form builders, see Action View Form Helpers.
7.3.2 Using Strong Parameters
Submitted form data is put into the params
Hash, alongside captured routeparameters. Thus, the create
action can access the submitted title viaparams[:article][:title]
and the submitted body via params[:article][:body]
.We could pass these values individually to Article.new
, but that would beverbose and possibly error-prone. And it would become worse as we add morefields.
Instead, we will pass a single Hash that contains the values. However, we muststill specify what values are allowed in that Hash. Otherwise, a malicious usercould potentially submit extra form fields and overwrite private data. In fact,if we pass the unfiltered params[:article]
Hash directly to Article.new
,Rails will raise a ForbiddenAttributesError
to alert us about the problem.So we will use a feature of Rails called Strong Parameters to filter params
.Think of it as strong typingfor params
.
Let's add a private method to the bottom of app/controllers/articles_controller.rb
named article_params
that filters params
. And let's change create
to useit:
class ArticlesController < ApplicationController def index @articles = Article.all end def show @article = Article.find(params[:id]) end def new @article = Article.new end def create @article = Article.new(article_params) if @article.save redirect_to @article else render :new, status: :unprocessable_entity end end private def article_params params.require(:article).permit(:title, :body) endend
To learn more about Strong Parameters, see Action Controller Overview §Strong Parameters.
7.3.3 Validations and Displaying Error Messages
As we have seen, creating a resource is a multi-step process. Handling invaliduser input is another step of that process. Rails provides a feature calledvalidations to help us deal with invalid user input. Validations are rulesthat are checked before a model object is saved. If any of the checks fail, thesave will be aborted, and appropriate error messages will be added to theerrors
attribute of the model object.
Let's add some validations to our model in app/models/article.rb
:
class Article < ApplicationRecord validates :title, presence: true validates :body, presence: true, length: { minimum: 10 }end
The first validation declares that a title
value must be present. Becausetitle
is a string, this means that the title
value must contain at least onenon-whitespace character.
The second validation declares that a body
value must also be present.Additionally, it declares that the body
value must be at least 10 characterslong.
You may be wondering where the title
and body
attributes are defined.Active Record automatically defines model attributes for every table column, soyou don't have to declare those attributes in your model file.
With our validations in place, let's modify app/views/articles/new.html.erb
todisplay any error messages for title
and body
:
<h1>New Article</h1><%= form_with model: @article do |form| %> <div> <%= form.label :title %><br> <%= form.text_field :title %> <% @article.errors.full_messages_for(:title).each do |message| %> <div><%= message %></div> <% end %> </div> <div> <%= form.label :body %><br> <%= form.text_area :body %><br> <% @article.errors.full_messages_for(:body).each do |message| %> <div><%= message %></div> <% end %> </div> <div> <%= form.submit %> </div><% end %>
The full_messages_formethod returns an array of user-friendly error messages for a specifiedattribute. If there are no errors for that attribute, the array will be empty.
To understand how all of this works together, let's take another look at thenew
and create
controller actions:
def new @article = Article.new end def create @article = Article.new(article_params) if @article.save redirect_to @article else render :new, status: :unprocessable_entity end end
When we visit http://localhost:3000/articles/new, the GET /articles/new
request is mapped to the new
action. The new
action does not attempt to save@article
. Therefore, validations are not checked, and there will be no errormessages.
When we submit the form, the POST /articles
request is mapped to the create
action. The create
action does attempt to save @article
. Therefore,validations are checked. If any validation fails, @article
will not besaved, and app/views/articles/new.html.erb
will be rendered with errormessages.
To learn more about validations, see Active Record Validations. To learn more about validation error messages,see Active Record Validations § Working with Validation Errors.
7.3.4 Finishing Up
We can now create an article by visiting http://localhost:3000/articles/new.To finish up, let's link to that page from the bottom ofapp/views/articles/index.html.erb
:
<h1>Articles</h1><ul> <% @articles.each do |article| %> <li> <%= link_to article.title, article %> </li> <% end %></ul><%= link_to "New Article", new_article_path %>
7.4 Updating an Article
We've covered the "CR" of CRUD. Now let's move on to the "U" (Update). Updatinga resource is very similar to creating a resource. They are both multi-stepprocesses. First, the user requests a form to edit the data. Then, the usersubmits the form. If there are no errors, then the resource is updated. Else,the form is redisplayed with error messages, and the process is repeated.
These steps are conventionally handled by a controller's edit
and update
actions. Let's add a typical implementation of these actions toapp/controllers/articles_controller.rb
, below the create
action:
class ArticlesController < ApplicationController def index @articles = Article.all end def show @article = Article.find(params[:id]) end def new @article = Article.new end def create @article = Article.new(article_params) if @article.save redirect_to @article else render :new, status: :unprocessable_entity end end def edit @article = Article.find(params[:id]) end def update @article = Article.find(params[:id]) if @article.update(article_params) redirect_to @article else render :edit, status: :unprocessable_entity end end private def article_params params.require(:article).permit(:title, :body) endend
Notice how the edit
and update
actions resemble the new
and create
actions.
The edit
action fetches the article from the database, and stores it in@article
so that it can be used when building the form. By default, the edit
action will render app/views/articles/edit.html.erb
.
The update
action (re-)fetches the article from the database, and attemptsto update it with the submitted form data filtered by article_params
. If novalidations fail and the update is successful, the action redirects the browserto the article's page. Else, the action redisplays the form — with errormessages — by rendering app/views/articles/edit.html.erb
.
Our edit
form will look the same as our new
form. Even the code will be thesame, thanks to the Rails form builder and resourceful routing. The form builderautomatically configures the form to make the appropriate kind of request, basedon whether the model object has been previously saved.
Because the code will be the same, we're going to factor it out into a sharedview called a partial. Let's create app/views/articles/_form.html.erb
withthe following contents:
<%= form_with model: article do |form| %> <div> <%= form.label :title %><br> <%= form.text_field :title %> <% article.errors.full_messages_for(:title).each do |message| %> <div><%= message %></div> <% end %> </div> <div> <%= form.label :body %><br> <%= form.text_area :body %><br> <% article.errors.full_messages_for(:body).each do |message| %> <div><%= message %></div> <% end %> </div> <div> <%= form.submit %> </div><% end %>
The above code is the same as our form in app/views/articles/new.html.erb
,except that all occurrences of @article
have been replaced with article
.Because partials are shared code, it is best practice that they do not depend onspecific instance variables set by a controller action. Instead, we will passthe article to the partial as a local variable.
Let's update app/views/articles/new.html.erb
to use the partial via render:
<h1>New Article</h1><%= render "form", article: @article %>
A partial's filename must be prefixed with an underscore, e.g._form.html.erb
. But when rendering, it is referenced without theunderscore, e.g. render "form"
.
And now, let's create a very similar app/views/articles/edit.html.erb
:
<h1>Edit Article</h1><%= render "form", article: @article %>
To learn more about partials, see Layouts and Rendering in Rails § UsingPartials.
7.4.2 Finishing Up
We can now update an article by visiting its edit page, e.g.http://localhost:3000/articles/1/edit. To finish up, let's link to the editpage from the bottom of app/views/articles/show.html.erb
:
<h1><%= @article.title %></h1><p><%= @article.body %></p><ul> <li><%= link_to "Edit", edit_article_path(@article) %></li></ul>
7.5 Deleting an Article
Finally, we arrive at the "D" (Delete) of CRUD. Deleting a resource is a simplerprocess than creating or updating. It only requires a route and a controlleraction. And our resourceful routing (resources :articles
) already provides theroute, which maps DELETE /articles/:id
requests to the destroy
action ofArticlesController
.
So, let's add a typical destroy
action to app/controllers/articles_controller.rb
,below the update
action:
class ArticlesController < ApplicationController def index @articles = Article.all end def show @article = Article.find(params[:id]) end def new @article = Article.new end def create @article = Article.new(article_params) if @article.save redirect_to @article else render :new, status: :unprocessable_entity end end def edit @article = Article.find(params[:id]) end def update @article = Article.find(params[:id]) if @article.update(article_params) redirect_to @article else render :edit, status: :unprocessable_entity end end def destroy @article = Article.find(params[:id]) @article.destroy redirect_to root_path, status: :see_other end private def article_params params.require(:article).permit(:title, :body) endend
The destroy
action fetches the article from the database, and calls destroyon it. Then, it redirects the browser to the root path with status code303 See Other.
We have chosen to redirect to the root path because that is our main accesspoint for articles. But, in other circ*mstances, you might choose to redirect toe.g. articles_path
.
Now let's add a link at the bottom of app/views/articles/show.html.erb
so thatwe can delete an article from its own page:
<h1><%= @article.title %></h1><p><%= @article.body %></p><ul> <li><%= link_to "Edit", edit_article_path(@article) %></li> <li><%= link_to "Destroy", article_path(@article), data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %></li></ul>
In the above code, we use the data
option to set the data-turbo-method
anddata-turbo-confirm
HTML attributes of the "Destroy" link. Both of theseattributes hook into Turbo, which is included bydefault in fresh Rails applications. data-turbo-method="delete"
will cause thelink to make a DELETE
request instead of a GET
request.data-turbo-confirm="Are you sure?"
will cause a confirmation dialog to appearwhen the link is clicked. If the user cancels the dialog, the request will beaborted.
And that's it! We can now list, show, create, update, and delete articles!InCRUDable!
8 Adding a Second Model
It's time to add a second model to the application. The second model will handlecomments on articles.
8.1 Generating a Model
We're going to see the same generator that we used before when creatingthe Article
model. This time we'll create a Comment
model to hold areference to an article. Run this command in your terminal:
$ bin/rails generate model Comment commenter:string body:text article:references
This command will generate four files:
File | Purpose |
---|---|
db/migrate/20140120201010_create_comments.rb | Migration to create the comments table in your database (your name will include a different timestamp) |
app/models/comment.rb | The Comment model |
test/models/comment_test.rb | Testing harness for the comment model |
test/fixtures/comments.yml | Sample comments for use in testing |
First, take a look at app/models/comment.rb
:
class Comment < ApplicationRecord belongs_to :articleend
This is very similar to the Article
model that you saw earlier. The differenceis the line belongs_to :article
, which sets up an Active Record association.You'll learn a little about associations in the next section of this guide.
The (:references
) keyword used in the shell command is a special data type for models.It creates a new column on your database table with the provided model name appended with an _id
that can hold integer values. To get a better understanding, analyze thedb/schema.rb
file after running the migration.
In addition to the model, Rails has also made a migration to create thecorresponding database table:
class CreateComments < ActiveRecord::Migration[7.1] def change create_table :comments do |t| t.string :commenter t.text :body t.references :article, null: false, foreign_key: true t.timestamps end endend
The t.references
line creates an integer column called article_id
, an indexfor it, and a foreign key constraint that points to the id
column of the articles
table. Go ahead and run the migration:
$ bin/rails db:migrate
Rails is smart enough to only execute the migrations that have not already beenrun against the current database, so in this case you will just see:
== CreateComments: migrating =================================================-- create_table(:comments) -> 0.0115s== CreateComments: migrated (0.0119s) ========================================
8.2 Associating Models
Active Record associations let you easily declare the relationship between twomodels. In the case of comments and articles, you could write out therelationships this way:
- Each comment belongs to one article.
- One article can have many comments.
In fact, this is very close to the syntax that Rails uses to declare thisassociation. You've already seen the line of code inside the Comment
model(app/models/comment.rb) that makes each comment belong to an Article:
class Comment < ApplicationRecord belongs_to :articleend
You'll need to edit app/models/article.rb
to add the other side of theassociation:
class Article < ApplicationRecord has_many :comments validates :title, presence: true validates :body, presence: true, length: { minimum: 10 }end
These two declarations enable a good bit of automatic behavior. For example, ifyou have an instance variable @article
containing an article, you can retrieveall the comments belonging to that article as an array using@article.comments
.
For more information on Active Record associations, see the Active RecordAssociations guide.
8.3 Adding a Route for Comments
As with the articles
controller, we will need to add a route so that Railsknows where we would like to navigate to see comments
. Open up theconfig/routes.rb
file again, and edit it as follows:
Rails.application.routes.draw do root "articles#index" resources :articles do resources :comments endend
This creates comments
as a nested resource within articles
. This isanother part of capturing the hierarchical relationship that exists betweenarticles and comments.
For more information on routing, see the Rails Routingguide.
8.4 Generating a Controller
With the model in hand, you can turn your attention to creating a matchingcontroller. Again, we'll use the same generator we used before:
$ bin/rails generate controller Comments
This creates three files and one empty directory:
File/Directory | Purpose |
---|---|
app/controllers/comments_controller.rb | The Comments controller |
app/views/comments/ | Views of the controller are stored here |
test/controllers/comments_controller_test.rb | The test for the controller |
app/helpers/comments_helper.rb | A view helper file |
Like with any blog, our readers will create their comments directly afterreading the article, and once they have added their comment, will be sent backto the article show page to see their comment now listed. Due to this, ourCommentsController
is there to provide a method to create comments and deletespam comments when they arrive.
So first, we'll wire up the Article show template(app/views/articles/show.html.erb
) to let us make a new comment:
<h1><%= @article.title %></h1><p><%= @article.body %></p><ul> <li><%= link_to "Edit", edit_article_path(@article) %></li> <li><%= link_to "Destroy", article_path(@article), data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %></li></ul><h2>Add a comment:</h2><%= form_with model: [ @article, @article.comments.build ] do |form| %> <p> <%= form.label :commenter %><br> <%= form.text_field :commenter %> </p> <p> <%= form.label :body %><br> <%= form.text_area :body %> </p> <p> <%= form.submit %> </p><% end %>
This adds a form on the Article
show page that creates a new comment bycalling the CommentsController
create
action. The form_with
call here usesan array, which will build a nested route, such as /articles/1/comments
.
Let's wire up the create
in app/controllers/comments_controller.rb
:
class CommentsController < ApplicationController def create @article = Article.find(params[:article_id]) @comment = @article.comments.create(comment_params) redirect_to article_path(@article) end private def comment_params params.require(:comment).permit(:commenter, :body) endend
You'll see a bit more complexity here than you did in the controller forarticles. That's a side-effect of the nesting that you've set up. Each requestfor a comment has to keep track of the article to which the comment is attached,thus the initial call to the find
method of the Article
model to get thearticle in question.
In addition, the code takes advantage of some of the methods available for anassociation. We use the create
method on @article.comments
to create andsave the comment. This will automatically link the comment so that it belongs tothat particular article.
Once we have made the new comment, we send the user back to the original articleusing the article_path(@article)
helper. As we have already seen, this callsthe show
action of the ArticlesController
which in turn renders theshow.html.erb
template. This is where we want the comment to show, so let'sadd that to the app/views/articles/show.html.erb
.
<h1><%= @article.title %></h1><p><%= @article.body %></p><ul> <li><%= link_to "Edit", edit_article_path(@article) %></li> <li><%= link_to "Destroy", article_path(@article), data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %></li></ul><h2>Comments</h2><% @article.comments.each do |comment| %> <p> <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> <strong>Comment:</strong> <%= comment.body %> </p><% end %><h2>Add a comment:</h2><%= form_with model: [ @article, @article.comments.build ] do |form| %> <p> <%= form.label :commenter %><br> <%= form.text_field :commenter %> </p> <p> <%= form.label :body %><br> <%= form.text_area :body %> </p> <p> <%= form.submit %> </p><% end %>
Now you can add articles and comments to your blog and have them show up in theright places.
9 Refactoring
Now that we have articles and comments working, take a look at theapp/views/articles/show.html.erb
template. It is getting long and awkward. Wecan use partials to clean it up.
9.1 Rendering Partial Collections
First, we will make a comment partial to extract showing all the comments forthe article. Create the file app/views/comments/_comment.html.erb
and put thefollowing into it:
<p> <strong>Commenter:</strong> <%= comment.commenter %></p><p> <strong>Comment:</strong> <%= comment.body %></p>
Then you can change app/views/articles/show.html.erb
to look like thefollowing:
<h1><%= @article.title %></h1><p><%= @article.body %></p><ul> <li><%= link_to "Edit", edit_article_path(@article) %></li> <li><%= link_to "Destroy", article_path(@article), data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %></li></ul><h2>Comments</h2><%= render @article.comments %><h2>Add a comment:</h2><%= form_with model: [ @article, @article.comments.build ] do |form| %> <p> <%= form.label :commenter %><br> <%= form.text_field :commenter %> </p> <p> <%= form.label :body %><br> <%= form.text_area :body %> </p> <p> <%= form.submit %> </p><% end %>
This will now render the partial in app/views/comments/_comment.html.erb
oncefor each comment that is in the @article.comments
collection. As the render
method iterates over the @article.comments
collection, it assigns eachcomment to a local variable named the same as the partial, in this casecomment
, which is then available in the partial for us to show.
9.2 Rendering a Partial Form
Let us also move that new comment section out to its own partial. Again, youcreate a file app/views/comments/_form.html.erb
containing:
<%= form_with model: [ @article, @article.comments.build ] do |form| %> <p> <%= form.label :commenter %><br> <%= form.text_field :commenter %> </p> <p> <%= form.label :body %><br> <%= form.text_area :body %> </p> <p> <%= form.submit %> </p><% end %>
Then you make the app/views/articles/show.html.erb
look like the following:
<h1><%= @article.title %></h1><p><%= @article.body %></p><ul> <li><%= link_to "Edit", edit_article_path(@article) %></li> <li><%= link_to "Destroy", article_path(@article), data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %></li></ul><h2>Comments</h2><%= render @article.comments %><h2>Add a comment:</h2><%= render 'comments/form' %>
The second render just defines the partial template we want to render,comments/form
. Rails is smart enough to spot the forward slash in thatstring and realize that you want to render the _form.html.erb
file inthe app/views/comments
directory.
The @article
object is available to any partials rendered in the view becausewe defined it as an instance variable.
9.3 Using Concerns
Concerns are a way to make large controllers or models easier to understand and manage. This also has the advantage of reusability when multiple models (or controllers) share the same concerns. Concerns are implemented using modules that contain methods representing a well-defined slice of the functionality that a model or controller is responsible for. In other languages, modules are often known as mixins.
You can use concerns in your controller or model the same way you would use any module. When you first created your app with rails new blog
, two folders were created within app/
along with the rest:
app/controllers/concernsapp/models/concerns
In the example below, we will implement a new feature for our blog that would benefit from using a concern. Then, we will create a concern, and refactor the code to use it, making the code more DRY and maintainable.
A blog article might have various statuses - for instance, it might be visible to everyone (i.e. public
), or only visible to the author (i.e. private
). It may also be hidden to all but still retrievable (i.e. archived
). Comments may similarly be hidden or visible. This could be represented using a status
column in each model.
First, let's run the following migrations to add status
to Articles
and Comments
:
$ bin/rails generate migration AddStatusToArticles status:string$ bin/rails generate migration AddStatusToComments status:string
And next, let's update the database with the generated migrations:
$ bin/rails db:migrate
To choose the status for the existing articles and comments you can add a default value to the generated migration files by adding the default: "public"
option and launch the migrations again. You can also call in a rails console Article.update_all(status: "public")
and Comment.update_all(status: "public")
.
To learn more about migrations, see Active Record Migrations.
We also have to permit the :status
key as part of the strong parameter, in app/controllers/articles_controller.rb
:
private def article_params params.require(:article).permit(:title, :body, :status) end
and in app/controllers/comments_controller.rb
:
private def comment_params params.require(:comment).permit(:commenter, :body, :status) end
Within the article
model, after running a migration to add a status
column using bin/rails db:migrate
command, you would add:
class Article < ApplicationRecord has_many :comments validates :title, presence: true validates :body, presence: true, length: { minimum: 10 } VALID_STATUSES = ['public', 'private', 'archived'] validates :status, inclusion: { in: VALID_STATUSES } def archived? status == 'archived' endend
and in the Comment
model:
class Comment < ApplicationRecord belongs_to :article VALID_STATUSES = ['public', 'private', 'archived'] validates :status, inclusion: { in: VALID_STATUSES } def archived? status == 'archived' endend
Then, in our index
action template (app/views/articles/index.html.erb
) we would use the archived?
method to avoid displaying any article that is archived:
<h1>Articles</h1><ul> <% @articles.each do |article| %> <% unless article.archived? %> <li> <%= link_to article.title, article %> </li> <% end %> <% end %></ul><%= link_to "New Article", new_article_path %>
Similarly, in our comment partial view (app/views/comments/_comment.html.erb
) we would use the archived?
method to avoid displaying any comment that is archived:
<% unless comment.archived? %> <p> <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> <strong>Comment:</strong> <%= comment.body %> </p><% end %>
However, if you look again at our models now, you can see that the logic is duplicated. If in the future we increase the functionality of our blog - to include private messages, for instance - we might find ourselves duplicating the logic yet again. This is where concerns come in handy.
A concern is only responsible for a focused subset of the model's responsibility; the methods in our concern will all be related to the visibility of a model. Let's call our new concern (module) Visible
. We can create a new file inside app/models/concerns
called visible.rb
, and store all of the status methods that were duplicated in the models.
app/models/concerns/visible.rb
module Visible def archived? status == 'archived' endend
We can add our status validation to the concern, but this is slightly more complex as validations are methods called at the class level. The ActiveSupport::Concern
(API Guide) gives us a simpler way to include them:
module Visible extend ActiveSupport::Concern VALID_STATUSES = ['public', 'private', 'archived'] included do validates :status, inclusion: { in: VALID_STATUSES } end def archived? status == 'archived' endend
Now, we can remove the duplicated logic from each model and instead include our new Visible
module:
In app/models/article.rb
:
class Article < ApplicationRecord include Visible has_many :comments validates :title, presence: true validates :body, presence: true, length: { minimum: 10 }end
and in app/models/comment.rb
:
class Comment < ApplicationRecord include Visible belongs_to :articleend
Class methods can also be added to concerns. If we want to display a count of public articles or comments on our main page, we might add a class method to Visible as follows:
module Visible extend ActiveSupport::Concern VALID_STATUSES = ['public', 'private', 'archived'] included do validates :status, inclusion: { in: VALID_STATUSES } end class_methods do def public_count where(status: 'public').count end end def archived? status == 'archived' endend
Then in the view, you can call it like any class method:
<h1>Articles</h1>Our blog has <%= Article.public_count %> articles and counting!<ul> <% @articles.each do |article| %> <% unless article.archived? %> <li> <%= link_to article.title, article %> </li> <% end %> <% end %></ul><%= link_to "New Article", new_article_path %>
To finish up, we will add a select box to the forms, and let the user select the status when they create a new article or post a new comment. We can also select the status of the object, or a default of public
if it hasn't been set yet. In app/views/articles/_form.html.erb
, we can add:
<div> <%= form.label :status %><br> <%= form.select :status, Visible::VALID_STATUSES, selected: article.status || 'public' %></div>
and in app/views/comments/_form.html.erb
:
<p> <%= form.label :status %><br> <%= form.select :status, Visible::VALID_STATUSES, selected: 'public' %></p>
Another important feature of a blog is being able to delete spam comments. To dothis, we need to implement a link of some sort in the view and a destroy
action in the CommentsController
.
So first, let's add the delete link in theapp/views/comments/_comment.html.erb
partial:
<% unless comment.archived? %> <p> <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> <strong>Comment:</strong> <%= comment.body %> </p> <p> <%= link_to "Destroy Comment", [comment.article, comment], data: { turbo_method: :delete, turbo_confirm: "Are you sure?" } %> </p><% end %>
Clicking this new "Destroy Comment" link will fire off a DELETE/articles/:article_id/comments/:id
to our CommentsController
, which can thenuse this to find the comment we want to delete, so let's add a destroy
actionto our controller (app/controllers/comments_controller.rb
):
class CommentsController < ApplicationController def create @article = Article.find(params[:article_id]) @comment = @article.comments.create(comment_params) redirect_to article_path(@article) end def destroy @article = Article.find(params[:article_id]) @comment = @article.comments.find(params[:id]) @comment.destroy redirect_to article_path(@article), status: :see_other end private def comment_params params.require(:comment).permit(:commenter, :body, :status) endend
The destroy
action will find the article we are looking at, locate the commentwithin the @article.comments
collection, and then remove it from thedatabase and send us back to the show action for the article.
10.1 Deleting Associated Objects
If you delete an article, its associated comments will also need to bedeleted, otherwise they would simply occupy space in the database. Rails allowsyou to use the dependent
option of an association to achieve this. Modify theArticle model, app/models/article.rb
, as follows:
class Article < ApplicationRecord include Visible has_many :comments, dependent: :destroy validates :title, presence: true validates :body, presence: true, length: { minimum: 10 }end
11 Security
11.1 Basic Authentication
If you were to publish your blog online, anyone would be able to add, edit anddelete articles or delete comments.
Rails provides an HTTP authentication system that will work nicely inthis situation.
In the ArticlesController
we need to have a way to block access to thevarious actions if the person is not authenticated. Here we can use the Railshttp_basic_authenticate_with
method, which allows access to the requestedaction if that method allows it.
To use the authentication system, we specify it at the top of ourArticlesController
in app/controllers/articles_controller.rb
. In our case,we want the user to be authenticated on every action except index
and show
,so we write that:
class ArticlesController < ApplicationController http_basic_authenticate_with name: "dhh", password: "secret", except: [:index, :show] def index @articles = Article.all end # snippet for brevityend
We also want to allow only authenticated users to delete comments, so in theCommentsController
(app/controllers/comments_controller.rb
) we write:
class CommentsController < ApplicationController http_basic_authenticate_with name: "dhh", password: "secret", only: :destroy def create @article = Article.find(params[:article_id]) # ... end # snippet for brevityend
Now if you try to create a new article, you will be greeted with a basic HTTPAuthentication challenge:
After entering the correct username and password, you will remain authenticateduntil a different username and password is required or the browser is closed.
Other authentication methods are available for Rails applications. Two popularauthentication add-ons for Rails are theDevise rails engine andthe Authlogic gem,along with a number of others.
11.2 Other Security Considerations
Security, especially in web applications, is a broad and detailed area. Securityin your Rails application is covered in more depth inthe Ruby on Rails Security Guide.
12 What's Next?
Now that you've seen your first Rails application, you should feel free toupdate it and experiment on your own.
Remember, you don't have to do everything without help. As you need assistancegetting up and running with Rails, feel free to consult these supportresources:
- The Ruby on Rails Guides
- The Ruby on Rails mailing list
13 Configuration Gotchas
The easiest way to work with Rails is to store all external data as UTF-8. Ifyou don't, Ruby libraries and Rails will often be able to convert your nativedata into UTF-8, but this doesn't always work reliably, so you're better offensuring that all external data is UTF-8.
If you have made a mistake in this area, the most common symptom is a blackdiamond with a question mark inside appearing in the browser. Another commonsymptom is characters like "ü" appearing instead of "ü". Rails takes a numberof internal steps to mitigate common causes of these problems that can beautomatically detected and corrected. However, if you have external data that isnot stored as UTF-8, it can occasionally result in these kinds of issues thatcannot be automatically detected by Rails and corrected.
Two very common sources of data that are not UTF-8:
- Your text editor: Most text editors (such as TextMate), default to savingfiles as UTF-8. If your text editor does not, this can result in specialcharacters that you enter in your templates (such as é) to appear as a diamondwith a question mark inside in the browser. This also applies to your i18ntranslation files. Most editors that do not already default to UTF-8 (such assome versions of Dreamweaver) offer a way to change the default to UTF-8. Doso.
- Your database: Rails defaults to converting data from your database into UTF-8at the boundary. However, if your database is not using UTF-8 internally, itmay not be able to store all characters that your users enter. For instance,if your database is using Latin-1 internally, and your user enters a Russian,Hebrew, or Japanese character, the data will be lost forever once it entersthe database. If possible, use UTF-8 as the internal storage of your database.
Feedback
You're encouraged to help improve the quality of this guide.
Please contribute if you see any typos or factual errors. To get started, you can read our documentation contributions section.
You may also find incomplete content or stuff that is not up to date. Please do add any missing documentation for main. Make sure to check Edge Guides first to verify if the issues are already fixed or not on the main branch. Check the Ruby on Rails Guides Guidelines for style and conventions.
If for whatever reason you spot something to fix but cannot patch it yourself, please open an issue.
And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome on the official Ruby on Rails Forum.