diff options
Diffstat (limited to 'guides/source')
26 files changed, 343 insertions, 139 deletions
diff --git a/guides/source/4_0_release_notes.textile b/guides/source/4_0_release_notes.textile index d545798f6f..2f21f8cc71 100644 --- a/guides/source/4_0_release_notes.textile +++ b/guides/source/4_0_release_notes.textile @@ -82,8 +82,6 @@ will generate the model with <tt>belongs_to :supplier, polymorphic: true</tt> as * Load all environments available in <tt>config.paths["config/environments"]</tt>. -* The application generator generates <tt>public/humans.txt</tt> with some basic data. - * Add <tt>config.queue_consumer</tt> to allow the default consumer to be configurable. * Add <tt>Rails.queue</tt> as an interface with a default implementation that consumes jobs in a separate thread. @@ -196,6 +194,37 @@ h5(#actioncontroller_deprecations). Deprecations h4. Action Dispatch +* Add Routing Concerns to declare common routes that can be reused inside others resources and routes. + +Code before: + +<ruby> +resources :messages do + resources :comments +end + +resources :posts do + resources :comments + resources :images, only: :index +end +</ruby> + +Code after: + +<ruby> +concern :commentable do + resources :comments +end + +concern :image_attachable do + resources :images, only: :index +end + +resources :messages, concerns: :commentable + +resources :posts, concerns: [:commentable, :image_attachable] +</ruby> + * Show routes in exception page while debugging a <tt>RoutingError</tt> in development. * Include <tt>mounted_helpers</tt> (helpers for accessing mounted engines) in <tt>ActionDispatch::IntegrationTest</tt> by default. @@ -747,6 +776,8 @@ h3. Active Resource h3. Active Support +* Add default values to all <tt>ActiveSupport::NumberHelper</tt> methods, to avoid errors with empty locales or missing values. + * <tt>Time#change</tt> now works with time values with offsets other than UTC or the local time zone. * Add <tt>Time#prev_quarter</tt> and <tt>Time#next_quarter</tt> short-hands for <tt>months_ago(3)</tt> and <tt>months_since(3)</tt>. diff --git a/guides/source/action_controller_overview.textile b/guides/source/action_controller_overview.textile index cc3350819b..67c9044d91 100644 --- a/guides/source/action_controller_overview.textile +++ b/guides/source/action_controller_overview.textile @@ -278,26 +278,31 @@ To reset the entire session, use +reset_session+. h4. The Flash -The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let's use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request: +The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for passing error messages etc. + +It is accessed in much the same way as the session, as a hash (it's a "FlashHash":http://api.rubyonrails.org/classes/ActionDispatch/Flash/FlashHash.html instance). + +Let's use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request: <ruby> class LoginsController < ApplicationController def destroy session[:current_user_id] = nil - flash[:notice] = "You have successfully logged out" + flash[:notice] = "You have successfully logged out." redirect_to root_url end end </ruby> -Note it is also possible to assign a flash message as part of the redirection. +Note that it is also possible to assign a flash message as part of the redirection. You can assign +:notice+, +:alert+ or the general purpose +:flash+: <ruby> -redirect_to root_url, :notice => "You have successfully logged out" +redirect_to root_url, :notice => "You have successfully logged out." +redirect_to root_url, :alert => "You're stuck here!" +redirect_to root_url, :flash => { :referral_code => 1234 } </ruby> - -The +destroy+ action redirects to the application's +root_url+, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display eventual errors or notices from the flash in the application's layout: +The +destroy+ action redirects to the application's +root_url+, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display any error alerts or notices from the flash in the application's layout: <ruby> <html> @@ -306,15 +311,23 @@ The +destroy+ action redirects to the application's +root_url+, where the messag <% if flash[:notice] %> <p class="notice"><%= flash[:notice] %></p> <% end %> - <% if flash[:error] %> - <p class="error"><%= flash[:error] %></p> + <% if flash[:alert] %> + <p class="alert"><%= flash[:alert] %></p> <% end %> <!-- more content --> </body> </html> </ruby> -This way, if an action sets an error or a notice message, the layout will display it automatically. +This way, if an action sets a notice or an alert message, the layout will display it automatically. + +You can pass anything that the session can store; you're not limited to notices and alerts: + +<ruby> +<% if flash[:just_signed_up] %> + <p class="welcome">Welcome to our site!</p> +<% end %> +</ruby> If you want a flash value to be carried over to another request, use the +keep+ method: @@ -478,9 +491,9 @@ class ChangesController < ActionController::Base end </ruby> -Note that an around filter wraps also rendering. In particular, if in the example above the view itself reads from the database via a scope or whatever, it will do so within the transaction and thus present the data to preview. +Note that an around filter also wraps rendering. In particular, if in the example above, the view itself reads from the database (e.g. via a scope), it will do so within the transaction and thus present the data to preview. -They can choose not to yield and build the response themselves, in which case the action is not run. +You can choose not to yield and build the response yourself, in which case the action will not be run. h4. Other Ways to Use Filters diff --git a/guides/source/action_mailer_basics.textile b/guides/source/action_mailer_basics.textile index 35288a0a1e..bca403ae72 100644 --- a/guides/source/action_mailer_basics.textile +++ b/guides/source/action_mailer_basics.textile @@ -4,7 +4,7 @@ This guide should provide you with all you need to get started in sending and re endprologue. -WARNING. This Guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails. +WARNING. This guide is based on Rails 3.2. Some of the code shown here will not work in earlier versions of Rails. h3. Introduction @@ -84,7 +84,7 @@ Create a file called +welcome_email.html.erb+ in +app/views/user_mailer/+. This </html> </erb> -It is also a good idea to make a text part for this email, to do this, create a file called +welcome_email.text.erb+ in +app/views/user_mailer/+: +It is also a good idea to make a text part for this email. To do this, create a file called +welcome_email.text.erb+ in +app/views/user_mailer/+: <erb> Welcome to example.com, <%= @user.name %> @@ -144,7 +144,7 @@ The method +welcome_email+ returns a <tt>Mail::Message</tt> object which can the NOTE: In previous versions of Rails, you would call +deliver_welcome_email+ or +create_welcome_email+. This has been deprecated in Rails 3.0 in favour of just calling the method name itself. -WARNING: Sending out an email should only take a fraction of a second, but if you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like Delayed Job. +WARNING: Sending out an email should only take a fraction of a second. If you are planning on sending out many emails, or you have a slow domain resolution service, you might want to investigate using a background process like Delayed Job. h4. Auto encoding header values @@ -152,14 +152,14 @@ Action Mailer now handles the auto encoding of multibyte characters inside of he If you are using UTF-8 as your character set, you do not have to do anything special, just go ahead and send in UTF-8 data to the address fields, subject, keywords, filenames or body of the email and Action Mailer will auto encode it into quoted printable for you in the case of a header field or Base64 encode any body parts that are non US-ASCII. -For more complex examples such as defining alternate character sets or self encoding text first, please refer to the Mail library. +For more complex examples such as defining alternate character sets or self-encoding text first, please refer to the Mail library. h4. Complete List of Action Mailer Methods There are just three methods that you need to send pretty much any email message: -* <tt>headers</tt> - Specifies any header on the email you want, you can pass a hash of header field names and value pairs, or you can call <tt>headers[:field_name] = 'value'</tt> -* <tt>attachments</tt> - Allows you to add attachments to your email, for example <tt>attachments['file-name.jpg'] = File.read('file-name.jpg')</tt> +* <tt>headers</tt> - Specifies any header on the email you want. You can pass a hash of header field names and value pairs, or you can call <tt>headers[:field_name] = 'value'</tt>. +* <tt>attachments</tt> - Allows you to add attachments to your email. For example, <tt>attachments['file-name.jpg'] = File.read('file-name.jpg')</tt>. * <tt>mail</tt> - Sends the actual email itself. You can pass in headers as a hash to the mail method as a parameter, mail will then create an email, either plain text, or multipart, depending on what email templates you have defined. h5. Custom Headers @@ -184,7 +184,7 @@ headers["X-Spam"] = value headers {"X-Spam" => value, "X-Special" => another_value} </ruby> -TIP: All <tt>X-Value</tt> headers per the RFC2822 can appear more than one time. If you want to delete an <tt>X-Value</tt> header, you need to assign it a value of <tt>nil</tt>. +TIP: All <tt>X-Value</tt> headers per the RFC2822 can appear more than once. If you want to delete an <tt>X-Value</tt> header, you need to assign it a value of <tt>nil</tt>. h5. Adding Attachments @@ -196,7 +196,7 @@ Adding attachments has been simplified in Action Mailer 3.0. attachments['filename.jpg'] = File.read('/path/to/filename.jpg') </ruby> -NOTE: Mail will automatically Base64 encode an attachment, if you want something different, pre-encode your content and pass in the encoded content and encoding in a +Hash+ to the +attachments+ method. +NOTE: Mail will automatically Base64 encode an attachment. If you want something different, pre-encode your content and pass in the encoded content and encoding in a +Hash+ to the +attachments+ method. * Pass the file name and specify headers and content and Action Mailer and Mail will use the settings you pass in. @@ -229,7 +229,7 @@ end <%= image_tag attachments['image.jpg'].url %> </erb> -* As this is a standard call to +image_tag+ you can pass in an options hash after the attachment url as you could for any other image: +* As this is a standard call to +image_tag+ you can pass in an options hash after the attachment URL as you could for any other image: <erb> <p>Hello there, this is our image</p> @@ -240,7 +240,7 @@ end h5. Sending Email To Multiple Recipients -It is possible to send email to one or more recipients in one email (for e.g. informing all admins of a new signup) by setting the list of emails to the <tt>:to</tt> key. The list of emails can be an array of email addresses or a single string with the addresses separated by commas. +It is possible to send email to one or more recipients in one email (e.g., informing all admins of a new signup) by setting the list of emails to the <tt>:to</tt> key. The list of emails can be an array of email addresses or a single string with the addresses separated by commas. <ruby> class AdminMailer < ActionMailer::Base diff --git a/guides/source/active_model_basics.textile b/guides/source/active_model_basics.textile index 7cafff2ad8..2c30ddb84c 100644 --- a/guides/source/active_model_basics.textile +++ b/guides/source/active_model_basics.textile @@ -1,18 +1,18 @@ h2. Active Model Basics -This guide should provide you with all you need to get started using model classes. Active Model allow for Action Pack helpers to interact with non-ActiveRecord models. Active Model also helps building custom ORMs for use outside of the Rails framework. +This guide should provide you with all you need to get started using model classes. Active Model allows for Action Pack helpers to interact with non-ActiveRecord models. Active Model also helps building custom ORMs for use outside of the Rails framework. endprologue. -WARNING. This Guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails. +WARNING. This guide is based on Rails 3.0. Some of the code shown here will not work in earlier versions of Rails. h3. Introduction -Active Model is a library containing various modules used in developing frameworks that need to interact with the Rails Action Pack library. Active Model provides a known set of interfaces for usage in classes. Some of modules are explained below - +Active Model is a library containing various modules used in developing frameworks that need to interact with the Rails Action Pack library. Active Model provides a known set of interfaces for usage in classes. Some of modules are explained below. h4. AttributeMethods -AttributeMethods module can add custom prefixes and suffixes on methods of a class. It is used by defining the prefixes and suffixes, which methods on the object will use them. +The AttributeMethods module can add custom prefixes and suffixes on methods of a class. It is used by defining the prefixes and suffixes, which methods on the object will use them. <ruby> class Person @@ -92,7 +92,7 @@ person.to_param #=> nil 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 +An object becomes dirty when it has gone through one or more changes to its attributes and has not been saved. This gives the ability to check whether an object has been changed or not. It also has attribute based accessor methods. Let's consider a Person class with attributes first_name and last_name <ruby> require 'active_model' @@ -168,7 +168,7 @@ Track what was the previous value of the attribute. person.first_name_was #=> "First Name" </ruby> -Track both previous and current value of the changed attribute. Returns an array if changed else returns nil +Track both previous and current value of the changed attribute. Returns an array if changed, else returns nil. <ruby> #attr_name_change diff --git a/guides/source/active_record_validations_callbacks.textile b/guides/source/active_record_validations_callbacks.textile index cf7293bd9e..b866337e3f 100644 --- a/guides/source/active_record_validations_callbacks.textile +++ b/guides/source/active_record_validations_callbacks.textile @@ -532,6 +532,16 @@ end Person.new.valid? => ActiveModel::StrictValidationFailed: Name can't be blank </ruby> +There is also an ability to pass custom exception to +:strict+ option + +<ruby> +class Person < ActiveRecord::Base + validates :token, :presence => true, :uniqueness => true, :strict => TokenGenerationException +end + +Person.new.valid? => TokenGenerationException: Token can't be blank +</ruby> + h3. Conditional Validation Sometimes it will make sense to validate an object just when a given predicate is satisfied. You can do that by using the +:if+ and +:unless+ options, which can take a symbol, a string, a +Proc+ or an +Array+. You may use the +:if+ option when you want to specify when the validation *should* happen. If you want to specify when the validation *should not* happen, then you may use the +:unless+ option. diff --git a/guides/source/active_support_core_extensions.textile b/guides/source/active_support_core_extensions.textile index 66de6fd310..109228f8c7 100644 --- a/guides/source/active_support_core_extensions.textile +++ b/guides/source/active_support_core_extensions.textile @@ -1325,6 +1325,41 @@ that amount of leading whitespace. NOTE: Defined in +active_support/core_ext/string/strip.rb+. +h4. +indent+ + +Indents the lines in the receiver: + +<ruby> +<<EOS.indent(2) +def some_method + some_code +end +EOS +# => + def some_method + some_code + end +</ruby> + +The second argument, +indent_string+, specifies which indent string to use. The default is +nil+, which tells the method to make an educated guess peeking at the first indented line, and fallback to a space if there is none. + +<ruby> +" foo".indent(2) # => " foo" +"foo\n\t\tbar".indent(2) # => "\t\tfoo\n\t\t\t\tbar" +"foo".indent(2, "\t") # => "\t\tfoo" +</ruby> + +While +indent_string+ is tipically one space or tab, it may be any string. + +The third argument, +indent_empty_lines+, is a flag that says whether empty lines should be indented. Default is false. + +<ruby> +"foo\n\nbar".indent(2) # => " foo\n\n bar" +"foo\n\nbar".indent(2, nil, true) # => " foo\n \n bar" +</ruby> + +The +indent!+ method performs indentation in-place. + h4. Access h5. +at(position)+ diff --git a/guides/source/api_documentation_guidelines.textile b/guides/source/api_documentation_guidelines.textile index c6aa1f0a2b..3de5b119ee 100644 --- a/guides/source/api_documentation_guidelines.textile +++ b/guides/source/api_documentation_guidelines.textile @@ -127,7 +127,7 @@ class Array end </ruby> -WARNING: Using a pair of ++...++ for fixed-width font only works with *words*; that is: anything matching <tt>\A\w+\z</tt>. For anything else use +<tt>...</tt>+, notably symbols, setters, inline snippets, etc: +WARNING: Using a pair of ++...++ for fixed-width font only works with *words*; that is: anything matching <tt>\A\w+\z</tt>. For anything else use +<tt>...</tt>+, notably symbols, setters, inline snippets, etc. h4. Regular Font diff --git a/guides/source/asset_pipeline.textile b/guides/source/asset_pipeline.textile index d0d1ab137c..9c641db964 100644 --- a/guides/source/asset_pipeline.textile +++ b/guides/source/asset_pipeline.textile @@ -70,11 +70,11 @@ The query string strategy has several disadvantages: <ol> <li> - <strong>Not all caches will reliably cache content where the filename only differs by query parameters</strong>.<br> + <strong>Not all caches will reliably cache content where the filename only differs by query parameters</strong>.<br /> "Steve Souders recommends":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/, "...avoiding a querystring for cacheable resources". He found that in this case 5-20% of requests will not be cached. Query strings in particular do not work at all with some CDNs for cache invalidation. </li> <li> - <strong>The file name can change between nodes in multi-server environments.</strong><br> + <strong>The file name can change between nodes in multi-server environments.</strong><br /> The default query string in Rails 2.x is based on the modification time of the files. When assets are deployed to a cluster, there is no guarantee that the timestamps will be the same, resulting in different values being used depending on which server handles the request. </li> <li> @@ -432,7 +432,7 @@ NOTE. If you are precompiling your assets locally, you can use +bundle install - The default matcher for compiling files includes +application.js+, +application.css+ and all non-JS/CSS files (this will include all image assets automatically): <ruby> -[ Proc.new{ |path| !File.extname(path).in?(['.js', '.css']) }, /application.(css|js)$/ ] +[ Proc.new{ |path| !%w(.js .css).include?(File.extname(path)) }, /application.(css|js)$/ ] </ruby> NOTE. The matcher (and other members of the precompile array; see below) is applied to final compiled file names. This means that anything that compiles to JS/CSS is excluded, as well as raw JS/CSS files; for example, +.coffee+ and +.scss+ files are *not* automatically included as they compile to JS/CSS. @@ -473,6 +473,9 @@ Precompiled assets exist on the filesystem and are served directly by your web s For Apache: <plain> +# the following requires mod_expires +# on Ubuntu issue: +# sudo a2enmod expires <LocationMatch "^/assets/.*$"> # Use of ETag is discouraged when Last-Modified is present Header unset ETag diff --git a/guides/source/association_basics.textile b/guides/source/association_basics.textile index 2b8b1bd937..d4c0a1ba74 100644 --- a/guides/source/association_basics.textile +++ b/guides/source/association_basics.textile @@ -967,10 +967,13 @@ end h6(#has_one-dependent). +:dependent+ -If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated object to delete that object. If you set the +:dependent+ option to +:delete+, then deleting this object will delete the associated object _without_ calling its +destroy+ method. If you set the +:dependent+ option to +:nullify+, then deleting this object will set the foreign key in the association object to +NULL+. -If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and a +DeleteRestrictionError+ exception is raised. +Controls what happens to the associated object when its owner is destroyed: -NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +config.active_record.dependent_restrict_raises = false+ to your application config. +* +:destroy+ causes the associated object to also be destroyed +* +:delete+ causes the asssociated object to be deleted directly from the database (so callbacks will not execute) +* +:nullify+ causes the foreign key to be set to +NULL+. Callbacks are not executed. +* +:restrict_with_exception+ causes an exception to be raised if there is an associated record +* +:restrict_with_error+ causes an error to be added to the owner if there is an associated object h6(#has_one-foreign_key). +:foreign_key+ @@ -1307,10 +1310,13 @@ end h6(#has_many-dependent). +:dependent+ -If you set the +:dependent+ option to +:destroy+, then deleting this object will call the +destroy+ method on the associated objects to delete those objects. If you set the +:dependent+ option to +:delete_all+, then deleting this object will delete the associated objects _without_ calling their +destroy+ method. If you set the +:dependent+ option to +:nullify+, then deleting this object will set the foreign key in the associated objects to +NULL+. -If you set the +:dependent+ option to +:restrict+, then the deletion of the object is restricted if a dependent associated object exist and a +DeleteRestrictionError+ exception is raised. +Controls what happens to the associated objects when their owner is destroyed: -NOTE: The default behavior for +:dependent => :restrict+ is to raise a +DeleteRestrictionError+ when associated objects exist. Since Rails 4.0 this behavior is being deprecated in favor of adding an error to the base model. To silence the warning in Rails 4.0, you should fix your code to not expect this Exception and add +config.active_record.dependent_restrict_raises = false+ to your application config. +* +:destroy+ causes all the associated objects to also be destroyed +* +:delete_all+ causes all the asssociated objects to be deleted directly from the database (so callbacks will not execute) +* +:nullify+ causes the foreign keys to be set to +NULL+. Callbacks are not executed. +* +:restrict_with_exception+ causes an exception to be raised if there are any associated records +* +:restrict_with_error+ causes an error to be added to the owner if there are any associated objects NOTE: This option is ignored when you use the +:through+ option on the association. diff --git a/guides/source/caching_with_rails.textile b/guides/source/caching_with_rails.textile index 3ee36ae971..815b2ef9c2 100644 --- a/guides/source/caching_with_rails.textile +++ b/guides/source/caching_with_rails.textile @@ -33,7 +33,7 @@ class ProductsController < ActionController caches_page :index def index - @products = Products.all + @products = Product.all end end </ruby> @@ -52,7 +52,7 @@ class ProductsController < ActionController caches_page :index def index - @products = Products.all + @products = Product.all end def create diff --git a/guides/source/configuring.textile b/guides/source/configuring.textile index cc5c352df4..27eaf1cbc5 100644 --- a/guides/source/configuring.textile +++ b/guides/source/configuring.textile @@ -50,8 +50,6 @@ config.after_initialize do end </ruby> -* +config.allow_concurrency+ should be true to allow concurrent (threadsafe) action processing. False by default. You probably don't want to call this one directly, though, because a series of other adjustments need to be made for threadsafe mode to work properly. Can also be enabled with +threadsafe!+. - * +config.asset_host+ sets the host for the assets. Useful when CDNs are used for hosting assets, or when you want to work around the concurrency constraints builtin in browsers using different domain aliases. Shorter version of +config.action_controller.asset_host+. * +config.asset_path+ lets you decorate asset paths. This can be a callable, a string, or be +nil+ which is the default. For example, the normal path for +blog.js+ would be +/javascripts/blog.js+, let that absolute path be +path+. If +config.asset_path+ is a callable, Rails calls it when generating asset paths passing +path+ as argument. If +config.asset_path+ is a string, it is expected to be a +sprintf+ format string with a +%s+ where +path+ will get inserted. In either case, Rails outputs the decorated path. Shorter version of +config.action_controller.asset_path+. @@ -89,6 +87,10 @@ end * +config.dependency_loading+ is a flag that allows you to disable constant autoloading setting it to false. It only has effect if +config.cache_classes+ is true, which it is by default in production mode. This flag is set to false by +config.threadsafe!+. +* +config.eager_load+ when true, eager loads all registered `config.eager_load_namespaces`. This includes your application, engines, Rails frameworks and any other registered namespace. + +* +config.eager_load_namespaces+ registers namespaces that are eager loaded when +config.eager_load+ is true. All namespaces in the list must respond to the +eager_load!+ method. + * +config.eager_load_paths+ accepts an array of paths from which Rails will eager load on boot if cache classes is enabled. Defaults to every folder in the +app+ directory of the application. * +config.encoding+ sets up the application-wide encoding. Defaults to UTF-8. @@ -109,8 +111,6 @@ end * +config.middleware+ allows you to configure the application's middleware. This is covered in depth in the "Configuring Middleware":#configuring-middleware section below. -* +config.preload_frameworks+ enables or disables preloading all frameworks at startup. Enabled by +config.threadsafe!+. Defaults to +nil+, so is disabled. - * +config.queue+ configures a different queue implementation for the application. Defaults to +Rails::Queueing::Queue+. Note that, if the default queue is changed, the default +queue_consumer+ is not going to be initialized, it is up to the new queue implementation to handle starting and shutting down its own consumer(s). * +config.queue_consumer+ configures a different consumer implementation for the default queue. Defaults to +Rails::Queueing::ThreadedConsumer+. @@ -129,10 +129,6 @@ config.session_store :my_custom_store This custom store must be defined as +ActionDispatch::Session::MyCustomStore+. In addition to symbols, they can also be objects implementing a certain API, like +ActiveRecord::SessionStore+, in which case no special namespace is required. -* +config.threadsafe!+ enables +allow_concurrency+, +cache_classes+, +dependency_loading+ and +preload_frameworks+ to make the application threadsafe. - -WARNING: Threadsafe operation is incompatible with the normal workings of development mode Rails. In particular, automatic dependency loading and class reloading are automatically disabled when you call +config.threadsafe!+. - * +config.time_zone+ sets the default time zone for the application and enables time zone awareness for Active Record. * +config.whiny_nils+ enables or disables warnings when a certain set of methods are invoked on +nil+ and it does not respond to them. Defaults to true in development and test environments. @@ -203,7 +199,7 @@ Every Rails application comes with a standard set of middleware which it uses in * +ActionDispatch::SSL+ forces every request to be under HTTPS protocol. Will be available if +config.force_ssl+ is set to +true+. Options passed to this can be configured by using +config.ssl_options+. * +ActionDispatch::Static+ is used to serve static assets. Disabled if +config.serve_static_assets+ is +true+. -* +Rack::Lock+ wraps the app in mutex so it can only be called by a single thread at a time. Only enabled if +config.action_controller.allow_concurrency+ is set to +false+, which it is by default. +* +Rack::Lock+ wraps the app in mutex so it can only be called by a single thread at a time. Only enabled when +config.cache_classes_+ is +false+. * +ActiveSupport::Cache::Strategy::LocalCache+ serves as a basic memory backed cache. This cache is not thread safe and is intended only for serving as a temporary memory cache for a single thread. * +Rack::Runtime+ sets an +X-Runtime+ header, containing the time (in seconds) taken to execute the request. * +Rails::Rack::Logger+ notifies the logs that the request has began. After request is complete, flushes all the logs. @@ -286,8 +282,6 @@ h4. Configuring Active Record * +config.active_record.auto_explain_threshold_in_seconds+ configures the threshold for automatic EXPLAINs (+nil+ disables this feature). Queries exceeding the threshold get their query plan logged. Default is 0.5 in development mode. -* +config.active_record.dependent_restrict_raises+ will control the behavior when an object with a <tt>:dependent => :restrict</tt> association is deleted. Setting this to false will prevent +DeleteRestrictionError+ from being raised and instead will add an error on the model object. Defaults to false in the development mode. - * +config.active_record.mass_assignment_sanitizer+ will determine the strictness of the mass assignment sanitization within Rails. Defaults to +:strict+. In this mode, mass assigning any non-+attr_accessible+ attribute in a +create+ or +update_attributes+ call will raise an exception. Setting this option to +:logger+ will only print to the log file when an attribute is being assigned and will not raise an exception. The MySQL adapter adds one additional configuration option: @@ -340,6 +334,12 @@ h4. Configuring Action Dispatch * +config.action_dispatch.session_store+ sets the name of the store for session data. The default is +:cookie_store+; other valid options include +:active_record_store+, +:mem_cache_store+ or the name of your own custom class. +* +config.action_dispatch.default_headers+ is a hash with HTTP headers that are set by default in each response. By default, this is defined as: + +<ruby> +config.action_dispatch.default_headers = { 'X-Frame-Options' => 'SAMEORIGIN', 'X-XSS-Protection' => '1; mode=block', 'X-Content-Type-Options' => 'nosniff' } +</ruby> + * +config.action_dispatch.tld_length+ sets the TLD (top-level domain) length for the application. Defaults to +1+. * +ActionDispatch::Callbacks.before+ takes a block of code to run before the request. @@ -652,8 +652,6 @@ Serves as a placeholder so that +:load_environment_config+ can be defined to run *+load_active_support+* Requires +active_support/dependencies+ which sets up the basis for Active Support. Optionally requires +active_support/all+ if +config.active_support.bare+ is un-truthful, which is the default. -*+preload_frameworks+* Loads all autoload dependencies of Rails automatically if +config.preload_frameworks+ is +true+ or "truthful". By default this configuration option is disabled. In Rails, when internal classes are referenced for the first time they are autoloaded. +:preload_frameworks+ loads all of this at once on initialization. - *+initialize_logger+* Initializes the logger (an +ActiveSupport::BufferedLogger+ object) for the application and makes it accessible at +Rails.logger+, provided that no initializer inserted before this point has defined +Rails.logger+. *+initialize_cache+* If +Rails.cache+ isn't set yet, initializes the cache by referencing the value in +config.cache_store+ and stores the outcome as +Rails.cache+. If this object responds to the +middleware+ method, its middleware is inserted before +Rack::Runtime+ in the middleware stack. @@ -748,13 +746,13 @@ The error occurred while evaluating nil.each *+build_middleware_stack+* Builds the middleware stack for the application, returning an object which has a +call+ method which takes a Rack environment object for the request. -*+eager_load!+* If +config.cache_classes+ is true, runs the +config.before_eager_load+ hooks and then calls +eager_load!+ which will load all the Ruby files from +config.eager_load_paths+. +*+eager_load!+* If +config.eager_load+ is true, runs the +config.before_eager_load+ hooks and then calls +eager_load!+ which will load all +config.eager_load_namespaces+. *+finisher_hook+* Provides a hook for after the initialization of process of the application is complete, as well as running all the +config.after_initialize+ blocks for the application, railties and engines. *+set_routes_reloader+* Configures Action Dispatch to reload the routes file using +ActionDispatch::Callbacks.to_prepare+. -*+disable_dependency_loading+* Disables the automatic dependency loading if the +config.cache_classes+ is set to true and +config.dependency_loading+ is set to false. +*+disable_dependency_loading+* Disables the automatic dependency loading if the +config.eager_load+ is set to true. h3. Database pooling diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile index dd43ef795f..427733fe03 100644 --- a/guides/source/contributing_to_ruby_on_rails.textile +++ b/guides/source/contributing_to_ruby_on_rails.textile @@ -36,20 +36,26 @@ Please don't put "feature request" items into GitHub Issues. If there's a new fe If you'd like feedback on an idea for a feature before doing the work for make a patch, please send an email to the "rails-core mailing list":https://groups.google.com/forum/?fromgroups#!forum/rubyonrails-core. You might get no response, which means that everyone is indifferent. You might find someone who's also interested in building that feature. You might get a "This won't be accepted." But it's the proper place to discuss new ideas. GitHub Issues are not a particularly good venue for the sometimes long and involved discussions new features require. -h3. Running the Test Suite +h3. Setting Up a Development Environment To move on from submitting bugs to helping resolve existing issues or contributing your own code to Ruby on Rails, you _must_ be able to run its test suite. In this section of the guide you'll learn how to set up the tests on your own computer. -h4. Install Git +h4. The Easy Way -Ruby on Rails uses git for source code control. The "git homepage":http://git-scm.com/ has installation instructions. There are a variety of resources on the net that will help you get familiar with git: +The easiest way to get a development environment ready to hack is to use the "Rails development box":https://github.com/rails/rails-dev-box. -* "Everyday Git":http://schacon.github.com/git/everyday.html will teach you just enough about git to get by. -* The "PeepCode screencast":https://peepcode.com/products/git on git ($9) is easier to follow. -* "GitHub":http://help.github.com offers links to a variety of git resources. -* "Pro Git":http://progit.org/book/ is an entire book about git with a Creative Commons license. +h4. The Hard Way -h4. Clone the Ruby on Rails Repository +h5. Install Git + +Ruby on Rails uses Git for source code control. The "Git homepage":http://git-scm.com/ has installation instructions. There are a variety of resources on the net that will help you get familiar with Git: + +* "Everyday Git":http://schacon.github.com/git/everyday.html will teach you just enough about Git to get by. +* The "PeepCode screencast":https://peepcode.com/products/git on Git ($9) is easier to follow. +* "GitHub":http://help.github.com offers links to a variety of Git resources. +* "Pro Git":http://git-scm.com/book is an entire book about Git with a Creative Commons license. + +h5. Clone the Ruby on Rails Repository Navigate to the folder where you want the Ruby on Rails source code (it will create its own +rails+ subdirectory) and run: @@ -58,7 +64,7 @@ $ git clone git://github.com/rails/rails.git $ cd rails </shell> -h4. Set up and Run the Tests +h5. Set up and Run the Tests The test suite must pass with any submitted code. No matter whether you are writing a new patch, or evaluating someone else's, you need to be able to run the tests. @@ -74,7 +80,7 @@ If you are on Fedora or CentOS, you can run $ sudo yum install libxml2 libxml2-devel libxslt libxslt-devel </shell> -If you have any problems with these libraries, you should install them manually compiling the source code. Just follow the instructions "here":http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos . +If you have any problems with these libraries, you should install them manually compiling the source code. Just follow the instructions at the "Red Hat/CentOS section of the Nokogiri tutorials":http://nokogiri.org/tutorials/installing_nokogiri.html#red_hat__centos . Also, SQLite3 and its development files for the +sqlite3-ruby+ gem -- in Ubuntu you're done with just @@ -128,36 +134,17 @@ $ cd actionpack $ bundle exec ruby -Itest test/template/form_helper_test.rb </shell> -h4. Warnings - -The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. - -As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: - -<shell> -$ RUBYOPT=-W0 bundle exec rake test -</shell> - -h4. Testing Active Record +h5. Active Record Setup The test suite of Active Record attempts to run four times: once for SQLite3, once for each of the two MySQL gems (+mysql+ and +mysql2+), and once for PostgreSQL. We are going to see now how to set up the environment for them. WARNING: If you're working with Active Record code, you _must_ ensure that the tests pass for at least MySQL, PostgreSQL, and SQLite3. Subtle differences between the various adapters have been behind the rejection of many patches that looked OK when tested only against MySQL. -h5. Database Configuration +h6. Database Configuration The Active Record test suite requires a custom config file: +activerecord/test/config.yml+. An example is provided in +activerecord/test/config.example.yml+ which can be copied and used as needed for your environment. -h5. SQLite3 - -The gem +sqlite3-ruby+ does not belong to the "db" group. Indeed, if you followed the instructions above you're ready. This is how you run the Active Record test suite only for SQLite3: - -<shell> -$ cd activerecord -$ bundle exec rake test_sqlite3 -</shell> - -h5. MySQL and PostgreSQL +h6. MySQL and PostgreSQL To be able to run the suite for MySQL and PostgreSQL we need their gems. Install first the servers, their client libraries, and their development files. In Ubuntu just run @@ -217,6 +204,15 @@ NOTE: You'll see the following warning (or localized warning) during activating If you’re using another database, check the file +activerecord/test/config.yml+ or +activerecord/test/config.example.yml+ for default connection information. You can edit +activerecord/test/config.yml+ to provide different credentials on your machine if you must, but obviously you should not push any such changes back to Rails. +h3. Testing Active Record + +This is how you run the Active Record test suite only for SQLite3: + +<shell> +$ cd activerecord +$ bundle exec rake test_sqlite3 +</shell> + You can now run the tests as you did for +sqlite3+. The tasks are respectively <shell> @@ -225,7 +221,7 @@ test_mysql2 test_postgresql </shell> -As we mentioned before +Finally, <shell> $ bundle exec rake test @@ -241,6 +237,16 @@ $ ARCONN=sqlite3 ruby -Itest test/cases/associations/has_many_associations_test. You can invoke +test_jdbcmysql+, +test_jdbcsqlite3+ or +test_jdbcpostgresql+ also. See the file +activerecord/RUNNING_UNIT_TESTS+ for information on running more targeted database tests, or the file +ci/travis.rb+ for the test suite run by the continuous integration server. +h4. Warnings + +The test suite runs with warnings enabled. Ideally, Ruby on Rails should issue no warnings, but there may be a few, as well as some from third-party libraries. Please ignore (or fix!) them, if any, and submit patches that do not issue new warnings. + +As of this writing (December, 2010) they are specially noisy with Ruby 1.9. If you are sure about what you are doing and would like to have a more clear output, there's a way to override the flag: + +<shell> +$ RUBYOPT=-W0 bundle exec rake test +</shell> + h4. Older Versions of Ruby on Rails If you want to add a fix to older versions of Ruby on Rails, you'll need to set up and switch to your own local tracking branch. Here is an example to switch to the 3-0-stable branch: @@ -250,7 +256,7 @@ $ git branch --track 3-0-stable origin/3-0-stable $ git checkout 3-0-stable </shell> -TIP: You may want to "put your git branch name in your shell prompt":http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/ to make it easier to remember which version of the code you're working with. +TIP: You may want to "put your Git branch name in your shell prompt":http://qugstart.com/blog/git-and-svn/add-colored-git-branch-name-to-your-shell-prompt/ to make it easier to remember which version of the code you're working with. h3. Helping to Resolve Existing Issues @@ -331,7 +337,7 @@ $ cd rails $ git checkout -b my_new_branch </shell> -It doesn’t matter much what name you use, because this branch will only exist on your local computer and your personal repository on Github. It won't be part of the Rails git repository. +It doesn’t matter much what name you use, because this branch will only exist on your local computer and your personal repository on Github. It won't be part of the Rails Git repository. h4. Write Your Code @@ -359,6 +365,31 @@ Rails follows a simple set of coding style conventions. The above are guidelines -- please use your best judgment in using them. +h4. Updating the CHANGELOG + +The CHANGELOG is an important part of every release. It keeps the list of changes for every Rails version. + +You should add an entry to the CHANGELOG of the framework that you modified if you're adding or removing a feature, commiting a bug fix or adding deprecation notices. Refactorings and documentation changes generally should not go to the CHANGELOG. + +A CHANGELOG entry should summarize what was changed and should end with author's name. You can use multiple lines if you need more space and you can attach code examples indented with 4 spaces. If a change is related to a specific issue, you should attach issue's number. Here is an example CHANGELOG entry: + +<plain> +* Summary of a change that briefly describes what was changed. You can use multiple + lines and wrap them at around 80 characters. Code examples are ok, too, if needed: + + class Foo + def bar + puts 'baz' + end + end + + You can continue after the code example and you can attach issue number. GH#1234 + + *Your Name* +</plain> + +Your name can be added directly after the last word if you don't provide any code examples or don't need multiple paragraphs. Otherwise, it's best to make as a new paragraph. + h4. Sanity Check You should not be the only person who looks at the code before you submit it. You know at least one other Rails developer, right? Show them what you’re doing and ask for feedback. Doing this in private before you push a patch out publicly is the “smoke test” for a patch: if you can’t convince one other developer of the beauty of your code, you’re unlikely to convince the core team either. @@ -367,7 +398,7 @@ You might want also to check out the "RailsBridge BugMash":http://wiki.railsbrid h4. Commit Your Changes -When you're happy with the code on your computer, you need to commit the changes to git: +When you're happy with the code on your computer, you need to commit the changes to Git: <shell> $ git commit -a @@ -386,7 +417,7 @@ 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 +Description can have multiple paragraphs and you can use code examples inside, just indent it with 4 spaces: class PostsController @@ -495,7 +526,7 @@ It’s entirely possible that the feedback you get will suggest changes. Don’t h4. Backporting -Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a rails team member before backporting your changes to avoid wasted effort. +Changes that are merged into master are intended for the next major release of Rails. Sometimes, it might be beneficial for your changes to propagate back to the maintenance releases for older stable branches. Generally, security fixes and bug fixes are good candidates for a backport, while new features and patches that introduce a change in behavior will not be accepted. When in doubt, it is best to consult a Rails team member before backporting your changes to avoid wasted effort. For simple fixes, the easiest way to backport your changes is to "extract a diff from your changes in master and apply them to the target branch":http://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git. @@ -520,9 +551,9 @@ $ git apply ~/my_changes.patch This works well for simple changes. However, if your changes are complicated or if the code in master has deviated significantly from your target branch, it might require more work on your part. The difficulty of a backport varies greatly from case to case, and sometimes it is simply not worth the effort. -Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the ruby versions listed in +.travis.yml+ before submitting your pull request. +Once you have resolved all conflicts and made sure all the tests are passing, push your changes and open a separate pull request for your backport. It is also worth noting that older branches might have a different set of build targets than master. When possible, it is best to first test your backport locally against the Ruby versions listed in +.travis.yml+ before submitting your pull request. -And then ... think about your next contribution! +And then... think about your next contribution! h3. Rails Contributors diff --git a/guides/source/engines.textile b/guides/source/engines.textile index de4bbb5656..fe8fcfbb3f 100644 --- a/guides/source/engines.textile +++ b/guides/source/engines.textile @@ -217,7 +217,7 @@ This helps prevent conflicts with any other engine or application that may have Finally, two files that are the assets for this resource are generated, +app/assets/javascripts/blorgh/posts.js+ and +app/assets/javascripts/blorgh/posts.css+. You'll see how to use these a little later. -By default, the scaffold styling is not applied to the engine as the engine's layout file, +app/views/blorgh/application.html.erb+ doesn't load it. To make this apply, insert this line into the +<head>+ tag of this layout: +By default, the scaffold styling is not applied to the engine as the engine's layout file, +app/views/blorgh/application.html.erb+ doesn't load it. To make this apply, insert this line into the +<head>+ tag of this layout: <erb> <%= stylesheet_link_tag "scaffold" %> @@ -369,7 +369,7 @@ This partial will be responsible for rendering just the comment text, for now. C <%= comment_counter + 1 %>. <%= comment.text %> </erb> -The +comment_counter+ local variable is given to us by the +<%= render @post.comments %>+ call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created. +The +comment_counter+ local variable is given to us by the +<%= render @post.comments %>+ call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created. That completes the comment function of the blogging engine. Now it's time to use it within an application. @@ -536,7 +536,7 @@ Finally, the author's name should be displayed on the post's page. Add this code </p> </erb> -By outputting +@post.author+ using the +<%=+ tag the +to_s+ method will be called on the object. By default, this will look quite ugly: +By outputting +@post.author+ using the +<%=+ tag the +to_s+ method will be called on the object. By default, this will look quite ugly: <plain> #<User:0x00000100ccb3b0> diff --git a/guides/source/form_helpers.textile b/guides/source/form_helpers.textile index 58338ce54b..f2d8755bf0 100644 --- a/guides/source/form_helpers.textile +++ b/guides/source/form_helpers.textile @@ -98,7 +98,7 @@ form_tag({:controller => "people", :action => "search"}, :method => "get", :clas h4. Helpers for Generating Form Elements -Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as +text_field_tag+ and +check_box_tag+), generate just a single +<input>+ element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the +params+ hash in the controller with the value entered by the user for that field. For example, if the form contains +<%= text_field_tag(:query) %>+, then you would be able to get the value of this field in the controller with +params[:query]+. +Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as +text_field_tag+ and +check_box_tag+), generate just a single +<input>+ element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the +params+ hash in the controller with the value entered by the user for that field. For example, if the form contains +<%= text_field_tag(:query) %>+, then you would be able to get the value of this field in the controller with +params[:query]+. When naming inputs, Rails uses certain conventions that make it possible to submit parameters with non-scalar values such as arrays or hashes, which will also be accessible in +params+. You can read more about them in "chapter 7 of this guide":#understanding-parameter-naming-conventions. For details on the precise usage of these helpers, please refer to the "API documentation":http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html. diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile index 22da369a2a..226c3dce14 100644 --- a/guides/source/getting_started.textile +++ b/guides/source/getting_started.textile @@ -124,7 +124,7 @@ application. Most of the work in this tutorial will happen in the +app/+ folder, |config.ru|Rack configuration for Rack based servers used to start the application.| |db/|Contains your current database schema, as well as the database migrations.| |doc/|In-depth documentation for your application.| -|Gemfile<BR />Gemfile.lock|These files allow you to specify what gem dependencies are needed for your Rails application. These files are used by the Bundler gem. For more information about Bundler, see "the Bundler website":http://gembundler.com | +|Gemfile<br />Gemfile.lock|These files allow you to specify what gem dependencies are needed for your Rails application. These files are used by the Bundler gem. For more information about Bundler, see "the Bundler website":http://gembundler.com | |lib/|Extended modules for your application.| |log/|Application log files.| |public/|The only folder seen to the world as-is. Contains the static files and compiled assets.| diff --git a/guides/source/i18n.textile b/guides/source/i18n.textile index c782539399..67863e590c 100644 --- a/guides/source/i18n.textile +++ b/guides/source/i18n.textile @@ -565,7 +565,7 @@ I18n.translate :thanks, :name => 'Jeremy' # => 'Thanks Jeremy!' </ruby> -If a translation uses +:default+ or +:scope+ as an interpolation variable, an I+18n::ReservedInterpolationKey+ exception is raised. If a translation expects an interpolation variable, but this has not been passed to +#translate+, an +I18n::MissingInterpolationArgument+ exception is raised. +If a translation uses +:default+ or +:scope+ as an interpolation variable, an +I18n::ReservedInterpolationKey+ exception is raised. If a translation expects an interpolation variable, but this has not been passed to +#translate+, an +I18n::MissingInterpolationArgument+ exception is raised. h4. Pluralization diff --git a/guides/source/initialization.textile b/guides/source/initialization.textile index 43d89eac4b..b23f31cb1a 100644 --- a/guides/source/initialization.textile +++ b/guides/source/initialization.textile @@ -17,7 +17,7 @@ NOTE: Paths in this guide are relative to Rails or a Rails application unless ot TIP: If you want to follow along while browsing the Rails "source code":https://github.com/rails/rails, we recommend that you use the +t+ -key binding to open the file finder inside github and find files +key binding to open the file finder inside GitHub and find files quickly. h3. Launch! @@ -359,7 +359,7 @@ set earlier) is required. h4. +config/application+ When +require APP_PATH+ is executed, +config/application.rb+ is loaded. -This is a file exists in your app and it's free for you to change based +This file exists in your app and it's free for you to change based on your needs. h4. +Rails::Server#start+ @@ -453,7 +453,7 @@ end The interesting part for a Rails app is the last line, +server.run+. Here we encounter the +wrapped_app+ method again, which this time we're going to explore more (even though it was executed before, and -thus memoized by now). +thus memorized by now). <ruby> @wrapped_app ||= build_app app @@ -540,12 +540,12 @@ end </ruby> This is where all the Rails frameworks are loaded and thus made -available to the application. We wont go into detail of what happens +available to the application. We won't go into detail of what happens inside each of those frameworks, but you're encouraged to try and explore them on your own. For now, just keep in mind that common functionality like Rails engines, -I18n and Rails configuration is all bein defined here. +I18n and Rails configuration is all being defined here. h4. Back to +config/environment.rb+ @@ -657,10 +657,10 @@ def self.run(app, options={}) end </ruby> -We wont dig into the server configuration itself, but this is +We won't dig into the server configuration itself, but this is the last piece of our journey in the Rails initialization process. -This high level overview will help you understand when you code is +This high level overview will help you understand when your code is executed and how, and overall become a better Rails developer. If you still want to know more, the Rails source code itself is probably the best place to go next. diff --git a/guides/source/kindle/KINDLE.md b/guides/source/kindle/KINDLE.md index a7d9a4e4cf..08937e053e 100644 --- a/guides/source/kindle/KINDLE.md +++ b/guides/source/kindle/KINDLE.md @@ -9,16 +9,16 @@ ## Resources - * [StackOverflow: Kindle Periodical Format](http://stackoverflow.com/questions/5379565/kindle-periodical-format) + * [Stack Overflow: Kindle Periodical Format](http://stackoverflow.com/questions/5379565/kindle-periodical-format) * Example Periodical [.ncx](https://gist.github.com/808c971ed087b839d462) and [.opf](https://gist.github.com/d6349aa8488eca2ee6d0) - * [Kindle Publishing guidelines](http://kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines.pdf) + * [Kindle Publishing Guidelines](http://kindlegen.s3.amazonaws.com/AmazonKindlePublishingGuidelines.pdf) * [KindleGen & Kindle Previewer](http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621) ## TODO ### Post release - * Integrate generated Kindle document in to published HTML guides + * Integrate generated Kindle document into published HTML guides * Tweak heading styles (most docs use h3/h4/h5, which end up being smaller than the text under it) * Tweak table styles (smaller text? Many of the tables are unusable on a Kindle in portrait mode) * Have the HTML/XML TOC 'drill down' into the TOCs of the individual guides diff --git a/guides/source/kindle/welcome.html.erb b/guides/source/kindle/welcome.html.erb index e30704c4e6..610a71570f 100644 --- a/guides/source/kindle/welcome.html.erb +++ b/guides/source/kindle/welcome.html.erb @@ -2,4 +2,4 @@ <h3>Kindle Edition</h3> -The Kindle Edition of the Rails Guides should be considered a work in progress. Feedback is really welcome, please see the "Feedback" section at the end of each guide for instructions. +The Kindle Edition of the Rails Guides should be considered a work in progress. Feedback is really welcome. Please see the "Feedback" section at the end of each guide for instructions. diff --git a/guides/source/migrations.textile b/guides/source/migrations.textile index 06e85e5914..a7de21b754 100644 --- a/guides/source/migrations.textile +++ b/guides/source/migrations.textile @@ -14,7 +14,7 @@ Migrations also allow you to describe these transformations using Ruby. The great thing about this is that (like most of Active Record's functionality) it is database independent: you don't need to worry about the precise syntax of +CREATE TABLE+ any more than you worry about variations on +SELECT *+ (you can -drop down to raw SQL for database specific features). For example you could use +drop down to raw SQL for database specific features). For example, you could use SQLite3 in development, but MySQL in production. In this guide, you'll learn all about migrations including: @@ -123,10 +123,10 @@ database independent way (you'll read about them in detail later): * +rename_column+ * +remove_reference+ -If you need to perform tasks specific to your database (for example create a +If you need to perform tasks specific to your database (e.g., create a "foreign key":#active-record-and-referential-integrity constraint) then the +execute+ method allows you to execute arbitrary SQL. A migration is just a -regular Ruby class so you're not limited to these functions. For example after +regular Ruby class so you're not limited to these functions. For example, after adding a column you could write code to set the value of that column for existing records (if necessary using your models). @@ -165,7 +165,7 @@ config.active_record.timestamped_migrations = false The combination of timestamps and recording which migrations have been run allows Rails to handle common situations that occur with multiple developers. -For example Alice adds migrations +20080906120000+ and +20080906123000+ and Bob +For example, Alice adds migrations +20080906120000+ and +20080906123000+ and Bob adds +20080906124500+ and runs it. Alice finishes her changes and checks in her migrations and Bob pulls down the latest changes. When Bob runs +rake db:migrate+, Rails knows that it has not run Alice's two migrations so it executes the +up+ method for each migration. @@ -182,7 +182,7 @@ migration again: Rails thinks it has already run the migration and so will do nothing when you run +rake db:migrate+. You must rollback the migration (for example with +rake db:rollback+), edit your migration and then run +rake db:migrate+ to run the corrected version. -In general editing existing migrations is not a good idea: you will be creating +In general, editing existing migrations is not a good idea. You will be creating extra work for yourself and your co-workers and cause major headaches if the existing version of the migration has already been run on production machines. Instead, you should write a new migration that performs the changes you require. @@ -209,8 +209,7 @@ Active Record supports the following database column types: These will be mapped onto an appropriate underlying database type. For example, with MySQL the type +:string+ is mapped to +VARCHAR(255)+. You can create -columns of types not supported by Active Record when using the non-sexy syntax, -for example +columns of types not supported by Active Record when using the non-sexy syntax such as <ruby> create_table :products do |t| @@ -255,7 +254,7 @@ by Active Record). h4. Creating a Standalone Migration -If you are creating migrations for other purposes (for example to add a column +If you are creating migrations for other purposes (e.g., to add a column to an existing table) then you can also use the migration generator: <shell> @@ -309,7 +308,7 @@ class RemovePartNumberFromProducts < ActiveRecord::Migration end </ruby> -You are not limited to one magically generated column, for example +You are not limited to one magically generated column. For example <shell> $ rails generate migration AddDetailsToProducts part_number:string price:decimal @@ -334,7 +333,7 @@ NOTE: The generated migration file for destructive migrations will still be old-style using the +up+ and +down+ methods. This is because Rails needs to know the original data types defined when you made the original changes. -Also the generator accepts column type as +references+(also available as +belongs_to+), for instance +Also, the generator accepts column type as +references+(also available as +belongs_to+). For instance <shell> $ rails generate migration AddUserRefToProducts user:references @@ -362,7 +361,7 @@ following modifiers: * +scale+ Defines the scale for the +decimal+ fields * +polymorphic+ Adds a +type+ column for +belongs_to+ associations -For instance running +For instance, running <shell> $ rails generate migration AddDetailsToProducts price:decimal{5,2} supplier:references{polymorphic} @@ -541,8 +540,8 @@ support":#active-record-and-referential-integrity. If the helpers provided by Active Record aren't enough you can use the +execute+ method to execute arbitrary SQL. -For more details and examples of individual methods, check the API documentation, -in particular the documentation for +For more details and examples of individual methods, check the API documentation. +In particular the documentation for "<tt>ActiveRecord::ConnectionAdapters::SchemaStatements</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html (which provides the methods available in the +up+ and +down+ methods), "<tt>ActiveRecord::ConnectionAdapters::TableDefinition</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html @@ -644,7 +643,7 @@ down to, but not including, 20080906120000. h4. Rolling Back -A common task is to rollback the last migration, for example if you made a +A common task is to rollback the last migration. For example, if you made a mistake in it and wish to correct it. Rather than tracking down the version number associated with the previous migration you can run @@ -839,7 +838,7 @@ An error has occurred, this and all later migrations canceled: undefined method `fuzz' for #<Product:0x000001049b14a0> </plain> -A fix for this is to create a local model within the migration. This keeps rails +A fix for this is to create a local model within the migration. This keeps Rails from running the validations, so that the migrations run to completion. When using a faux model, it's a good idea to call diff --git a/guides/source/performance_testing.textile b/guides/source/performance_testing.textile index b7d4f1ef33..6c5676c346 100644 --- a/guides/source/performance_testing.textile +++ b/guides/source/performance_testing.textile @@ -649,6 +649,7 @@ h4. Rails Plugins and Gems * "Palmist":http://www.flyingmachinestudios.com/programming/announcing-palmist * "Rails Footnotes":https://github.com/josevalim/rails-footnotes/tree/master * "Query Reviewer":https://github.com/dsboulder/query_reviewer/tree/master +* "MiniProfiler":http://www.miniprofiler.com h4. Generic Tools @@ -668,4 +669,4 @@ Rails has been lucky to have a few companies dedicated to Rails-specific performance tools. A couple of those are: * "New Relic":http://www.newrelic.com -* "Scout":http://scoutapp.com
\ No newline at end of file +* "Scout":http://scoutapp.com diff --git a/guides/source/plugins.textile b/guides/source/plugins.textile index 9001857a5f..50ea6b166a 100644 --- a/guides/source/plugins.textile +++ b/guides/source/plugins.textile @@ -13,7 +13,7 @@ After reading this guide you should be familiar with: This guide describes how to build a test-driven plugin that will: -* Extend core ruby classes like Hash and String +* Extend core Ruby classes like Hash and String * Add methods to ActiveRecord::Base in the tradition of the 'acts_as' plugins * Give you information about where to put generators in your plugin. @@ -28,7 +28,7 @@ h3. Setup _"vendored plugins"_ were available in previous versions of Rails, but they are deprecated in Rails 3.2, and will not be available in the future. -Currently, Rails plugins are built as gems, _gemified plugins_. They can be shared accross +Currently, Rails plugins are built as gems, _gemified plugins_. They can be shared across different rails applications using RubyGems and Bundler if desired. h4. Generate a gemified plugin. @@ -174,11 +174,11 @@ require 'test_helper' class ActsAsYaffleTest < Test::Unit::TestCase def test_a_hickwalls_yaffle_text_field_should_be_last_squawk - assert_equal :last_squawk, Hickwall.yaffle_text_field + assert_equal "last_squawk", Hickwall.yaffle_text_field end def test_a_wickwalls_yaffle_text_field_should_be_last_tweet - assert_equal :last_tweet, Wickwall.yaffle_text_field + assert_equal "last_tweet", Wickwall.yaffle_text_field end end @@ -392,7 +392,7 @@ the creation of generators can be found in the "Generators Guide":generators.htm h3. Publishing your Gem Gem plugins currently in development can easily be shared from any Git repository. To share the Yaffle gem with others, simply -commit the code to a Git repository (like Github) and add a line to the Gemfile of the application in question: +commit the code to a Git repository (like GitHub) and add a line to the Gemfile of the application in question: <ruby> gem 'yaffle', :git => 'git://github.com/yaffle_watcher/yaffle.git' @@ -401,7 +401,7 @@ gem 'yaffle', :git => 'git://github.com/yaffle_watcher/yaffle.git' After running +bundle install+, your gem functionality will be available to the application. When the gem is ready to be shared as a formal release, it can be published to "RubyGems":http://www.rubygems.org. -For more information about publishing gems to RubyGems, see: "http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html":http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html +For more information about publishing gems to RubyGems, see: "Creating and Publishing Your First Ruby Gem":http://blog.thepete.net/2010/11/creating-and-publishing-your-first-ruby.html h3. RDoc Documentation @@ -414,7 +414,7 @@ The first step is to update the README file with detailed information about how * How to add the functionality to the app (several examples of common use cases) * Warnings, gotchas or tips that might help users and save them time -Once your README is solid, go through and add rdoc comments to all of the methods that developers will use. It's also customary to add '#:nodoc:' comments to those parts of the code that are not included in the public api. +Once your README is solid, go through and add rdoc comments to all of the methods that developers will use. It's also customary to add '#:nodoc:' comments to those parts of the code that are not included in the public API. Once your comments are good to go, navigate to your plugin directory and run: @@ -425,6 +425,6 @@ $ rake rdoc h4. References * "Developing a RubyGem using Bundler":https://github.com/radar/guides/blob/master/gem-development.md -* "Using Gemspecs As Intended":http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/ +* "Using .gemspecs as Intended":http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/ * "Gemspec Reference":http://docs.rubygems.org/read/chapter/20 -* "GemPlugins":http://www.intridea.com/blog/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins +* "GemPlugins: A Brief Introduction to the Future of Rails Plugins":http://www.intridea.com/blog/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins diff --git a/guides/source/rails_application_templates.textile b/guides/source/rails_application_templates.textile index f50ced3307..2fa40bc4cc 100644 --- a/guides/source/rails_application_templates.textile +++ b/guides/source/rails_application_templates.textile @@ -38,7 +38,7 @@ rake("db:migrate") git :init git :add => "." -git :commit => "-a -m 'Initial commit'" +git :commit => %Q{ -m 'Initial commit' } </ruby> The following sections outlines the primary methods provided by the API: diff --git a/guides/source/routing.textile b/guides/source/routing.textile index cffbf9bec4..bed7d03e06 100644 --- a/guides/source/routing.textile +++ b/guides/source/routing.textile @@ -273,6 +273,36 @@ The corresponding route helper would be +publisher_magazine_photo_url+, requirin TIP: _Resources should never be nested more than 1 level deep._ +h4. Routing concerns + +Routing Concerns allows you to declare common routes that can be reused inside others resources and routes. + +<ruby> +concern :commentable do + resources :comments +end + +concern :image_attachable do + resources :images, only: :index +end +</ruby> + +These concerns can be used in resources to avoid code duplication and share behavior across routes. + +<ruby> +resources :messages, concerns: :commentable + +resources :posts, concerns: [:commentable, :image_attachable] +</ruby> + +Also you can use them in any place that you want inside the routes, for example in a scope or namespace call: + +<ruby> +namespace :posts do + concerns :commentable +end +</ruby> + h4. Creating Paths and URLs From Objects In addition to using the routing helpers, Rails can also create paths and URLs from an array of parameters. For example, suppose you have this set of routes: diff --git a/guides/source/security.textile b/guides/source/security.textile index 49e5da6bb7..f3c3ab9d87 100644 --- a/guides/source/security.textile +++ b/guides/source/security.textile @@ -1021,6 +1021,47 @@ Content-Type: text/html Under certain circumstances this would present the malicious HTML to the victim. However, this only seems to work with Keep-Alive connections (and many browsers are using one-time connections). But you can't rely on this. _(highlight)In any case this is a serious bug, and you should update your Rails to version 2.0.5 or 2.1.2 to eliminate Header Injection (and thus response splitting) risks._ +h3. Default Headers + +Every HTTP response from your Rails application receives the following default security headers. + +<ruby> +config.action_dispatch.default_headers = { + 'X-Frame-Options' => 'SAMEORIGIN', + 'X-XSS-Protection' => '1; mode=block', + 'X-Content-Type-Options' => 'nosniff' +} +</ruby> + +You can configure default headers in <ruby>config/application.rb</ruby>. + +<ruby> +config.action_dispatch.default_headers = { + 'Header-Name' => 'Header-Value', + 'X-Frame-Options' => 'DENY' +} +</ruby> + +Or you can remove them. + +<ruby> +config.action_dispatch.default_headers.clear +</ruby> + +Here is the list of common headers: +* X-Frame-Options +_'SAMEORIGIN' in Rails by default_ - allow framing on same domain. Set it to 'DENY' to deny framing at all or 'ALLOWALL' if you want to allow framing for all website. +* X-XSS-Protection +_'1; mode=block' in Rails by default_ - use XSS Auditor and block page if XSS attack is detected. Set it to '0;' if you want to switch XSS Auditor off(useful if response contents scripts from request parameters) +* X-Content-Type-Options +_'nosniff' in Rails by default_ - stops the browser from guessing the MIME type of a file. +* X-Content-Security-Policy +"A powerful mechanism for controlling which sites certain content types can be loaded from":http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html +* Access-Control-Allow-Origin +Used to control which sites are allowed to bypass same origin policies and send cross-origin requests. +* Strict-Transport-Security +"Used to control if the browser is allowed to only access a site over a secure connection":http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security + h3. Additional Resources The security landscape shifts and it is important to keep up to date, because missing a new vulnerability can be catastrophic. You can find additional resources about (Rails) security here: diff --git a/guides/source/upgrading_ruby_on_rails.textile b/guides/source/upgrading_ruby_on_rails.textile index 5024bc4c37..cdf7306264 100644 --- a/guides/source/upgrading_ruby_on_rails.textile +++ b/guides/source/upgrading_ruby_on_rails.textile @@ -44,6 +44,8 @@ The <tt>delete</tt> method in collection associations can now receive <tt>Fixnum Rails 4.0 has changed how orders get stacked in +ActiveRecord::Relation+. In previous versions of rails new order was applied after previous defined order. But this is no long true. Check "ActiveRecord Query guide":active_record_querying.html#ordering for more information. +Rails 4.0 has changed <tt>serialized_attributes</tt> and <tt>_attr_readonly</tt> to class methods only. Now you shouldn't use instance methods, it's deprecated. You must change them, e.g. <tt>self.serialized_attributes</tt> to <tt>self.class.serialized_attributes</tt>. + h4(#active_model4_0). Active Model Rails 4.0 has changed how errors attach with the <tt>ActiveModel::Validations::ConfirmationValidator</tt>. Now when confirmation validations fail the error will be attached to <tt>:#{attribute}_confirmation</tt> instead of <tt>attribute</tt>. @@ -54,6 +56,10 @@ Rails 4.0 changed how <tt>assert_generates</tt>, <tt>assert_recognizes</tt>, and Rails 4.0 also changed the way unicode character routes are drawn. Now you can draw unicode character routes directly. If you already draw such routes, you must change them, e.g. <tt>get Rack::Utils.escape('こんにちは'), :controller => 'welcome', :action => 'index'</tt> to <tt>get 'こんにちは', :controller => 'welcome', :action => 'index'</tt>. +h4(#active_support4_0). Active Support + +Rails 4.0 Removed the `j` alias for `ERB::Util#json_escape` since `j` is already used for `ActionView::Helpers::JavaScriptHelper#escape_javascript`. + h4(#helpers_order). Helpers Loading Order The loading order of helpers from more than one directory has changed in Rails 4.0. Previously, helpers from all directories were gathered and then sorted alphabetically. After upgrade to Rails 4.0 helpers will preserve the order of loaded directories and will be sorted alphabetically only within each directory. Unless you explicitly use <tt>helpers_path</tt> parameter, this change will only impact the way of loading helpers from engines. If you rely on the fact that particular helper from engine loads before or after another helper from application or another engine, you should check if correct methods are available after upgrade. If you would like to change order in which engines are loaded, you can use <tt>config.railties_order=</tt> method. |