diff options
Diffstat (limited to 'guides/source')
20 files changed, 498 insertions, 271 deletions
diff --git a/guides/source/action_view_overview.textile b/guides/source/action_view_overview.textile index fd1b6c5fc2..bde30ba21c 100644 --- a/guides/source/action_view_overview.textile +++ b/guides/source/action_view_overview.textile @@ -59,7 +59,6 @@ Now we'll create a simple "Hello World" application that uses the +titleize+ met *hello_world.rb:* <ruby> -require 'rubygems' require 'active_support/core_ext/string/inflections' require 'rack' @@ -94,7 +93,6 @@ Now we'll create the same "Hello World" application in Sinatra. *hello_world.rb:* <ruby> -require 'rubygems' require 'action_view' require 'sinatra' diff --git a/guides/source/active_model_basics.textile b/guides/source/active_model_basics.textile index 98b3533000..d373f4ac85 100644 --- a/guides/source/active_model_basics.textile +++ b/guides/source/active_model_basics.textile @@ -20,7 +20,7 @@ class Person attribute_method_prefix 'reset_' attribute_method_suffix '_highest?' - define_attribute_methods ['age'] + define_attribute_methods 'age' attr_accessor :age @@ -95,12 +95,11 @@ h4. Dirty An object becomes dirty when an object is gone through one or more changes to its attributes and not yet saved. This gives the ability to check whether an object has been changed or not. It also has attribute based accessor methods. Lets consider a Person class with attributes first_name and last_name <ruby> -require 'rubygems' require 'active_model' class Person include ActiveModel::Dirty - define_attribute_methods [:first_name, :last_name] + define_attribute_methods :first_name, :last_name def first_name @first_name diff --git a/guides/source/active_record_querying.textile b/guides/source/active_record_querying.textile index a9cb424eaa..294ef25b33 100644 --- a/guides/source/active_record_querying.textile +++ b/guides/source/active_record_querying.textile @@ -1260,6 +1260,24 @@ with Client.pluck(:id) </ruby> +h3. +ids+ + ++ids+ can be used to pluck all the IDs for the relation using the table's primary key. + +<ruby> +Person.ids +# SELECT id FROM people +</ruby> + +<ruby> +class Person < ActiveRecord::Base + self.primary_key = "person_id" +end + +Person.ids +# SELECT person_id FROM people +</ruby> + h3. Existence of Objects If you simply want to check for the existence of the object there's a method called +exists?+. This method will query the database using the same query as +find+, but instead of returning an object or collection of objects it will return either +true+ or +false+. diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile index c56cb0b9e5..e2118e8f61 100644 --- a/guides/source/active_support_core_extensions.textile +++ b/guides/source/active_support_core_extensions.textile @@ -84,7 +84,7 @@ The following values are considered to be blank in a Rails application: * any other object that responds to +empty?+ and it is empty. -INFO: In Ruby 1.9 the predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. In Ruby 1.8 whitespace is considered to be <tt>\s</tt> together with the ideographic space U+3000. +INFO: The predicate for strings uses the Unicode-aware character class <tt>[:space:]</tt>, so for example U+2029 (paragraph separator) is considered to be whitespace. WARNING: Note that numbers are not mentioned, in particular 0 and 0.0 are *not* blank. @@ -229,7 +229,7 @@ You can evaluate code in the context of any object's singleton class using +clas <ruby> class Proc def bind(object) - block, time = self, Time.now + block, time = self, Time.current object.class_eval do method_name = "__bind_#{time.to_i}_#{time.usec}" define_method(method_name, &block) @@ -1079,49 +1079,6 @@ A model may find it useful to set +:instance_accessor+ to +false+ as a way to pr NOTE: Defined in +active_support/core_ext/class/attribute_accessors.rb+. -h4. Class Inheritable Attributes - -WARNING: Class Inheritable Attributes are deprecated. It's recommended that you use +Class#class_attribute+ instead. - -Class variables are shared down the inheritance tree. Class instance variables are not shared, but they are not inherited either. The macros +class_inheritable_reader+, +class_inheritable_writer+, and +class_inheritable_accessor+ provide accessors for class-level data which is inherited but not shared with children: - -<ruby> -module ActionController - class Base - # FIXME: REVISE/SIMPLIFY THIS COMMENT. - # The value of allow_forgery_protection is inherited, - # but its value in a particular class does not affect - # the value in the rest of the controllers hierarchy. - class_inheritable_accessor :allow_forgery_protection - end -end -</ruby> - -They accomplish this with class instance variables and cloning on subclassing, there are no class variables involved. Cloning is performed with +dup+ as long as the value is duplicable. - -There are some variants specialised in arrays and hashes: - -<ruby> -class_inheritable_array -class_inheritable_hash -</ruby> - -Those writers take any inherited array or hash into account and extend them rather than overwrite them. - -As with vanilla class attribute accessors these macros create convenience instance methods for reading and writing. The generation of the writer instance method can be prevented setting +:instance_writer+ to +false+ (not any false value, but exactly +false+): - -<ruby> -module ActiveRecord - class Base - class_inheritable_accessor :default_scoping, :instance_writer => false - end -end -</ruby> - -Since values are copied when a subclass is defined, if the base class changes the attribute after that, the subclass does not see the new value. That's the point. - -NOTE: Defined in +active_support/core_ext/class/inheritable_attributes.rb+. - h4. Subclasses & Descendants h5. +subclasses+ @@ -1300,9 +1257,14 @@ Pass a +:separator+ to truncate the string at a natural break: # => "Oh dear! Oh..." </ruby> -In the above example "dear" gets cut first, but then +:separator+ prevents it. +The option +:separator+ can be a regexp: -WARNING: The option +:separator+ can't be a regexp. +<ruby> +"Oh dear! Oh dear! I shall be late!".truncate(18, :separator => /\s/) +# => "Oh dear! Oh..." +</ruby> + +In above examples "dear" gets cut first, but then +:separator+ prevents it. NOTE: Defined in +active_support/core_ext/string/filters.rb+. @@ -1315,20 +1277,6 @@ The <tt>inquiry</tt> method converts a string into a +StringInquirer+ object mak "active".inquiry.inactive? # => false </ruby> -h4. Key-based Interpolation - -In Ruby 1.9 the <tt>%</tt> string operator supports key-based interpolation, both formatted and unformatted: - -<ruby> -"Total is %<total>.02f" % {:total => 43.1} # => Total is 43.10 -"I say %{foo}" % {:foo => "wadus"} # => "I say wadus" -"I say %{woo}" % {:foo => "wadus"} # => KeyError -</ruby> - -Active Support adds that functionality to <tt>%</tt> in previous versions of Ruby. - -NOTE: Defined in +active_support/core_ext/string/interpolation.rb+. - h4. +starts_with?+ and +ends_with?+ Active Support defines 3rd person aliases of +String#start_with?+ and +String#end_with?+: @@ -1375,7 +1323,7 @@ Returns the character of the string at position +position+: "hello".at(0) # => "h" "hello".at(4) # => "o" "hello".at(-1) # => "o" -"hello".at(10) # => ERROR if < 1.9, nil in 1.9 +"hello".at(10) # => nil </ruby> NOTE: Defined in +active_support/core_ext/string/access.rb+. @@ -1855,6 +1803,43 @@ Singular forms are aliased so you are able to say: NOTE: Defined in +active_support/core_ext/numeric/bytes.rb+. +h4. Time + +Enables the use of time calculations and declarations, like @45.minutes <plus> 2.hours <plus> 4.years@. + +These methods use Time#advance for precise date calculations when using from_now, ago, etc. +as well as adding or subtracting their results from a Time object. For example: + +<ruby> +# equivalent to Time.current.advance(:months => 1) +1.month.from_now + +# equivalent to Time.current.advance(:years => 2) +2.years.from_now + +# equivalent to Time.current.advance(:months => 4, :years => 5) +(4.months + 5.years).from_now +</ruby> + +While these methods provide precise calculation when used as in the examples above, care +should be taken to note that this is not true if the result of `months', `years', etc is +converted before use: + +<ruby> +# equivalent to 30.days.to_i.from_now +1.month.to_i.from_now + +# equivalent to 365.25.days.to_f.from_now +1.year.to_f.from_now +</ruby> + +In such cases, Ruby's core +Date[http://ruby-doc.org/stdlib/libdoc/date/rdoc/Date.html] and +Time[http://ruby-doc.org/stdlib/libdoc/time/rdoc/Time.html] should be used for precision +date and time arithmetic. + +NOTE: Defined in +active_support/core_ext/numeric/time.rb+. + h3. Extensions to +Integer+ h4. +multiple_of?+ @@ -2108,7 +2093,7 @@ h5. +to_formatted_s+ The method +to_formatted_s+ acts like +to_s+ by default. -If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs, though technically any object in Ruby 1.8 responds to +id+ indeed. Returned strings are: +If the array contains items that respond to +id+, however, it may be passed the symbol <tt>:db</tt> as argument. That's typically used with collections of ARs. Returned strings are: <ruby> [].to_formatted_s(:db) # => "null" @@ -2148,20 +2133,20 @@ To do so it sends +to_xml+ to every item in turn, and collects the results under By default, the name of the root element is the underscorized and dasherized plural of the name of the class of the first item, provided the rest of elements belong to that type (checked with <tt>is_a?</tt>) and they are not hashes. In the example above that's "contributors". -If there's any element that does not belong to the type of the first one the root node becomes "records": +If there's any element that does not belong to the type of the first one the root node becomes "objects": <ruby> [Contributor.first, Commit.first].to_xml # => # <?xml version="1.0" encoding="UTF-8"?> -# <records type="array"> -# <record> +# <objects type="array"> +# <object> # <id type="integer">4583</id> # <name>Aaron Batalion</name> # <rank type="integer">53</rank> # <url-id>aaron-batalion</url-id> -# </record> -# <record> +# </object> +# <object> # <author>Joshua Peek</author> # <authored-timestamp type="datetime">2009-09-02T16:44:36Z</authored-timestamp> # <branch>origin/master</branch> @@ -2172,30 +2157,30 @@ If there's any element that does not belong to the type of the first one the roo # <imported-from-svn type="boolean">false</imported-from-svn> # <message>Kill AMo observing wrap_with_notifications since ARes was only using it</message> # <sha1>723a47bfb3708f968821bc969a9a3fc873a3ed58</sha1> -# </record> -# </records> +# </object> +# </objects> </ruby> -If the receiver is an array of hashes the root element is by default also "records": +If the receiver is an array of hashes the root element is by default also "objects": <ruby> [{:a => 1, :b => 2}, {:c => 3}].to_xml # => # <?xml version="1.0" encoding="UTF-8"?> -# <records type="array"> -# <record> +# <objects type="array"> +# <object> # <b type="integer">2</b> # <a type="integer">1</a> -# </record> -# <record> +# </object> +# <object> # <c type="integer">3</c> -# </record> -# </records> +# </object> +# </objects> </ruby> WARNING. If the collection is empty the root element is by default "nil-classes". That's a gotcha, for example the root element of the list of contributors above would not be "contributors" if the collection was empty, but "nil-classes". You may use the <tt>:root</tt> option to ensure a consistent root element. -The name of children nodes is by default the name of the root node singularized. In the examples above we've seen "contributor" and "record". The option <tt>:children</tt> allows you to set these node names. +The name of children nodes is by default the name of the root node singularized. In the examples above we've seen "contributor" and "object". The option <tt>:children</tt> allows you to set these node names. The default XML builder is a fresh instance of <tt>Builder::XmlMarkup</tt>. You can configure your own builder via the <tt>:builder</tt> option. The method also accepts options like <tt>:dasherize</tt> and friends, they are forwarded to the builder: @@ -2564,6 +2549,38 @@ There's also the bang variant +except!+ that removes keys in the very receiver. NOTE: Defined in +active_support/core_ext/hash/except.rb+. +h5. +transform_keys+ and +transform_keys!+ + +The method +transform_keys+ accepts a block and returns a hash that has applied the block operations to each of the keys in the receiver: + +<ruby> +{nil => nil, 1 => 1, :a => :a}.transform_keys{ |key| key.to_s.upcase } +# => {"" => nil, "A" => :a, "1" => 1} +</ruby> + +The result in case of collision is undefined: + +<ruby> +{"a" => 1, :a => 2}.transform_keys{ |key| key.to_s.upcase } +# => {"A" => 2}, in my test, can't rely on this result though +</ruby> + +This method may be useful for example to build specialized conversions. For instance +stringify_keys+ and +symbolize_keys+ use +transform_keys+ to perform their key conversions: + +<ruby> +def stringify_keys + transform_keys{ |key| key.to_s } +end +... +def symbolize_keys + transform_keys{ |key| key.to_sym rescue key } +end +</ruby> + +There's also the bang variant +transform_keys!+ that applies the block operations to keys in the very receiver. + +NOTE: Defined in +active_support/core_ext/hash/keys.rb+. + h5. +stringify_keys+ and +stringify_keys!+ The method +stringify_keys+ returns a hash that has a stringified version of the keys in the receiver. It does so by sending +to_s+ to them: @@ -2594,6 +2611,13 @@ The second line can safely access the "type" key, and let the user to pass eithe There's also the bang variant +stringify_keys!+ that stringifies keys in the very receiver. +Besides that, one can use +deep_stringify_keys+ and +deep_stringify_keys!+ to stringify all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, :nested => {:a => 3, 5 => 5}}.deep_stringify_keys +# => {""=>nil, "1"=>1, "nested"=>{"a"=>3, "5"=>5}} +</ruby> + NOTE: Defined in +active_support/core_ext/hash/keys.rb+. h5. +symbolize_keys+ and +symbolize_keys!+ @@ -2628,6 +2652,13 @@ The second line can safely access the +:params+ key, and let the user to pass ei There's also the bang variant +symbolize_keys!+ that symbolizes keys in the very receiver. +Besides that, one can use +deep_symbolize_keys+ and +deep_symbolize_keys!+ to symbolize all the keys in the given hash and all the hashes nested into it. An example of the result is: + +<ruby> +{nil => nil, 1 => 1, "nested" => {"a" => 3, 5 => 5}}.deep_symbolize_keys +# => {nil=>nil, 1=>1, :nested=>{:a=>3, 5=>5}} +</ruby> + NOTE: Defined in +active_support/core_ext/hash/keys.rb+. h5. +to_options+ and +to_options!+ @@ -2768,36 +2799,27 @@ As the example depicts, the +:db+ format generates a +BETWEEN+ SQL clause. That NOTE: Defined in +active_support/core_ext/range/conversions.rb+. -h4. +step+ - -Active Support extends the method +Range#step+ so that it can be invoked without a block: - -<ruby> -(1..10).step(2) # => [1, 3, 5, 7, 9] -</ruby> - -As the example shows, in that case the method returns an array with the corresponding elements. - -NOTE: Defined in +active_support/core_ext/range/blockless_step.rb+. - h4. +include?+ -The method +Range#include?+ says whether some value falls between the ends of a given instance: +The methods +Range#include?+ and +Range#===+ say whether some value falls between the ends of a given instance: <ruby> (2..3).include?(Math::E) # => true </ruby> -Active Support extends this method so that the argument may be another range in turn. In that case we test whether the ends of the argument range belong to the receiver themselves: +Active Support extends these methods so that the argument may be another range in turn. In that case we test whether the ends of the argument range belong to the receiver themselves: <ruby> (1..10).include?(3..7) # => true (1..10).include?(0..7) # => false (1..10).include?(3..11) # => false (1...9).include?(3..9) # => false -</ruby> -WARNING: The original +Range#include?+ is still the one aliased to +Range#===+. +(1..10) === (3..7) # => true +(1..10) === (0..7) # => false +(1..10) === (3..11) # => false +(1...9) === (3..9) # => false +</ruby> NOTE: Defined in +active_support/core_ext/range/include_range.rb+. @@ -2893,8 +2915,6 @@ d.prev_year # => Sun, 28 Feb 1999 d.next_year # => Wed, 28 Feb 2001 </ruby> -Active Support defines these methods as well for Ruby 1.8. - +prev_year+ is aliased to +last_year+. h6. +prev_month+, +next_month+ @@ -2916,8 +2936,6 @@ Date.new(2000, 5, 31).next_month # => Fri, 30 Jun 2000 Date.new(2000, 1, 31).next_month # => Tue, 29 Feb 2000 </ruby> -Active Support defines these methods as well for Ruby 1.8. - +prev_month+ is aliased to +last_month+. h6. +beginning_of_week+, +end_of_week+ @@ -3127,18 +3145,38 @@ The method +beginning_of_day+ returns a timestamp at the beginning of the day (0 <ruby> date = Date.new(2010, 6, 7) -date.beginning_of_day # => Sun Jun 07 00:00:00 +0200 2010 +date.beginning_of_day # => Mon Jun 07 00:00:00 +0200 2010 </ruby> The method +end_of_day+ returns a timestamp at the end of the day (23:59:59): <ruby> date = Date.new(2010, 6, 7) -date.end_of_day # => Sun Jun 06 23:59:59 +0200 2010 +date.end_of_day # => Mon Jun 07 23:59:59 +0200 2010 </ruby> +beginning_of_day+ is aliased to +at_beginning_of_day+, +midnight+, +at_midnight+. +h6. +beginning_of_hour+, +end_of_hour+ + +The method +beginning_of_hour+ returns a timestamp at the beginning of the hour (hh:00:00): + +<ruby> +date = DateTime.new(2010, 6, 7, 19, 55, 25) +date.beginning_of_hour # => Mon Jun 07 19:00:00 +0200 2010 +</ruby> + +The method +end_of_hour+ returns a timestamp at the end of the hour (hh:59:59): + +<ruby> +date = DateTime.new(2010, 6, 7, 19, 55, 25) +date.end_of_hour # => Mon Jun 07 19:59:59 +0200 2010 +</ruby> + ++beginning_of_hour+ is aliased to +at_beginning_of_hour+. + +INFO: +beginning_of_hour+ and +end_of_hour+ are implemented for +Time+ and +DateTime+ but *not* +Date+ as it does not make sense to request the beginning or end of an hour on a +Date+ instance. + h6. +ago+, +since+ The method +ago+ receives a number of seconds as argument and returns a timestamp those many seconds ago from midnight: @@ -3206,6 +3244,13 @@ since (in) On the other hand, +advance+ and +change+ are also defined and support more options, they are documented below. +The following methods are only implemented in +active_support/core_ext/date_time/calculations.rb+ as they only make sense when used with a +DateTime+ instance: + +<ruby> +beginning_of_hour (at_beginning_of_hour) +end_of_hour +</ruby> + h5. Named Datetimes h6. +DateTime.current+ @@ -3348,6 +3393,8 @@ ago since (in) beginning_of_day (midnight, at_midnight, at_beginning_of_day) end_of_day +beginning_of_hour (at_beginning_of_hour) +end_of_hour beginning_of_week (at_beginning_of_week) end_of_week (at_end_of_week) monday diff --git a/guides/source/ajax_on_rails.textile b/guides/source/ajax_on_rails.textile index cda9c64460..bfd007490a 100644 --- a/guides/source/ajax_on_rails.textile +++ b/guides/source/ajax_on_rails.textile @@ -78,7 +78,7 @@ will produce <ruby> button_to('Destroy', 'http://www.example.com', :confirm => 'Are you sure?', - :method => "delete", :remote => true, :disable_with => 'loading...') + :method => "delete", :remote => true, 'data-disable-with' => 'loading...') </ruby> will produce @@ -87,7 +87,7 @@ will produce <form class='button_to' method='post' action='http://www.example.com' data-remote='true'> <div> <input name='_method' value='delete' type='hidden' /> - <input value='Destroy' type='submit' disable_with='loading...' data-confirm='Are you sure?' /> + <input value='Destroy' type='submit' data-disable-with='loading...' data-confirm='Are you sure?' /> </div> </form> </html> diff --git a/guides/source/asset_pipeline.textile b/guides/source/asset_pipeline.textile index 010154f1d1..105efe229e 100644 --- a/guides/source/asset_pipeline.textile +++ b/guides/source/asset_pipeline.textile @@ -396,7 +396,7 @@ Rails comes bundled with a rake task to compile the asset manifests and other fi Compiled assets are written to the location specified in +config.assets.prefix+. By default, this is the +public/assets+ directory. -You can call this task on the server during deployment to create compiled versions of your assets directly on the server. If you do not have write access to your production file system, you can call this task locally and then deploy the compiled assets. +You can call this task on the server during deployment to create compiled versions of your assets directly on the server. See the next section for information on compiling locally. The rake task is: @@ -516,6 +516,41 @@ If you're compiling nginx with Phusion Passenger you'll need to pass that option A robust configuration for Apache is possible but tricky; please Google around. (Or help update this Guide if you have a good example configuration for Apache.) +h4. Local Precompilation + +There are several reasons why you might want to precompile your assets locally. Among them are: + +* You may not have write access to your production file system. +* You may be deploying to more than one server, and want to avoid the duplication of work. +* You may be doing frequent deploys that do not include asset changes. + +Local compilation allows you to commit the compiled files into source control, and deploy as normal. + +There are two caveats: + +* You must not run the Capistrano deployment task that precompiles assets. +* You must change the following two application configuration settings. + +In <tt>config/environments/development.rb</tt>, place the following line: + +<erb> +config.assets.prefix = "/dev-assets" +</erb> + +You will also need this in application.rb: + +<erb> +config.assets.initialize_on_precompile = false +</erb> + +The +prefix+ change makes Rails use a different URL for serving assets in development mode, and pass all requests to Sprockets. The prefix is still set to +/assets+ in the production environment. Without this change, the application would serve the precompiled assets from +public/assets+ in development, and you would not see any local changes until you compile assets again. + +The +initialize_on_precompile+ change tells the precompile task to run without invoking Rails. This is because the precompile task runs in production mode by default, and will attempt to connect to your specified production database. Please note that you cannot have code in pipeline files that relies on Rails resources (such as the database) when compiling locally with this option. + +You will also need to ensure that any compressors or minifiers are available on your development system. + +In practice, this will allow you to precompile locally, have those files in your working tree, and commit those files to source control when needed. Development mode will work as expected. + h4. Live Compilation In some circumstances you may wish to use live compilation. In this mode all requests for assets in the pipeline are handled by Sprockets directly. diff --git a/guides/source/caching_with_rails.textile b/guides/source/caching_with_rails.textile index e455b504ce..34a100cd3a 100644 --- a/guides/source/caching_with_rails.textile +++ b/guides/source/caching_with_rails.textile @@ -229,6 +229,42 @@ class ProductsController < ActionController end </ruby> +Sometimes it is necessary to disambiguate the controller when you call +expire_action+, such as when there are two identically named controllers in separate namespaces: + +<ruby> +class ProductsController < ActionController + caches_action :index + + def index + @products = Product.all + end +end + +module Admin + class ProductsController < ActionController + cache_sweeper :product_sweeper + + def new + @product = Product.new + end + + def create + @product = Product.create(params[:product]) + end + end +end + +class ProductSweeper < ActionController::Caching::Sweeper + observe Product + + def after_create(product) + expire_action(:controller => '/products', :action => 'index') + end +end +</ruby> + +Note the use of '/products' here rather than 'products'. If you wanted to expire an action cache for the +Admin::ProductsController+, you would use 'admin/products' instead. + h4. SQL Caching Query caching is a Rails feature that caches the result set returned by each query so that if Rails encounters the same query again for that request, it will use the cached result set as opposed to running the query against the database again. diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile index 5629c82ca0..f114075cae 100644 --- a/guides/source/configuring.textile +++ b/guides/source/configuring.textile @@ -186,13 +186,13 @@ The full set of methods that can be used in this block are as follows: * +force_plural+ allows pluralized model names. Defaults to +false+. * +helper+ defines whether or not to generate helpers. Defaults to +true+. * +integration_tool+ defines which integration tool to use. Defaults to +nil+. -* +javascripts+ turns on the hook for javascripts in generators. Used in Rails for when the +scaffold+ generator is ran. Defaults to +true+. +* +javascripts+ turns on the hook for javascripts in generators. Used in Rails for when the +scaffold+ generator is run. Defaults to +true+. * +javascript_engine+ configures the engine to be used (for eg. coffee) when generating assets. Defaults to +nil+. * +orm+ defines which orm to use. Defaults to +false+ and will use Active Record by default. * +performance_tool+ defines which performance tool to use. Defaults to +nil+. * +resource_controller+ defines which generator to use for generating a controller when using +rails generate resource+. Defaults to +:controller+. * +scaffold_controller+ different from +resource_controller+, defines which generator to use for generating a _scaffolded_ controller when using +rails generate scaffold+. Defaults to +:scaffold_controller+. -* +stylesheets+ turns on the hook for stylesheets in generators. Used in Rails for when the +scaffold+ generator is ran, but this hook can be used in other generates as well. Defaults to +true+. +* +stylesheets+ turns on the hook for stylesheets in generators. Used in Rails for when the +scaffold+ generator is run, but this hook can be used in other generates as well. Defaults to +true+. * +stylesheet_engine+ configures the stylesheet engine (for eg. sass) to be used when generating assets. Defaults to +:css+. * +test_framework+ defines which test framework to use. Defaults to +false+ and will use Test::Unit by default. * +template_engine+ defines which template engine to use, such as ERB or Haml. Defaults to +:erb+. @@ -448,9 +448,9 @@ There are a few configuration options available in Active Support: * +config.active_support.bare+ enables or disables the loading of +active_support/all+ when booting Rails. Defaults to +nil+, which means +active_support/all+ is loaded. -* +config.active_support.escape_html_entities_in_json+ enables or disables the escaping of HTML entities in JSON serialization. Defaults to +true+. +* +config.active_support.escape_html_entities_in_json+ enables or disables the escaping of HTML entities in JSON serialization. Defaults to +false+. -* +config.active_support.use_standard_json_time_format+ enables or disables serializing dates to ISO 8601 format. Defaults to +false+. +* +config.active_support.use_standard_json_time_format+ enables or disables serializing dates to ISO 8601 format. Defaults to +true+. * +ActiveSupport::BufferedLogger.silencer+ is set to +false+ to disable the ability to silence logging in a block. The default is +true+. @@ -589,15 +589,15 @@ TIP: If you have any ordering dependency in your initializers, you can control t h3. Initialization events -Rails has 5 initialization events which can be hooked into (listed in the order that they are ran): +Rails has 5 initialization events which can be hooked into (listed in the order that they are run): * +before_configuration+: This is run as soon as the application constant inherits from +Rails::Application+. The +config+ calls are evaluated before this happens. * +before_initialize+: This is run directly before the initialization process of the application occurs with the +:bootstrap_hook+ initializer near the beginning of the Rails initialization process. -* +to_prepare+: Run after the initializers are ran for all Railties (including the application itself), but before eager loading and the middleware stack is built. More importantly, will run upon every request in +development+, but only once (during boot-up) in +production+ and +test+. +* +to_prepare+: Run after the initializers are run for all Railties (including the application itself), but before eager loading and the middleware stack is built. More importantly, will run upon every request in +development+, but only once (during boot-up) in +production+ and +test+. -* +before_eager_load+: This is run directly before eager loading occurs, which is the default behaviour for the _production_ environment and not for the +development+ environment. +* +before_eager_load+: This is run directly before eager loading occurs, which is the default behaviour for the +production+ environment and not for the +development+ environment. * +after_initialize+: Run directly after the initialization of the application, but before the application initializers are run. @@ -736,7 +736,7 @@ The error occurred while evaluating nil.each *+load_config_initializers+* Loads all Ruby files from +config/initializers+ in the application, railties and engines. The files in this directory can be used to hold configuration settings that should be made after all of the frameworks are loaded. -*+engines_blank_point+* Provides a point-in-initialization to hook into if you wish to do anything before engines are loaded. After this point, all railtie and engine initializers are ran. +*+engines_blank_point+* Provides a point-in-initialization to hook into if you wish to do anything before engines are loaded. After this point, all railtie and engine initializers are run. *+add_generator_templates+* Finds templates for generators at +lib/templates+ for the application, railities and engines and adds these to the +config.generators.templates+ setting, which will make the templates available for all generators to reference. diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile index df475a2359..a2254a550c 100644 --- a/guides/source/contributing_to_ruby_on_rails.textile +++ b/guides/source/contributing_to_ruby_on_rails.textile @@ -343,9 +343,39 @@ h4. Commit Your Changes When you're happy with the code on your computer, you need to commit the changes to git: <shell> -$ git commit -a -m "Here is a commit message on what I changed in this commit" +$ git commit -a </shell> +At this point, your editor should be fired up and you can write a message for this commit. Well formatted and descriptive commit messages are extremely helpful for the others, especially when figuring out why given change was made, so please take the time to write it. + +Good commit message should be formatted according to the following example: + +<plain> +Short summary (ideally 50 characters or less) + +More detailed description, if necessary. It should be wrapped to 72 +characters. Try to be as descriptive as you can, even if you think that +the commit content is obvious, it may not be obvious to others. You +should add such description also if it's already present in bug tracker, +it should not be necessary to visit a webpage to check the history. + +Description can have multiple paragraps and you can use code examples +inside, just indent it with 4 spaces: + + class PostsController + def index + respond_with Post.limit(10) + end + end + +You can also add bullet points: + +- you can use dashes or asterisks + +- also, try to indent next line of a point for readability, if it's too + long to fit in 72 characters +</plain> + TIP. Please squash your commits into a single commit when appropriate. This simplifies future cherry picks, and also keeps the git log clean. h4. Update Master diff --git a/guides/source/debugging_rails_applications.textile b/guides/source/debugging_rails_applications.textile index 903ed59e7b..45fa4ada78 100644 --- a/guides/source/debugging_rails_applications.textile +++ b/guides/source/debugging_rails_applications.textile @@ -124,7 +124,7 @@ h4. Log Levels When something is logged it's printed into the corresponding log if the log level of the message is equal or higher than the configured log level. If you want to know the current log level you can call the +Rails.logger.level+ method. -The available log levels are: +:debug+, +:info+, +:warn+, +:error+, and +:fatal+, corresponding to the log level numbers from 0 up to 4 respectively. To change the default log level, use +The available log levels are: +:debug+, +:info+, +:warn+, +:error+, +:fatal+, and +:unknown+, corresponding to the log level numbers from 0 up to 5 respectively. To change the default log level, use <ruby> config.log_level = :warn # In any environment initializer, or diff --git a/guides/source/engines.textile b/guides/source/engines.textile index 71bcf6b713..c35305a822 100644 --- a/guides/source/engines.textile +++ b/guides/source/engines.textile @@ -448,6 +448,8 @@ rake db:migrate SCOPE=blorgh VERSION=0 h4. Using a class provided by the application +h5. Using a model provided by the application + When an engine is created, it may want to use specific classes from an application to provide links between the pieces of the engine and the pieces of the application. In the case of the +blorgh+ engine, making posts and comments have authors would make a lot of sense. Usually, an application would have a +User+ class that would provide the objects that would represent the posts' and comments' authors, but there could be a case where the application calls this class something different, such as +Person+. It's because of this reason that the engine should not hardcode the associations to be exactly for a +User+ class, but should allow for some flexibility around what the class is called. @@ -544,6 +546,19 @@ end Now instead of the ugly Ruby object output the author's name will be displayed. +h5. Using a controller provided by the application + +Because Rails controllers generally share code for things like authentication and accessing session variables, by default they inherit from <tt>ApplicationController</tt>. Rails engines, however are scoped to run independently from the main application, so each engine gets a scoped +ApplicationController+. This namespace prevents code collisions, but often engine controllers should access methods in the main application's +ApplicationController+. An easy way to provide this access is to change the engine's scoped +ApplicationController+ to inherit from the main application's +ApplicationController+. For our Blorgh engine this would be done by changing +app/controllers/blorgh/application_controller.rb+ to look like: + +<ruby> +class Blorgh::ApplicationController < ApplicationController +end +</ruby> + +By default, the engine's controllers inherit from <tt>Blorgh::ApplicationController</tt>. So, after making this change they will have access to the main applications +ApplicationController+ as though they were part of the main application. + +This change does require that the engine is run from a Rails application that has an +ApplicationController+. + h4. Configuring an engine This section covers firstly how you can make the +user_class+ setting of the Blorgh engine configurable, followed by general configuration tips for the engine. @@ -723,7 +738,7 @@ This tells sprockets to add you engine assets when +rake assets:precompile+ is r You can define assets for precompilation in +engine.rb+ <ruby> -initializer do |app| +initializer "blorgh.assets.precompile" do |app| app.config.assets.precompile += %w(admin.css admin.js) end </ruby> diff --git a/guides/source/form_helpers.textile b/guides/source/form_helpers.textile index b6420db798..8106de6f9d 100644 --- a/guides/source/form_helpers.textile +++ b/guides/source/form_helpers.textile @@ -150,7 +150,7 @@ NOTE: Always use labels for checkbox and radio buttons. They associate text with h4. Other Helpers of Interest -Other form controls worth mentioning are textareas, password fields, hidden fields, search fields, telephone fields, date fields, URL fields and email fields: +Other form controls worth mentioning are textareas, password fields, hidden fields, search fields, telephone fields, date fields, time fields, color fields, datetime fields, datetime-local fields, month fields, week fields, URL fields and email fields: <erb> <%= text_area_tag(:message, "Hi, nice site", :size => "24x6") %> @@ -159,8 +159,14 @@ Other form controls worth mentioning are textareas, password fields, hidden fiel <%= search_field(:user, :name) %> <%= telephone_field(:user, :phone) %> <%= date_field(:user, :born_on) %> +<%= datetime_field(:user, :meeting_time) %> +<%= datetime_local_field(:user, :graduation_day) %> +<%= month_field(:user, :birthday_month) %> +<%= week_field(:user, :birthday_week) %> <%= url_field(:user, :homepage) %> <%= email_field(:user, :address) %> +<%= color_field(:user, :favorite_color) %> +<%= time_field(:task, :started_at) %> </erb> Output: @@ -172,13 +178,19 @@ Output: <input id="user_name" name="user[name]" type="search" /> <input id="user_phone" name="user[phone]" type="tel" /> <input id="user_born_on" name="user[born_on]" type="date" /> +<input id="user_meeting_time" name="user[meeting_time]" type="datetime" /> +<input id="user_graduation_day" name="user[graduation_day]" type="datetime-local" /> +<input id="user_birthday_month" name="user[birthday_month]" type="month" /> +<input id="user_birthday_week" name="user[birthday_week]" type="week" /> <input id="user_homepage" name="user[homepage]" type="url" /> <input id="user_address" name="user[address]" type="email" /> +<input id="user_favorite_color" name="user[favorite_color]" type="color" value="#000000" /> +<input id="task_started_at" name="task[started_at]" type="time" /> </html> Hidden inputs are not shown to the user but instead hold data like any textual input. Values inside them can be changed with JavaScript. -IMPORTANT: The search, telephone, date, URL, and email inputs are HTML5 controls. If you require your app to have a consistent experience in older browsers, you will need an HTML5 polyfill (provided by CSS and/or JavaScript). There is definitely "no shortage of solutions for this":https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills, although a couple of popular tools at the moment are "Modernizr":http://www.modernizr.com/ and "yepnope":http://yepnopejs.com/, which provide a simple way to add functionality based on the presence of detected HTML5 features. +IMPORTANT: The search, telephone, date, time, color, datetime, datetime-local, month, week, URL, and email inputs are HTML5 controls. If you require your app to have a consistent experience in older browsers, you will need an HTML5 polyfill (provided by CSS and/or JavaScript). There is definitely "no shortage of solutions for this":https://github.com/Modernizr/Modernizr/wiki/HTML5-Cross-Browser-Polyfills, although a couple of popular tools at the moment are "Modernizr":http://www.modernizr.com/ and "yepnope":http://yepnopejs.com/, which provide a simple way to add functionality based on the presence of detected HTML5 features. TIP: If you're using password input fields (for any purpose), you might want to configure your application to prevent those parameters from being logged. You can learn about this in the "Security Guide":security.html#logging. @@ -405,6 +417,8 @@ Whenever Rails sees that the internal value of an option being generated matches TIP: The second argument to +options_for_select+ must be exactly equal to the desired internal value. In particular if the value is the integer 2 you cannot pass "2" to +options_for_select+ -- you must pass 2. Be aware of values extracted from the +params+ hash as they are all strings. +WARNING: when +:inlude_blank+ or +:prompt:+ are not present, +:include_blank+ is forced true if the select attribute +required+ is true, display +size+ is one and +multiple+ is not true. + h4. Select Boxes for Dealing with Models In most cases form controls will be tied to a specific database model and as you might expect Rails provides helpers tailored for that purpose. Consistent with other form helpers, when dealing with models you drop the +_tag+ suffix from +select_tag+: @@ -469,7 +483,7 @@ Rails _used_ to have a +country_select+ helper for choosing countries, but this h3. Using Date and Time Form Helpers -You can choose not to use the form helpers generating HTML5 date input fields and use the alternative date and time helpers. These date and time helpers differ from all the other form helpers in two important respects: +You can choose not to use the form helpers generating HTML5 date and time input fields and use the alternative date and time helpers. These date and time helpers differ from all the other form helpers in two important respects: # Dates and times are not representable by a single input element. Instead you have several, one for each component (year, month, day etc.) and so there is no single value in your +params+ hash with your date or time. # Other helpers use the +_tag+ suffix to indicate whether a helper is a barebones helper or one that operates on model objects. With dates and times, +select_date+, +select_time+ and +select_datetime+ are the barebones helpers, +date_select+, +time_select+ and +datetime_select+ are the equivalent model object helpers. diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile index 947abd7ba0..e25dac22da 100644 --- a/guides/source/getting_started.textile +++ b/guides/source/getting_started.textile @@ -183,9 +183,9 @@ Rails will create several files for you. Most important of these are of course t Open the +app/views/welcome/index.html.erb+ file in your text editor and edit it to contain a single line of code: -<code class="html"> +<html> <h1>Hello, Rails!</h1> -</code> +</html> h4. Setting the Application Home Page @@ -193,7 +193,7 @@ Now that we have made the controller and view, we need to tell Rails when we wan To fix this, delete the +index.html+ file located inside the +public+ directory of the application. -You need to do this because Rails will serve any static file in the +public+ directory that matches a route in preference to any dynamic content you generate from the controllers. +You need to do this because Rails will serve any static file in the +public+ directory that matches a route in preference to any dynamic content you generate from the controllers. The +index.html+ file is special: it will be served if a request comes in at the root route, e.g. http://localhost:3000. If another request such as http://localhost:3000/welcome happened, a static file at <tt>public/welcome.html</tt> would be served first, but only if it existed. Next, you have to tell Rails where your actual home page is located. @@ -210,7 +210,7 @@ Blog::Application.routes.draw do The +root :to => "welcome#index"+ tells Rails to map requests to the root of the application to the welcome controller's index action. This was created earlier when you ran the controller generator (+rails generate controller welcome index+). -If you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see +Hello, Rails!+. +If you navigate to "http://localhost:3000":http://localhost:3000 in your browser, you'll see the +Hello, Rails!+ message you put into +app/views/welcome/index.html.erb+, indicating that this new route is indeed going to +WelcomeController+'s +index+ action and is rendering the view correctly. NOTE. For more information about routing, refer to "Rails Routing from the Outside In":routing.html. @@ -220,7 +220,7 @@ Now that you've seen how to create a controller, an action and a view, let's cre In the Blog application, you will now create a new _resource_. A resource is the term used for a collection of similar objects, such as posts, people or animals. You can create, read, update and destroy items for a resource and these operations are referred to as _CRUD_ operations. -In the next section, you will add the ability to create new posts in your application and be able to view them. This is the "CR" from CRUD. The form for doing this will look like this: +In the next section, you will add the ability to create new posts in your application and be able to view them. This is the "C" and the "R" from CRUD: creation and reading. The form for doing this will look like this: !images/getting_started/new_post.png(The new post form)! @@ -232,7 +232,7 @@ The first thing that you are going to need to create a new post within the appli !images/getting_started/routing_error_no_route_matches.png(A routing error, no route matches /posts/new)! -This is because there is nowhere inside the routes for the application -- defined inside +config/routes.rb+ -- that defines this route. By default, Rails has no routes configured at all, and so you must define your routes as you need them. +This is because there is nowhere inside the routes for the application -- defined inside +config/routes.rb+ -- that defines this route. By default, Rails has no routes configured at all, besides the root route you defined earlier, and so you must define your routes as you need them. To do this, you're going to need to create a route inside +config/routes.rb+ file, on a new line between the +do+ and the +end+ for the +draw+ method: @@ -282,9 +282,9 @@ You're getting this error now because Rails expects plain actions like this one In the above image, the bottom line has been truncated. Let's see what the full thing looks like: -<text> +<blockquote> Missing template posts/new, application/new with {:locale=>[:en], :formats=>[:html], :handlers=>[:erb, :builder, :coffee]}. Searched in: * "/path/to/blog/app/views" -</text> +</blockquote> That's quite a lot of text! Let's quickly go through and understand what each part of it does. @@ -330,11 +330,17 @@ method called +form_for+. To use this method, add this code into +app/views/post If you refresh the page now, you'll see the exact same form as in the example. Building forms in Rails is really just that easy! -When you call +form_for+, you pass it an identifying object for this form. In this case, it's the symbol +:post+. This tells the +form_for+ helper what this form is for. Inside the block for this method, the FormBuilder object -- represented by +f+ -- is used to build two labels and two text fields, one each for the title and text of a post. Finally, a call to +submit+ on the +f+ object will create a submit button for the form. +When you call +form_for+, you pass it an identifying object for this +form. In this case, it's the symbol +:post+. This tells the +form_for+ +helper what this form is for. Inside the block for this method, the ++FormBuilder+ object -- represented by +f+ -- is used to build two labels and two text fields, one each for the title and text of a post. Finally, a call to +submit+ on the +f+ object will create a submit button for the form. There's one problem with this form though. If you inspect the HTML that is generated, by viewing the source of the page, you will see that the +action+ attribute for the form is pointing at +/posts/new+. This is a problem because this route goes to the very page that you're on right at the moment, and that route should only be used to display the form for a new post. -So the form needs to use a different URL in order to go somewhere else. This can be done quite simply with the +:url+ option of +form_for+. Typically in Rails, the action that is used for new form submissions like this is called "create", and so the form should be pointed to this action. +The form needs to use a different URL in order to go somewhere else. +This can be done quite simply with the +:url+ option of +form_for+. +Typically in Rails, the action that is used for new form submissions +like this is called "create", and so the form should be pointed to that action. Edit the +form_for+ line inside +app/views/posts/new.html.erb+ to look like this: @@ -350,11 +356,11 @@ post "posts/create" By using the +post+ method rather than the +get+ method, Rails will define a route that will only respond to POST methods. The POST method is the typical method used by forms all over the web. -With the form and the route for it defined now, you will be able to fill in the form and then click the submit button to begin the process of creating a new post, so go ahead and do that. When you submit the form, you should see a familiar error: +With the form and its associated route defined, you will be able to fill in the form and then click the submit button to begin the process of creating a new post, so go ahead and do that. When you submit the form, you should see a familiar error: !images/getting_started/unknown_action_create_for_posts.png(Unknown action create for PostsController)! -You will now need to create the +create+ action within the +PostsController+ for this to work. +You now need to create the +create+ action within the +PostsController+ for this to work. h4. Creating posts @@ -381,7 +387,7 @@ def create end </ruby> -The +render+ method here is taking a very simple hash with the key of +text+ and the value of +params[:post].inspect+. The +params+ method here is the object which represents the parameters (or fields) coming in from the form. The +params+ method returns a +HashWithIndifferentAccess+ object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. +The +render+ method here is taking a very simple hash with a key of +text+ and value of +params[:post].inspect+. The +params+ method is the object which represents the parameters (or fields) coming in from the form. The +params+ method returns a +HashWithIndifferentAccess+ object, which allows you to access the keys of the hash using either strings or symbols. In this situation, the only parameters that matter are the ones from the form. If you re-submit the form one more time you'll now no longer get the missing template error. Instead, you'll see something that looks like the following: @@ -402,16 +408,22 @@ To create the new model, run this command in your terminal: $ rails generate model Post title:string text:text </shell> -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 +With that command we told Rails that we want a +Post+ model, together +with a _title_ attribute of type string, and a _text_ attribute of type text. Those attributes are automatically added to the +posts+ table in the database and mapped to the +Post+ model. -Rails in turn responded by creating a bunch of files. For +Rails responded by creating a bunch of files. For now, we're only interested in +app/models/post.rb+ and -+db/migrate/20120419084633_create_posts.rb+. The latter is responsible ++db/migrate/20120419084633_create_posts.rb+ (your name could be a bit +different). The latter is responsible for creating the database structure, which is what we'll look at next. +TIP: Active Record is smart enough to automatically map column names to +model attributes, which means you don't have to declare attributes +inside Rails models, as that will be done automatically by Active +Record. + h4. Running a Migration As we've just seen, +rails generate model+ created a _database @@ -472,8 +484,8 @@ invoking the command: +rake db:migrate RAILS_ENV=production+. h4. Saving data in the controller Back in +posts_controller+, we need to change the +create+ action -to use the new +Post+ model to save data in the database. Open that file -and change the +create+ action to look like the following: +to use the new +Post+ model to save the data in the database. Open that file +and change the +create+ action to look like this: <ruby> def create @@ -485,22 +497,21 @@ end </ruby> Here's what's going on: every Rails model can be initialized with its -respective attributes, which are automatically mapped to its +respective attributes, which are automatically mapped to the respective database columns. In the first line we do just that (remember that +params[:post]+ contains the attributes we're interested in). Then, +@post.save+ is responsible for saving the model in the database. -Finally, on the last line we redirect the user to the +show+ action, -wich we have not defined yet. +Finally, we redirect the user to the +show+ action, +wich we'll define later. TIP: As we'll see later, +@post.save+ returns a boolean indicating -wherever the model was saved or not, and you can (and usually do) take -different actions depending on the result of calling +@post.save+. +wherever the model was saved or not. -h4. Showing posts +h4. Showing Posts -Before trying to create a new post, let's add the +show+ action, which -will be responsible for showing our posts. Open +config/routes.rb+ -and add the following route: +If you submit the form again now, Rails will complain about not finding +the +show+ action. That's not very useful though, so let's add the ++show+ action before proceeding. Open +config/routes.rb+ and add the following route: <ruby> get "posts/:id" => "posts#show" @@ -549,19 +560,21 @@ be able to create a post. Try it! h4. Listing all posts We still need a way to list all our posts, so let's do that. As usual, -we'll need a route, a controller action, and a view: +we'll need a route placed into +config/routes.rb+: <ruby> -# Add to config/routes.rb get "posts" => "posts#index" +</ruby> + +And an action for that route inside the +PostsController+ in the +app/controllers/posts_controller.rb+ file: -# Add to app/controllers/posts_controller.rb +<ruby> def index @posts = Post.all end </ruby> -+app/view/posts/index.html.erb+: +And then finally a view for this action, located at +app/views/posts/index.html.erb+: <erb> <h1>Listing posts</h1> @@ -572,15 +585,17 @@ end <th>Text</th> </tr> -<% @posts.each do |post| %> - <tr> - <td><%= post.title %></td> - <td><%= post.text %></td> - </tr> -<% end %> + <% @posts.each do |post| %> + <tr> + <td><%= post.title %></td> + <td><%= post.text %></td> + </tr> + <% end %> </table> </erb> +Now if you go to +http://localhost:3000/posts+ you will see a list of all the posts that you have created. + h4. Adding links You can now create, show, and list posts. Now let's add some links to @@ -597,41 +612,25 @@ The +link_to+ method is one of Rails' built-in view helpers. It creates a hyperlink based on text to display and where to go - in this case, to the path for posts. -Let's add links to the other views as well. +Let's add links to the other views as well, starting with adding this "New Post" link to +app/views/posts/index.html.erb+, placing it above the +<table>+ tag: <erb> -# app/views/posts/index.html.erb - -<h1>Listing posts</h1> - <%= link_to 'New post', :action => :new %> +</erb> -<table> - <tr> - <th>Title</th> - <th>Text</th> - <th></th> - </tr> - -<% @posts.each do |post| %> - <tr> - <td><%= post.title %></td> - <td><%= post.text %></td> - <td><%= link_to 'Show', :action => :show, :id => post.id %></td> - </tr> -<% end %> -</table> - -# app/views/posts/new.html.erb +This link will allow you to bring up the form that lets you create a new post. You should also add a link to this template -- +app/views/posts/new.html.erb+ -- to go back to the +index+ action. Do this by adding this underneath the form in this template: +<erb> <%= form_for :post do |f| %> ... <% end %> <%= link_to 'Back', :action => :index %> +</erb> -# app/views/posts/show.html.erb +Finally, add another link to the +app/views/posts/show.html.erb+ template to go back to the +index+ action as well, so that people who are viewing a single post can go back and view the whole list again: +<erb> <p> <strong>Title:</strong> <%= @post.title %> @@ -653,7 +652,7 @@ TIP: In development mode (which is what you're working in by default), Rails reloads your application with every browser request, so there's no need to stop and restart the web server when a change is made. -h4. Adding Some Validation +h4. Allowing the update of fields The model file, +app/models/post.rb+ is about as simple as it can get: @@ -668,11 +667,28 @@ your Rails models for free, including basic database CRUD (Create, Read, Update, Destroy) operations, data validation, as well as sophisticated search support and the ability to relate multiple models to one another. +Rails includes methods to help you secure some of your model fields. +Open the +app/models/post.rb+ file and edit it: + +<ruby> +class Post < ActiveRecord::Base + attr_accessible :text, :title +end +</ruby> + +This change will ensure that all changes made through HTML forms can edit the content of the text and title fields. +It will not be possible to define any other field value through forms. You can still define them by calling the `field=` method of course. +Accessible attributes and the mass assignment problem is covered in details in the "Security guide":security.html#mass-assignment + +h4. Adding Some Validation + Rails includes methods to help you validate the data that you send to models. Open the +app/models/post.rb+ file and edit it: <ruby> class Post < ActiveRecord::Base + attr_accessible :text, :title + validates :title, :presence => true, :length => { :minimum => 5 } end @@ -684,9 +700,12 @@ format, and the existence of associated objects. Validations are covered in deta in "Active Record Validations and Callbacks":active_record_validations_callbacks.html#validations-overview -If you open +posts_controller+ again, you'll notice that we don't check -the result of calling +@post.save+. We need to change its behavior to -show the form back to the user if any error occur: +With the validation now in place, when you call +@post.save+ on an invalid +post, it will return +false+. If you open +app/controllers/posts_controller.rb+ +again, you'll notice that we don't check the result of calling +@post.save+ +inside the +create+ action. If +@post.save+ fails in this situation, we need to +show the form back to the user. To do this, change the +new+ and +create+ +actions inside +app/controllers/posts_controller.rb+ to these: <ruby> def new @@ -704,20 +723,18 @@ def create end </ruby> -Notice that I've also added +@post = Post.new+ to the +new+ action. I'll -explain why I did that in the next section, for now add that to your -controller as well. +The +new+ action is now creating a new instance variable called +@post+, and +you'll see why that is in just a few moments. -Also notice that we use +render+ instead of +redirect_to+ when +save+ -returns false. We can use +render+ so that the +@post+ object is passed -back to the view. +Notice that inside the +create+ action we use +render+ instead of +redirect_to+ when +save+ +returns +false+. The +render+ method is used so that the +@post+ object is passed back to the +new+ template when it is rendered. This rendering is done within the same request as the form submission, whereas the +redirect_to+ will tell the browser to issue another request. If you reload "http://localhost:3000/posts/new":http://localhost:3000/posts/new and try to save a post without a title, Rails will send you back to the form, but that's not very useful. You need to tell the user that something went wrong. To do that, you'll modify -+app/views/posts/index.html.erb+ to check for error messages: ++app/views/posts/new.html.erb+ to check for error messages: <erb> <%= form_for :post, :url => { :action => :create } do |f| %> @@ -754,9 +771,8 @@ A few things are going on. We check if there are any errors with +@post.errors.any?+, and in that case we show a list of all errors with +@post.errors.full_messages+. -+pluralize+ is a rails helper -that takes a number and a string as its arguments. If the number is -greater than one, the string will be automatically pluralized. ++pluralize+ is a rails helper that takes a number and a string as its +arguments. If the number is greater than one, the string will be automatically pluralized. The reason why we added +@post = Post.new+ in +posts_controller+ is that otherwise +@post+ would be +nil+ in our view, and calling @@ -766,7 +782,8 @@ TIP: Rails automatically wraps fields that contain an error with a div with class +field_with_errors+. You can define a css rule to make them standout. -Now you'll get a nice error message when saving a post without title: +Now you'll get a nice error message when saving a post without title when you +attempt to do just that on the "new post form(http://localhost:3000/posts/new)":http://localhost:3000/posts/new. !images/getting_started/form_with_errors.png(Form With Errors)! @@ -830,21 +847,23 @@ it look as follows: <%= link_to 'Back', :action => :index %> </erb> -This time we point the form to the +update+ action (not defined yet). +This time we point the form to the +update+ action, which is not defined yet +but will be very soon. + The +:method => :put+ option tells Rails that we want this form to be -submitted via +put+, which is the http method you're expected to use to +submitted via the +PUT+, HTTP method which is the HTTP method you're expected to use to *update* resources according to the REST protocol. TIP: By default forms built with the +form_for_ helper are sent via +POST+. -Moving on, we need to add the +update+ action. The file +Next, we need to add the +update+ action. The file +config/routes.rb+ will need just one more line: <ruby> put "posts/:id" => "posts#update" </ruby> -And the +update+ action in +posts_controller+ itself should not look too complicated by now: +And then create the +update+ action in +app/controllers/posts_controller.rb+: <ruby> def update @@ -858,7 +877,7 @@ def update end </ruby> -The new method +update_attributes+ is used when you want to update a record +The new method, +update_attributes+, is used when you want to update a record that already exists, and it accepts an hash containing the attributes that you want to update. As before, if there was an error updating the post we want to show the form back to the user. @@ -868,11 +887,11 @@ example, if you'd call +@post.update_attributes(:title => 'A new title')+ Rails would only update the +title+ attribute, leaving all other attributes untouched. -Finally, we want to show a link to the +edit+ action in the +index+ and -+show+ views: +Finally, we want to show a link to the +edit+ action in the list of all the +posts, so let's add that now to +app/views/posts/index.html.erb+ to make it +appear next to the "Show" link: <erb> -# app/view/posts/index.html.erb <table> <tr> @@ -891,11 +910,16 @@ Finally, we want to show a link to the +edit+ action in the +index+ and </tr> <% end %> </table> +</erb> -# app/view/posts/show.html.erb +And we'll also add one to the +app/views/posts/show.html.erb+ template as well, +so that there's also an "Edit" link on a post's page. Add this at the bottom of +the template: +<erb> ... + <%= link_to 'Back', :action => :index %> | <%= link_to 'Edit', :action => :edit, :id => @post.id %> </erb> @@ -924,8 +948,8 @@ simple example: <%= @user.about_me %> </erb> -The +show+ view will automatically include the content of the -+_user_details+ view. Note that partials are prefixed by an underscore, +The +users/show+ template will automatically include the content of the ++users/_user_details+ template. Note that partials are prefixed by an underscore, as to not be confused with regular views. However, you don't include the underscore when including them with the +helper+ method. @@ -934,7 +958,7 @@ Rails":layouts_and_rendering.html guide. Our +edit+ action looks very similar to the +new+ action, in fact they both share the same code for displaying the form. Lets clean them up by -using a +_form+ partial. +using a partial. Create a new file +app/views/posts/_form.html.erb+ with the following content: @@ -944,7 +968,7 @@ content: <% if @post.errors.any? %> <div id="errorExplanation"> <h2><%= pluralize(@post.errors.count, "error") %> prohibited - this post from being saved:</h2> + this post from being saved:</h2> <ul> <% @post.errors.full_messages.each do |msg| %> <li><%= msg %></li> @@ -968,23 +992,23 @@ content: <% end %> </erb> -Everything except for the +form_for+ declaration remained the same. I'll -explain later how +form_for+ can figure out the right +action+ and -+method+ attributes when building the form, for now let's update the -+new+ and +edit+ views: +Everything except for the +form_for+ declaration remained the same. +How +form_for+ can figure out the right +action+ and +method+ attributes +when building the form will be explained in just a moment. For now, let's update the ++app/views/posts/new.html.erb+ view to use this new partial, rewriting it +completely: <erb> -# app/views/posts/new.html.erb - <h1>New post</h1> <%= render 'form' %> <%= link_to 'Back', :action => :index %> +</erb> +Then do the same for the +app/views/posts/edit.html.erb+ view: -# app/views/posts/edit.html.erb - +<erb> <h1>Edit post</h1> <%= render 'form' %> @@ -992,8 +1016,7 @@ explain later how +form_for+ can figure out the right +action+ and <%= link_to 'Back', :action => :index %> </erb> -Point your browser to -"http://localhost:3000/posts/new":http://localhost:3000/posts/new and +Point your browser to "http://localhost:3000/posts/new":http://localhost:3000/posts/new and try creating a new post. Everything still works. Now try editing the post and you'll receive the following error: @@ -1011,7 +1034,8 @@ knows that it should create new objects via POST and update them via PUT. If you run +rake routes+ from the console you'll see that we already -have a +posts_path+ route, which was created automatically by Rails. +have a +posts_path+ route, which was created automatically by Rails when we +defined the route for the index action. However, we don't have a +post_path+ yet, which is the reason why we received an error before. @@ -1034,26 +1058,37 @@ line like this: get "posts/:id" => "posts#show", :as => :post </ruby> -Now you'll be able to update posts again. +The +:as+ option tells the +get+ method that we want to make routing helpers +called +post_url+ and +post_path+ available to our application. These are +precisely the methods that the +form_for+ needs when editing a post, and so now +you'll be able to update posts again. + +NOTE: The +:as+ option is available on the +post+, +put+, +delete+ and +match+ +routing methods also. h4. Deleting Posts We're now ready to cover the "D" part of CRUD, deleting posts from the database. Following the REST convention, we're going to add a route for -deleting posts: +deleting posts to +config/routes.rb+: <ruby> -# config/routes.rb - delete "posts/:id" => "posts#destroy" </ruby> -We use the +delete+ method for destroying resources, which is mapped to -the +destroy+ action, which is provided below: +The +delete+ routing method should be used for routes that destroy +resources. If this was left as a typical +get+ route, it could be possible for +people to craft malicious URLs like this: -<ruby> -# app/controllers/posts_controller.rb +<html> +<a href='http://yoursite.com/posts/1/destroy'>look at this cat!</a> +</html> +We use the +delete+ method for destroying resources, and this route is mapped to +the +destroy+ action inside +app/controllers/posts_controller.rb+, which doesn't exist yet, but is +provided below: + +<ruby> def destroy @post = Post.find(params[:id]) @post.destroy @@ -1063,13 +1098,15 @@ end </ruby> You can call +destroy+ on Active Record objects when you want to delete -them from the dabase. Note that we don't need to add a view for this +them from the database. Note that we don't need to add a view for this action since we're redirecting to the +index+ action. -Finally, add a 'destroy' link to your +index+ action to wrap everything +Finally, add a 'destroy' link to your +index+ action template +(+app/views/posts/index.html.erb) to wrap everything together. <erb> +<h1>Listing Posts</h1> <table> <tr> <th>Title</th> @@ -1092,11 +1129,14 @@ together. </erb> Here we're using +link_to+ in a different way. We wrap the -+:action+ and +:id+ attributes in a hash so that we can pass other -arguments to +link_to+. The +:method+ and +:confirm+ ++:action+ and +:id+ attributes in a hash so that we can pass those two keys in +first as one argument, and then the final two keys as another argument. The +:method+ and +:confirm+ options are used as html5 attributes so that when the click is linked, Rails will first show a confirm dialog to the user, and then submit the -link with method +delete+. This is done via javascript automatically. +link with method +delete+. This is done via the JavaScript file +jquery_ujs+ +which is automatically included into your application's layout +(+app/views/layouts/application.html.erb+) when you generated the application. +Without this file, the confirmation dialog box wouldn't appear. !images/getting_started/confirm_dialog.png(Confirm Dialog)! @@ -1136,7 +1176,7 @@ end </ruby> 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. +declared before are still available: <shell> # rake routes @@ -1150,18 +1190,22 @@ edit_post GET /posts/:id/edit(.:format) posts#edit root / welcome#index </shell> +Also, if you go through the motions of creating, updating and deleting +posts the app still works as before. + TIP: In general, Rails encourages the use of resources objects in place -of declaring routes manually. For more information about routing, see +of declaring routes manually. It was only done in this guide as a learning +exercise. For more information about routing, see "Rails Routing from the Outside In":routing.html. h3. Adding a Second Model It's time to add a second model to the application. The second model will handle comments on -blog posts. +posts. h4. Generating a Model -We're going to se the same generator that we used before when creating +We're going to see 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: @@ -1321,7 +1365,7 @@ So first, we'll wire up the Post show template <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Add a comment:</h2> @@ -1344,7 +1388,10 @@ So first, we'll wire up the Post show template </erb> This adds a form on the +Post+ show page that creates a new comment by -calling the +CommentsController+ +create+ action. Let's wire that up: +calling the +CommentsController+ +create+ action. The +form_for+ call here uses +an array, which will build a nested route, such as +/posts/1/comments+. + +Let's wire up the +create+: <ruby> class CommentsController < ApplicationController @@ -1380,7 +1427,7 @@ template. This is where we want the comment to show, so let's add that to the <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Comments</h2> @@ -1428,7 +1475,7 @@ use partials to clean it up. h4. Rendering Partial Collections -First we will make a comment partial to extract showing all the comments for the +First, we will make a comment partial to extract showing all the comments for the post. Create the file +app/views/comments/_comment.html.erb+ and put the following into it: @@ -1455,7 +1502,7 @@ following: <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Comments</h2> @@ -1517,7 +1564,7 @@ Then you make the +app/views/posts/show.html.erb+ look like the following: <p> <strong>Text:</strong> - <%= @post.texthttp://beginningruby.org/ %> + <%= @post.text %> </p> <h2>Add a comment:</h2> diff --git a/guides/source/i18n.textile b/guides/source/i18n.textile index 6179694c40..ee7176a6c8 100644 --- a/guides/source/i18n.textile +++ b/guides/source/i18n.textile @@ -127,7 +127,7 @@ If you want to translate your Rails application to a *single language other than However, you would probably like to *provide support for more locales* in your application. In such case, you need to set and pass the locale between requests. -WARNING: You may be tempted to store the chosen locale in a _session_ or a <em>cookie</em>. *Do not do so*. The locale should be transparent and a part of the URL. This way you don't break people's basic assumptions about the web itself: if you send a URL of some page to a friend, she should see the same page, same content. A fancy word for this would be that you're being "<em>RESTful</em>":http://en.wikipedia.org/wiki/Representational_State_Transfer. Read more about the RESTful approach in "Stefan Tilkov's articles":http://www.infoq.com/articles/rest-introduction. There may be some exceptions to this rule, which are discussed below. +WARNING: You may be tempted to store the chosen locale in a _session_ or a <em>cookie</em>, however *do not do this*. The locale should be transparent and a part of the URL. This way you won't break people's basic assumptions about the web itself: if you send a URL to a friend, they should see the same page and content as you. A fancy word for this would be that you're being "<em>RESTful</em>":http://en.wikipedia.org/wiki/Representational_State_Transfer. Read more about the RESTful approach in "Stefan Tilkov's articles":http://www.infoq.com/articles/rest-introduction. Sometimes there are exceptions to this rule and those are discussed below. The _setting part_ is easy. You can set the locale in a +before_filter+ in the +ApplicationController+ like this: @@ -220,7 +220,7 @@ Every helper method dependent on +url_for+ (e.g. helpers for named routes like + You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this. -You probably want URLs to look like this: +www.example.com/en/books+ (which loads the English locale) and +www.example.com/nl/books+ (which loads the Netherlands locale). This is achievable with the "over-riding +default_url_options+" strategy from above: you just have to set up your routes with "+path_prefix+":http://api.rubyonrails.org/classes/ActionController/Resources.html#M000354 option in this way: +You probably want URLs to look like this: +www.example.com/en/books+ (which loads the English locale) and +www.example.com/nl/books+ (which loads the Dutch locale). This is achievable with the "over-riding +default_url_options+" strategy from above: you just have to set up your routes with "+path_prefix+":http://api.rubyonrails.org/classes/ActionController/Resources.html#M000354 option in this way: <ruby> # config/routes.rb @@ -229,7 +229,7 @@ scope "/:locale" do end </ruby> -Now, when you call the +books_path+ method you should get +"/en/books"+ (for the default locale). An URL like +http://localhost:3001/nl/books+ should load the Netherlands locale, then, and following calls to +books_path+ should return +"/nl/books"+ (because the locale changed). +Now, when you call the +books_path+ method you should get +"/en/books"+ (for the default locale). An URL like +http://localhost:3001/nl/books+ should load the Dutch locale, then, and following calls to +books_path+ should return +"/nl/books"+ (because the locale changed). If you don't want to force the use of a locale in your routes you can use an optional path scope (denoted by the parentheses) like so: diff --git a/guides/source/initialization.textile b/guides/source/initialization.textile index 69e5c1edcc..155a439e64 100644 --- a/guides/source/initialization.textile +++ b/guides/source/initialization.textile @@ -137,8 +137,6 @@ h4. +config/boot.rb+ +config/boot.rb+ contains this: <ruby> -require 'rubygems' - # Set up gems listed in the Gemfile. gemfile = File.expand_path('../../Gemfile', __FILE__) begin diff --git a/guides/source/layouts_and_rendering.textile b/guides/source/layouts_and_rendering.textile index e4a1fd6951..b0a87a5981 100644 --- a/guides/source/layouts_and_rendering.textile +++ b/guides/source/layouts_and_rendering.textile @@ -860,12 +860,6 @@ You can supply a hash of additional HTML options: <%= image_tag "icons/delete.gif", {:height => 45} %> </erb> -You can also supply an alternate image to show on mouseover: - -<erb> -<%= image_tag "home.gif", :onmouseover => "menu/home_highlight.gif" %> -</erb> - You can supply alternate text for the image which will be used if the user has images turned off in their browser. If you do not specify an alt text explicitly, it defaults to the file name of the file, capitalized and with no extension. For example, these two image tags would return the same code: <erb> diff --git a/guides/source/migrations.textile b/guides/source/migrations.textile index f855072fd8..52dba76e68 100644 --- a/guides/source/migrations.textile +++ b/guides/source/migrations.textile @@ -737,9 +737,7 @@ column. class AddFlagToProduct < ActiveRecord::Migration def change add_column :products, :flag, :boolean - Product.all.each do |product| - product.update_attributes!(:flag => false) - end + Product.update_all :flag => false end end </ruby> @@ -762,9 +760,7 @@ column. class AddFuzzToProduct < ActiveRecord::Migration def change add_column :products, :fuzz, :string - Product.all.each do |product| - product.update_attributes! :fuzz => 'fuzzy' - end + Product.update_all :fuzz => 'fuzzy' end end </ruby> @@ -816,9 +812,7 @@ class AddFlagToProduct < ActiveRecord::Migration def change add_column :products, :flag, :boolean Product.reset_column_information - Product.all.each do |product| - product.update_attributes!(:flag => false) - end + Product.update_all :flag => false end end </ruby> @@ -833,9 +827,7 @@ class AddFuzzToProduct < ActiveRecord::Migration def change add_column :products, :fuzz, :string Product.reset_column_information - Product.all.each do |product| - product.update_attributes!(:fuzz => 'fuzzy') - end + Product.update_all :fuzz => 'fuzzy' end end </ruby> diff --git a/guides/source/rails_on_rack.textile b/guides/source/rails_on_rack.textile index ff862273fd..d8910cf1d0 100644 --- a/guides/source/rails_on_rack.textile +++ b/guides/source/rails_on_rack.textile @@ -152,9 +152,9 @@ You can swap an existing middleware in the middleware stack using +config.middle config.middleware.swap ActionDispatch::ShowExceptions, Lifo::ShowExceptions </ruby> -h5. Middleware Stack is an Array +h5. Middleware Stack is an Enumerable -The middleware stack behaves just like a normal +Array+. You can use any +Array+ methods to insert, reorder, or remove items from the stack. Methods described in the section above are just convenience methods. +The middleware stack behaves just like a normal +Enumerable+. You can use any +Enumerable+ methods to manipulate or interrogate the stack. The middleware stack also implements some +Array+ methods including <tt>[]</tt>, +unshift+ and +delete+. Methods described in the section above are just convenience methods. Append following lines to your application configuration: diff --git a/guides/source/security.textile b/guides/source/security.textile index ac64b82bf6..ac55d60368 100644 --- a/guides/source/security.textile +++ b/guides/source/security.textile @@ -627,7 +627,7 @@ h4. Whitelists versus Blacklists -- _When sanitizing, protecting or verifying something, whitelists over blacklists._ -A blacklist can be a list of bad e-mail addresses, non-public actions or bad HTML tags. This is opposed to a whitelist which lists the good e-mail addresses, public actions, good HTML tags and so on. Although, sometimes it is not possible to create a whitelist (in a SPAM filter, for example), _(highlight)prefer to use whitelist approaches_: +A blacklist can be a list of bad e-mail addresses, non-public actions or bad HTML tags. This is opposed to a whitelist which lists the good e-mail addresses, public actions, good HTML tags and so on. Although sometimes it is not possible to create a whitelist (in a SPAM filter, for example), _(highlight)prefer to use whitelist approaches_: * Use before_filter :only => [...] instead of :except => [...]. This way you don't forget to turn it off for newly added actions. * Use attr_accessible instead of attr_protected. See the mass-assignment section for details diff --git a/guides/source/upgrading_ruby_on_rails.textile b/guides/source/upgrading_ruby_on_rails.textile index 2b2e65c813..02407a5fe8 100644 --- a/guides/source/upgrading_ruby_on_rails.textile +++ b/guides/source/upgrading_ruby_on_rails.textile @@ -42,6 +42,10 @@ 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>. +h4(#action_pack4_0). ActionPack + +Rails 4.0 changed how <tt>assert_generates</tt>, <tt>assert_recognizes</tt>, and <tt>assert_routing</tt> work. Now all these assertions raise <tt>Assertion</tt> instead of <tt>RoutingError</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. |