diff --git a/railties/guides/source/3_0_release_notes.textile b/railties/guides/source/3_0_release_notes.textile index 77bd49f6b6..68edfc18d9 100644 --- a/railties/guides/source/3_0_release_notes.textile +++ b/railties/guides/source/3_0_release_notes.textile @@ -24,8 +24,8 @@ TIP: To install the Rails 3 prerelease beta using rubygems you have to install a # Use sudo if your setup requires it -gem install tzinfo builder memcache-client rack \ - rack-test rack-mount erubis mail text-format \ +gem install tzinfo builder i18n memcache-client rack \ + rake rack-test rack-mount erubis mail text-format \ thor bundler gem install rails --pre @@ -509,7 +509,7 @@ These are the main changes in Active Support: * String#to_time and String#to_datetime handle fractional seconds. * Added support to new callbacks for around filter object that respond to :before and :after used in before and after callbacks. * The ActiveSupport::OrderedHash#to_a method returns an ordered set of arrays. Matches Ruby 1.9's Hash#to_a. -* MissingSourceFile exists as a constant but it is now just equals to LoadError +* MissingSourceFile exists as a constant but it is now just equals to LoadError. * Added Class#class_attribute, to be able to declare a class-level attribute whose value is inheritable and overwritable by subclasses. * Finally removed +DeprecatedCallbacks+ in ActiveRecord::Associations. @@ -530,8 +530,7 @@ The following methods have been removed because they are no longer used in the f * Object#remove_subclasses_of, Object#subclasses_of, Object#extend_with_included_modules_from, Object#extended_by * Class#subclasses, Class#reachable?, Class#remove_class -* Regexp#number_of_captures -* Regexp.unoptionalize, Regexp.optionalize, Regexp#number_of_captures +* Regexp#number_of_captures, Regexp.unoptionalize, Regexp.optionalize, Regexp#number_of_captures h3. Action Mailer @@ -540,11 +539,11 @@ Action Mailer has been given a new API with TMail being replaced out with the ne * All mailers are now in app/mailers by default. * Can now send email using new API with three methods: +attachments+, +headers+ and +mail+. -* ActionMailer emailing methods now return Mail::Message objects, which can then be sent the +deliver+ message to send itself. +* Action Mailer emailing methods now return Mail::Message objects, which can then be sent the +deliver+ message to send itself. * All delivery methods are now abstracted out to the Mail gem. * The mail delivery method can accept a hash of all valid mail header fields with their value pair. -* The mail delivery method acts in a similar way to Action Controller's respond_to block, and you can explicitly or implicitly render templates. Action Mailer will turn the email into a multipart email as needed. -* You can pass a proc to the format.mime_type calls within the mail block and explicitly render specific types of text, or add layouts or different templates. The +render+ call inside the proc is from Abstract Controller, so all the same options are available as they are in Action Controller. +* The +mail+ delivery method acts in a similar way to Action Controller's +respond_to+, and you can explicitly or implicitly render templates. Action Mailer will turn the email into a multipart email as needed. +* You can pass a proc to the format.mime_type calls within the mail block and explicitly render specific types of text, or add layouts or different templates. The +render+ call inside the proc is from Abstract Controller and supports the same options. * What were mailer unit tests have been moved to functional tests. Deprecations: @@ -553,7 +552,7 @@ Deprecations: * Mailer dynamic create_method_name and deliver_method_name are deprecated, just call method_name which now returns a Mail::Message object. * ActionMailer.deliver(message) is deprecated, just call message.deliver. * template_root is deprecated, pass options to a render call inside a proc from the format.mime_type method inside the mail generation block -* The body method to define instance variables is deprecated (body {:ivar => value}), just declare instance variables in the method directly and they will be available in the view. +* The +body+ method to define instance variables is deprecated (body {:ivar => value}), just declare instance variables in the method directly and they will be available in the view. * Mailers being in app/models is deprecated, use app/mailers instead. More Information: diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index fb4c42f118..5d0bc01fee 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -624,6 +624,69 @@ NOTE: Defined in +active_support/core_ext/class/delegating_attributes.rb+. h3. Extensions to +String+ +h4. Output Safety + +Inserting data into HTML templates needs extra care. For example you can't just interpolate +@review.title+ verbatim into an HTML page. On one hand if the review title is "Flanagan & Matz rules!" the output won't be well-formed because an ampersand has to be escaped as "&amp;". On the other hand, depending on the application that may be a big security hole because users can inject malicious HTML setting a hand-crafted review title. Check out the "section about cross-site scripting in the Security guide":security.html#cross-site-scripting-xss for further information about the risks. + +Active Support has the concept of (html) safe strings since Rails 3. A safe string is one that is marked as being insertable into HTML as is. It is trusted, no matter whether it has been escaped or not. + +Strings are considered to be unsafe by default: + + +"".html_safe? # => false + + +You can obtain a safe string from a given one with the +html_safe+ method: + + +s = "".html_safe +s.html_safe? # => true + + +It is important to understand that +html_safe+ performs no escaping whatsoever, it is just an assertion: + + +s = "".html_safe +s.html_safe? # => true +s # => "" + + +It is your responsability to ensure calling +html_safe+ on a particular string is fine. + +NOTE: For performance reasons safe strings are implemented in a way that cannot offer an in-place +html_safe!+ variant. + +If you append onto a safe string, either in-place with +concat+/<<, or with +, the result is a safe string. Unsafe arguments are escaped: + + +"".html_safe + "<" # => "<" + + +Safe arguments are directly appended: + + +"".html_safe + "<".html_safe # => "<" + + +These methods should not be used in ordinary views. In Rails 3 unsafe values are automatically escaped: + + +<%= @review.title %> <%# fine in Rails 3, escaped if needed %> + + +To insert something verbatim use the +raw+ helper rather than calling +html_safe+: + + +<%= raw @cms.current_template %> <%# inserts @cms.current_template as is %> + + +The +raw+ helper calls +html_safe+ for you: + + +def raw(stringish) + stringish.to_s.html_safe +end + + h4. +squish+ The method +String#squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each: diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index c173748944..d7c9d39fd3 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -187,8 +187,8 @@ h4. Installing the Required Gems Rails uses the _Bundler_ gem to populate the +vendor+ directory with all the gems your application depends on. As we don't need any special gems beyond the default, we just need to do the following: -$ gem install bundle -$ gem bundle +$ gem install bundler +$ bundle install This will copy down the latest versions of all the gems you need to start a rails application.