diff options
Diffstat (limited to 'guides/source')
| -rw-r--r-- | guides/source/2_2_release_notes.textile | 4 | ||||
| -rw-r--r-- | guides/source/2_3_release_notes.textile | 2 | ||||
| -rw-r--r-- | guides/source/4_0_release_notes.textile | 12 | ||||
| -rw-r--r-- | guides/source/contributing_to_ruby_on_rails.textile | 25 | ||||
| -rw-r--r-- | guides/source/debugging_rails_applications.textile | 6 | ||||
| -rw-r--r-- | guides/source/i18n.textile | 2 | ||||
| -rw-r--r-- | guides/source/migrations.textile | 47 | ||||
| -rw-r--r-- | guides/source/plugins.textile | 2 | ||||
| -rw-r--r-- | guides/source/security.textile | 2 | ||||
| -rw-r--r-- | guides/source/testing.textile | 78 |
10 files changed, 120 insertions, 60 deletions
diff --git a/guides/source/2_2_release_notes.textile b/guides/source/2_2_release_notes.textile index 3a0f2efbaf..eb4b32329b 100644 --- a/guides/source/2_2_release_notes.textile +++ b/guides/source/2_2_release_notes.textile @@ -118,9 +118,9 @@ h4. Transactional Migrations Historically, multiple-step Rails migrations have been a source of trouble. If something went wrong during a migration, everything before the error changed the database and everything after the error wasn't applied. Also, the migration version was stored as having been executed, which means that it couldn't be simply rerun by +rake db:migrate:redo+ after you fix the problem. Transactional migrations change this by wrapping migration steps in a DDL transaction, so that if any of them fail, the entire migration is undone. In Rails 2.2, transactional migrations are supported on PostgreSQL out of the box. The code is extensible to other database types in the future - and IBM has already extended it to support the DB2 adapter. -* Lead Contributor: "Adam Wiggins":http://adam.blog.heroku.com/ +* Lead Contributor: "Adam Wiggins":http://adam.heroku.com/ * More information: -** "DDL Transactions":http://adam.blog.heroku.com/past/2008/9/3/ddl_transactions/ +** "DDL Transactions":http://adam.heroku.com/past/2008/9/3/ddl_transactions/ ** "A major milestone for DB2 on Rails":http://db2onrails.com/2008/11/08/a-major-milestone-for-db2-on-rails/ h4. Connection Pooling diff --git a/guides/source/2_3_release_notes.textile b/guides/source/2_3_release_notes.textile index 15abba66ab..36f425574b 100644 --- a/guides/source/2_3_release_notes.textile +++ b/guides/source/2_3_release_notes.textile @@ -561,7 +561,7 @@ This will layer the changes from the template on top of whatever code the projec h4. Quieter Backtraces -Building on Thoughtbot's "Quiet Backtrace":http://www.thoughtbot.com/projects/quietbacktrace plugin, which allows you to selectively remove lines from +Test::Unit+ backtraces, Rails 2.3 implements +ActiveSupport::BacktraceCleaner+ and +Rails::BacktraceCleaner+ in core. This supports both filters (to perform regex-based substitutions on backtrace lines) and silencers (to remove backtrace lines entirely). Rails automatically adds silencers to get rid of the most common noise in a new application, and builds a +config/backtrace_silencers.rb+ file to hold your own additions. This feature also enables prettier printing from any gem in the backtrace. +Building on Thoughtbot's "Quiet Backtrace":https://github.com/thoughtbot/quietbacktrace plugin, which allows you to selectively remove lines from +Test::Unit+ backtraces, Rails 2.3 implements +ActiveSupport::BacktraceCleaner+ and +Rails::BacktraceCleaner+ in core. This supports both filters (to perform regex-based substitutions on backtrace lines) and silencers (to remove backtrace lines entirely). Rails automatically adds silencers to get rid of the most common noise in a new application, and builds a +config/backtrace_silencers.rb+ file to hold your own additions. This feature also enables prettier printing from any gem in the backtrace. h4. Faster Boot Time in Development Mode with Lazy Loading/Autoload diff --git a/guides/source/4_0_release_notes.textile b/guides/source/4_0_release_notes.textile index b7ac11999a..895372ba63 100644 --- a/guides/source/4_0_release_notes.textile +++ b/guides/source/4_0_release_notes.textile @@ -122,6 +122,16 @@ h3. Action Pack h4. Action Controller +* Add <tt>ActionController::Flash.add_flash_types</tt> method to allow people to register their own flash types. e.g.: + +<ruby> +class ApplicationController + add_flash_types :error, :warning +end +</ruby> + +If you add the above code, you can use <tt><%= error %></tt> in an erb, and <tt>redirect_to /foo, :error => 'message'</tt> in a controller. + * Remove Active Model dependency from Action Pack. * Support unicode characters in routes. Route will be automatically escaped, so instead of manually escaping: @@ -186,6 +196,8 @@ h5(#actioncontroller_deprecations). Deprecations h4. Action Dispatch +* 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. * Added <tt>ActionDispatch::SSL</tt> middleware that when included force all the requests to be under HTTPS protocol. diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile index 5de5d2e9f3..a8a097d156 100644 --- a/guides/source/contributing_to_ruby_on_rails.textile +++ b/guides/source/contributing_to_ruby_on_rails.textile @@ -68,12 +68,26 @@ Install first libxml2 and libxslt together with their development files for Noko $ sudo apt-get install libxml2 libxml2-dev libxslt1-dev </shell> +If you are on Fedora or CentOS, you can run + +<shell> +$ 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 . + Also, SQLite3 and its development files for the +sqlite3-ruby+ gem -- in Ubuntu you're done with just <shell> $ sudo apt-get install sqlite3 libsqlite3-dev </shell> +And if you are on Fedora or CentOS, you're done with + +<shell> +$ sudo yum install sqlite3 sqlite3-devel +</shell> + Get a recent version of "Bundler":http://gembundler.com/: <shell> @@ -152,6 +166,13 @@ $ sudo apt-get install mysql-server libmysqlclient15-dev $ sudo apt-get install postgresql postgresql-client postgresql-contrib libpq-dev </shell> +On Fedora or CentOS, just run: + +<shell> +$ sudo yum install mysql-server mysql-devel +$ sudo yum install postgresql-server postgresql-devel +</shell> + After that run: <shell> @@ -174,7 +195,7 @@ and create the test databases: <shell> $ cd activerecord -$ rake mysql:build_databases +$ bundle exec rake mysql:build_databases </shell> PostgreSQL's authentication works differently. A simple way to set up the development environment for example is to run with your development account @@ -187,7 +208,7 @@ and then create the test databases with <shell> $ cd activerecord -$ rake postgresql:build_databases +$ bundle exec rake postgresql:build_databases </shell> NOTE: Using the rake task to create the test databases ensures they have the correct character set and collation. diff --git a/guides/source/debugging_rails_applications.textile b/guides/source/debugging_rails_applications.textile index cc172042e9..667f2d2140 100644 --- a/guides/source/debugging_rails_applications.textile +++ b/guides/source/debugging_rails_applications.textile @@ -626,7 +626,7 @@ In this section, you will learn how to find and fix such leaks by using tools su h4. BleakHouse -"BleakHouse":https://github.com/fauna/bleak_house/tree/master is a library for finding memory leaks. +"BleakHouse":https://github.com/evan/bleak_house/ is a library for finding memory leaks. If a Ruby object does not go out of scope, the Ruby Garbage Collector won't sweep it since it is referenced somewhere. Leaks like this can grow slowly and your application will consume more and more memory, gradually affecting the overall system performance. This tool will help you find leaks on the Ruby heap. @@ -675,7 +675,7 @@ To analyze it, just run the listed command. The top 20 leakiest lines will be li This way you can find where your application is leaking memory and fix it. -If "BleakHouse":https://github.com/fauna/bleak_house/tree/master doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter. In that case, try using Valgrind to investigate further. +If "BleakHouse":https://github.com/evan/bleak_house/ doesn't report any heap growth but you still have memory growth, you might have a broken C extension, or real leak in the interpreter. In that case, try using Valgrind to investigate further. h4. Valgrind @@ -708,4 +708,4 @@ h3. References * "Debugging with ruby-debug":http://bashdb.sourceforge.net/ruby-debug.html * "ruby-debug cheat sheet":http://cheat.errtheblog.com/s/rdebug/ * "Ruby on Rails Wiki: How to Configure Logging":http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging -* "Bleak House Documentation":http://blog.evanweaver.com/files/doc/fauna/bleak_house/files/README.html +* "Bleak House Documentation":http://blog.evanweaver.com/files/doc/fauna/bleak_house/ diff --git a/guides/source/i18n.textile b/guides/source/i18n.textile index ee7176a6c8..8ad6ee4b73 100644 --- a/guides/source/i18n.textile +++ b/guides/source/i18n.textile @@ -220,7 +220,7 @@ Every helper method dependent on +url_for+ (e.g. helpers for named routes like + You may be satisfied with this. It does impact the readability of URLs, though, when the locale "hangs" at the end of every URL in your application. Moreover, from the architectural standpoint, locale is usually hierarchically above the other parts of the application domain: and URLs should reflect this. -You probably want URLs to look like this: +www.example.com/en/books+ (which loads the English locale) and +www.example.com/nl/books+ (which loads the Dutch locale). This is achievable with the "over-riding +default_url_options+" strategy from above: you just have to set up your routes with "+path_prefix+":http://api.rubyonrails.org/classes/ActionController/Resources.html#M000354 option in this way: +You probably want URLs to look like this: +www.example.com/en/books+ (which loads the English locale) and +www.example.com/nl/books+ (which loads the Dutch locale). This is achievable with the "over-riding +default_url_options+" strategy from above: you just have to set up your routes with "+scoping+":http://api.rubyonrails.org/classes/ActionDispatch/Routing/Mapper/Scoping.html option in this way: <ruby> # config/routes.rb diff --git a/guides/source/migrations.textile b/guides/source/migrations.textile index 342b5a4d57..06e85e5914 100644 --- a/guides/source/migrations.textile +++ b/guides/source/migrations.textile @@ -111,6 +111,7 @@ Active Record provides methods that perform common data definition tasks in a database independent way (you'll read about them in detail later): * +add_column+ +* +add_reference+ * +add_index+ * +change_column+ * +change_table+ @@ -120,6 +121,7 @@ database independent way (you'll read about them in detail later): * +remove_column+ * +remove_index+ * +rename_column+ +* +remove_reference+ If you need to perform tasks specific to your database (for example create a "foreign key":#active-record-and-referential-integrity constraint) then the @@ -332,6 +334,51 @@ 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 + +<shell> +$ rails generate migration AddUserRefToProducts user:references +</shell> + +generates + +<ruby> +class AddUserRefToProducts < ActiveRecord::Migration + def change + add_reference :products, :user, :index => true + end +end +</ruby> + +This migration will create a user_id column and appropriate index. + +h4. Supported type modifiers + +You can also specify some options just after the field type between curly braces. You can use the +following modifiers: + +* +limit+ Sets the maximum size of the +string/text/binary/integer+ fields +* +precision+ Defines the precision for the +decimal+ fields +* +scale+ Defines the scale for the +decimal+ fields +* +polymorphic+ Adds a +type+ column for +belongs_to+ associations + +For instance running + +<shell> +$ rails generate migration AddDetailsToProducts price:decimal{5,2} supplier:references{polymorphic} +</shell> + +will produce a migration that looks like this + +<ruby> +class AddDetailsToProducts < ActiveRecord::Migration + def change + add_column :products, :price, :precision => 5, :scale => 2 + add_reference :products, :user, :polymorphic => true, :index => true + end +end +</ruby> + h3. Writing a Migration Once you have created your migration using one of the generators it's time to diff --git a/guides/source/plugins.textile b/guides/source/plugins.textile index 95e38db483..9001857a5f 100644 --- a/guides/source/plugins.textile +++ b/guides/source/plugins.textile @@ -427,4 +427,4 @@ 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/ * "Gemspec Reference":http://docs.rubygems.org/read/chapter/20 -* "GemPlugins":http://www.mbleigh.com/2008/06/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins +* "GemPlugins":http://www.intridea.com/blog/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins diff --git a/guides/source/security.textile b/guides/source/security.textile index 626d6fa508..8879122b66 100644 --- a/guides/source/security.textile +++ b/guides/source/security.textile @@ -851,7 +851,7 @@ Network traffic is mostly based on the limited Western alphabet, so new characte &#108;&#101;&#114;&#116;&#40;&#39;&#88;&#83;&#83;&#39;&#41;> </html> -This example pops up a message box. It will be recognized by the above sanitize() filter, though. A great tool to obfuscate and encode strings, and thus “get to know your enemy”, is the "Hackvertor":http://www.businessinfo.co.uk/labs/hackvertor/hackvertor.php. Rails' sanitize() method does a good job to fend off encoding attacks. +This example pops up a message box. It will be recognized by the above sanitize() filter, though. A great tool to obfuscate and encode strings, and thus “get to know your enemy”, is the "Hackvertor":https://hackvertor.co.uk/public. Rails' sanitize() method does a good job to fend off encoding attacks. h5. Examples from the Underground diff --git a/guides/source/testing.textile b/guides/source/testing.textile index 947c491d8d..4faf59fad8 100644 --- a/guides/source/testing.textile +++ b/guides/source/testing.textile @@ -1,62 +1,57 @@ h2. A Guide to Testing Rails Applications -This guide covers built-in mechanisms offered by Rails to test your application. By referring to this guide, you will be able to: +This guide covers built-in mechanisms offered by Rails to test your +application. By referring to this guide, you will be able to: * Understand Rails testing terminology -* Write unit, functional and integration tests for your application +* Write unit, functional, and integration tests for your application * Identify other popular testing approaches and plugins -This guide won't teach you to write a Rails application; it assumes basic familiarity with the Rails way of doing things. - endprologue. h3. Why Write Tests for your Rails Applications? -* Rails makes it super easy to write your tests. It starts by producing skeleton test code in the background while you are creating your models and controllers. -* By simply running your Rails tests you can ensure your code adheres to the desired functionality even after some major code refactoring. -* Rails tests can also simulate browser requests and thus you can test your application's response without having to test it through your browser. - -h3. Introduction to Testing - -Testing support was woven into the Rails fabric from the beginning. It wasn't an "oh! let's bolt on support for running tests because they're new and cool" epiphany. Just about every Rails application interacts heavily with a database - and, as a result, your tests will need a database to interact with as well. To write efficient tests, you'll need to understand how to set up this database and populate it with sample data. +Rails makes it super easy to write your tests. It starts by producing skeleton test code while you are creating your models and controllers. -h4. The Three Environments +By simply running your Rails tests you can ensure your code adheres to the desired functionality even after some major code refactoring. -Every Rails application you build has 3 sides: a side for production, a side for development, and a side for testing. +Rails tests can also simulate browser requests and thus you can test your application's response without having to test it through your browser. -One place you'll find this distinction is in the +config/database.yml+ file. This YAML configuration file has 3 different sections defining 3 unique database setups: +h3. Introduction to Testing -* production -* development -* test +Testing support was woven into the Rails fabric from the beginning. It wasn't an "oh! let's bolt on support for running tests because they're new and cool" epiphany. Just about every Rails application interacts heavily with a database and, as a result, your tests will need a database to interact with as well. To write efficient tests, you'll need to understand how to set up this database and populate it with sample data. -This allows you to set up and interact with test data without any danger of your tests altering data from your production environment. +h4. The Test Environment -For example, suppose you need to test your new +delete_this_user_and_every_everything_associated_with_it+ function. Wouldn't you want to run this in an environment where it makes no difference if you destroy data or not? +By default, every Rails application has three environments: development, test, and production. The database for each one of them is configured in +config/database.yml+. -When you do end up destroying your testing database (and it will happen, trust me), you can rebuild it from scratch according to the specs defined in the development database. You can do this by running +rake db:test:prepare+. +A dedicated test database allows you to set up and interact with test data in isolation. Tests can mangle test data with confidence, that won't touch the data in the development or production databases. h4. Rails Sets up for Testing from the Word Go Rails creates a +test+ folder for you as soon as you create a Rails project using +rails new+ _application_name_. If you list the contents of this folder then you shall see: <shell> -$ ls -F test/ +$ ls -F test -fixtures/ functional/ integration/ test_helper.rb unit/ +fixtures/ functional/ integration/ performance/ test_helper.rb unit/ </shell> -The +unit+ folder is meant to hold tests for your models, the +functional+ folder is meant to hold tests for your controllers, and the +integration+ folder is meant to hold tests that involve any number of controllers interacting. Fixtures are a way of organizing test data; they reside in the +fixtures+ folder. The +test_helper.rb+ file holds the default configuration for your tests. +The +unit+ directory is meant to hold tests for your models, the +functional+ directory is meant to hold tests for your controllers, the +integration+ directory is meant to hold tests that involve any number of controllers interacting, and the +performance+ directory is meant for performance tests. + +Fixtures are a way of organizing test data; they reside in the +fixtures+ folder. + +The +test_helper.rb+ file holds the default configuration for your tests. h4. The Low-Down on Fixtures For good tests, you'll need to give some thought to setting up test data. In Rails, you can handle this by defining and customizing fixtures. -h5. What are Fixtures? +h5. What Are Fixtures? -_Fixtures_ is a fancy word for sample data. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent and assume a single format: *YAML*. +_Fixtures_ is a fancy word for sample data. Fixtures allow you to populate your testing database with predefined data before your tests run. Fixtures are database independent written in YAML. There is one file per model. -You'll find fixtures under your +test/fixtures+ directory. When you run +rails generate model+ to create a new model, fixture stubs will be automatically created and placed in this directory. +You'll find fixtures under your +test/fixtures+ directory. When you run +rails generate model+ to create a new model fixture stubs will be automatically created and placed in this directory. h5. YAML @@ -77,35 +72,20 @@ steve: profession: guy with keyboard </yaml> -Each fixture is given a name followed by an indented list of colon-separated key/value pairs. Records are separated by a blank space. You can place comments in a fixture file by using the # character in the first column. +Each fixture is given a name followed by an indented list of colon-separated key/value pairs. Records are typically separated by a blank space. You can place comments in a fixture file by using the # character in the first column. h5. ERB'in It Up -ERB allows you to embed ruby code within templates. YAML fixture format is pre-processed with ERB when you load fixtures. This allows you to use Ruby to help you generate some sample data. - -<erb> -<% earth_size = 20 %> -mercury: - size: <%= earth_size / 50 %> - brightest_on: <%= 113.days.ago.to_s(:db) %> - -venus: - size: <%= earth_size / 2 %> - brightest_on: <%= 67.days.ago.to_s(:db) %> - -mars: - size: <%= earth_size - 69 %> - brightest_on: <%= 13.days.from_now.to_s(:db) %> -</erb> - -Anything encased within the +ERB allows you to embed Ruby code within templates. The YAML fixture format is pre-processed with ERB when Rails loads fixtures. This allows you to use Ruby to help you generate some sample data. For example, the following code generates a thousand users: <erb> -<% %> +<% 1000.times do |n| %> +user_<%= n %>: + username: <%= "user%03d" % n %> + email: <%= "user%03d@example.com" % n %> +<% end %> </erb> -tag is considered Ruby code. When this fixture is loaded, the +size+ attribute of the three records will be set to 20/50, 20/2, and 20-69 respectively. The +brightest_on+ attribute will also be evaluated and formatted by Rails to be compatible with the database. - h5. Fixtures in Action Rails by default automatically loads all fixtures from the +test/fixtures+ folder for your unit and functional test. Loading involves three steps: @@ -526,7 +506,7 @@ You also have access to three instance variables in your functional tests: h4. Testing Templates and Layouts -If you want to make sure that the response rendered the correct template and layout, you can use the +assert_template+ +If you want to make sure that the response rendered the correct template and layout, you can use the +assert_template+ method: <ruby> |