diff options
Diffstat (limited to 'railties')
| -rw-r--r-- | railties/guides/source/3_0_release_notes.textile | 17 | ||||
| -rw-r--r-- | railties/guides/source/active_support_core_extensions.textile | 63 | ||||
| -rw-r--r-- | railties/guides/source/getting_started.textile | 4 |
3 files changed, 73 insertions, 11 deletions
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 <shell> # 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 </shell> @@ -509,7 +509,7 @@ These are the main changes in Active Support: * <tt>String#to_time</tt> and <tt>String#to_datetime</tt> handle fractional seconds. * Added support to new callbacks for around filter object that respond to <tt>:before</tt> and <tt>:after</tt> used in before and after callbacks. * The <tt>ActiveSupport::OrderedHash#to_a</tt> method returns an ordered set of arrays. Matches Ruby 1.9's <tt>Hash#to_a</tt>. -* <tt>MissingSourceFile</tt> exists as a constant but it is now just equals to <tt>LoadError</tt> +* <tt>MissingSourceFile</tt> exists as a constant but it is now just equals to <tt>LoadError</tt>. * Added <tt>Class#class_attribute</tt>, to be able to declare a class-level attribute whose value is inheritable and overwritable by subclasses. * Finally removed +DeprecatedCallbacks+ in <tt>ActiveRecord::Associations</tt>. @@ -530,8 +530,7 @@ The following methods have been removed because they are no longer used in the f * <tt>Object#remove_subclasses_of</tt>, <tt>Object#subclasses_of</tt>, <tt>Object#extend_with_included_modules_from</tt>, <tt>Object#extended_by</tt> * <tt>Class#subclasses</tt>, <tt>Class#reachable?</tt>, <tt>Class#remove_class</tt> -* <tt>Regexp#number_of_captures</tt> -* <tt>Regexp.unoptionalize</tt>, <tt>Regexp.optionalize</tt>, <tt>Regexp#number_of_captures</tt> +* <tt>Regexp#number_of_captures</tt>, <tt>Regexp.unoptionalize</tt>, <tt>Regexp.optionalize</tt>, <tt>Regexp#number_of_captures</tt> 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 <tt>app/mailers</tt> 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 <tt>Mail::Message</tt> 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 <tt>format.mime_type</tt> 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 <tt>format.mime_type</tt> 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 <tt>create_method_name</tt> and <tt>deliver_method_name</tt> are deprecated, just call <tt>method_name</tt> which now returns a <tt>Mail::Message</tt> object. * <tt>ActionMailer.deliver(message)</tt> is deprecated, just call <tt>message.deliver</tt>. * <tt>template_root</tt> is deprecated, pass options to a render call inside a proc from the <tt>format.mime_type</tt> method inside the <tt>mail</tt> generation block -* The body method to define instance variables is deprecated (<tt>body {:ivar => value}</tt>), 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 (<tt>body {:ivar => value}</tt>), just declare instance variables in the method directly and they will be available in the view. * Mailers being in <tt>app/models</tt> is deprecated, use <tt>app/mailers</tt> 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 <i>(html) safe</i> 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 <i>unsafe</i> by default: + +<ruby> +"".html_safe? # => false +</ruby> + +You can obtain a safe string from a given one with the +html_safe+ method: + +<ruby> +s = "".html_safe +s.html_safe? # => true +</ruby> + +It is important to understand that +html_safe+ performs no escaping whatsoever, it is just an assertion: + +<ruby> +s = "<script>...</script>".html_safe +s.html_safe? # => true +s # => "<script>...</script>" +</ruby> + +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+/<tt><<</tt>, or with <tt>+</tt>, the result is a safe string. Unsafe arguments are escaped: + +<ruby> +"".html_safe + "<" # => "<" +</ruby> + +Safe arguments are directly appended: + +<ruby> +"".html_safe + "<".html_safe # => "<" +</ruby> + +These methods should not be used in ordinary views. In Rails 3 unsafe values are automatically escaped: + +<erb> +<%= @review.title %> <%# fine in Rails 3, escaped if needed %> +</erb> + +To insert something verbatim use the +raw+ helper rather than calling +html_safe+: + +<erb> +<%= raw @cms.current_template %> <%# inserts @cms.current_template as is %> +</erb> + +The +raw+ helper calls +html_safe+ for you: + +<ruby> +def raw(stringish) + stringish.to_s.html_safe +end +</ruby> + 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: <shell> -$ gem install bundle -$ gem bundle +$ gem install bundler +$ bundle install </shell> This will copy down the latest versions of all the gems you need to start a rails application. |