Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Merge branch 'master' of github.com:lifo/docrails

  • Loading branch information...
commit 1efaed5af13f876833b3acd614e8d0116812f308 2 parents 85c8d73 + 010dbf7
Dan Pickett authored
Showing with 185 additions and 141 deletions.
  1. +2 −0  actionpack/lib/action_controller/vendor/html-scanner/html/selector.rb
  2. +1 −1  activemodel/lib/active_model/dirty.rb
  3. +1 −1  activemodel/lib/active_model/naming.rb
  4. +2 −2 activemodel/lib/active_model/translation.rb
  5. +4 −4 activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
  6. +11 −10 activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
  7. +5 −1 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
  8. +13 −0 activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb
  9. +10 −2 activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
  10. +7 −3 activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
  11. +12 −1 activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
  12. +3 −3 activerecord/lib/active_record/validations.rb
  13. +1 −3 activesupport/lib/active_support/deprecation/reporting.rb
  14. +3 −3 activesupport/lib/active_support/notifications/fanout.rb
  15. +3 −3 railties/guides/source/action_mailer_basics.textile
  16. +31 −4 railties/guides/source/active_record_querying.textile
  17. +9 −9 railties/guides/source/active_support_core_extensions.textile
  18. +5 −26 railties/guides/source/association_basics.textile
  19. +7 −7 railties/guides/source/debugging_rails_applications.textile
  20. +4 −11 railties/guides/source/getting_started.textile
  21. +49 −45 railties/guides/source/migrations.textile
  22. +2 −2 railties/guides/source/routing.textile
View
2  actionpack/lib/action_controller/vendor/html-scanner/html/selector.rb
@@ -128,6 +128,8 @@ module HTML
# (no parent element).
# * <tt>:empty</tt> -- Match the element only if it has no child elements,
# and no text content.
+ # * <tt>:content(string)</tt> -- Match the element only if it has <tt>string</tt>
+ # as its text content (ignoring leading and trailing whitespace).
# * <tt>:only-child</tt> -- Match the element if it is the only child (element)
# of its parent element.
# * <tt>:only-of-type</tt> -- Match the element if it is the only child (element)
View
2  activemodel/lib/active_model/dirty.rb
@@ -93,7 +93,7 @@ module Dirty
attribute_method_affix :prefix => 'reset_', :suffix => '!'
end
- # Do any attributes have unsaved changes?
+ # Returns true if any attribute have unsaved changes, false otherwise.
# person.changed? # => false
# person.name = 'bob'
# person.changed? # => true
View
2  activemodel/lib/active_model/naming.rb
@@ -68,7 +68,7 @@ def _singularize(string, replacement='_')
# BookModule::BookCover.model_name.i18n_key # => "book_module.book_cover"
#
# Providing the functionality that ActiveModel::Naming provides in your object
- # is required to pass the Active Model Lint test. So either extending the provided
+ # is required to pass the Active Model Lint test. So either extending the provided
# method below, or rolling your own is required.
module Naming
# Returns an ActiveModel::Name object for module. It can be
View
4 activemodel/lib/active_model/translation.rb
@@ -18,12 +18,12 @@ module ActiveModel
#
# This also provides the required class methods for hooking into the
# Rails internationalization API, including being able to define a
- # class based i18n_scope and lookup_ancestors to find translations in
+ # class based +i18n_scope+ and +lookup_ancestors+ to find translations in
# parent classes.
module Translation
include ActiveModel::Naming
- # Returns the i18n_scope for the class. Overwrite if you want custom lookup.
+ # Returns the +i18n_scope+ for the class. Overwrite if you want custom lookup.
def i18n_scope
:activemodel
end
View
8 activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb
@@ -113,7 +113,7 @@ def initialize(spec)
end
end
- # A cached lookup for table existence
+ # A cached lookup for table existence.
def table_exists?(name)
return true if @tables.key? name
@@ -135,7 +135,7 @@ def clear_cache!
@tables.clear
end
- # Clear out internal caches for table with +table_name+
+ # Clear out internal caches for table with +table_name+.
def clear_table_cache!(table_name)
@columns.delete table_name
@columns_hash.delete table_name
@@ -193,7 +193,7 @@ def disconnect!
@connections = []
end
- # Clears the cache which maps classes
+ # Clears the cache which maps classes.
def clear_reloadable_connections!
@reserved_connections.each do |name, conn|
checkin conn
@@ -365,7 +365,7 @@ def clear_active_connections!
@connection_pools.each_value {|pool| pool.release_connection }
end
- # Clears the cache which maps classes
+ # Clears the cache which maps classes.
def clear_reloadable_connections!
@connection_pools.each_value {|pool| pool.clear_reloadable_connections! }
end
View
21 activerecord/lib/active_record/connection_adapters/abstract/database_limits.rb
@@ -2,52 +2,53 @@ module ActiveRecord
module ConnectionAdapters # :nodoc:
module DatabaseLimits
- # the maximum length of a table alias
+ # Returns the maximum length of a table alias.
def table_alias_length
255
end
- # the maximum length of a column name
+ # Returns the maximum length of a column name.
def column_name_length
64
end
- # the maximum length of a table name
+ # Returns the maximum length of a table name.
def table_name_length
64
end
- # the maximum length of an index name
+ # Returns the maximum length of an index name.
def index_name_length
64
end
- # the maximum number of columns per table
+ # Returns the maximum number of columns per table.
def columns_per_table
1024
end
- # the maximum number of indexes per table
+ # Returns the maximum number of indexes per table.
def indexes_per_table
16
end
- # the maximum number of columns in a multicolumn index
+ # Returns the maximum number of columns in a multicolumn index.
def columns_per_multicolumn_index
16
end
- # the maximum number of elements in an IN (x,y,z) clause. nil means no limit
+ # Returns the maximum number of elements in an IN (x,y,z) clause.
+ # nil means no limit.
def in_clause_length
nil
end
- # the maximum length of an SQL query
+ # Returns the maximum length of an SQL query.
def sql_query_length
1048575
end
- # maximum number of joins in a single query
+ # Returns maximum number of joins in a single query.
def joins_per_query
256
end
View
6 activerecord/lib/active_record/connection_adapters/abstract/schema_statements.rb
@@ -17,6 +17,10 @@ def table_alias_for(table_name)
# def tables(name = nil) end
+ # Checks to see if the table +table_name+ exists on the database.
+ #
+ # === Example
+ # table_exists?(:developers)
def table_exists?(table_name)
tables.include?(table_name.to_s)
end
@@ -24,7 +28,7 @@ def table_exists?(table_name)
# Returns an array of indexes for the given table.
# def indexes(table_name, name = nil) end
- # Checks to see if an index exists on a table for a given index definition
+ # Checks to see if an index exists on a table for a given index definition.
#
# === Examples
# # Check an index exists
View
13 activerecord/lib/active_record/connection_adapters/mysql2_adapter.rb
@@ -132,6 +132,7 @@ def adapter_name
ADAPTER_NAME
end
+ # Returns true, since this connection adapter supports migrations.
def supports_migrations?
true
end
@@ -140,6 +141,7 @@ def supports_primary_key?
true
end
+ # Returns true, since this connection adapter supports savepoints.
def supports_savepoints?
true
end
@@ -385,6 +387,10 @@ def create_database(name, options = {})
end
end
+ # Drops a MySQL database.
+ #
+ # Example:
+ # drop_database('sebastian_development')
def drop_database(name) #:nodoc:
execute "DROP DATABASE IF EXISTS `#{name}`"
end
@@ -415,6 +421,7 @@ def drop_table(table_name, options = {})
super(table_name, options)
end
+ # Returns an array of indexes for the given table.
def indexes(table_name, name = nil)
indexes = []
current_index = nil
@@ -432,6 +439,7 @@ def indexes(table_name, name = nil)
indexes
end
+ # Returns an array of +Mysql2Column+ objects for the table specified by +table_name+.
def columns(table_name, name = nil)
sql = "SHOW FIELDS FROM #{quote_table_name(table_name)}"
columns = []
@@ -446,6 +454,10 @@ def create_table(table_name, options = {})
super(table_name, options.reverse_merge(:options => "ENGINE=InnoDB"))
end
+ # Renames a table.
+ #
+ # Example:
+ # rename_table('octopuses', 'octopi')
def rename_table(table_name, new_name)
execute "RENAME TABLE #{quote_table_name(table_name)} TO #{quote_table_name(new_name)}"
end
@@ -530,6 +542,7 @@ def show_variable(name)
variables.first['Value'] unless variables.empty?
end
+ # Returns a table's primary key and belonging sequence.
def pk_and_sequence_for(table)
keys = []
result = execute("describe #{quote_table_name(table)}")
View
12 activerecord/lib/active_record/connection_adapters/mysql_adapter.rb
@@ -201,13 +201,13 @@ def supports_bulk_alter? #:nodoc:
true
end
- # Returns +true+, since this connection adapter supports prepared statement
+ # Returns true, since this connection adapter supports prepared statement
# caching.
def supports_statement_cache?
true
end
- # Returns true.
+ # Returns true, since this connection adapter supports migrations.
def supports_migrations? #:nodoc:
true
end
@@ -217,6 +217,7 @@ def supports_primary_key? #:nodoc:
true
end
+ # Returns true, since this connection adapter supports savepoints.
def supports_savepoints? #:nodoc:
true
end
@@ -583,6 +584,7 @@ def drop_table(table_name, options = {})
super(table_name, options)
end
+ # Returns an array of indexes for the given table.
def indexes(table_name, name = nil)#:nodoc:
indexes = []
current_index = nil
@@ -601,6 +603,7 @@ def indexes(table_name, name = nil)#:nodoc:
indexes
end
+ # Returns an array of +MysqlColumn+ objects for the table specified by +table_name+.
def columns(table_name, name = nil)#:nodoc:
sql = "SHOW FIELDS FROM #{quote_table_name(table_name)}"
columns = []
@@ -614,6 +617,10 @@ def create_table(table_name, options = {}) #:nodoc:
super(table_name, options.reverse_merge(:options => "ENGINE=InnoDB"))
end
+ # Renames a table.
+ #
+ # Example:
+ # rename_table('octopuses', 'octopi')
def rename_table(table_name, new_name)
execute "RENAME TABLE #{quote_table_name(table_name)} TO #{quote_table_name(new_name)}"
end
@@ -891,6 +898,7 @@ def supports_views?
version[0] >= 5
end
+ # Returns the version of the connected MySQL server.
def version
@version ||= @connection.server_info.scan(/^(\d+)\.(\d+)\.(\d+)/).flatten.map { |v| v.to_i }
end
View
10 activerecord/lib/active_record/connection_adapters/postgresql_adapter.rb
@@ -294,7 +294,7 @@ def native_database_types #:nodoc:
NATIVE_DATABASE_TYPES
end
- # Does PostgreSQL support migrations?
+ # Returns true, since this connection adapter supports migrations.
def supports_migrations?
true
end
@@ -320,6 +320,7 @@ def supports_ddl_transactions?
true
end
+ # Returns true, since this connection adapter supports savepoints.
def supports_savepoints?
true
end
@@ -681,7 +682,7 @@ def extract_schema_and_table(name)
[schema, table]
end
- # Returns the list of all indexes for a table.
+ # Returns an array of indexes for the given table.
def indexes(table_name, name = nil)
schemas = schema_search_path.split(/,/).map { |p| quote(p) }.join(',')
result = query(<<-SQL, name)
@@ -846,6 +847,9 @@ def primary_key(table)
end
# Renames a table.
+ #
+ # Example:
+ # rename_table('octopuses', 'octopi')
def rename_table(name, new_name)
execute "ALTER TABLE #{quote_table_name(name)} RENAME TO #{quote_table_name(new_name)}"
end
@@ -930,7 +934,7 @@ def distinct(columns, orders) #:nodoc:
end
protected
- # Returns the version of the connected PostgreSQL version.
+ # Returns the version of the connected PostgreSQL server.
def postgresql_version
@connection.server_version
end
View
13 activerecord/lib/active_record/connection_adapters/sqlite_adapter.rb
@@ -58,10 +58,12 @@ def adapter_name #:nodoc:
'SQLite'
end
+ # Returns true if SQLite version is '2.0.0' or greater, false otherwise.
def supports_ddl_transactions?
sqlite_version >= '2.0.0'
end
+ # Returns true if SQLite version is '3.6.8' or greater, false otherwise.
def supports_savepoints?
sqlite_version >= '3.6.8'
end
@@ -72,7 +74,7 @@ def supports_statement_cache?
true
end
- # Returns true.
+ # Returns true, since this connection adapter supports migrations.
def supports_migrations? #:nodoc:
true
end
@@ -86,6 +88,7 @@ def requires_reloading?
true
end
+ # Returns true if SQLite version is '3.1.6' or greater, false otherwise.
def supports_add_column?
sqlite_version >= '3.1.6'
end
@@ -103,10 +106,12 @@ def clear_cache!
@statements.clear
end
+ # Returns true if SQLite version is '3.2.6' or greater, false otherwise.
def supports_count_distinct? #:nodoc:
sqlite_version >= '3.2.6'
end
+ # Returns true if SQLite version is '3.1.0' or greater, false otherwise.
def supports_autoincrement? #:nodoc:
sqlite_version >= '3.1.0'
end
@@ -249,6 +254,7 @@ def tables(name = 'SCHEMA') #:nodoc:
end
end
+ # Returns an array of +SQLiteColumn+ objects for the table specified by +table_name+.
def columns(table_name, name = nil) #:nodoc:
table_structure(table_name).map do |field|
case field["dflt_value"]
@@ -264,6 +270,7 @@ def columns(table_name, name = nil) #:nodoc:
end
end
+ # Returns an array of indexes for the given table.
def indexes(table_name, name = nil) #:nodoc:
exec_query("PRAGMA index_list(#{quote_table_name(table_name)})", name).map do |row|
IndexDefinition.new(
@@ -287,6 +294,10 @@ def remove_index!(table_name, index_name) #:nodoc:
exec_query "DROP INDEX #{quote_column_name(index_name)}"
end
+ # Renames a table.
+ #
+ # Example:
+ # rename_table('octopuses', 'octopi')
def rename_table(name, new_name)
exec_query "ALTER TABLE #{quote_table_name(name)} RENAME TO #{quote_table_name(new_name)}"
end
View
6 activerecord/lib/active_record/validations.rb
@@ -30,7 +30,7 @@ module Validations
include ActiveModel::Validations
module ClassMethods
- # Creates an object just like Base.create but calls save! instead of save
+ # Creates an object just like Base.create but calls <tt>save!</tt> instead of +save+
# so an exception is raised if the record is invalid.
def create!(attributes = nil, &block)
if attributes.is_a?(Array)
@@ -44,13 +44,13 @@ def create!(attributes = nil, &block)
end
end
- # The validation process on save can be skipped by passing :validate => false. The regular Base#save method is
+ # The validation process on save can be skipped by passing <tt>:validate => false</tt>. The regular Base#save method is
# replaced with this when the validations module is mixed in, which it is by default.
def save(options={})
perform_validations(options) ? super : false
end
- # Attempts to save the record just like Base#save but will raise a RecordInvalid exception instead of returning false
+ # Attempts to save the record just like Base#save but will raise a +RecordInvalid+ exception instead of returning false
# if the record is not valid.
def save!(options={})
perform_validations(options) ? super : raise(RecordInvalid.new(self))
View
4 activesupport/lib/active_support/deprecation/reporting.rb
@@ -5,10 +5,8 @@ class << self
# Outputs a deprecation warning to the output configured by <tt>ActiveSupport::Deprecation.behavior</tt>
#
- # Example:
- #
# ActiveSupport::Deprecation.warn("something broke!")
- # #=> "DEPRECATION WARNING: something broke! (called from your_code.rb:1)"
+ # # => "DEPRECATION WARNING: something broke! (called from your_code.rb:1)"
def warn(message = nil, callstack = caller)
return if silenced
deprecation_message(callstack, message).tap do |m|
View
6 activesupport/lib/active_support/notifications/fanout.rb
@@ -1,7 +1,7 @@
module ActiveSupport
module Notifications
- # This is a default queue implementation that ships with Notifications. It
- # just pushes events to all registered log subscribers.
+ # This is a default queue implementation that ships with Notifications.
+ # It just pushes events to all registered log subscribers.
class Fanout
def initialize
@subscribers = []
@@ -33,7 +33,7 @@ def listening?(name)
listeners_for(name).any?
end
- # This is a sync queue, so there is not waiting.
+ # This is a sync queue, so there is no waiting.
def wait
end
View
6 railties/guides/source/action_mailer_basics.textile
@@ -120,7 +120,7 @@ Now that we have a user model to play with, we will just edit the +app/controlle
<ruby>
class UsersController < ApplicationController
# POST /users
- # POST /users.xml
+ # POST /users.json
def create
@user = User.new(params[:user])
@@ -130,10 +130,10 @@ class UsersController < ApplicationController
UserMailer.welcome_email(@user).deliver
format.html { redirect_to(@user, :notice => 'User was successfully created.') }
- format.xml { render :xml => @user, :status => :created, :location => @user }
+ format.json { render :json => @user, :status => :created, :location => @user }
else
format.html { render :action => "new" }
- format.xml { render :xml => @user.errors, :status => :unprocessable_entity }
+ format.json { render :json => @user.errors, :status => :unprocessable_entity }
end
end
end
View
35 railties/guides/source/active_record_querying.textile
@@ -56,6 +56,7 @@ The methods are:
* +select+
* +group+
* +order+
+* +reorder+
* +limit+
* +offset+
* +joins+
@@ -495,9 +496,9 @@ This will return single order objects for each day, but only for the last month.
h3. Overriding Conditions
-You can specify certain conditions to be excepted by using the +except+ method.
+h4. +except+
-For example:
+You can specify certain conditions to be excepted by using the +except+ method. For example:
<ruby>
Post.where('id > 10').limit(20).order('id asc').except(:order)
@@ -509,9 +510,9 @@ The SQL that would be executed:
SELECT * FROM posts WHERE id > 10 LIMIT 20
</sql>
-You can also override conditions using the +only+ method.
+h4. +only+
-For example:
+You can also override conditions using the +only+ method. For example:
<ruby>
Post.where('id > 10').limit(20).order('id desc').only(:order, :where)
@@ -523,6 +524,32 @@ The SQL that would be executed:
SELECT * FROM posts WHERE id > 10 ORDER BY id DESC
</sql>
+h4. +reorder+
+
+The +reorder+ method overrides the default scope order. For example:
+
+<ruby>
+class Post < ActiveRecord::Base
+ ..
+ ..
+ has_many :comments, :order => 'posted_at DESC'
+end
+
+Post.find(10).comments.reorder('name')
+</ruby>
+
+The SQL that would be executed:
+
+<sql>
+SELECT * FROM posts WHERE id = 10 ORDER BY name
+</sql>
+
+In case the +reorder+ clause is not used, the SQL executed would be:
+
+<sql>
+SELECT * FROM posts WHERE id = 10 ORDER BY posted_at DESC
+</sql>
+
h3. Readonly Objects
Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.
View
18 railties/guides/source/active_support_core_extensions.textile
@@ -449,9 +449,9 @@ The predicate +in?+ tests if an object is included in another object. An +Argume
Examples of +in?+:
<ruby>
- 1.in?([1,2]) # => true
- "lo".in?("hello") # => true
- 25.in?(30..50) # => false
+1.in?([1,2]) # => true
+"lo".in?("hello") # => true
+25.in?(30..50) # => false
</ruby>
NOTE: Defined in +active_support/core_ext/object/inclusion.rb+.
@@ -541,9 +541,9 @@ The default value can be also specified with a block, which is called in the con
<ruby>
class User
attr_accessor :name, :surname
- attr_accessor_with_default(:full_name) {
- [name, surname].compact.join(" ")
- }
+ attr_accessor_with_default(:full_name) do
+ [name, surname].compact.join(" ")
+ end
end
u = User.new
@@ -1223,7 +1223,7 @@ NOTE: Defined in +active_support/core_ext/string/output_safety.rb+.
h4. +squish+
-The method +String#squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each:
+The method +squish+ strips leading and trailing whitespace, and substitutes runs of whitespace with a single space each:
<ruby>
" \n foo\n\r \t bar \n".squish # => "foo bar"
@@ -1996,11 +1996,11 @@ Active Support augments the API of arrays to ease certain ways of accessing them
[].to(7) # => []
</ruby>
-Similarly, +from+ returns the tail from the element at the passed index on:
+Similarly, +from+ returns the tail from the element at the passed index to the end. If the index is greater than the length of the array, it returns an empty array.
<ruby>
%w(a b c d).from(2) # => %w(c d)
-%w(a b c d).from(10) # => nil
+%w(a b c d).from(10) # => []
[].from(0) # => []
</ruby>
View
31 railties/guides/source/association_basics.textile
@@ -229,7 +229,7 @@ The corresponding migration might look like this:
<ruby>
class CreateSuppliers < ActiveRecord::Migration
- def self.up
+ def change
create_table :suppliers do |t|
t.string :name
t.timestamps
@@ -241,11 +241,6 @@ class CreateSuppliers < ActiveRecord::Migration
t.timestamps
end
end
-
- def self.down
- drop_table :accounts
- drop_table :suppliers
- end
end
</ruby>
@@ -314,7 +309,7 @@ If you have an instance of the +Picture+ model, you can get to its parent via +@
<ruby>
class CreatePictures < ActiveRecord::Migration
- def self.up
+ def change
create_table :pictures do |t|
t.string :name
t.integer :imageable_id
@@ -322,10 +317,6 @@ class CreatePictures < ActiveRecord::Migration
t.timestamps
end
end
-
- def self.down
- drop_table :pictures
- end
end
</ruby>
@@ -333,17 +324,13 @@ This migration can be simplified by using the +t.references+ form:
<ruby>
class CreatePictures < ActiveRecord::Migration
- def self.up
+ def change
create_table :pictures do |t|
t.string :name
t.references :imageable, :polymorphic => true
t.timestamps
end
end
-
- def self.down
- drop_table :pictures
- end
end
</ruby>
@@ -413,17 +400,13 @@ This declaration needs to be backed up by the proper foreign key declaration on
<ruby>
class CreateOrders < ActiveRecord::Migration
- def self.up
+ def change
create_table :orders do |t|
t.datetime :order_date
t.string :order_number
t.integer :customer_id
end
end
-
- def self.down
- drop_table :orders
- end
end
</ruby>
@@ -451,16 +434,12 @@ These need to be backed up by a migration to create the +assemblies_parts+ table
<ruby>
class CreateAssemblyPartJoinTable < ActiveRecord::Migration
- def self.up
+ def change
create_table :assemblies_parts, :id => false do |t|
t.integer :assembly_id
t.integer :part_id
end
end
-
- def self.down
- drop_table :assemblies_parts
- end
end
</ruby>
View
14 railties/guides/source/debugging_rails_applications.textile
@@ -279,14 +279,14 @@ This command shows you where you are in the code by printing 10 lines centered a
[1, 10] in /PathToProject/posts_controller.rb
1 class PostsController < ApplicationController
2 # GET /posts
- 3 # GET /posts.xml
+ 3 # GET /posts.json
4 def index
5 debugger
=> 6 @posts = Post.all
7
8 respond_to do |format|
9 format.html # index.html.erb
- 10 format.xml { render :xml => @posts }
+ 10 format.json { render :json => @posts }
</shell>
If you repeat the +list+ command, this time using just +l+, the next ten lines of the file will be printed out.
@@ -298,7 +298,7 @@ If you repeat the +list+ command, this time using just +l+, the next ten lines o
12 end
13
14 # GET /posts/1
- 15 # GET /posts/1.xml
+ 15 # GET /posts/1.json
16 def show
17 @post = Post.find(params[:id])
18
@@ -315,14 +315,14 @@ On the other hand, to see the previous ten lines you should type +list-+ (or +l-
[1, 10] in /PathToProject/posts_controller.rb
1 class PostsController < ApplicationController
2 # GET /posts
- 3 # GET /posts.xml
+ 3 # GET /posts.json
4 def index
5 debugger
6 @posts = Post.all
7
8 respond_to do |format|
9 format.html # index.html.erb
- 10 format.xml { render :xml => @posts }
+ 10 format.json { render :json => @posts }
</shell>
This way you can move inside the file, being able to see the code above and over the line you added the +debugger+.
@@ -333,14 +333,14 @@ Finally, to see where you are in the code again you can type +list=+
[1, 10] in /PathToProject/posts_controller.rb
1 class PostsController < ApplicationController
2 # GET /posts
- 3 # GET /posts.xml
+ 3 # GET /posts.json
4 def index
5 debugger
=> 6 @posts = Post.all
7
8 respond_to do |format|
9 format.html # index.html.erb
- 10 format.xml { render :xml => @posts }
+ 10 format.json { render :json => @posts }
</shell>
h4. The Context
View
15 railties/guides/source/getting_started.textile
@@ -378,7 +378,7 @@ If you look in the +db/migrate/20100207214725_create_posts.rb+ file (remember, y
<ruby>
class CreatePosts < ActiveRecord::Migration
- def self.up
+ def change
create_table :posts do |t|
t.string :name
t.string :title
@@ -387,14 +387,10 @@ class CreatePosts < ActiveRecord::Migration
t.timestamps
end
end
-
- def self.down
- drop_table :posts
- end
end
</ruby>
-The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date. The +up+ command in this case creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide.
+The above migration creates a method name +change+ which will be called when you run this migration. The action defined in that method is also reversible, which means Rails knows how to reverse the change made by this migration, in case you want to reverse it at later date. By default, when you run this migration it will creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide.
At this point, you can use a rake command to run the migration:
@@ -807,7 +803,7 @@ In addition to the model, Rails has also made a migration to create the correspo
<ruby>
class CreateComments < ActiveRecord::Migration
- def self.up
+ def change
create_table :comments do |t|
t.string :commenter
t.text :body
@@ -818,10 +814,6 @@ class CreateComments < ActiveRecord::Migration
add_index :comments, :post_id
end
-
- def self.down
- drop_table :comments
- end
end
</ruby>
@@ -1458,6 +1450,7 @@ Two very common sources of data that are not UTF-8:
h3. Changelog
+* April 26, 2011: Changed migration code from +up+, +down+ pair to +change+ method "Prem Sichanugrist":"http://sikachu.com"
* April 11, 2011: Changed scaffold_controller generator to create format block for JSON instead of XML "Sebastian Martinez":http://www.wyeworks.com
* August 30, 2010: Minor editing after Rails 3 release by "Joost Baaij":http://www.spacebabies.nl
* July 12, 2010: Fixes, editing and updating of code samples by "Jaime Iniesta":http://jaimeiniesta.com
View
94 railties/guides/source/migrations.textile
@@ -21,7 +21,7 @@ Before I dive into the details of a migration, here are a few examples of the so
<ruby>
class CreateProducts < ActiveRecord::Migration
- def self.up
+ def up
create_table :products do |t|
t.string :name
t.text :description
@@ -30,7 +30,7 @@ class CreateProducts < ActiveRecord::Migration
end
end
- def self.down
+ def down
drop_table :products
end
end
@@ -42,14 +42,14 @@ Migrations are not limited to changing the schema. You can also use them to fix
<ruby>
class AddReceiveNewsletterToUsers < ActiveRecord::Migration
- def self.up
+ def up
change_table :users do |t|
t.boolean :receive_newsletter, :default => false
end
User.update_all ["receive_newsletter = ?", true]
end
- def self.down
+ def down
remove_column :users, :receive_newsletter
end
end
@@ -58,6 +58,21 @@ end
This migration adds a +receive_newsletter+ column to the +users+ table. We want it to default to +false+ for new users, but existing users are considered
to have already opted in, so we use the User model to set the flag to +true+ for existing users.
+Rails 3.1 makes migrations smarter by providing a new <tt>change</tt> method. This method is preferred for writing constructive migrations (adding columns or tables). The migration knows how to migrate your database and reverse it when the migration is rolled back without the need to write a separate +down+ method.
+
+<ruby>
+class CreateProducts < ActiveRecord::Migration
+ def change
+ create_table :products do |t|
+ t.string :name
+ t.text :description
+
+ t.timestamps
+ end
+ end
+end
+</ruby>
+
NOTE: Some "caveats":#using-models-in-your-migrations apply to using models in your migrations.
h4. Migrations are Classes
@@ -116,7 +131,7 @@ will create a migration that looks like this
<ruby>
class CreateProducts < ActiveRecord::Migration
- def self.up
+ def change
create_table :products do |t|
t.string :name
t.text :description
@@ -124,10 +139,6 @@ class CreateProducts < ActiveRecord::Migration
t.timestamps
end
end
-
- def self.down
- drop_table :products
- end
end
</ruby>
@@ -146,10 +157,7 @@ This will create an empty but appropriately named migration:
<ruby>
class AddPartNumberToProducts < ActiveRecord::Migration
- def self.up
- end
-
- def self.down
+ def change
end
end
</ruby>
@@ -164,13 +172,9 @@ will generate
<ruby>
class AddPartNumberToProducts < ActiveRecord::Migration
- def self.up
+ def change
add_column :products, :part_number, :string
end
-
- def self.down
- remove_column :products, :part_number
- end
end
</ruby>
@@ -184,11 +188,11 @@ generates
<ruby>
class RemovePartNumberFromProducts < ActiveRecord::Migration
- def self.up
+ def up
remove_column :products, :part_number
end
- def self.down
+ def down
add_column :products, :part_number, :string
end
end
@@ -204,20 +208,17 @@ generates
<ruby>
class AddDetailsToProducts < ActiveRecord::Migration
- def self.up
+ def change
add_column :products, :part_number, :string
add_column :products, :price, :decimal
end
-
- def self.down
- remove_column :products, :price
- remove_column :products, :part_number
- end
end
</ruby>
As always, what has been generated for you is just a starting point. You can add or remove from it as you see fit.
+NOTE: The generated migration file for destructive migrations will still be old-style using the +up+ and +down+ methods. This is because Rails doesn't know the original data types defined when you made the original changes.
+
h3. Writing a Migration
Once you have created your migration using one of the generators it's time to get to work!
@@ -337,6 +338,21 @@ If the helpers provided by Active Record aren't enough you can use the +execute+
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 (which provides the methods available on the object yielded by +create_table+) and "<tt>ActiveRecord::ConnectionAdapters::Table</tt>":http://api.rubyonrails.org/classes/ActiveRecord/ConnectionAdapters/Table.html (which provides the methods available on the object yielded by +change_table+).
+h4. Writing Your +change+ Method
+
+The +change+ method removes the need to write both +up+ and +down+ methods in those cases that Rails know how to revert the changes automatically. Currently, the +change+ method supports only these migration definitions:
+
+* +add_column+
+* +add_index+
+* +add_timestamp+
+* +create_table+
+* +remove_timestamps+
+* +rename_column+
+* +rename_index+
+* +rename_table+
+
+If you're going to use other methods, you'll have to write the +up+ and +down+ methods normally.
+
h4. Writing Your +down+ Method
The +down+ method of your migration should revert the transformations done by the +up+ method. In other words the database schema should be unchanged if you do an +up+ followed by a +down+. For example if you create a table in the +up+ method you should drop it in the +down+ method. It is wise to do things in precisely the reverse order to in the +up+ method. For example
@@ -344,7 +360,7 @@ The +down+ method of your migration should revert the transformations done by th
<ruby>
class ExampleMigration < ActiveRecord::Migration
- def self.up
+ def up
create_table :products do |t|
t.references :category
end
@@ -361,7 +377,7 @@ class ExampleMigration < ActiveRecord::Migration
rename_column :users, :email, :email_address
end
- def self.down
+ def down
rename_column :users, :email_address, :email
remove_column :users, :home_page_url
execute "ALTER TABLE products DROP FOREIGN KEY fk_products_categories"
@@ -369,9 +385,8 @@ class ExampleMigration < ActiveRecord::Migration
end
end
</ruby>
-Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise +IrreversibleMigration+ from your +down+ method. If someone tries to revert your migration an error message will be
-displayed saying that it can't be done.
+Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise +IrreversibleMigration+ from your +down+ method. If someone tries to revert your migration an error message will be displayed saying that it can't be done.
h3. Running Migrations
@@ -449,7 +464,7 @@ For example, this migration
<ruby>
class CreateProducts < ActiveRecord::Migration
- def self.up
+ def change
suppress_messages do
create_table :products do |t|
t.string :name
@@ -465,10 +480,6 @@ class CreateProducts < ActiveRecord::Migration
250
end
end
-
- def self.down
- drop_table :products
- end
end
</ruby>
@@ -499,11 +510,7 @@ class AddPartNumberToProducts < ActiveRecord::Migration
class Product < ActiveRecord::Base
end
- def self.up
- ...
- end
-
- def self.down
+ def change
...
end
end
@@ -519,15 +526,11 @@ class AddPartNumberToProducts < ActiveRecord::Migration
class Product < ActiveRecord::Base
end
- def self.up
+ def change
add_column :product, :part_number, :string
Product.reset_column_information
...
end
-
- def self.down
- ...
- end
end
</ruby>
@@ -590,5 +593,6 @@ Although Active Record does not provide any tools for working directly with such
h3. Changelog
+* April 26, 2011: change generated +up+ and +down+ methods to +change+ method, and describe detail about +change+ method by "Prem Sichanugrist":http://sikachu.com
* July 15, 2010: minor typos corrected by "Jaime Iniesta":http://jaimeiniesta.com
* September 14, 2008: initial version by "Frederick Cheung":credits.html#fcheung
View
4 railties/guides/source/routing.textile
@@ -391,7 +391,7 @@ NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment.
match ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/
</ruby>
-TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment add a constraint which overrides this - for example +:id => /[^\/]<plus>/+ allows anything except a slash.
+TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment add a constraint which overrides this - for example +:id+ => /[^\/]+/ allows anything except a slash.
h4. Static Segments
@@ -660,7 +660,7 @@ end
NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context.
-TIP: By default the +:id+ parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an +:id+ add a constraint which overrides this - for example +:id => /[^\/]+/+ allows anything except a slash.
+TIP: By default the +:id+ parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an +:id+ add a constraint which overrides this - for example +:id+ => /[^\/]+/ allows anything except a slash.
h4. Overriding the Named Helpers
Please sign in to comment.
Something went wrong with that request. Please try again.