diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/action_mailer_basics.textile | 2 | ||||
| -rw-r--r-- | guides/source/action_view_overview.textile | 2 | ||||
| -rw-r--r-- | guides/source/active_record_querying.textile | 66 | ||||
| -rw-r--r-- | guides/source/active_support_core_extensions.textile | 75 | ||||
| -rw-r--r-- | guides/source/asset_pipeline.textile | 2 | ||||
| -rw-r--r-- | guides/source/caching_with_rails.textile | 2 | ||||
| -rw-r--r-- | guides/source/command_line.textile | 18 | ||||
| -rw-r--r-- | guides/source/configuring.textile | 36 | ||||
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.textile | 13 | ||||
| -rw-r--r-- | guides/source/getting_started.textile | 816 | ||||
| -rw-r--r-- | guides/source/index.html.erb | 2 | ||||
| -rw-r--r-- | guides/source/layouts_and_rendering.textile | 66 | ||||
| -rw-r--r-- | guides/source/routing.textile | 2 | ||||
| -rw-r--r-- | guides/source/security.textile | 3 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.textile | 4 |
15 files changed, 323 insertions, 786 deletions
diff --git a/guides/source/action_mailer_basics.textile b/guides/source/action_mailer_basics.textile index c277f764e7..ebe774fbef 100644 --- a/guides/source/action_mailer_basics.textile +++ b/guides/source/action_mailer_basics.textile @@ -4,7 +4,7 @@ This guide should provide you with all you need to get started in sending and re endprologue. -WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails. +WARNING. This Guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails. h3. Introduction diff --git a/guides/source/action_view_overview.textile b/guides/source/action_view_overview.textile index 6649974eea..fd1b6c5fc2 100644 --- a/guides/source/action_view_overview.textile +++ b/guides/source/action_view_overview.textile @@ -833,7 +833,7 @@ Reports the approximate distance in time between two Time or Date objects or int <ruby> distance_of_time_in_words(Time.now, Time.now + 15.seconds) # => less than a minute -distance_of_time_in_words(Time.now, Time.now + 15.seconds, true) # => less than 20 seconds +distance_of_time_in_words(Time.now, Time.now + 15.seconds, :include_seconds => true) # => less than 20 seconds </ruby> h5. select_date diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile index 902ceeb78b..a9cb424eaa 100644 --- a/guides/source/active_record_querying.textile +++ b/guides/source/active_record_querying.textile @@ -99,9 +99,28 @@ SELECT * FROM clients WHERE (clients.id = 10) LIMIT 1 <tt>Model.find(primary_key)</tt> will raise an +ActiveRecord::RecordNotFound+ exception if no matching record is found. +h5. +take+ + +<tt>Model.take</tt> retrieves a record without any implicit ordering. For example: + +<ruby> +client = Client.take +# => #<Client id: 1, first_name: "Lifo"> +</ruby> + +The SQL equivalent of the above is: + +<sql> +SELECT * FROM clients LIMIT 1 +</sql> + +<tt>Model.take</tt> returns +nil+ if no record is found and no exception will be raised. + +TIP: The retrieved record may vary depending on the database engine. + h5. +first+ -<tt>Model.first</tt> finds the first record matched by the supplied options, if any. For example: +<tt>Model.first</tt> finds the first record ordered by the primary key. For example: <ruby> client = Client.first @@ -111,14 +130,14 @@ client = Client.first The SQL equivalent of the above is: <sql> -SELECT * FROM clients LIMIT 1 +SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 </sql> -<tt>Model.first</tt> returns +nil+ if no matching record is found. No exception will be raised. +<tt>Model.first</tt> returns +nil+ if no matching record is found and no exception will be raised. h5. +last+ -<tt>Model.last</tt> finds the last record matched by the supplied options. For example: +<tt>Model.last</tt> finds the last record ordered by the primary key. For example: <ruby> client = Client.last @@ -131,7 +150,7 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 </sql> -<tt>Model.last</tt> returns +nil+ if no matching record is found. No exception will be raised. +<tt>Model.last</tt> returns +nil+ if no matching record is found and no exception will be raised. h5. +find_by+ @@ -148,12 +167,29 @@ Client.find_by first_name: 'Jon' It is equivalent to writing: <ruby> -Client.where(first_name: 'Lifo').first +Client.where(first_name: 'Lifo').take </ruby> +h5(#take_1). +take!+ + +<tt>Model.take!</tt> retrieves a record without any implicit ordering. For example: + +<ruby> +client = Client.take! +# => #<Client id: 1, first_name: "Lifo"> +</ruby> + +The SQL equivalent of the above is: + +<sql> +SELECT * FROM clients LIMIT 1 +</sql> + +<tt>Model.take!</tt> raises +ActiveRecord::RecordNotFound+ if no matching record is found. + h5(#first_1). +first!+ -<tt>Model.first!</tt> finds the first record. For example: +<tt>Model.first!</tt> finds the first record ordered by the primary key. For example: <ruby> client = Client.first! @@ -163,14 +199,14 @@ client = Client.first! The SQL equivalent of the above is: <sql> -SELECT * FROM clients LIMIT 1 +SELECT * FROM clients ORDER BY clients.id ASC LIMIT 1 </sql> -<tt>Model.first!</tt> raises +RecordNotFound+ if no matching record is found. +<tt>Model.first!</tt> raises +ActiveRecord::RecordNotFound+ if no matching record is found. h5(#last_1). +last!+ -<tt>Model.last!</tt> finds the last record. For example: +<tt>Model.last!</tt> finds the last record ordered by the primary key. For example: <ruby> client = Client.last! @@ -183,24 +219,24 @@ The SQL equivalent of the above is: SELECT * FROM clients ORDER BY clients.id DESC LIMIT 1 </sql> -<tt>Model.last!</tt> raises +RecordNotFound+ if no matching record is found. +<tt>Model.last!</tt> raises +ActiveRecord::RecordNotFound+ if no matching record is found. h5(#find_by_1). +find_by!+ -<tt>Model.find_by!</tt> finds the first record matching some conditions. It raises +RecordNotFound+ if no matching record is found. For example: +<tt>Model.find_by!</tt> finds the first record matching some conditions. It raises +ActiveRecord::RecordNotFound+ if no matching record is found. For example: <ruby> Client.find_by! first_name: 'Lifo' # => #<Client id: 1, first_name: "Lifo"> Client.find_by! first_name: 'Jon' -# => RecordNotFound +# => ActiveRecord::RecordNotFound </ruby> It is equivalent to writing: <ruby> -Client.where(first_name: 'Lifo').first! +Client.where(first_name: 'Lifo').take! </ruby> h4. Retrieving Multiple Objects @@ -910,7 +946,7 @@ This code looks fine at the first sight. But the problem lies within the total n Active Record lets you specify in advance all the associations that are going to be loaded. This is possible by specifying the +includes+ method of the +Model.find+ call. With +includes+, Active Record ensures that all of the specified associations are loaded using the minimum possible number of queries. -Revisiting the above case, we could rewrite +Client.all+ to use eager load addresses: +Revisiting the above case, we could rewrite +Client.limit(10)+ to use eager load addresses: <ruby> clients = Client.includes(:address).limit(10) diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile index 52c1cea4b9..b995d53806 100644 --- a/guides/source/active_support_core_extensions.textile +++ b/guides/source/active_support_core_extensions.textile @@ -154,6 +154,51 @@ WARNING. Any class can disallow duplication removing +dup+ and +clone+ or raisin NOTE: Defined in +active_support/core_ext/object/duplicable.rb+. +h4. +deep_dup+ + +The +deep_dup+ method returns deep copy of given object. Normally, when you +dup+ an object that contains other objects, ruby does not +dup+ them. If you have array with a string, for example, it will look like this: + +<ruby> +array = ['string'] +duplicate = array.dup + +duplicate.push 'another-string' + +# object was duplicated, element added only to duplicate +array #=> ['string'] +duplicate #=> ['string', 'another-string'] + +duplicate.first.gsub!('string', 'foo') + +# first element was not duplicated, it will be changed for both arrays +array #=> ['foo'] +duplicate #=> ['foo', 'another-string'] +</ruby> + +As you can see, after duplicating +Array+ instance, we got another object, therefore we can modify it and the original object will stay unchanged. This is not true for array's elements, however. Since +dup+ does not make deep copy, the string inside array is still the same object. + +If you need a deep copy of an object, you should use +deep_dup+ in such situation: + +<ruby> +array = ['string'] +duplicate = array.deep_dup + +duplicate.first.gsub!('string', 'foo') + +array #=> ['string'] +duplicate #=> ['foo'] +</ruby> + +If object is not duplicable +deep_dup+ will just return this object: + +<ruby> +number = 1 +dup = number.deep_dup +number.object_id == dup.object_id # => true +</ruby> + +NOTE: Defined in +active_support/core_ext/object/deep_dup.rb+. + h4. +try+ Sometimes you want to call a method provided the receiver object is not +nil+, which is something you usually check first. +try+ is like +Object#send+ except that it returns +nil+ if sent to +nil+. @@ -2216,6 +2261,19 @@ Thus, in this case the behavior is different for +nil+, and the differences with NOTE: Defined in +active_support/core_ext/array/wrap.rb+. +h4. Duplicating + +The method +Array.deep_dup+ duplicates itself and all objects inside recursively with ActiveSupport method +Object#deep_dup+. It works like +Array#map+ with sending +deep_dup+ method to each object inside. + +<ruby> +array = [1, [2, 3]] +dup = array.deep_dup +dup[1][2] = 4 +array[1][2] == nil # => true +</ruby> + +NOTE: Defined in +active_support/core_ext/array/deep_dup.rb+. + h4. Grouping h5. +in_groups_of(number, fill_with = nil)+ @@ -2422,6 +2480,23 @@ The method +deep_merge!+ performs a deep merge in place. NOTE: Defined in +active_support/core_ext/hash/deep_merge.rb+. +h4. Deep duplicating + +The method +Hash.deep_dup+ duplicates itself and all keys and values inside recursively with ActiveSupport method +Object#deep_dup+. It works like +Enumerator#each_with_object+ with sending +deep_dup+ method to each pair inside. + +<ruby> +hash = { :a => 1, :b => { :c => 2, :d => [3, 4] } } + +dup = hash.deep_dup +dup[:b][:e] = 5 +dup[:b][:d] << 5 + +hash[:b][:e] == nil # => true +hash[:b][:d] == [3, 4] # => true +</ruby> + +NOTE: Defined in +active_support/core_ext/hash/deep_dup.rb+. + h4. Diffing The method +diff+ returns a hash that represents a diff of the receiver and the argument with the following logic: diff --git a/guides/source/asset_pipeline.textile b/guides/source/asset_pipeline.textile index d79eb01ab2..010154f1d1 100644 --- a/guides/source/asset_pipeline.textile +++ b/guides/source/asset_pipeline.textile @@ -204,6 +204,8 @@ Images can also be organized into subdirectories if required, and they can be ac <%= image_tag "icons/rails.png" %> </erb> +WARNING: If you're precompiling your assets (see "In Production":#in-production below), linking to an asset that does not exist will raise an exception in the calling page. This includes linking to a blank string. As such, be careful using <tt>image_tag</tt> and the other helpers with user-supplied data. + h5. CSS and ERB The asset pipeline automatically evaluates ERB. This means that if you add an +erb+ extension to a CSS asset (for example, +application.css.erb+), then helpers like +asset_path+ are available in your CSS rules: diff --git a/guides/source/caching_with_rails.textile b/guides/source/caching_with_rails.textile index 12bc32f4e1..e455b504ce 100644 --- a/guides/source/caching_with_rails.textile +++ b/guides/source/caching_with_rails.textile @@ -157,7 +157,7 @@ and you can expire it using the +expire_fragment+ method, like so: expire_fragment(:controller => 'products', :action => 'recent', :action_suffix => 'all_products') </ruby> -If you don't want the cache block to bind to the action that called it, You can also use globally keyed fragments by calling the +cache+ method with a key, like so: +If you don't want the cache block to bind to the action that called it, you can also use globally keyed fragments by calling the +cache+ method with a key: <ruby> <% cache('all_available_products') do %> diff --git a/guides/source/command_line.textile b/guides/source/command_line.textile index 858ce47db1..b656a0857a 100644 --- a/guides/source/command_line.textile +++ b/guides/source/command_line.textile @@ -12,7 +12,7 @@ endprologue. NOTE: This tutorial assumes you have basic Rails knowledge from reading the "Getting Started with Rails Guide":getting_started.html. -WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails. +WARNING. This Guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails. h3. Command Line Basics @@ -31,7 +31,7 @@ h4. +rails new+ The first thing we'll want to do is create a new Rails application by running the +rails new+ command after installing Rails. -WARNING: You can install the rails gem by typing +gem install rails+, if you don't have it already. Follow the instructions in the "Rails 3 Release Notes":/3_0_release_notes.html +TIP: You can install the rails gem by typing +gem install rails+, if you don't have it already. <shell> $ rails new commandsapp @@ -185,8 +185,6 @@ $ rails server => Booting WEBrick... </shell> -WARNING: Make sure that you do not have any "tilde backup" files in +app/views/(controller)+, or else WEBrick will _not_ show the expected output. This seems to be a *bug* in Rails 2.3.0. - The URL will be "http://localhost:3000/greetings/hello":http://localhost:3000/greetings/hello. INFO: With a normal, plain-old Rails application, your URLs will generally follow the pattern of http://(host)/(controller)/(action), and a URL like http://(host)/(controller) will hit the *index* action of that controller. @@ -446,6 +444,18 @@ app/model/post.rb: NOTE. When using specific annotations and custom annotations, the annotation name (FIXME, BUG etc) is not displayed in the output lines. +By default, +rake notes+ will look in the +app+, +config+, +lib+, +script+ and +test+ directories. If you would like to search other directories, you can provide them as a comma separated list in an environment variable +SOURCE_ANNOTATION_DIRECTORIES+. + +<shell> +$ export SOURCE_ANNOTATION_DIRECTORIES='rspec,vendor' +$ rake notes +(in /home/foobar/commandsapp) +app/model/user.rb: + * [ 35] [FIXME] User should have a subscription at this point +rspec/model/user_spec.rb: + * [122] [TODO] Verify the user that has a subscription works +</shell> + h4. +routes+ +rake routes+ will list all of your defined routes, which is useful for tracking down routing problems in your app, or giving you a good overview of the URLs in an app you're trying to get familiar with. diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile index 68426221bf..5629c82ca0 100644 --- a/guides/source/configuring.textile +++ b/guides/source/configuring.textile @@ -70,12 +70,23 @@ NOTE. The +config.asset_path+ configuration is ignored if the asset pipeline is * +config.action_view.cache_template_loading+ controls whether or not templates should be reloaded on each request. Defaults to whatever is set for +config.cache_classes+. -* +config.cache_store+ configures which cache store to use for Rails caching. Options include one of the symbols +:memory_store+, +:file_store+, +:mem_cache_store+, or an object that implements the cache API. Defaults to +:file_store+ if the directory +tmp/cache+ exists, and to +:memory_store+ otherwise. +* +config.cache_store+ configures which cache store to use for Rails caching. Options include one of the symbols +:memory_store+, +:file_store+, +:mem_cache_store+, +:null_store+, or an object that implements the cache API. Defaults to +:file_store+ if the directory +tmp/cache+ exists, and to +:memory_store+ otherwise. * +config.colorize_logging+ specifies whether or not to use ANSI color codes when logging information. Defaults to true. * +config.consider_all_requests_local+ is a flag. If true then any error will cause detailed debugging information to be dumped in the HTTP response, and the +Rails::Info+ controller will show the application runtime context in +/rails/info/properties+. True by default in development and test environments, and false in production mode. For finer-grained control, set this to false and implement +local_request?+ in controllers to specify which requests should provide debugging information on errors. +* +config.console+ allows you to set class that will be used as console you run +rails console+. It's best to run it in +console+ block: + +<ruby> +console do + # this block is called only when running console, + # so we can safely require pry here + require "pry" + config.console = Pry +end +</ruby> + * +config.dependency_loading+ is a flag that allows you to disable constant autoloading setting it to false. It only has effect if +config.cache_classes+ is true, which it is by default in production mode. This flag is set to false by +config.threadsafe!+. * +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application. @@ -100,6 +111,10 @@ NOTE. The +config.asset_path+ configuration is ignored if the asset pipeline is * +config.preload_frameworks+ enables or disables preloading all frameworks at startup. Enabled by +config.threadsafe!+. Defaults to +nil+, so is disabled. +* +config.queue+ configures a different queue implementation for the application. Defaults to +Rails::Queueing::Queue+. Note that, if the default queue is changed, the default +queue_consumer+ is not going to be initialized, it is up to the new queue implementation to handle starting and shutting down its own consumer(s). + +* +config.queue_consumer+ configures a different consumer implementation for the default queue. Defaults to +Rails::Queueing::ThreadedConsumer+. + * +config.reload_classes_only_on_change+ enables or disables reloading of classes only when tracked files change. By default tracks everything on autoload paths and is set to true. If +config.cache_classes+ is true, this option is ignored. * +config.secret_token+ used for specifying a key which allows sessions for the application to be verified against a known secure key to prevent tampering. Applications get +config.secret_token+ initialized to a random key in +config/initializers/secret_token.rb+. @@ -122,17 +137,6 @@ WARNING: Threadsafe operation is incompatible with the normal workings of develo * +config.whiny_nils+ enables or disables warnings when a certain set of methods are invoked on +nil+ and it does not respond to them. Defaults to true in development and test environments. -* +config.console+ allows you to set class that will be used as console you run +rails console+. It's best to run it in +console+ block: - -<ruby> -console do - # this block is called only when running console, - # so we can safely require pry here - require "pry" - config.console = Pry -end -</ruby> - h4. Configuring Assets Rails 3.1, by default, is set up to use the +sprockets+ gem to manage assets within an application. This gem concatenates and compresses assets in order to make serving them much less painful. @@ -248,14 +252,6 @@ They can also be removed from the stack completely: config.middleware.delete ActionDispatch::BestStandardsSupport </ruby> -In addition to these methods to handle the stack, if your application is going to be used as an API endpoint only, the middleware stack can be configured like this: - -<ruby> -config.middleware.http_only! -</ruby> - -By doing this, Rails will create a smaller middleware stack, by not adding some middlewares that are usually useful for browser access only, such as Cookies, Session and Flash, BestStandardsSupport, and MethodOverride. You can always add any of them later manually if you want. Refer to the "API App docs":api_app.html for more info on how to setup your application for API only apps. - h4. Configuring i18n * +config.i18n.default_locale+ sets the default locale of an application used for i18n. Defaults to +:en+. diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile index fbb3483dae..df475a2359 100644 --- a/guides/source/contributing_to_ruby_on_rails.textile +++ b/guides/source/contributing_to_ruby_on_rails.textile @@ -105,6 +105,13 @@ $ cd railties $ TEST_DIR=generators bundle exec rake test </shell> +You can run any single test separately too: + +<shell> +$ cd actionpack +$ ruby -Itest test/template/form_helper_test.rb +</shell> + h4. Warnings The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. @@ -201,6 +208,12 @@ $ bundle exec rake test will now run the four of them in turn. +You can also run any single test separately: + +<shell> +$ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test.rb +</shell> + You can invoke +test_jdbcmysql+, +test_jdbcsqlite3+ or +test_jdbcpostgresql+ also. See the file +activerecord/RUNNING_UNIT_TESTS+ for information on running more targeted database tests, or the file +ci/travis.rb+ for the test suite run by the continuous integration server. h4. Older Versions of Ruby on Rails diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile index b48ebbceb2..947abd7ba0 100644 --- a/guides/source/getting_started.textile +++ b/guides/source/getting_started.textile @@ -72,7 +72,8 @@ step needed to make this example application has been left out, so you can literally follow along step by step. You can get the complete code "here":https://github.com/lifo/docrails/tree/master/guides/code/getting_started. -By following along with this guide, you'll create a Rails project called <tt>blog</tt>, a +By following along with this guide, you'll create a Rails project called ++blog+, a (very) simple weblog. Before you can start building the application, you need to make sure that you have Rails itself installed. @@ -86,7 +87,10 @@ To install Rails, use the +gem install+ command provided by RubyGems: # gem install rails </shell> -TIP. If you're working on Windows, you can quickly install Ruby and Rails with "Rails Installer":http://railsinstaller.org. +TIP. A number of tools exist to help you quickly install Ruby and Ruby +on Rails on your system. Windows users can use "Rails +Installer":http://railsinstaller.org, while Mac OS X users can use +"Rails One Click":http://railsoneclick.com. To verify that you have everything installed correctly, you should be able to run the following: @@ -108,7 +112,8 @@ $ rails new blog This will create a Rails application called Blog in a directory called blog. -TIP: You can see all of the command line options that the Rails application builder accepts by running <tt>rails new -h</tt>. +TIP: You can see all of the command line options that the Rails +application builder accepts by running +rails new -h+. After you create the blog application, switch to its folder to continue work directly in that application: @@ -116,7 +121,10 @@ After you create the blog application, switch to its folder to continue work dir $ cd blog </shell> -The +rails new blog+ command we ran above created a folder in your working directory called <tt>blog</tt>. The <tt>blog</tt> directory has a number of auto-generated files and folders that make up the structure of a Rails application. Most of the work in this tutorial will happen in the <tt>app/</tt> folder, but here's a basic rundown on the function of each of the files and folders that Rails created by default: +The +rails new blog+ command we ran above created a folder in your +working directory called +blog+. The +blog+ directory has a number of +auto-generated files and folders that make up the structure of a Rails +application. Most of the work in this tutorial will happen in the +app/+ folder, but here's a basic rundown on the function of each of the files and folders that Rails created by default: |_.File/Folder|_.Purpose| |app/|Contains the controllers, models, views, helpers, mailers and assets for your application. You'll focus on this folder for the remainder of this guide.| @@ -385,11 +393,10 @@ This action is now displaying the parameters for the post that are coming in fro h4. Creating the Post model -Rails uses models to manage database objects, so if you want to save -data to the database you'll have to create a model. In our blog -application you want to save posts, so you'll create a +Post+ model. - -You can create a model with the following command: +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: <shell> $ rails generate model Post title:string text:text @@ -397,7 +404,10 @@ $ rails generate model Post title:string text:text With that command we told Rails that we want a +Post+ model, which in turn should have a title attribute of type string, and a text attribute -of type text. Rails in turn responded by creating a bunch of files. For +of type text. Those attributes are automatically added to the +posts+ +table in the database and mapped to the +Post+ model. + +Rails in turn 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+. The latter is responsible for creating the database structure, which is what we'll look at next. @@ -457,7 +467,7 @@ 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: <tt>rake db:migrate RAILS_ENV=production</tt>. +invoking the command: +rake db:migrate RAILS_ENV=production+. h4. Saving data in the controller @@ -1095,424 +1105,65 @@ posts. In the next section will see how Rails can aid us when creating REST applications, and how we can refactor our Blog app to take advantage of it. -h4. Using the Console - -To see your validations in action, you can use the console. The console is a -command-line tool that lets you execute Ruby code in the context of your -application: - -<shell> -$ rails console -</shell> - -TIP: The default console will make changes to your database. You can instead -open a console that will roll back any changes you make by using <tt>rails console ---sandbox</tt>. - -After the console loads, you can use it to work with your application's models: - -<shell> ->> p = Post.new(:content => "A new post") -=> #<Post id: nil, name: nil, title: nil, - content: "A new post", created_at: nil, - updated_at: nil> ->> p.save -=> false ->> p.errors.full_messages -=> ["Name can't be blank", "Title can't be blank", "Title is too short (minimum is 5 characters)"] -</shell> +h4. Going Deeper into REST -This code shows creating a new +Post+ instance, attempting to save it and -getting +false+ for a return value (indicating that the save failed), and -inspecting the +errors+ of the post. - -When you're finished, type +exit+ and hit +return+ to exit the console. - -TIP: Unlike the development web server, the console does not automatically load -your code afresh for each line. If you make changes to your models (in your editor) -while the console is open, type +reload!+ at the console prompt to load them. - -h4. Listing All Posts - -Let's dive into the Rails code a little deeper to see how the application is -showing us the list of Posts. Open the file -+app/controllers/posts_controller.rb+ and look at the -+index+ action: +We've now covered all the CRUD actions of a REST app. We did so by +declaring separate routes with the appropriate verbs into ++config/routes.rb+. Here's how that file looks so far: <ruby> -def index - @posts = Post.all - - respond_to do |format| - format.html # index.html.erb - format.json { render :json => @posts } - end -end -</ruby> - -+Post.all+ returns all of the posts currently in the database as an array -of +Post+ records that we store in an instance variable called +@posts+. - -TIP: For more information on finding records with Active Record, see "Active -Record Query Interface":active_record_querying.html. - -The +respond_to+ block handles both HTML and JSON calls to this action. If you -browse to "http://localhost:3000/posts.json":http://localhost:3000/posts.json, -you'll see a JSON containing all of the posts. The HTML format looks for a view -in +app/views/posts/+ with a name that corresponds to the action name. Rails -makes all of the instance variables from the action available to the view. -Here's +app/views/posts/index.html.erb+: - -<erb> -<h1>Listing posts</h1> - -<table> - <tr> - <th>Name</th> - <th>Title</th> - <th>Content</th> - <th></th> - <th></th> - <th></th> - </tr> - -<% @posts.each do |post| %> - <tr> - <td><%= post.name %></td> - <td><%= post.title %></td> - <td><%= post.content %></td> - <td><%= link_to 'Show', post %></td> - <td><%= link_to 'Edit', edit_post_path(post) %></td> - <td><%= link_to 'Destroy', post, :confirm => 'Are you sure?', - :method => :delete %></td> - </tr> -<% end %> -</table> - -<br /> - -<%= link_to 'New post', new_post_path %> -</erb> - -This view iterates over the contents of the +@posts+ array to display content -and links. A few things to note in the view: - -* +link_to+ builds a hyperlink to a particular destination -* +edit_post_path+ and +new_post_path+ are helpers that Rails provides as part of RESTful routing. You'll see a variety of these helpers for the different actions that the controller includes. - -NOTE. In previous versions of Rails, you had to use +<%=h post.name %>+ so -that any HTML would be escaped before being inserted into the page. In Rails -3 and above, this is now the default. To get unescaped HTML, you now use <tt><%= raw post.name %></tt>. - -TIP: For more details on the rendering process, see "Layouts and Rendering in -Rails":layouts_and_rendering.html. - -h4. Customizing the Layout - -The view is only part of the story of how HTML is displayed in your web browser. -Rails also has the concept of +layouts+, which are containers for views. When -Rails renders a view to the browser, it does so by putting the view's HTML into -a layout's HTML. In previous versions of Rails, the +rails generate scaffold+ -command would automatically create a controller specific layout, like -+app/views/layouts/posts.html.erb+, for the posts controller. However this has -been changed in Rails 3. An application specific +layout+ is used for all the -controllers and can be found in +app/views/layouts/application.html.erb+. Open -this layout in your editor and modify the +body+ tag to include the style directive -below: - -<erb> -<!DOCTYPE html> -<html> -<head> - <title>Blog</title> - <%= stylesheet_link_tag "application" %> - <%= javascript_include_tag "application" %> - <%= csrf_meta_tags %> -</head> -<body style="background-color: #EEEEEE;"> - -<%= yield %> - -</body> -</html> -</erb> - -Now when you refresh the +/posts+ page, you'll see a gray background to the -page. This same gray background will be used throughout all the views. - -h4. Creating New Posts - -Creating a new post involves two actions. The first is the +new+ action, which -instantiates an empty +Post+ object: - -<ruby> -def new - @post = Post.new - - respond_to do |format| - format.html # new.html.erb - format.json { render :json => @post } - end -end -</ruby> - -The +new.html.erb+ view displays this empty Post to the user: - -<erb> -<h1>New post</h1> - -<%= render 'form' %> - -<%= link_to 'Back', posts_path %> -</erb> - -The +<%= render 'form' %>+ line is our first introduction to _partials_ in -Rails. A partial is a snippet of HTML and Ruby code that can be reused in -multiple locations. In this case, the form used to make a new post is basically -identical to the form used to edit a post, both having text fields for the name and -title, a text area for the content, and a button to create the new post or to update -the existing one. - -If you take a look at +views/posts/_form.html.erb+ file, you will see the -following: - -<erb> -<%= form_for(@post) do |f| %> - <% if @post.errors.any? %> - <div id="errorExplanation"> - <h2><%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:</h2> - <ul> - <% @post.errors.full_messages.each do |msg| %> - <li><%= msg %></li> - <% end %> - </ul> - </div> - <% end %> - - <div class="field"> - <%= f.label :name %><br /> - <%= f.text_field :name %> - </div> - <div class="field"> - <%= f.label :title %><br /> - <%= f.text_field :title %> - </div> - <div class="field"> - <%= f.label :content %><br /> - <%= f.text_area :content %> - </div> - <div class="actions"> - <%= f.submit %> - </div> -<% end %> -</erb> - -This partial receives all the instance variables defined in the calling view -file. In this case, the controller assigned the new +Post+ object to +@post+, -which will thus be available in both the view and the partial as +@post+. - -For more information on partials, refer to the "Layouts and Rendering in -Rails":layouts_and_rendering.html#using-partials guide. - -The +form_for+ block is used to create an HTML form. Within this block, you have -access to methods to build various controls on the form. For example, -+f.text_field :name+ tells Rails to create a text input on the form and to hook -it up to the +name+ attribute of the instance being displayed. You can only use -these methods with attributes of the model that the form is based on (in this -case +name+, +title+, and +content+). Rails uses +form_for+ in preference to -having you write raw HTML because the code is more succinct, and because it -explicitly ties the form to a particular model instance. - -The +form_for+ block is also smart enough to work out if you are doing a _New -Post_ or an _Edit Post_ action, and will set the form +action+ tags and submit -button names appropriately in the HTML output. - -TIP: If you need to create an HTML form that displays arbitrary fields, not tied -to a model, you should use the +form_tag+ method, which provides shortcuts for -building forms that are not necessarily tied to a model instance. - -When the user clicks the +Create Post+ button on this form, the browser will -send information back to the +create+ action of the controller (Rails knows to -call the +create+ action because the form is sent with an HTTP POST request; -that's one of the conventions that were mentioned earlier): - -<ruby> -def create - @post = Post.new(params[:post]) - - respond_to do |format| - if @post.save - format.html { redirect_to(@post, - :notice => 'Post was successfully created.') } - format.json { render :json => @post, - :status => :created, :location => @post } - else - format.html { render :action => "new" } - format.json { render :json => @post.errors, - :status => :unprocessable_entity } - end - end -end -</ruby> - -The +create+ action instantiates a new Post object from the data supplied by the -user on the form, which Rails makes available in the +params+ hash. After -successfully saving the new post, +create+ returns the appropriate format that -the user has requested (HTML in our case). It then redirects the user to the -resulting post +show+ action and sets a notice to the user that the Post was -successfully created. - -If the post was not successfully saved, due to a validation error, then the -controller returns the user back to the +new+ action with any error messages so -that the user has the chance to fix the error and try again. - -The "Post was successfully created." message is stored in the Rails -+flash+ hash (usually just called _the flash_), so that messages can be carried -over to another action, providing the user with useful information on the status -of their request. In the case of +create+, the user never actually sees any page -rendered during the post creation process, because it immediately redirects to -the new +Post+ as soon as Rails saves the record. The Flash carries over a message to -the next action, so that when the user is redirected back to the +show+ action, -they are presented with a message saying "Post was successfully created." - -h4. Showing an Individual Post - -When you click the +show+ link for a post on the index page, it will bring you -to a URL like +http://localhost:3000/posts/1+. Rails interprets this as a call -to the +show+ action for the resource, and passes in +1+ as the +:id+ parameter. -Here's the +show+ action: - -<ruby> -def show - @post = Post.find(params[:id]) - - respond_to do |format| - format.html # show.html.erb - format.json { render :json => @post } - end -end +get "posts" => "posts#index" +get "posts/new" +post "posts/create" +get "posts/:id" => "posts#show", :as => :post +get "posts/:id/edit" => "posts#edit" +put "posts/:id" => "posts#update" +delete "posts/:id" => "posts#destroy" </ruby> -The +show+ action uses +Post.find+ to search for a single record in the database -by its id value. After finding the record, Rails displays it by using -+app/views/posts/show.html.erb+: - -<erb> -<p id="notice"><%= notice %></p> - -<p> - <b>Name:</b> - <%= @post.name %> -</p> - -<p> - <b>Title:</b> - <%= @post.title %> -</p> - -<p> - <b>Content:</b> - <%= @post.content %> -</p> - - -<%= link_to 'Edit', edit_post_path(@post) %> | -<%= link_to 'Back', posts_path %> -</erb> - -h4. Editing Posts - -Like creating a new post, editing a post is a two-part process. The first step -is a request to +edit_post_path(@post)+ with a particular post. This calls the -+edit+ action in the controller: +That's a lot to type for covering a single *resource*. Fortunately, +Rails provides a +resources+ method which can be used to declare a +standard REST resource. Here's how +config/routes/rb+ looks after the +cleanup: <ruby> -def edit - @post = Post.find(params[:id]) -end -</ruby> - -After finding the requested post, Rails uses the +edit.html.erb+ view to display -it: - -<erb> -<h1>Editing post</h1> - -<%= render 'form' %> - -<%= link_to 'Show', @post %> | -<%= link_to 'Back', posts_path %> -</erb> - -Again, as with the +new+ action, the +edit+ action is using the +form+ partial. -This time, however, the form will do a PUT action to the +PostsController+ and the -submit button will display "Update Post". - -Submitting the form created by this view will invoke the +update+ action within -the controller: +Blog::Application.routes.draw do -<ruby> -def update - @post = Post.find(params[:id]) + resources :posts - respond_to do |format| - if @post.update_attributes(params[:post]) - format.html { redirect_to(@post, - :notice => 'Post was successfully updated.') } - format.json { head :no_content } - else - format.html { render :action => "edit" } - format.json { render :json => @post.errors, - :status => :unprocessable_entity } - end - end + root :to => "welcome#index" end </ruby> -In the +update+ action, Rails first uses the +:id+ parameter passed back from -the edit view to locate the database record that's being edited. The -+update_attributes+ call then takes the +post+ parameter (a hash) from the request -and applies it to this record. If all goes well, the user is redirected to the -post's +show+ action. If there are any problems, it redirects back to the +edit+ action to -correct them. - -h4. Destroying a Post - -Finally, clicking one of the +destroy+ links sends the associated id to the -+destroy+ action: - -<ruby> -def destroy - @post = Post.find(params[:id]) - @post.destroy +If you run +rake routes+, you'll see that all the routes that we +declared before are still available, and the app still works as before. - respond_to do |format| - format.html { redirect_to posts_url } - format.json { head :no_content } - end -end -</ruby> +<shell> +# rake routes + posts GET /posts(.:format) posts#index + POST /posts(.:format) posts#create + new_post GET /posts/new(.:format) posts#new +edit_post GET /posts/:id/edit(.:format) posts#edit + post GET /posts/:id(.:format) posts#show + PUT /posts/:id(.:format) posts#update + DELETE /posts/:id(.:format) posts#destroy + root / welcome#index +</shell> -The +destroy+ method of an Active Record model instance removes the -corresponding record from the database. After that's done, there isn't any -record to display, so Rails redirects the user's browser to the index action of -the controller. +TIP: In general, Rails encourages the use of resources objects in place +of declaring routes manually. For more information about routing, see +"Rails Routing from the Outside In":routing.html. h3. Adding a Second Model -Now that you've seen what a model built with scaffolding looks like, it's time to -add a second model to the application. The second model will handle comments on +It's time to add a second model to the application. The second model will handle comments on blog posts. h4. Generating a Model -Models in Rails use a singular name, and their corresponding database tables use -a plural name. For the model to hold comments, the convention is to use the name -+Comment+. Even if you don't want to use the entire apparatus set up by -scaffolding, most Rails developers still use generators to make things like -models and controllers. To create the new model, run this command in your -terminal: +We're going to se the same generator that we used before when creating +the +Post+ model. This time we'll create a +Comment+ model to hold +reference of post comments. Run this command in your terminal: <shell> $ rails generate model Comment commenter:string body:text post:references @@ -1600,7 +1251,6 @@ You'll need to edit the +post.rb+ file to add the other side of the association: <ruby> class Post < ActiveRecord::Base - validates :name, :presence => true validates :title, :presence => true, :length => { :minimum => 5 } @@ -1619,9 +1269,7 @@ h4. Adding a Route for Comments As with the +welcome+ controller, we will need to add a route so that Rails knows where we would like to navigate to see +comments+. Open up the -+config/routes.rb+ file again. Near the top, you will see the entry for +posts+ -that was added automatically by the scaffold generator: <tt>resources -:posts</tt>. Edit it as follows: ++config/routes.rb+ file again, and edit it as follows: <ruby> resources :posts do @@ -1639,7 +1287,7 @@ In":routing.html guide. h4. Generating a Controller With the model in hand, you can turn your attention to creating a matching -controller. Again, there's a generator for this: +controller. Again, we'll use the same generator we used before: <shell> $ rails generate controller Comments @@ -1666,40 +1314,33 @@ So first, we'll wire up the Post show template (+/app/views/posts/show.html.erb+) to let us make a new comment: <erb> -<p id="notice"><%= notice %></p> - -<p> - <b>Name:</b> - <%= @post.name %> -</p> - <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> - <%= @post.content %> + <strong>Text:</strong> + <%= @post.texthttp://beginningruby.org/ %> </p> <h2>Add a comment:</h2> <%= form_for([@post, @post.comments.build]) do |f| %> - <div class="field"> + <p> <%= f.label :commenter %><br /> <%= f.text_field :commenter %> - </div> - <div class="field"> + </p> + <p> <%= f.label :body %><br /> <%= f.text_area :body %> - </div> - <div class="actions"> + </p> + <p> <%= f.submit %> - </div> + </p> <% end %> <%= link_to 'Edit Post', edit_post_path(@post) %> | -<%= link_to 'Back to Posts', posts_path %> | +<%= link_to 'Back to Posts', posts_path %> </erb> This adds a form on the +Post+ show page that creates a new comment by @@ -1732,60 +1373,53 @@ template. This is where we want the comment to show, so let's add that to the +app/views/posts/show.html.erb+. <erb> -<p id="notice"><%= notice %></p> - <p> - <b>Name:</b> - <%= @post.name %> -</p> - -<p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> - <%= @post.content %> + <strong>Text:</strong> + <%= @post.texthttp://beginningruby.org/ %> </p> <h2>Comments</h2> <% @post.comments.each do |comment| %> <p> - <b>Commenter:</b> + <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> - <b>Comment:</b> + <strong>Comment:</strong> <%= comment.body %> </p> <% end %> <h2>Add a comment:</h2> <%= form_for([@post, @post.comments.build]) do |f| %> - <div class="field"> + <p> <%= f.label :commenter %><br /> <%= f.text_field :commenter %> - </div> - <div class="field"> + </p> + <p> <%= f.label :body %><br /> <%= f.text_area :body %> - </div> - <div class="actions"> + </p> + <p> <%= f.submit %> - </div> + </p> <% end %> -<br /> - <%= link_to 'Edit Post', edit_post_path(@post) %> | -<%= link_to 'Back to Posts', posts_path %> | +<%= link_to 'Back to Posts', posts_path %> </erb> Now you can add posts and comments to your blog and have them show up in the right places. +!images/getting_started/post_with_comments.png(Post with Comments)! + h3. Refactoring Now that we have posts and comments working, take a look at the @@ -1800,12 +1434,12 @@ following into it: <erb> <p> - <b>Commenter:</b> + <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> - <b>Comment:</b> + <strong>Comment:</strong> <%= comment.body %> </p> </erb> @@ -1814,21 +1448,14 @@ Then you can change +app/views/posts/show.html.erb+ to look like the following: <erb> -<p id="notice"><%= notice %></p> - <p> - <b>Name:</b> - <%= @post.name %> -</p> - -<p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> - <%= @post.content %> + <strong>Text:</strong> + <%= @post.texthttp://beginningruby.org/ %> </p> <h2>Comments</h2> @@ -1836,23 +1463,21 @@ following: <h2>Add a comment:</h2> <%= form_for([@post, @post.comments.build]) do |f| %> - <div class="field"> + <p> <%= f.label :commenter %><br /> <%= f.text_field :commenter %> - </div> - <div class="field"> + </p> + <p> <%= f.label :body %><br /> <%= f.text_area :body %> - </div> - <div class="actions"> + </p> + <p> <%= f.submit %> - </div> + </p> <% end %> -<br /> - <%= link_to 'Edit Post', edit_post_path(@post) %> | -<%= link_to 'Back to Posts', posts_path %> | +<%= link_to 'Back to Posts', posts_path %> </erb> This will now render the partial in +app/views/comments/_comment.html.erb+ once @@ -1868,50 +1493,38 @@ create a file +app/views/comments/_form.html.erb+ containing: <erb> <%= form_for([@post, @post.comments.build]) do |f| %> - <div class="field"> + <p> <%= f.label :commenter %><br /> <%= f.text_field :commenter %> - </div> - <div class="field"> + </p> + <p> <%= f.label :body %><br /> <%= f.text_area :body %> - </div> - <div class="actions"> + </p> + <p> <%= f.submit %> - </div> + </p> <% end %> </erb> Then you make the +app/views/posts/show.html.erb+ look like the following: <erb> -<p id="notice"><%= notice %></p> - <p> - <b>Name:</b> - <%= @post.name %> -</p> - -<p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> - <%= @post.content %> + <strong>Text:</strong> + <%= @post.texthttp://beginningruby.org/ %> </p> -<h2>Comments</h2> -<%= render @post.comments %> - <h2>Add a comment:</h2> <%= render "comments/form" %> -<br /> - <%= link_to 'Edit Post', edit_post_path(@post) %> | -<%= link_to 'Back to Posts', posts_path %> | +<%= link_to 'Back to Posts', posts_path %> </erb> The second render just defines the partial template we want to render, @@ -1933,12 +1546,12 @@ So first, let's add the delete link in the <erb> <p> - <b>Commenter:</b> + <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> - <b>Comment:</b> + <strong>Comment:</strong> <%= comment.body %> </p> @@ -1987,7 +1600,6 @@ model, +app/models/post.rb+, as follows: <ruby> class Post < ActiveRecord::Base - validates :name, :presence => true validates :title, :presence => true, :length => { :minimum => 5 } has_many :comments, :dependent => :destroy @@ -2016,11 +1628,8 @@ class PostsController < ApplicationController http_basic_authenticate_with :name => "dhh", :password => "secret", :except => [:index, :show] - # GET /posts - # GET /posts.json def index @posts = Post.all - respond_to do |format| # snipped for brevity </ruby> @@ -2042,213 +1651,6 @@ Authentication challenge !images/challenge.png(Basic HTTP Authentication Challenge)! -h3. Building a Multi-Model Form - -Another feature of your average blog is the ability to tag posts. To implement -this feature your application needs to interact with more than one model on a -single form. Rails offers support for nested forms. - -To demonstrate this, we will add support for giving each post multiple tags, -right in the form where you create the post. First, create a new model to hold -the tags: - -<shell> -$ rails generate model Tag name:string post:references -</shell> - -Again, run the migration to create the database table: - -<shell> -$ rake db:migrate -</shell> - -Next, edit the +post.rb+ file to create the other side of the association, and -to tell Rails (via the +accepts_nested_attributes_for+ macro) that you intend to -edit tags via posts: - -<ruby> -class Post < ActiveRecord::Base - validates :name, :presence => true - validates :title, :presence => true, - :length => { :minimum => 5 } - - has_many :comments, :dependent => :destroy - has_many :tags - - accepts_nested_attributes_for :tags, :allow_destroy => :true, - :reject_if => proc { |attrs| attrs.all? { |k, v| v.blank? } } -end -</ruby> - -The +:allow_destroy+ option tells Rails to enable destroying tags through the -nested attributes (you'll handle that by displaying a "remove" checkbox on the -view that you'll build shortly). The +:reject_if+ option prevents saving new -tags that do not have any attributes filled in. - -We will modify +views/posts/_form.html.erb+ to render a partial to make a tag: - -<erb> -<% @post.tags.build %> -<%= form_for(@post) do |post_form| %> - <% if @post.errors.any? %> - <div id="errorExplanation"> - <h2><%= pluralize(@post.errors.count, "error") %> prohibited this post from being saved:</h2> - <ul> - <% @post.errors.full_messages.each do |msg| %> - <li><%= msg %></li> - <% end %> - </ul> - </div> - <% end %> - - <div class="field"> - <%= post_form.label :name %><br /> - <%= post_form.text_field :name %> - </div> - <div class="field"> - <%= post_form.label :title %><br /> - <%= post_form.text_field :title %> - </div> - <div class="field"> - <%= post_form.label :content %><br /> - <%= post_form.text_area :content %> - </div> - <h2>Tags</h2> - <%= render :partial => 'tags/form', - :locals => {:form => post_form} %> - <div class="actions"> - <%= post_form.submit %> - </div> -<% end %> -</erb> - -Note that we have changed the +f+ in +form_for(@post) do |f|+ to +post_form+ to -make it easier to understand what is going on. - -This example shows another option of the render helper, being able to pass in -local variables, in this case, we want the local variable +form+ in the partial -to refer to the +post_form+ object. - -We also add a <tt>@post.tags.build</tt> at the top of this form. This is to make -sure there is a new tag ready to have its name filled in by the user. If you do -not build the new tag, then the form will not appear as there is no new Tag -object ready to create. - -Now create the folder <tt>app/views/tags</tt> and make a file in there called -<tt>_form.html.erb</tt> which contains the form for the tag: - -<erb> -<%= form.fields_for :tags do |tag_form| %> - <div class="field"> - <%= tag_form.label :name, 'Tag:' %> - <%= tag_form.text_field :name %> - </div> - <% unless tag_form.object.nil? || tag_form.object.new_record? %> - <div class="field"> - <%= tag_form.label :_destroy, 'Remove:' %> - <%= tag_form.check_box :_destroy %> - </div> - <% end %> -<% end %> -</erb> - -Finally, we will edit the <tt>app/views/posts/show.html.erb</tt> template to -show our tags. - -<erb> -<p id="notice"><%= notice %></p> - -<p> - <b>Name:</b> - <%= @post.name %> -</p> - -<p> - <b>Title:</b> - <%= @post.title %> -</p> - -<p> - <b>Content:</b> - <%= @post.content %> -</p> - -<p> - <b>Tags:</b> - <%= @post.tags.map { |t| t.name }.join(", ") %> -</p> - -<h2>Comments</h2> -<%= render @post.comments %> - -<h2>Add a comment:</h2> -<%= render "comments/form" %> - - -<%= link_to 'Edit Post', edit_post_path(@post) %> | -<%= link_to 'Back to Posts', posts_path %> | -</erb> - -With these changes in place, you'll find that you can edit a post and its tags -directly on the same view. - -However, that method call <tt>@post.tags.map { |t| t.name }.join(", ")</tt> is -awkward, we could handle this by making a helper method. - -h3. View Helpers - -View Helpers live in <tt>app/helpers</tt> and provide small snippets of reusable -code for views. In our case, we want a method that strings a bunch of objects -together using their name attribute and joining them with a comma. As this is -for the Post show template, we put it in the PostsHelper. - -Open up <tt>app/helpers/posts_helper.rb</tt> and add the following: - -<erb> -module PostsHelper - def join_tags(post) - post.tags.map { |t| t.name }.join(", ") - end -end -</erb> - -Now you can edit the view in <tt>app/views/posts/show.html.erb</tt> to look like -this: - -<erb> -<p id="notice"><%= notice %></p> - -<p> - <b>Name:</b> - <%= @post.name %> -</p> - -<p> - <b>Title:</b> - <%= @post.title %> -</p> - -<p> - <b>Content:</b> - <%= @post.content %> -</p> - -<p> - <b>Tags:</b> - <%= join_tags(@post) %> -</p> - -<h2>Comments</h2> -<%= render @post.comments %> - -<h2>Add a comment:</h2> -<%= render "comments/form" %> - - -<%= link_to 'Edit Post', edit_post_path(@post) %> | -<%= link_to 'Back to Posts', posts_path %> | -</erb> - h3. What's Next? Now that you've seen your first Rails application, you should feel free to diff --git a/guides/source/index.html.erb b/guides/source/index.html.erb index 5439459b42..74805b2754 100644 --- a/guides/source/index.html.erb +++ b/guides/source/index.html.erb @@ -13,7 +13,7 @@ Ruby on Rails Guides and <%= link_to 'Free Kindle Reading Apps', 'http://www.amazon.com/gp/kindle/kcp' %> for the iPad, iPhone, Mac, Android, etc. Download them from <%= link_to 'here', @mobi %>. </dd> - <dd class="work-in-progress">Guides marked with this icon are currently being worked on. While they might still be useful to you, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections to the author.</dd> + <dd class="work-in-progress">Guides marked with this icon are currently being worked on and will not be available in the Guides Index menu. While still useful, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections.</dd> </dl> </div> <% end %> diff --git a/guides/source/layouts_and_rendering.textile b/guides/source/layouts_and_rendering.textile index f69afaa281..e4a1fd6951 100644 --- a/guides/source/layouts_and_rendering.textile +++ b/guides/source/layouts_and_rendering.textile @@ -78,16 +78,16 @@ If we want to display the properties of all the books in our view, we can do so <tr> <td><%= book.title %></td> <td><%= book.content %></td> - <td><%= link_to 'Show', book %></td> - <td><%= link_to 'Edit', edit_book_path(book) %></td> - <td><%= link_to 'Remove', book, :confirm => 'Are you sure?', :method => :delete %></td> + <td><%= link_to "Show", book %></td> + <td><%= link_to "Edit", edit_book_path(book) %></td> + <td><%= link_to "Remove", book, :confirm => "Are you sure?", :method => :delete %></td> </tr> <% end %> </table> <br /> -<%= link_to 'New book', new_book_path %> +<%= link_to "New book", new_book_path %> </ruby> NOTE: The actual rendering is done by subclasses of +ActionView::TemplateHandlers+. This guide does not dig into that process, but it's important to know that the file extension on your view controls the choice of template handler. Beginning with Rails 2, the standard extensions are +.erb+ for ERB (HTML with embedded Ruby), and +.builder+ for Builder (XML generator). @@ -177,13 +177,13 @@ h5. Rendering an Action's Template from Another Controller What if you want to render a template from an entirely different controller from the one that contains the action code? You can also do that with +render+, which accepts the full path (relative to +app/views+) of the template to render. For example, if you're running code in an +AdminProductsController+ that lives in +app/controllers/admin+, you can render the results of an action to a template in +app/views/products+ this way: <ruby> -render 'products/show' +render "products/show" </ruby> Rails knows that this view belongs to a different controller because of the embedded slash character in the string. If you want to be explicit, you can use the +:template+ option (which was required on Rails 2.2 and earlier): <ruby> -render :template => 'products/show' +render :template => "products/show" </ruby> h5. Rendering an Arbitrary File @@ -216,18 +216,18 @@ In fact, in the BooksController class, inside of the update action where we want <ruby> render :edit render :action => :edit -render 'edit' -render 'edit.html.erb' -render :action => 'edit' -render :action => 'edit.html.erb' -render 'books/edit' -render 'books/edit.html.erb' -render :template => 'books/edit' -render :template => 'books/edit.html.erb' -render '/path/to/rails/app/views/books/edit' -render '/path/to/rails/app/views/books/edit.html.erb' -render :file => '/path/to/rails/app/views/books/edit' -render :file => '/path/to/rails/app/views/books/edit.html.erb' +render "edit" +render "edit.html.erb" +render :action => "edit" +render :action => "edit.html.erb" +render "books/edit" +render "books/edit.html.erb" +render :template => "books/edit" +render :template => "books/edit.html.erb" +render "/path/to/rails/app/views/books/edit" +render "/path/to/rails/app/views/books/edit.html.erb" +render :file => "/path/to/rails/app/views/books/edit" +render :file => "/path/to/rails/app/views/books/edit.html.erb" </ruby> Which one you use is really a matter of style and convention, but the rule of thumb is to use the simplest one that makes sense for the code you are writing. @@ -306,7 +306,7 @@ h6. The +:content_type+ Option By default, Rails will serve the results of a rendering operation with the MIME content-type of +text/html+ (or +application/json+ if you use the +:json+ option, or +application/xml+ for the +:xml+ option.). There are times when you might like to change this, and you can do so by setting the +:content_type+ option: <ruby> -render :file => filename, :content_type => 'application/rss' +render :file => filename, :content_type => "application/rss" </ruby> h6. The +:layout+ Option @@ -316,7 +316,7 @@ With most of the options to +render+, the rendered content is displayed as part You can use the +:layout+ option to tell Rails to use a specific file as the layout for the current action: <ruby> -render :layout => 'special_layout' +render :layout => "special_layout" </ruby> You can also tell Rails to render with no layout at all: @@ -378,7 +378,7 @@ You can use a symbol to defer the choice of layout until a request is processed: <ruby> class ProductsController < ApplicationController - layout :products_layout + layout "products_layout" def show @product = Product.find(params[:id]) @@ -398,7 +398,7 @@ You can even use an inline method, such as a Proc, to determine the layout. For <ruby> class ProductsController < ApplicationController - layout Proc.new { |controller| controller.request.xhr? ? 'popup' : 'application' } + layout Proc.new { |controller| controller.request.xhr? ? "popup" : "application" } end </ruby> @@ -445,7 +445,7 @@ end <ruby> class OldPostsController < SpecialPostsController - layout nil + layout false def show @post = Post.find(params[:id]) @@ -583,7 +583,7 @@ def show @book = Book.find_by_id(params[:id]) if @book.nil? @books = Book.all - render "index", :alert => 'Your book was not found!' + render "index", :alert => "Your book was not found!" end end </ruby> @@ -770,7 +770,7 @@ By default, the combined file will be delivered as +javascripts/all.js+. You can <erb> <%= javascript_include_tag "main", "columns", - :cache => 'cache/main/display' %> + :cache => "cache/main/display" %> </erb> You can even use dynamic paths such as +cache/#{current_site}/main/display+. @@ -833,7 +833,7 @@ By default, the combined file will be delivered as +stylesheets/all.css+. You ca <erb> <%= stylesheet_link_tag "main", "columns", - :cache => 'cache/main/display' %> + :cache => "cache/main/display" %> </erb> You can even use dynamic paths such as +cache/#{current_site}/main/display+. @@ -884,7 +884,7 @@ In addition to the above special tags, you can supply a final hash of standard H <erb> <%= image_tag "home.gif", :alt => "Go Home", :id => "HomeImage", - :class => 'nav_bar' %> + :class => "nav_bar" %> </erb> h5. Linking to Videos with the +video_tag+ @@ -905,7 +905,7 @@ Like an +image_tag+ you can supply a path, either absolute, or relative to the + The video tag also supports all of the +<video>+ HTML options through the HTML options hash, including: -* +:poster => 'image_name.png'+, provides an image to put in place of the video before it starts playing. +* +:poster => "image_name.png"+, provides an image to put in place of the video before it starts playing. * +:autoplay => true+, starts playing the video on page load. * +:loop => true+, loops the video once it gets to the end. * +:controls => true+, provides browser supplied controls for the user to interact with the video. @@ -1159,7 +1159,7 @@ In the event that the collection is empty, +render+ will return nil, so it shoul <erb> <h1>Products</h1> -<%= render(@products) || 'There are no products available.' %> +<%= render(@products) || "There are no products available." %> </erb> h5. Local Variables @@ -1175,7 +1175,7 @@ With this change, you can access an instance of the +@products+ collection as th You can also pass in arbitrary local variables to any partial you are rendering with the +:locals => {}+ option: <erb> -<%= render :partial => 'products', :collection => @products, +<%= render :partial => "products", :collection => @products, :as => :item, :locals => {:title => "Products Page"} %> </erb> @@ -1214,8 +1214,8 @@ Suppose you have the following +ApplicationController+ layout: <erb> <html> <head> - <title><%= @page_title or 'Page Title' %></title> - <%= stylesheet_link_tag 'layout' %> + <title><%= @page_title or "Page Title" %></title> + <%= stylesheet_link_tag "layout" %> <style><%= yield :stylesheets %></style> </head> <body> @@ -1239,7 +1239,7 @@ On pages generated by +NewsController+, you want to hide the top menu and add a <div id="right_menu">Right menu items here</div> <%= content_for?(:news_content) ? yield(:news_content) : yield %> <% end %> -<%= render :template => 'layouts/application' %> +<%= render :template => "layouts/application" %> </erb> That's it. The News views will use the new layout, hiding the top menu and adding a new right menu inside the "content" div. diff --git a/guides/source/routing.textile b/guides/source/routing.textile index 836e0cdd70..4a50edbb15 100644 --- a/guides/source/routing.textile +++ b/guides/source/routing.textile @@ -837,7 +837,7 @@ If you have a large route file that you would like to break up into multiple fil draw :admin </ruby> -Then, create a file called +config/routes/admin.rb+. Name the file the same as the symbol passed to the +draw+ method). You can then use the normal routing DSL inside that file: +Then, create a file called +config/routes/admin.rb+. Name the file the same as the symbol passed to the +draw+ method. You can then use the normal routing DSL inside that file: <ruby> # in config/routes/admin.rb diff --git a/guides/source/security.textile b/guides/source/security.textile index c065529cac..ac64b82bf6 100644 --- a/guides/source/security.textile +++ b/guides/source/security.textile @@ -1,7 +1,6 @@ h2. Ruby On Rails Security Guide -This manual describes common security problems in web applications and how to avoid them with Rails. If you have any questions or suggestions, please -mail me, Heiko Webers, at 42 {_et_} rorsecurity.info. After reading it, you should be familiar with: +This manual describes common security problems in web applications and how to avoid them with Rails. After reading it, you should be familiar with: * All countermeasures _(highlight)that are highlighted_ * The concept of sessions in Rails, what to put in there and popular attack methods diff --git a/guides/source/upgrading_ruby_on_rails.textile b/guides/source/upgrading_ruby_on_rails.textile index e63548abc9..2b2e65c813 100644 --- a/guides/source/upgrading_ruby_on_rails.textile +++ b/guides/source/upgrading_ruby_on_rails.textile @@ -38,6 +38,10 @@ h4(#identity_map4_0). IdentityMap Rails 4.0 has removed <tt>IdentityMap</tt> from <tt>ActiveRecord</tt>, due to "some inconsistencies with associations":https://github.com/rails/rails/commit/302c912bf6bcd0fa200d964ec2dc4a44abe328a6. If you have manually enabled it in your application, you will have to remove the following config that has no effect anymore: <tt>config.active_record.identity_map</tt>. +h4(#active_model4_0). ActiveModel + +Rails 4.0 has changed how errors attach with the ConfirmationValidator. Now when confirmation validations fail the error will be attached to <tt>:#{attribute}_confirmation</tt> instead of <tt>attribute</tt>. + h3. Upgrading from Rails 3.1 to Rails 3.2 If your application is currently on any version of Rails older than 3.1.x, you should upgrade to Rails 3.1 before attempting an update to Rails 3.2. |