diff options
Diffstat (limited to 'railties/guides')
-rw-r--r-- | railties/guides/source/action_mailer_basics.textile | 2 | ||||
-rw-r--r-- | railties/guides/source/active_support_core_extensions.textile | 4 | ||||
-rw-r--r-- | railties/guides/source/api_documentation_guidelines.textile | 4 | ||||
-rw-r--r-- | railties/guides/source/configuring.textile | 14 | ||||
-rw-r--r-- | railties/guides/source/form_helpers.textile | 2 | ||||
-rw-r--r-- | railties/guides/source/generators.textile | 65 | ||||
-rw-r--r-- | railties/guides/source/i18n.textile | 8 | ||||
-rw-r--r-- | railties/guides/source/index.html.erb | 2 | ||||
-rw-r--r-- | railties/guides/source/initialization.textile | 46 | ||||
-rw-r--r-- | railties/guides/source/layout.html.erb | 8 | ||||
-rw-r--r-- | railties/guides/source/ruby_on_rails_guides_guidelines.textile | 6 |
11 files changed, 101 insertions, 60 deletions
diff --git a/railties/guides/source/action_mailer_basics.textile b/railties/guides/source/action_mailer_basics.textile index b77a0be37b..6ee17ee5b8 100644 --- a/railties/guides/source/action_mailer_basics.textile +++ b/railties/guides/source/action_mailer_basics.textile @@ -248,7 +248,7 @@ It is possible to send email to one or more recipients in one email (for e.g. in class AdminMailer < ActionMailer::Base default :to => Admin.all.map(&:email).join(", "), :from => "notification@example.com" - + def new_registration(user) @user = user mail(:subject => "New User Signup: #{@user.email}") diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 2e295aec3d..bddff1c987 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -3389,12 +3389,12 @@ Modifies the datetime format output by the formatter class associated with this <ruby> class Logger::FormatWithTime < Logger::Formatter cattr_accessor(:datetime_format) { "%Y%m%d%H%m%S" } - + def self.call(severity, timestamp, progname, msg) "#{timestamp.strftime(datetime_format)} -- #{String === msg ? msg : msg.inspect}\n" end end - + logger = Logger.new("log/development.log") logger.formatter = Logger::FormatWithTime logger.info("<- is the current time") diff --git a/railties/guides/source/api_documentation_guidelines.textile b/railties/guides/source/api_documentation_guidelines.textile index e3ccd6396c..b977d9373e 100644 --- a/railties/guides/source/api_documentation_guidelines.textile +++ b/railties/guides/source/api_documentation_guidelines.textile @@ -46,10 +46,10 @@ Short docs do not need an explicit "Examples" label to introduce snippets, they # Converts a collection of elements into a formatted string by calling # <tt>to_s</tt> on all elements and joining them. # -# Blog.find(:all).to_formatted_s # => "First PostSecond PostThird Post" +# Blog.all.to_formatted_s # => "First PostSecond PostThird Post" </ruby> -On the other hand big chunks of structured documentation may have a separate "Examples" section: +On the other hand, big chunks of structured documentation may have a separate "Examples" section: <ruby> # ==== Examples diff --git a/railties/guides/source/configuring.textile b/railties/guides/source/configuring.textile index d5faf3da2c..497c8318f0 100644 --- a/railties/guides/source/configuring.textile +++ b/railties/guides/source/configuring.textile @@ -190,6 +190,12 @@ Middlewares can also be completely swapped out and replaced with others: config.middleware.swap ActionDispatch::BestStandardsSupport, Magical::Unicorns </ruby> +They can also be removed from the stack completely: + +<ruby> + config.middleware.delete ActionDispatch::BestStandardsSupport +</ruby> + h4. Configuring i18n * +config.i18n.default_locale+ sets the default locale of an application used for i18n. Defaults to +:en+. @@ -272,11 +278,11 @@ h4. Configuring Action Dispatch * +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. +* +ActionDispatch::Callbacks.before+ takes a block of code to run before the request. * +ActionDispatch::Callbacks.to_prepare+ takes a block to run after +ActionDispatch::Callbacks.before+, but before the request. Runs for every request in +development+ mode, but only once for +production+ or environments with +cache_classes+ set to +true+. -* +ActionDispatch::Callbacks.after+ takes a block of code to run after the request. +* +ActionDispatch::Callbacks.after+ takes a block of code to run after the request. h4. Configuring Action View @@ -392,7 +398,7 @@ Rails has 5 initialization events which can be hooked into (listed in order that * +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. +* +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. * +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+ enviroment. @@ -411,7 +417,7 @@ initializer "active_support.initialize_whiny_nils" do |app| end </ruby> -The +initializer+ method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The +:before+ key in the options hash can be specified to specify which initializer this new initializer must run before, and the +:after+ key will specify which initializer to run this initializer _after_. +The +initializer+ method takes three arguments with the first being the name for the initializer and the second being an options hash (not shown here) and the third being a block. The +:before+ key in the options hash can be specified to specify which initializer this new initializer must run before, and the +:after+ key will specify which initializer to run this initializer _after_. Initializers defined using the +initializer+ method will be ran in the order they are defined in, with the exception of ones that use the +:before+ or +:after+ methods. diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile index e178a60307..7b4426b335 100644 --- a/railties/guides/source/form_helpers.textile +++ b/railties/guides/source/form_helpers.textile @@ -644,7 +644,7 @@ Fundamentally HTML forms don't know about any sort of structured data, all they TIP: You may find you can try out examples in this section faster by using the console to directly invoke Rails' parameter parser. For example, <ruby> -ActionController::UrlEncodedPairParser.parse_query_parameters "name=fred&phone=0123456789" +ActionController::UrlEncodedPairParser.parse_query_parameters "name=fred&phone=0123456789" # => {"name"=>"fred", "phone"=>"0123456789"} </ruby> diff --git a/railties/guides/source/generators.textile b/railties/guides/source/generators.textile index 6945f6f9bb..4fec1760c4 100644 --- a/railties/guides/source/generators.textile +++ b/railties/guides/source/generators.textile @@ -371,16 +371,16 @@ h3. Application templates Now that you've seen how generators can be used _inside_ an application, did you know they can also be used to _generate_ applications too? This kind of generator is referred as a "template". <ruby> - gem("rspec-rails", :group => "test") - gem("cucumber-rails", :group => "test") - - if yes?("Would you like to install Devise?") - gem("devise") - generate("devise:install") - model_name = ask("What would you like the user model to be called? [user]") - model_name = "user" if model_name.blank? - generate("devise", model_name) - end +gem("rspec-rails", :group => "test") +gem("cucumber-rails", :group => "test") + +if yes?("Would you like to install Devise?") + gem("devise") + generate("devise:install") + model_name = ask("What would you like the user model to be called? [user]") + model_name = "user" if model_name.blank? + generate("devise", model_name) +end </ruby> In the above template we specify that the application relies on the +rspec-rails+ and +cucumber-rails+ gem so these two will be added to the +test+ group in the +Gemfile+. Then we pose a question to the user about whether or not they would like to install Devise. If the user replies "y" or "yes" to this question, then the template will add Devise to the +Gemfile+ outside of any group and then runs the +devise:install+ generator. This template then takes the users input and runs the +devise+ generator, with the user's answer from the last question being passed to this generator. @@ -403,7 +403,7 @@ Whilst the final section of this guide doesn't cover how to generate the most aw h3. Generator methods -The following are methods available for both generators and templates for Rails. +The following are methods available for both generators and templates for Rails. NOTE: Methods provided by Thor are not covered this guide and can be found in "Thor's documentation":http://rdoc.info/github/wycats/thor/master/Thor/Actions.html @@ -428,8 +428,8 @@ h4. +gem+ Specifies a gem dependency of the application. <ruby> - gem("rspec", :group => "test", :version => "2.1.0") - gem("devise", "1.1.5") +gem("rspec", :group => "test", :version => "2.1.0") +gem("devise", "1.1.5") </ruby> Available options are: @@ -470,10 +470,9 @@ Adds a line to +config/application.rb+ directly after the application class defi This method can also take a block: <ruby> - application do - "config.asset_host = 'http://example.com'" - end - end +application do + "config.asset_host = 'http://example.com'" +end </ruby> Available options are: @@ -481,9 +480,9 @@ Available options are: * +:env+ - Specify an environment for this configuration option. If you wish to use this option with the block syntax the recommended syntax is as follows: <ruby> - application(nil, :env => "development") do - "config.asset_host = 'http://localhost:3000'" - end +application(nil, :env => "development") do + "config.asset_host = 'http://localhost:3000'" +end </ruby> h4. +git+ @@ -526,9 +525,9 @@ Places a file into +lib+ which contains the specified code. This method also takes a block: <ruby> - lib("super_special.rb") do - puts "Super special!" - end +lib("super_special.rb") do + puts "Super special!" +end </ruby> h4. +rakefile+ @@ -542,13 +541,13 @@ Creates a Rake file in the +lib/tasks+ directory of the application. This method also takes a block: <ruby> - rakefile("test.rake") do - %Q{ - task :rock => :environment do - puts "Rockin'" - end - } - end +rakefile("test.rake") do + %Q{ + task :rock => :environment do + puts "Rockin'" + end + } +end </ruby> h4. +initializer+ @@ -562,9 +561,9 @@ Creates an initializer in the +config/initializers+ directory of the application This method also takes a block: <ruby> - initializer("begin.rb") do - puts "Almost done!" - end +initializer("begin.rb") do + puts "Almost done!" +end </ruby> h4. +generate+ diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index 8a39bdf3c1..46e3b80a76 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -852,7 +852,7 @@ h3. Conclusion At this point you should have a good overview about how I18n support in Ruby on Rails works and are ready to start translating your project. -If you find anything missing or wrong in this guide please file a ticket on "our issue tracker":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview. If you want to discuss certain portions or have questions please sign up to our "mailinglist":http://groups.google.com/group/rails-i18n. +If you find anything missing or wrong in this guide, please file a ticket on our "issue tracker":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview. If you want to discuss certain portions or have questions, please sign up to our "mailing list":http://groups.google.com/group/rails-i18n. h3. Contributing to Rails I18n @@ -867,10 +867,10 @@ If you find your own locale (language) missing from our "example translations da h3. Resources * "rails-i18n.org":http://rails-i18n.org - Homepage of the rails-i18n project. You can find lots of useful resources on the "wiki":http://rails-i18n.org/wiki. -* "rails-i18n Google group":http://groups.google.com/group/rails-i18n - The project's mailing list. +* "Google group: rails-i18n":http://groups.google.com/group/rails-i18n - The project's mailing list. * "Github: rails-i18n":http://github.com/svenfuchs/rails-i18n/tree/master - Code repository for the rails-i18n project. Most importantly you can find lots of "example translations":http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale for Rails that should work for your application in most cases. -* "Lighthouse: rails-i18n":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview - Issue tracker for the rails-i18n project. * "Github: i18n":http://github.com/svenfuchs/i18n/tree/master - Code repository for the i18n gem. +* "Lighthouse: rails-i18n":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview - Issue tracker for the rails-i18n project. * "Lighthouse: i18n":http://i18n.lighthouseapp.com/projects/14947-ruby-i18n/overview - Issue tracker for the i18n gem. @@ -879,7 +879,7 @@ h3. Authors * "Sven Fuchs":http://www.workingwithrails.com/person/9963-sven-fuchs (initial author) * "Karel Minařík":http://www.workingwithrails.com/person/7476-karel-mina-k -If you found this guide useful please consider recommending its authors on "workingwithrails":http://www.workingwithrails.com. +If you found this guide useful, please consider recommending its authors on "workingwithrails":http://www.workingwithrails.com. h3. Footnotes diff --git a/railties/guides/source/index.html.erb b/railties/guides/source/index.html.erb index 84fbc53a69..771cfbb794 100644 --- a/railties/guides/source/index.html.erb +++ b/railties/guides/source/index.html.erb @@ -161,7 +161,7 @@ Ruby on Rails Guides <%= guide('API Documentation Guidelines', 'api_documentation_guidelines.html') do %> <p>This guide documents the Ruby on Rails API documentation guidelines.</p> <% end %> - + <%= guide('Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html') do %> <p>This guide documents the Ruby on Rails guides guidelines.</p> <% end %> diff --git a/railties/guides/source/initialization.textile b/railties/guides/source/initialization.textile index 72e10191f9..6dc13930f0 100644 --- a/railties/guides/source/initialization.textile +++ b/railties/guides/source/initialization.textile @@ -31,7 +31,7 @@ The actual +rails+ command is kept in _bin/rails_ at the and goes like this: end </ruby> -This file will attempt to load +rails/cli+ and if it cannot find it then add the +railties/lib+ path to the load path (+$:+) and will then try to require it again. +This file will attempt to load +rails/cli+ and if it cannot find it then add the +railties/lib+ path to the load path (+$:+) and will then try to require it again. h4. +railites/lib/rails/cli.rb+ @@ -120,7 +120,7 @@ This climbs the directory tree until it reaches a path which contains a +script/ This is effectively the same as doing +ruby script/rails [arguments]+. Where +[arguments]+ at this point in time is simply "server". -h4. +script/rails+ +h4. +script/rails+ This file looks like this: @@ -236,7 +236,7 @@ Now back to +action_pack/lib/action_dispatch.rb+. The next +require+ in this fil After this line, there's a require to +active_model+ which simply defines autoloads for the +ActiveModel+ part of Rails and sets up the +ActiveModel+ module which is used later on. -The last of the requires is to +rack+, which like the +active_model+ and +active_support+ requires before it, sets up the +Rack+ module as well as the autoloads for constants within it. +The last of the requires is to +rack+, which like the +active_model+ and +active_support+ requires before it, sets up the +Rack+ module as well as the autoloads for constants within it. Finally in +action_dispatch.rb+ the +ActionDispatch+ module and *its* autoloads are declared. @@ -337,7 +337,7 @@ The class *is* defined in +Rack::Server+, but is overwritten in +Rails::Server+ ... </ruby> -This method will set up keys for the +options+ which Rails will then be able to use to determine how its server should run. After +initialize+ has finished, then the +start+ method will launch the server. +This method will set up keys for the +options+ which Rails will then be able to use to determine how its server should run. After +initialize+ has finished, then the +start+ method will launch the server. h4. +Rails::Server#start+ @@ -448,7 +448,7 @@ This file begins with requiring +config/application.rb+. h4. +config/application.rb+ -This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger. +This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger. Then the fun begins! The next line is: @@ -486,6 +486,42 @@ This file is responsible for the initial definition of the +Rails+ module and, r However, before all that takes place the +rails/ruby_version_check+ file is required first. +h4. +railties/lib/rails/ruby_version_check.rb+ + +This file simply checks if the Ruby version is less than 1.8.7 or is 1.9.1 and raises an error if that is the case. Rails 3 simply will not run on earlier versions of Ruby than 1.8.7 or 1.9.1. + +NOTE: You should always endeavour to run the latest version of Ruby with your Rails applications. The benefits are many, including security fixes and the like, and very often there is a speed increase associated with it. The caveat is that you could have code that potentially breaks on the latest version, which should be fixed to work on the latest version rather than kept around as an excuse not to upgrade. + +h4. +active_support/core_ext/kernel/reporting.rb+ + +This is the first of the many Active Support core extensions that come with Rails. This one in particular defines methods in the +Kernel+ module which is mixed in to the +Object+ class so the methods are available on +main+ and can therefore be called like this: + +<ruby> + silence_warnings do + # some code + end +</ruby> + +These methods can be used to silence STDERR responses and the +silence_stream+ allows you to also silence other streams. Additionally, this mixin allows you to suppress exceptions and capture streams. For more information see the "Silencing Warnings, Streams, and Exceptions":http://guides.rubyonrails.org/active_support_core_extensions.html#silencing-warnings-streams-and-exceptions section from the Active Support Core Extensions Guide. + +h4. +active_support/core_ext/logger.rb+ + +The next file that is required is another Active Support core extension, this time to the +Logger+ class. This begins by defining the +around_[level]+ helpers for the +Logger+ class as well as other methods such as a +datetime_format+ getter and setter for the +formatter+ object tied to a +Logger+ object. + +For more information see the "Extensions to Logger":http://guides.rubyonrails.org/active_support_core_extensions.html#extensions-to-logger section from the Active Support Core Extensions Guide. + +h4. +railties/lib/rails/application.rb+ + +The next file required by +railties/lib/rails.rb+ is +application.rb+. This file defines the +Rails::Application+ constant which the application's class defined in +config/application.rb+ in a standard Rails application depends on. Before the +Rails::Application+ class is defined however, there's some other files that get required first. + +The first of these is +active_support/core_ext/hash/reverse_merge+ which can be "read about in the Active Support Core Extensions guide":http://guides.rubyonrails.org/active_support_core_extensions.html#merging under the "Merging" section. + +h4. +active_support/file_update_checker.rb+ + +The +ActiveSupport::FileUpdateChecker+ class defined within this file is responsible for checking if a file has been updated since it was last checked. This is used for monitoring the routes file for changes during development environment runs. + + + diff --git a/railties/guides/source/layout.html.erb b/railties/guides/source/layout.html.erb index bb62506f04..dbb48124d0 100644 --- a/railties/guides/source/layout.html.erb +++ b/railties/guides/source/layout.html.erb @@ -106,14 +106,14 @@ <div class="wrapper"> <div id="mainCol"> <%= yield.html_safe %> - + <h3>Feedback</h3> <p> You're encouraged to help in keeping the quality of this guide. </p> <p> If you see any typos or factual errors you are confident to - patch please clone <%= link_to 'docrails', 'https://github.com/lifo/docrails' %> + patch, please clone <%= link_to 'docrails', 'https://github.com/lifo/docrails' %> and push the change yourself. That branch of Rails has public write access. Commits are still reviewed, but that happens after you've submitted your contribution. <%= link_to 'docrails', 'https://github.com/lifo/docrails' %> is @@ -123,10 +123,10 @@ You may also find incomplete content, or stuff that is not up to date. Please do add any missing documentation for master. Check the <%= link_to 'Ruby on Rails Guides Guidelines', 'ruby_on_rails_guides_guidelines.html' %> - guide for style and conventions. + for style and conventions. </p> <p> - Issues may also be reported <%= link_to 'in Github', 'https://github.com/lifo/docrails/issues' %>. + Issues may also be reported in <%= link_to 'Github', 'https://github.com/lifo/docrails/issues' %>. </p> <p>And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome in the <%= link_to 'rubyonrails-docs mailing list', 'http://groups.google.com/group/rubyonrails-docs' %>. diff --git a/railties/guides/source/ruby_on_rails_guides_guidelines.textile b/railties/guides/source/ruby_on_rails_guides_guidelines.textile index 0bc409cbda..a2e830b574 100644 --- a/railties/guides/source/ruby_on_rails_guides_guidelines.textile +++ b/railties/guides/source/ruby_on_rails_guides_guidelines.textile @@ -16,7 +16,7 @@ h3. Titles The title of every guide uses +h2+, guide sections use +h3+, subsections +h4+, etc. -Capitalize all words except for internal articles, prepositions, conjuctions, and forms of the verb to be: +Capitalize all words except for internal articles, prepositions, conjunctions, and forms of the verb to be: <plain> h5. Middleware Stack is an Array @@ -48,7 +48,7 @@ To generate all the guides just cd into the +railties+ directory and execute rake generate_guides </plain> -You'll need the gems erubis, i18n, and RedCloth. +You'll need the gems erubis, i18n, and RedCloth. To process +my_guide.textile+ and nothing else use the +ONLY+ environment variable: @@ -58,7 +58,7 @@ rake generate_guides ONLY=my_guide Although by default guides that have not been modified are not processed, so +ONLY+ is rarely needed in practice. -To force process of al the guides pass +ALL=1+. +To force process of all the guides, pass +ALL=1+. It is also recommended that you work with +WARNINGS=1+, this detects duplicate IDs and warns about broken internal links. |