Missing template posts/new, application/new with {:locale=>[:en], :formats=>[:html], :handlers=>[:erb, :builder, :coffee]}. Searched in: * "/path/to/blog/app/views"That's quite a lot of text! Let's quickly go through and understand what each part of it does. The first part identifies what template is missing. In this case, it's the `posts/new` template. Rails will first look for this template. If not found, then it will attempt to load a template called `application/new`. It looks for one here because the `PostsController` inherits from `ApplicationController`. The next part of the message contains a hash. The `:locale` key in this hash simply indicates what spoken language template should be retrieved. By default, this is the English -- or "en" -- template. The next key, `:formats` specifies the format of template to be served in response . The default format is `:html`, and so Rails is looking for an HTML template. The final key, `:handlers`, is telling us what _template handlers_ could be used to render our template. `:erb` is most commonly used for HTML templates, `:builder` is used for XML templates, and `:coffee` uses CoffeeScript to build JavaScript templates. The final part of this message tells us where Rails has looked for the templates. Templates within a basic Rails application like this are kept in a single location, but in more complex applications it could be many different paths. The simplest template that would work in this case would be one located at `app/views/posts/new.html.erb`. The extension of this file name is key: the first extension is the _format_ of the template, and the second extension is the _handler_ that will be used. Rails is attempting to find a template called `posts/new` within `app/views` for the application. The format for this template can only be `html` and the handler must be one of `erb`, `builder` or `coffee`. Because you want to create a new HTML form, you will be using the `ERB` language. Therefore the file should be called `posts/new.html.erb` and needs to be located inside the `app/views` directory of the application. Go ahead now and create a new file at `app/views/posts/new.html.erb` and write this content in it: ```html
<%= f.label :title %>
<%= f.text_field :title %>
<%= f.label :text %>
<%= f.text_area :text %>
<%= f.submit %>
<% end %> ``` If you refresh the page now, you'll see the exact same form as in the example. Building forms in Rails is really just that easy! When you call `form_for`, you pass it an identifying object for this form. In this case, it's the symbol `:post`. This tells the `form_for` helper what this form is for. Inside the block for this method, the `FormBuilder` object -- represented by `f` -- is used to build two labels and two text fields, one each for the title and text of a post. Finally, a call to `submit` on the `f` object will create a submit button for the form. There's one problem with this form though. If you inspect the HTML that is generated, by viewing the source of the page, you will see that the `action` attribute for the form is pointing at `/posts/new`. This is a problem because this route goes to the very page that you're on right at the moment, and that route should only be used to display the form for a new post. The form needs to use a different URL in order to go somewhere else. This can be done quite simply with the `:url` option of `form_for`. Typically in Rails, the action that is used for new form submissions like this is called "create", and so the form should be pointed to that action. Edit the `form_for` line inside `app/views/posts/new.html.erb` to look like this: ```html+erb <%= form_for :post, :url => { :action => :create } do |f| %> ``` In this example, a `Hash` object is passed to the `:url` option. What Rails will do with this is that it will point the form to the `create` action of the current controller, the `PostsController`, and will send a `POST` request to that route. For this to work, you will need to add a route to `config/routes.rb`, right underneath the one for "posts/new": ```ruby post "posts" => "posts#create" ``` By using the `post` method rather than the `get` method, Rails will define a route that will only respond to POST methods. The POST method is the typical method used by forms all over the web. With the form and its associated route defined, you will be able to fill in the form and then click the submit button to begin the process of creating a new post, so go ahead and do that. When you submit the form, you should see a familiar error:  You now need to create the `create` action within the `PostsController` for this to work. ### Creating posts To make the "Unknown action" go away, you can define a `create` action within the `PostsController` class in `app/controllers/posts_controller.rb`, underneath the `new` action: ```ruby class PostsController < ApplicationController def new end def create end end ``` If you re-submit the form now, you'll see another familiar error: a template is missing. That's ok, we can ignore that for now. What the `create` action should be doing is saving our new post to a database. When a form is submitted, the fields of the form are sent to Rails as _parameters_. These parameters can then be referenced inside the controller actions, typically to perform a particular task. To see what these parameters look like, change the `create` action to this: ```ruby def create render :text => params[:post].inspect end ``` The `render` method here is taking a very simple hash with a key of `text` and value of `params[:post].inspect`. The `params` method is the object which represents the parameters (or fields) coming in from the form. The `params` method returns a `HashWithIndifferentAccess` object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. If you re-submit the form one more time you'll now no longer get the missing template error. Instead, you'll see something that looks like the following: ```ruby {"title"=>"First post!", "text"=>"This is my first post."} ``` This action is now displaying the parameters for the post that are coming in from the form. However, this isn't really all that helpful. Yes, you can see the parameters but nothing in particular is being done with them. ### Creating the Post model Models in Rails use a singular name, and their corresponding database tables use a plural name. Rails provides a generator for creating models, which most Rails developers tend to use when creating new models. To create the new model, run this command in your terminal: ```bash $ rails generate model Post title:string text:text ``` With that command we told Rails that we want a `Post` model, together with a _title_ attribute of type string, and a _text_ attribute of type text. Those attributes are automatically added to the `posts` table in the database and mapped to the `Post` model. Rails responded by creating a bunch of files. For now, we're only interested in `app/models/post.rb` and `db/migrate/20120419084633_create_posts.rb` (your name could be a bit different). The latter is responsible for creating the database structure, which is what we'll look at next. TIP: Active Record is smart enough to automatically map column names to model attributes, which means you don't have to declare attributes inside Rails models, as that will be done automatically by Active Record. ### Running a Migration As we've just seen, `rails generate model` created a _database migration_ file inside the `db/migrate` directory. Migrations are Ruby classes that are designed to make it simple to create and modify database tables. Rails uses rake commands to run migrations, and it's possible to undo a migration after it's been applied to your database. Migration filenames include a timestamp to ensure that they're processed in the order that they were created. If you look in the `db/migrate/20120419084633_create_posts.rb` file (remember, yours will have a slightly different name), here's what you'll find: ```ruby class CreatePosts < ActiveRecord::Migration def change create_table :posts do |t| t.string :title t.text :text t.timestamps end end end ``` The above migration creates a method named `change` which will be called when you run this migration. The action defined in this method is also reversible, which means Rails knows how to reverse the change made by this migration, in case you want to reverse it later. When you run this migration it will create a `posts` table with one string column and a text column. It also creates two timestamp fields to allow Rails to track post creation and update times. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. At this point, you can use a rake command to run the migration: ```bash $ rake db:migrate ``` Rails will execute this migration command and tell you it created the Posts table. ```bash == CreatePosts: migrating ==================================================== -- create_table(:posts) -> 0.0019s == CreatePosts: migrated (0.0020s) =========================================== ``` NOTE. Because you're working in the development environment by default, this command will apply to the database defined in the `development` section of your `config/database.yml` file. If you would like to execute migrations in another environment, for instance in production, you must explicitly pass it when invoking the command: `rake db:migrate RAILS_ENV=production`. ### Saving data in the controller Back in `posts_controller`, we need to change the `create` action to use the new `Post` model to save the data in the database. Open that file and change the `create` action to look like this: ```ruby def create @post = Post.new(params[:post]) @post.save redirect_to :action => :show, :id => @post.id end ``` Here's what's going on: every Rails model can be initialized with its respective attributes, which are automatically mapped to the respective database columns. In the first line we do just that (remember that `params[:post]` contains the attributes we're interested in). Then, `@post.save` is responsible for saving the model in the database. Finally, we redirect the user to the `show` action, which we'll define later. TIP: As we'll see later, `@post.save` returns a boolean indicating wherever the model was saved or not. ### Showing Posts If you submit the form again now, Rails will complain about not finding the `show` action. That's not very useful though, so let's add the `show` action before proceeding. Open `config/routes.rb` and add the following route: ```ruby get "posts/:id" => "posts#show" ``` The special syntax `:id` tells rails that this route expects an `:id` parameter, which in our case will be the id of the post. Note that this time we had to specify the actual mapping, `posts#show` because otherwise Rails would not know which action to render. As we did before, we need to add the `show` action in the `posts_controller` and its respective view. ```ruby def show @post = Post.find(params[:id]) end ``` A couple of things to note. We use `Post.find` to find the post we're interested in. We also use an instance variable (prefixed by `@`) to hold a reference to the post object. We do this because Rails will pass all instance variables to the view. Now, create a new file `app/view/posts/show.html.erb` with the following content: ```html+erbTitle: <%= @post.title %>
Text: <%= @post.text %>
``` Finally, if you now go to| Title | Text |
|---|---|
| <%= post.title %> | <%= post.text %> |
| Title | Text | ||
|---|---|---|---|
| <%= post.title %> | <%= post.text %> | <%= link_to 'Show', :action => :show, :id => post.id %> | <%= link_to 'Edit', :action => :edit, :id => post.id %> |
<%= f.label :title %>
<%= f.text_field :title %>
<%= f.label :text %>
<%= f.text_area :text %>
<%= f.submit %>
<% end %> ``` Everything except for the `form_for` declaration remained the same. How `form_for` can figure out the right `action` and `method` attributes when building the form will be explained in just a moment. For now, let's update the `app/views/posts/new.html.erb` view to use this new partial, rewriting it completely: ```html+erb| Title | Text | |||
|---|---|---|---|---|
| <%= post.title %> | <%= post.text %> | <%= link_to 'Show', :action => :show, :id => post.id %> | <%= link_to 'Edit', :action => :edit, :id => post.id %> | <%= link_to 'Destroy', { :action => :destroy, :id => post.id }, :method => :delete, :data => { :confirm => 'Are you sure?' } %> |
Title: <%= @post.title %>
Text: <%= @post.text %>
<%= f.label :commenter %>
<%= f.text_field :commenter %>
<%= f.label :body %>
<%= f.text_area :body %>
<%= f.submit %>
<% end %> <%= link_to 'Edit Post', edit_post_path(@post) %> | <%= link_to 'Back to Posts', posts_path %> ``` This adds a form on the `Post` show page that creates a new comment by calling the `CommentsController` `create` action. The `form_for` call here uses an array, which will build a nested route, such as `/posts/1/comments`. Let's wire up the `create`: ```ruby class CommentsController < ApplicationController def create @post = Post.find(params[:post_id]) @comment = @post.comments.create(params[:comment]) redirect_to post_path(@post) end end ``` You'll see a bit more complexity here than you did in the controller for posts. That's a side-effect of the nesting that you've set up. Each request for a comment has to keep track of the post to which the comment is attached, thus the initial call to the `find` method of the `Post` model to get the post in question. In addition, the code takes advantage of some of the methods available for an association. We use the `create` method on `@post.comments` to create and save the comment. This will automatically link the comment so that it belongs to that particular post. Once we have made the new comment, we send the user back to the original post using the `post_path(@post)` helper. As we have already seen, this calls the `show` action of the `PostsController` which in turn renders the `show.html.erb` template. This is where we want the comment to show, so let's add that to the `app/views/posts/show.html.erb`. ```html+erbTitle: <%= @post.title %>
Text: <%= @post.text %>
Commenter: <%= comment.commenter %>
Comment: <%= comment.body %>
<% end %>
<%= f.label :commenter %>
<%= f.text_field :commenter %>
<%= f.label :body %>
<%= f.text_area :body %>
<%= f.submit %>
<% end %> <%= link_to 'Edit Post', edit_post_path(@post) %> | <%= link_to 'Back to Posts', posts_path %> ``` Now you can add posts and comments to your blog and have them show up in the right places.  Refactoring ----------- Now that we have posts and comments working, take a look at the `app/views/posts/show.html.erb` template. It is getting long and awkward. We can use partials to clean it up. ### Rendering Partial Collections First, we will make a comment partial to extract showing all the comments for the post. Create the file `app/views/comments/_comment.html.erb` and put the following into it: ```html+erbCommenter: <%= comment.commenter %>
Comment: <%= comment.body %>
``` Then you can change `app/views/posts/show.html.erb` to look like the following: ```html+erbTitle: <%= @post.title %>
Text: <%= @post.text %>
<%= f.label :commenter %>
<%= f.text_field :commenter %>
<%= f.label :body %>
<%= f.text_area :body %>
<%= f.submit %>
<% end %> <%= link_to 'Edit Post', edit_post_path(@post) %> | <%= link_to 'Back to Posts', posts_path %> ``` This will now render the partial in `app/views/comments/_comment.html.erb` once for each comment that is in the `@post.comments` collection. As the `render` method iterates over the `@post.comments` collection, it assigns each comment to a local variable named the same as the partial, in this case `comment` which is then available in the partial for us to show. ### Rendering a Partial Form Let us also move that new comment section out to its own partial. Again, you create a file `app/views/comments/_form.html.erb` containing: ```html+erb <%= form_for([@post, @post.comments.build]) do |f| %>
<%= f.label :commenter %>
<%= f.text_field :commenter %>
<%= f.label :body %>
<%= f.text_area :body %>
<%= f.submit %>
<% end %> ``` Then you make the `app/views/posts/show.html.erb` look like the following: ```html+erbTitle: <%= @post.title %>
Text: <%= @post.text %>
Commenter: <%= comment.commenter %>
Comment: <%= comment.body %>
<%= link_to 'Destroy Comment', [comment.post, comment], :method => :delete, :data => { :confirm => 'Are you sure?' } %>
``` Clicking this new "Destroy Comment" link will fire off a `DELETE /posts/:id/comments/:id` to our `CommentsController`, which can then use this to find the comment we want to delete, so let's add a destroy action to our controller: ```ruby class CommentsController < ApplicationController def create @post = Post.find(params[:post_id]) @comment = @post.comments.create(params[:comment]) redirect_to post_path(@post) end def destroy @post = Post.find(params[:post_id]) @comment = @post.comments.find(params[:id]) @comment.destroy redirect_to post_path(@post) end end ``` The `destroy` action will find the post we are looking at, locate the comment within the `@post.comments` collection, and then remove it from the database and send us back to the show action for the post. ### Deleting Associated Objects If you delete a post then its associated comments will also need to be deleted. Otherwise they would simply occupy space in the database. Rails allows you to use the `dependent` option of an association to achieve this. Modify the Post model, `app/models/post.rb`, as follows: ```ruby class Post < ActiveRecord::Base validates :title, :presence => true, :length => { :minimum => 5 } has_many :comments, :dependent => :destroy end ``` Security -------- If you were to publish your blog online, anybody would be able to add, edit and delete posts or delete comments. Rails provides a very simple HTTP authentication system that will work nicely in this situation. In the `PostsController` we need to have a way to block access to the various actions if the person is not authenticated, here we can use the Rails `http_basic_authenticate_with` method, allowing access to the requested action if that method allows it. To use the authentication system, we specify it at the top of our `PostsController`, in this case, we want the user to be authenticated on every action, except for `index` and `show`, so we write that: ```ruby class PostsController < ApplicationController http_basic_authenticate_with :name => "dhh", :password => "secret", :except => [:index, :show] def index @posts = Post.all end # snipped for brevity ``` We also only want to allow authenticated users to delete comments, so in the `CommentsController` we write: ```ruby class CommentsController < ApplicationController http_basic_authenticate_with :name => "dhh", :password => "secret", :only => :destroy def create @post = Post.find(params[:post_id]) ... end # snipped for brevity ``` Now if you try to create a new post, you will be greeted with a basic HTTP Authentication challenge  What's Next? ------------ Now that you've seen your first Rails application, you should feel free to update it and experiment on your own. But you don't have to do everything without help. As you need assistance getting up and running with Rails, feel free to consult these support resources: * The [Ruby on Rails guides](index.html) * The [Ruby on Rails Tutorial](http://railstutorial.org/book) * The [Ruby on Rails mailing list](http://groups.google.com/group/rubyonrails-talk) * The [#rubyonrails](irc://irc.freenode.net/#rubyonrails) channel on irc.freenode.net Rails also comes with built-in help that you can generate using the rake command-line utility: * Running `rake doc:guides` will put a full copy of the Rails Guides in the `doc/guides` folder of your application. Open `doc/guides/index.html` in your web browser to explore the Guides. * Running `rake doc:rails` will put a full copy of the API documentation for Rails in the `doc/api` folder of your application. Open `doc/api/index.html` in your web browser to explore the API documentation. Configuration Gotchas --------------------- The easiest way to work with Rails is to store all external data as UTF-8. If you don't, Ruby libraries and Rails will often be able to convert your native data into UTF-8, but this doesn't always work reliably, so you're better off ensuring that all external data is UTF-8. If you have made a mistake in this area, the most common symptom is a black diamond with a question mark inside appearing in the browser. Another common symptom is characters like "ü" appearing instead of "ü". Rails takes a number of internal steps to mitigate common causes of these problems that can be automatically detected and corrected. However, if you have external data that is not stored as UTF-8, it can occasionally result in these kinds of issues that cannot 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 saving files as UTF-8. If your text editor does not, this can result in special characters that you enter in your templates (such as é) to appear as a diamond with a question mark inside in the browser. This also applies to your I18N translation files. Most editors that do not already default to UTF-8 (such as some versions of Dreamweaver) offer a way to change the default to UTF-8. Do so. * Your database. Rails defaults to converting data from your database into UTF-8 at the boundary. However, if your database is not using UTF-8 internally, it may 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 enters the database. If possible, use UTF-8 as the internal storage of your database.