diff options
Diffstat (limited to 'railties/guides/source')
-rw-r--r-- | railties/guides/source/3_0_release_notes.textile | 4 | ||||
-rw-r--r-- | railties/guides/source/active_record_validations_callbacks.textile | 4 | ||||
-rw-r--r-- | railties/guides/source/active_support_core_extensions.textile | 81 | ||||
-rw-r--r-- | railties/guides/source/association_basics.textile | 10 | ||||
-rw-r--r-- | railties/guides/source/getting_started.textile | 2 | ||||
-rw-r--r-- | railties/guides/source/index.html.erb | 2 | ||||
-rw-r--r-- | railties/guides/source/initialization.textile | 215 | ||||
-rw-r--r-- | railties/guides/source/layouts_and_rendering.textile | 2 | ||||
-rw-r--r-- | railties/guides/source/plugins.textile | 2 | ||||
-rw-r--r-- | railties/guides/source/routing.textile | 32 | ||||
-rw-r--r-- | railties/guides/source/security.textile | 2 |
11 files changed, 180 insertions, 176 deletions
diff --git a/railties/guides/source/3_0_release_notes.textile b/railties/guides/source/3_0_release_notes.textile index b32ca4fce9..7dcaf508c6 100644 --- a/railties/guides/source/3_0_release_notes.textile +++ b/railties/guides/source/3_0_release_notes.textile @@ -339,7 +339,9 @@ h5. Other Changes * You no longer need to place a minus sign at the end of a ruby interpolation inside an ERb template to remove the trailing carriage return in the HTML output. * Added +grouped_collection_select+ helper to Action View. * +content_for?+ has been added allowing you to check for the existence of content in a view before rendering. - +* passing +:value => nil+ to form helpers will set the field's +value+ attribute to nil as opposed to using the default value +* passing +:id => nil+ to form helpers will cause those fields to be rendered with no +id+ attribute +* passing +:alt => nil+ to +image_tag+ will cause the +img+ tag to render with no +alt+ attribute h3. Active Model diff --git a/railties/guides/source/active_record_validations_callbacks.textile b/railties/guides/source/active_record_validations_callbacks.textile index cfd4ae55cc..84c33e34f9 100644 --- a/railties/guides/source/active_record_validations_callbacks.textile +++ b/railties/guides/source/active_record_validations_callbacks.textile @@ -86,9 +86,9 @@ The following methods skip validations, and will save the object to the database * +update_attribute+ * +update_counters+ -Note that +save+ also has the ability to skip validations if passed +false+ as argument. This technique should be used with caution. +Note that +save+ also has the ability to skip validations if passed +:validate => false+ as argument. This technique should be used with caution. -* +save(false)+ +* +save(:validate => false)+ h4. +valid?+ and +invalid?+ diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 844b9428bd..58824d7aeb 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -387,40 +387,6 @@ TIP: Since +with_options+ forwards calls to its receiver they can be nested. Eac NOTE: Defined in +active_support/core_ext/object/with_options.rb+. -h5. +subclasses_of+ - -The method +subclasses_of+ receives an arbitrary number of class objects and returns all their anonymous or reachable descendants as a single array: - -<ruby> -class C; end -subclasses_of(C) # => [] - -subclasses_of(Integer) # => [Bignum, Fixnum] - -module M - class A; end - class B1 < A; end - class B2 < A; end -end - -module N - class C < M::B1; end -end - -subclasses_of(M::A) # => [N::C, M::B2, M::B1] -</ruby> - -The order in which these classes are returned is unspecified. The returned collection may have duplicates: - -<ruby> -subclasses_of(Numeric, Integer) -# => [Bignum, Float, Fixnum, Integer, Date::Infinity, Rational, BigDecimal, Bignum, Fixnum] -</ruby> - -See also +Class#subclasses+ in "Extensions to +Class+ FIX THIS LINK":FIXME. - -NOTE: Defined in +active_support/core_ext/object/extending.rb+. - h4. Instance Variables Active Support provides several methods to ease access to instance variables. @@ -1141,36 +1107,51 @@ If for whatever reason an application loads the definition of a mailer class and NOTE: Defined in +active_support/core_ext/class/delegating_attributes.rb+. -h4. Descendants +h4. Subclasses & Descendants h5. +subclasses+ -The +subclasses+ method returns the names of all the anonymous or reachable descendants of its receiver as an array of strings: +The +subclasses+ method returns the subclasses of the receiver: <ruby> class C; end C.subclasses # => [] -Integer.subclasses # => ["Bignum", "Fixnum"] +class B < C; end +C.subclasses # => [B] -module M - class A; end - class B1 < A; end - class B2 < A; end -end +class A < B; end +C.subclasses # => [B] -module N - class C < M::B1; end -end - -M::A.subclasses # => ["N::C", "M::B2", "M::B1"] +class D < C; end +C.subclasses # => [B, D] </ruby> -The order in which these class names are returned is unspecified. +The order in which these classes are returned is unspecified. + +WARNING: This method is redefined in some Rails core classes but should be all compatible in Rails 3.1. + +NOTE: Defined in +active_support/core_ext/class/subclasses.rb+. -See also +Object#subclasses_of+ in "Extensions to All Objects FIX THIS LINK":FIXME. +h5. +descendants+ + +The +descendants+ method returns all classes that are <tt><</tt> than its receiver: + +<ruby> +class C; end +C.descendants # => [] + +class B < C; end +C.descendants # => [B] + +class A < B; end +C.descendants # => [B, A] + +class D < C; end +C.descendants # => [B, A, D] +</ruby> -WARNING: This method is redefined in some Rails core classes. +The order in which these classes are returned is unspecified. NOTE: Defined in +active_support/core_ext/class/subclasses.rb+. diff --git a/railties/guides/source/association_basics.textile b/railties/guides/source/association_basics.textile index 335d17579d..c69f2ae8c9 100644 --- a/railties/guides/source/association_basics.textile +++ b/railties/guides/source/association_basics.textile @@ -137,6 +137,16 @@ end !images/has_many_through.png(has_many :through Association Diagram)! +The collection of join models can be managed via the API. For example, if you assign + +<ruby> +physician.patients = patients +</ruby> + +new join models are created for newly associated objects, and if some are gone their rows are deleted. + +WARNING: Automatic deletion of join models is direct, no destroy callbacks are triggered. + The +has_many :through+ association is also useful for setting up "shortcuts" through nested +has_many+ associations. For example, if a document has many sections, and a section has many paragraphs, you may sometimes want to get a simple collection of all paragraphs in the document. You could set that up this way: <ruby> diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 6abb3ed9f4..f547f29087 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -958,7 +958,7 @@ You'll see a bit more complexity here than you did in the controller for posts. 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/view/posts/show.html.erb+. +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+. <erb> <p class="notice"><%= notice %></p> diff --git a/railties/guides/source/index.html.erb b/railties/guides/source/index.html.erb index be077fcd2f..a930db0f1d 100644 --- a/railties/guides/source/index.html.erb +++ b/railties/guides/source/index.html.erb @@ -68,7 +68,7 @@ Ruby on Rails Guides <% end %> <%= guide("Action View Form Helpers", 'form_helpers.html', :ticket => 1) do %> - <p>Guide to using built in Form helpers.</p> + <p>Guide to using built-in Form helpers.</p> <% end %> </dl> diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index e458413b35..7a44ef7c77 100644 --- a/railties/guides/source/initialization.textile +++ b/railties/guides/source/initialization.textile @@ -11,7 +11,7 @@ This guide first describes the process of +rails server+ then explains the Passe h3. Launch! -As of Rails 3, +script/server+ has become +rails server+. This was done to centralise all rails related commands to one common file. +As of Rails 3, +script/server+ has become +rails server+. This was done to centralize all rails related commands to one common file. The actual +rails+ command is kept in _railties/bin/rails_ and goes like this: @@ -58,11 +58,8 @@ In +script/rails+ we see the following: #!/usr/bin/env ruby # This command will automatically be run when you run "rails" with Rails 3 gems installed from the root of your application. - ENV_PATH = File.expand_path('../../config/environment', __FILE__) - BOOT_PATH = File.expand_path('../../config/boot', __FILE__) - APP_PATH = File.expand_path('../../config/application', __FILE__) - - require BOOT_PATH + APP_PATH = File.expand_path('../../config/application', __FILE__) + require File.expand_path('../../config/boot', __FILE__) require 'rails/commands' </ruby> @@ -79,15 +76,19 @@ h3. _config/boot.rb_ _config/boot.rb_ is the first stop for everything for initializing your application. This boot process does quite a bit of work for you and so this section attempts to go in-depth enough to explain what each of the pieces does. <ruby> - # Use Bundler (preferred) + require 'rubygems' + + # Set up gems listed in the Gemfile. + gemfile = File.expand_path('../../Gemfile', __FILE__) begin - require File.expand_path('../../.bundle/environment', __FILE__) - rescue LoadError - require 'rubygems' + ENV['BUNDLE_GEMFILE'] = gemfile require 'bundler' Bundler.setup - end - + rescue Bundler::GemNotFound => e + STDERR.puts e.message + STDERR.puts "Try running `bundle install`." + exit! + end if File.exist?(gemfile) </ruby> h3. Bundled Rails (3.x) @@ -140,8 +141,8 @@ Here the only two gems we need are +rails+ and +sqlite3-ruby+, so it seems. This * activesupport-3.0.0.beta4.gem * arel-0.4.0.gem * builder-2.1.2.gem -* bundler-0.9.26.gem -* erubis-2.6.5.gem +* bundler-1.0.0.beta.2.gem +* erubis-2.6.6.gem * i18n-0.4.1.gem * mail-2.2.4.gem * memcache-client-1.8.3.gem @@ -156,7 +157,7 @@ Here the only two gems we need are +rails+ and +sqlite3-ruby+, so it seems. This * sqlite3-ruby-1.3.0.gem * text-format-1.0.0.gem * text-hyphen-1.0.0.gem -* thor-0.13.6.gem +* thor-0.13.7.gem * treetop-1.4.8.gem * tzinfo-0.3.22.gem @@ -164,33 +165,7 @@ TODO: Prettify when it becomes more stable. I won't go into what each of these gems are, as that is really something that needs covering on a case-by-case basis. We will however just dig a little under the surface of Bundler. -Back in _config/boot.rb_, the first line will try to include _.bundle/environment.rb_, which doesn't exist in a bare-bones Rails application and because this file does not exist Ruby will raise a +LoadError+ which will be rescued and run the following code: - -<ruby> - require 'rubygems' - require 'bundler' - Bundler.setup -</ruby> - -+Bundler.setup+ here will load and parse the +Gemfile+ and add the _lib_ directory of the gems mentioned **and** their dependencies (**and** their dependencies' dependencies, and so on) to the +$LOAD_PATH+. - -Now we will go down the alternate timeline where we generate a _.bundle/environment.rb_ file using the +bundle lock+ command. This command also creates a _Gemfile.lock_ file which is actually a YAML file loaded by this method in Bundler before it moves on to check for _Gemfile_: - -<ruby> - def definition(gemfile = default_gemfile) - configure - root = Pathname.new(gemfile).dirname - lockfile = root.join("Gemfile.lock") - if lockfile.exist? - Definition.from_lock(lockfile) - else - Definition.from_gemfile(gemfile) - end - end -</ruby> - - -The _.bundle/environment.rb_ file adds the _lib_ directory of all the gems specified in +Gemfile.lock+ to +$LOAD_PATH+. +Back in _config/boot.rb_, we call +Bundler.setup+ which will load and parse the +Gemfile+ and add the _lib_ directory of the gems mentioned **and** their dependencies (**and** their dependencies' dependencies, and so on) to the +$LOAD_PATH+. h3. Requiring Rails @@ -326,6 +301,11 @@ As you can see for the duration of the +eager_autoload+ block the class variable module ActiveSupport extend ActiveSupport::Autoload + autoload :DescendantsTracker + autoload :FileUpdateChecker + autoload :LogSubscriber + autoload :Notifications + # TODO: Narrow this list down eager_autoload do autoload :BacktraceCleaner @@ -348,7 +328,6 @@ As you can see for the duration of the +eager_autoload+ block the class variable autoload :OptionMerger autoload :OrderedHash autoload :OrderedOptions - autoload :Notifications autoload :Rescuable autoload :SecureRandom autoload :StringInquirer @@ -589,19 +568,20 @@ This file (_railties/lib/rails.rb_) requires the very, very basics that Rails ne require 'action_dispatch/railtie' </ruby> -+require 'pathname'+ requires the Pathname class which is used for returning a Pathname object for +Rails.root+ so that instead of doing: ++require 'pathname'+ requires the Pathname class which is used for returning a Pathname object for +Rails.root+. Although is coming to use this path name to generate paths as below: <ruby> - File.join(Rails.root, "app/controllers") + Rails.root.join("app/controllers") </ruby> -You may do: +Pathname can also be converted to string, so the following syntax is preferred: <ruby> - Rails.root.join("app/controllers") + "#{Rails.root}/app/controllers" </ruby> -Although this is not new to Rails 3 (it was available in 2.3.5), it is something worthwhile pointing out. + +This works because Ruby automatically handles file path conversions. Although this is not new to Rails 3 (it was available in 2.3.5), it is something worthwhile pointing out. Inside this file there are other helpful helper methods defined, such as +Rails.root+, +Rails.env+, +Rails.logger+ and +Rails.application+. @@ -1833,7 +1813,7 @@ We do not already have a +Rails.application+, so instead this resorts to calling end </ruby> -This +called_from+ setting looks a little overwhelming to begin with, but the short end of it is that it returns the route to your application's config directory, something like: _/home/you/yourapp/config_. After +called_from+ has been set, +super+ is again called and this means the +Rails::Railtie#inherited+ method (in _railties/lib/rails/railtie.rb_): +This +called_from+ setting looks a little overwhelming to begin with, but the short end of it is that it returns your application's root, something like: _/home/you/yourapp_. After +called_from+ has been set, +super+ is again called and this means the +Rails::Railtie#inherited+ method (in _railties/lib/rails/railtie.rb_): <ruby> def inherited(base) @@ -3588,28 +3568,24 @@ h3. Appendix A This file is _activesupport/lib/active_support/inflector/inflections.rb_ and defines the +ActiveSupport::Inflector::Inflections+ class which defines the +singularize+, +pluralize+, +humanize+, +tableize+, +titleize+ and +classify+ methods as well as the code to defining how to work out the irregular, singular, plural and human versions of words. These methods are called +irregular+, +singular+, +plural+ and +human+ respectively, as is the Rails way. -This file is _activesupport/lib/active_support/inflector/transliterate.rb_ and defines two methods, +transliterate+ and +parameterize+. What +transliterate+ does depends on your Ruby version. If you have something greater than 1.9 installed it will just print out a warning message using the +Kernel#warn+ method (simply called using +warn+) reading "Ruby 1.9 doesn't support Unicode normalization yet". If you're running something that's not 1.9 it will attempt to convert +"föö"+ to +foo+ and if that fails then it'll redefine it. +This file is _activesupport/lib/active_support/inflector/transliterate.rb_ and defines two methods, +transliterate+ and +parameterize+. -This file first makes a require to _activesupport/lib/active_support/core_ext/string/multibyte.rb_ which then goes on to require _activesupport/lib/active_support/multibyte.rb_ and that requires _activesupport/core_ext/module/attribute_accessors.rb_. The _attribute_accessors.rb_ file is used to gain access to the +mattr_accessor+ (module attribute accessor) method which is called in _active_suport/multibyte.rb_. Also in _active_support/multibyte.rb_ there's a couple of autoloaded classes: +This file first requires _activesupport/lib/active_support/core_ext/string/multibyte.rb_, which requires _activesupport/lib/active_support/multibyte.rb_, which subsequently requires _activesupport/core_ext/module/attribute_accessors.rb_. The _attribute_accessors.rb_ file is needed to gain access to the +mattr_accessor+ (module attribute accessor) method, which is called in _active_suport/multibyte.rb_. The file _active_support/multibyte.rb_ also autoloads three other classes: <ruby> module ActiveSupport #:nodoc: module Multibyte autoload :EncodingError, 'active_support/multibyte/exceptions' autoload :Chars, 'active_support/multibyte/chars' - autoload :UnicodeDatabase, 'active_support/multibyte/unicode_database' - autoload :Codepoint, 'active_support/multibyte/unicode_database' - autoload :UCD, 'active_support/multibyte/unicode_database' - ... + autoload :Unicode, 'active_support/multibyte/unicode' + ... end end </ruby> -There's also these method definitions: +There are also these method definitions: <ruby> - self.default_normalization_form = :kc - # The proxy class returned when calling mb_chars. You can use this accessor to configure your own proxy # class so you can support other encodings. See the ActiveSupport::Multibyte::Chars implementation for # an example how to do this. @@ -3628,63 +3604,92 @@ There's also these method definitions: These methods are used in _activesupport/lib/active_support/core_ext/string/multibyte.rb_. -If we go back to _activesupport/lib/active_support/core_ext/string/multibyte.rb_, this file makes a couple of extensions to the +String+ class based on if your version of Ruby's +String+ class responds to the +force_encoding+ method. This method was introduced in Ruby 1.9. If you're using 1.9 the methods are defined like this: - -<ruby> - def mb_chars #:nodoc - self - end - - def is_utf8? #:nodoc - case encoding - when Encoding::UTF_8 - valid_encoding? - when Encoding::ASCII_8BIT, Encoding::US_ASCII - dup.force_encoding(Encoding::UTF_8).valid_encoding? - else - false - end - end -</ruby> - -You can see that calling +mb_chars+ on a +String+ instance in Ruby 1.9 will simply return that +String+ object. +String+ objects in Ruby 1.9 are already multibyte strings, so Rails does not need to do any conversion on them. - -The second method, +is_utf8?+ return +true+ if the +String+ object is of the UTF8 encoding or if it's able to be forced into that encoding and +false+ if it can't force its encoding or if the encoding of the string is neither +UTF8+, +ASCII_8BIT+ or +US_ASCII+. - -If you're using a Ruby version less than 1.9 there are 3 methods defined instead of 2, and they are defined like this: +The file _activesupport/lib/active_support/core_ext/string/chars.rb_ defines the default proxy class that will be returned by +mb_chars+. + +Because Ruby 1.9's +String+ class has support for multibyte encodings, some methods are defined only for Ruby 1.8: + +* +self.wants?+ +* +++ +* +=~+ +* +=~+ +* +center+ +* +include?+ +* +index+ +* +insert+ +* +ljust+ +* +lstrip+, +lstrip!+ +* +ord+ +* +rindex+ +* +rjust+ +* +rstrip+, +rstrip!+ +* +size+ +* +strip+, +strip!+ + +However, Ruby 1.9 lacks support for some needed operations, so the following methods are defined for both Ruby 1.8 and Ruby 1.9: + +* +<=>+ +* +[]=+ +* +capitalize+, +capitalize!+ +* +compose+ +* +decompose+ +* +downcase+, +downcase!+ +* +g_length+ +* +limit+ +* +normalize+ +* +reverse+, +reverse+! +* +slice+, +slice!+ +* +split+ +* +tidy_bytes+, +tidy_bytes!+ +* +titleize+ +* +upcase+, +upcase!+ + +<ruby> + class String + if RUBY_VERSION >= "1.9" + def mb_chars + if ActiveSupport::Multibyte.proxy_class.consumes?(self) + ActiveSupport::Multibyte.proxy_class.new(self) + else + self + end + end -<ruby> - def mb_chars - if ActiveSupport::Multibyte.proxy_class.wants?(self) - ActiveSupport::Multibyte.proxy_class.new(self) + def is_utf8? #:nodoc + case encoding + when Encoding::UTF_8 + valid_encoding? + when Encoding::ASCII_8BIT, Encoding::US_ASCII + dup.force_encoding(Encoding::UTF_8).valid_encoding? + else + false + end + end else - self - end - end - - # Returns true if the string has UTF-8 semantics (a String used for purely byte resources is unlikely to have - # them), returns false otherwise. - def is_utf8? - ActiveSupport::Multibyte::Chars.consumes?(self) - end + def mb_chars + if ActiveSupport::Multibyte.proxy_class.wants?(self) + ActiveSupport::Multibyte.proxy_class.new(self) + else + self + end + end - unless '1.8.7 and later'.respond_to?(:chars) - def chars - ActiveSupport::Deprecation.warn('String#chars has been deprecated in favor of String#mb_chars.', caller) - mb_chars + # Returns true if the string has UTF-8 semantics (a String used for purely byte resources is unlikely to have + # them), returns false otherwise. + def is_utf8? + ActiveSupport::Multibyte::Chars.consumes?(self) + end end - end - </ruby> +As you can see, +mb_chars+ is where the +proxy_class+ property comes in handy. This method will create a new instance of the configured proxy class using the instance of +String+ as a constructor argument. By default, the new +String+-like object will be an instance of the proxy class +ActiveSupport::Multibyte::Chars+. You can use +ActiveSupport::Multibyte.proxy_class=+ to set a different proxy class if you wish. -As you can see, +mb_chars+ is where the +proxy_class+ method comes in handy. This will create a new instance of that class and pass in the +String+ object in order to make it multibyte-compatible. In this case the new +String+ object will be an instance of the +ActiveSupport::Multibyte::Chars+ class. You can use +ActiveSupport::Multibyte.proxy_class=+ to set this to be a different class if you're that way inclined. - -Here, +is_utf8?+ calls a +consumes+ method on the not-yet-loaded +ActiveSupport::Multibyte::Chars+ class. The keen-eye would have seen this was specified as an auto-load earlier, so that is what is going to happen if we call this method or +mb_chars+. This means that it'll require the file located at _activesupport/lib/active_support/multibyte/chars.rb_. This file includes _activesupport/lib/active_support/string/access.rb_ which defines methods such as +at+, +from+, +to+, +first+ and +last+. These methods will return parts of the string depending on what is passed to them and they are defined differently depending on if you're using Ruby 1.9 or not. The second file included is _activesupport/lib/active_support/string/behaviour.rb_ which defines a single method +acts_like_string?+ on +String+ which always returns +true+. This method is used through the +acts_like?+ method which is passed a single argument representing the downcased and symbolised version of the class you want to know if it acts like. In this case the code would be +acts_like?(:string)+. +Here, +mb_chars+ invokes +is_utf8?+ to checks if the string can be treated as UTF-8. On 1.9, the string's +encoding+ property is checked. On 1.8, +wants?+ checks to see if +$KCODE+ is "UTF-8" and, and +consumes?+ checks whether the string can be unpacked as UTF-8 without raising an error. -The +Chars+ class defines, along with +consumes?+, other methods such as the "spaceship" method +<=>+. This method is referenced by the methods defined in the included +Comparable+ module and will return either +-1+, +0+ or +1+ depending on if the word is before, identical or after the compared word. For example, +'é'.mb_chars <=> 'ü'.mb_chars+ returns +-1+ as e comes before u in the alphabet. Other methods are the commonly used +split+, +=~+, +insert+ and +include?+. +The keen eye will have seen +ActiveSupport::Multibyte::Chars+ was specified as an +autoload+ earlier: _activesupport/lib/active_support/multibyte/chars.rb_ will be loaded without an explicit +require+ when we call +is_utf8+ on 1.8, or +mb_chars+ on any Ruby version. This file includes _activesupport/lib/active_support/string/access.rb_ which defines methods such as +at+, +from+, +to+, +first+ and +last+. These methods will return parts of the string depending on what is passed to them. +The second file included is _activesupport/lib/active_support/string/behavior.rb_ which only defines +acts_like_string?+ on +String+, a method which always returns +true+. This method is used by +Object#acts_like?+, which accepts a single argument representing the downcased and symbolised version of a class, and returns true if the object's behavior is like that class. In this case the code would be +acts_like?(:string)+. +The +Chars+ class also defines other important methods such as the "spaceship" method +<=>+, which is needed by the +Comparable+ module, in order to allow UTF-8-aware sorting. h3. Common Includes diff --git a/railties/guides/source/layouts_and_rendering.textile b/railties/guides/source/layouts_and_rendering.textile index a874fa0ca7..f4ba6dd53b 100644 --- a/railties/guides/source/layouts_and_rendering.textile +++ b/railties/guides/source/layouts_and_rendering.textile @@ -2,7 +2,7 @@ h2. Layouts and Rendering in Rails This guide covers the basic layout features of Action Controller and Action View. By referring to this guide, you will be able to: -* Use the various rendering methods built in to Rails +* Use the various rendering methods built into Rails * Create layouts with multiple content sections * Use partials to DRY up your views * Use nested layouts (sub-templates) diff --git a/railties/guides/source/plugins.textile b/railties/guides/source/plugins.textile index a12434a95b..e853ba79e9 100644 --- a/railties/guides/source/plugins.textile +++ b/railties/guides/source/plugins.textile @@ -1284,7 +1284,7 @@ class YaffleMigrationGenerator < Rails::Generator::NamedBase end </ruby> -The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement. It reuses the built in rails +migration_template+ method, and reuses the built-in rails migration template. +The generator creates a new file in 'db/migrate' with a timestamp and an 'add_column' statement. It reuses the built-in rails +migration_template+ method, and reuses the built-in rails migration template. It's courteous to check to see if table names are being pluralized whenever you create a generator that needs to be aware of table names. This way people using your generator won't have to manually change the generated files if they've turned pluralization off. diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index 9ff06856c3..72a76e25bb 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -382,6 +382,12 @@ match ':controller/:action/:id/:user_id' An incoming URL of +/photos/show/1/2+ will be dispatched to the +show+ action of the +PhotosController+. +params[:id]+ will be +"1"+, and +params[:user_id]+ will be +"2"+. +NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment. If you need to do this then use a constraint on :controller that matches the namespace you require. e.g: + +<ruby> +match ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/ +</ruby> + h4. Static Segments You can specify static segments when creating a route: @@ -645,13 +651,13 @@ scope :path_names => { :new => "make" } do end </ruby> -h4. Overriding the Named Helper Prefix +h4. Prefixing the Named Route Helpers -You can use the :name_prefix option to add a prefix to the named route helpers that Rails generates for a route. You can use this option to prevent collisions between routes using a path scope. +You can use the +:as+ option to prefix the named route helpers that Rails generates for a route. Use this option to prevent name collisions between routes using a path scope. <ruby> scope "admin" do - resources :photos, :name_prefix => "admin" + resources :photos, :as => "admin_photos" end resources :photos @@ -659,17 +665,17 @@ resources :photos This will provide route helpers such as +admin_photos_path+, +new_admin_photo_path+ etc. -You could specify a name prefix to use for a group of routes in the scope: +To prefix a group of routes, use +:as+ with +scope+: <ruby> -scope "admin", :name_prefix => "admin" do +scope "admin", :as => "admin" do resources :photos, :accounts end resources :photos, :accounts </ruby> -NOTE: The +namespace+ scope will automatically add a +:name_prefix+ as well as +:module+ and +:path+ prefixes. +NOTE: The +namespace+ scope will automatically add +:as+ as well as +:module+ and +:path+ prefixes. h4. Restricting the Routes Created @@ -714,21 +720,21 @@ Rails now creates routes to the +CategoriesControlleR+. h4. Overriding the Singular Form -If you want to customize the singular name of the route in the named helpers, you can use the +:singular+ option. +If you want to define the singular form of a resource, you should add additional rules to the +Inflector+. <ruby> -resources :teeth, :singular => "tooth" +ActiveSupport::Inflector.inflections do |inflect| + inflect.irregular 'tooth', 'teeth' +end </ruby> -TIP: If you want to define the singular form of a word for your entire application, you should add additional rules to the +Inflector+ instead. - -h4(#nested-name-prefix). Using +:name_prefix+ in Nested Resources +h4(#nested-names). Using +:as+ in Nested Resources -The +:name_prefix+ option overrides the automatically-generated prefix for the parent resource in nested route helpers. For example, +The +:as+ option overrides the automatically-generated name for the resource in nested route helpers. For example, <ruby> resources :magazines do - resources :ads, :name_prefix => 'periodical' + resources :ads, :as => 'periodical_ads' end </ruby> diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile index b45514f66d..60108d5ab3 100644 --- a/railties/guides/source/security.textile +++ b/railties/guides/source/security.textile @@ -670,7 +670,7 @@ Also, the second query renames some columns with the AS statement so that the we h5(#sql-injection-countermeasures). Countermeasures -Ruby on Rails has a built in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <em class="highlight">Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure</em>. But in SQL fragments, especially <em class="highlight">in conditions fragments (+:conditions => "..."+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually</em>. +Ruby on Rails has a built-in filter for special SQL characters, which will escape ' , " , NULL character and line breaks. <em class="highlight">Using +Model.find(id)+ or +Model.find_by_some thing(something)+ automatically applies this countermeasure</em>. But in SQL fragments, especially <em class="highlight">in conditions fragments (+:conditions => "..."+), the +connection.execute()+ or +Model.find_by_sql()+ methods, it has to be applied manually</em>. Instead of passing a string to the conditions option, you can pass an array to sanitize tainted strings like this: |