Permalink
Browse files

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

  • Loading branch information...
2 parents ae4febd + ea49935 commit 46ce7f1f77b91d3762e7eeab16a19afcb79c8477 @vijaydev vijaydev committed Oct 5, 2011
@@ -63,7 +63,7 @@ def helper_method(*methods)
methods.flatten.each do |method|
_helpers.module_eval <<-end_eval
def #{method}(*args, &block) # def current_user(*args, &block)
- _test_case.send(%(#{method}), *args, &block) # test_case.send(%(current_user), *args, &block)
+ _test_case.send(%(#{method}), *args, &block) # _test_case.send(%(current_user), *args, &block)
end # end
end_eval
end
@@ -93,10 +93,10 @@ module ClassMethods
#
# Provides you with:
#
- # AttributePerson.primary_key
+ # Person.primary_key
# # => "sysid"
- # AttributePerson.inheritance_column = 'address'
- # AttributePerson.inheritance_column
+ # Person.inheritance_column = 'address'
+ # Person.inheritance_column
# # => 'address_id'
def define_attr_method(name, value=nil, &block)
sing = singleton_class
@@ -15,7 +15,7 @@ module JSON
self.include_root_in_json = true
end
- # Returns a JSON string representing the model. Some configuration can be
+ # Returns a hash representing the model. Some configuration can be
# passed through +options+.
#
# The option <tt>include_root_in_json</tt> controls the top-level behavior
@@ -42,7 +42,7 @@ module JSON
# The remainder of the examples in this section assume include_root_in_json is set to
# <tt>false</tt>.
#
- # Without any +options+, the returned JSON string will include all the model's
+ # Without any +options+, the returned Hash will include all the model's
# attributes. For example:
#
# user = User.find(1)
@@ -38,47 +38,48 @@ When writing applications using other programming languages or frameworks, it ma
h4. Naming Conventions
-By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class +Book+, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the camelCase form, while the table name must contain the words separated by underscores. Examples:
+By default, Active Record uses some naming conventions to find out how the mapping between models and database tables should be created. Rails will pluralize your class names to find the respective database table. So, for a class +Book+, you should have a database table called *books*. The Rails pluralization mechanisms are very powerful, being capable to pluralize (and singularize) both regular and irregular words. When using class names composed of two or more words, the model class name should follow the Ruby conventions, using the CamelCase form, while the table name must contain the words separated by underscores. Examples:
-* Database Table - Plural with underscores separating words (e.g., book_clubs)
-* Model Class - Singular with the first letter of each word capitalized (e.g., BookClub)
+* Database Table - Plural with underscores separating words (e.g., +book_clubs+)
+* Model Class - Singular with the first letter of each word capitalized (e.g., +BookClub+)
|_.Model / Class |_.Table / Schema |
-|Post |posts|
-|LineItem |line_items|
-|Deer |deer|
-|Mouse |mice|
-|Person |people|
+|+Post+ |+posts+|
+|+LineItem+ |+line_items+|
+|+Deer+ |+deer+|
+|+Mouse+ |+mice+|
+|+Person+ |+people+|
h4. Schema Conventions
Active Record uses naming conventions for the columns in database tables, depending on the purpose of these columns.
-* *Foreign keys* - These fields should be named following the pattern table_id (e.g., item_id, order_id). These are the fields that Active Record will look for when you create associations between your models.
-* *Primary keys* - By default, Active Record will use an integer column named "id" as the table's primary key. When using "Rails Migrations":migrations.html to create your tables, this column will be automatically created.
+* *Foreign keys* - These fields should be named following the pattern +singularized_table_name_id+ (e.g., +item_id+, +order_id+). These are the fields that Active Record will look for when you create associations between your models.
+* *Primary keys* - By default, Active Record will use an integer column named +id+ as the table's primary key. When using "Rails Migrations":migrations.html to create your tables, this column will be automatically created.
There are also some optional column names that will create additional features to Active Record instances:
-* *created_at* - Automatically gets set to the current date and time when the record is first created.
-* *created_on* - Automatically gets set to the current date when the record is first created.
-* *updated_at* - Automatically gets set to the current date and time whenever the record is updated.
-* *updated_on* - Automatically gets set to the current date whenever the record is updated.
-* *lock_version* - Adds "optimistic locking":http://api.rubyonrails.org/classes/ActiveRecord/Locking.html to a model.
-* *type* - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.org/classes/ActiveRecord/Base.html
-* *(table_name)_count* - Used to cache the number of belonging objects on associations. For example, a +comments_count+ column in a +Post+ class that has many instances of +Comment+ will cache the number of existent comments for each post.
+* +created_at+ - Automatically gets set to the current date and time when the record is first created.
+* +created_on+ - Automatically gets set to the current date when the record is first created.
+* +updated_at+ - Automatically gets set to the current date and time whenever the record is updated.
+* +updated_on+ - Automatically gets set to the current date whenever the record is updated.
+* +lock_version+ - Adds "optimistic locking":http://api.rubyonrails.org/classes/ActiveRecord/Locking.html to a model.
+* +type+ - Specifies that the model uses "Single Table Inheritance":http://api.rubyonrails.org/classes/ActiveRecord/Base.html
+* +(table_name)_count+ - Used to cache the number of belonging objects on associations. For example, a +comments_count+ column in a +Post+ class that has many instances of +Comment+ will cache the number of existent comments for each post.
-NOTE: While these column names are optional they are in fact reserved by Active Record. Steer clear of reserved keywords unless you want the extra functionality. For example, "type" is a reserved keyword used to designate a table using Single Table Inheritance. If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling.
+NOTE: While these column names are optional, they are in fact reserved by Active Record. Steer clear of reserved keywords unless you want the extra functionality. For example, +type+ is a reserved keyword used to designate a table using Single Table Inheritance (STI). If you are not using STI, try an analogous keyword like "context", that may still accurately describe the data you are modeling.
h3. Creating Active Record Models
-It's very easy to create Active Record models. All you have to do is to subclass the +ActiveRecord::Base+ class and you're good to go:
+It is very easy to create Active Record models. All you have to do is to subclass the +ActiveRecord::Base+ class and you're good to go:
<ruby>
-class Product < ActiveRecord::Base; end
+class Product < ActiveRecord::Base
+end
</ruby>
-This will create a +Product+ model, mapped to a *products* table at the database. By doing this you'll also have the ability to map the columns of each row in that table with the attributes of the instances of your model. So, suppose that the *products* table was created using an SQL sentence like:
+This will create a +Product+ model, mapped to a +products+ table at the database. By doing this you'll also have the ability to map the columns of each row in that table with the attributes of the instances of your model. Suppose that the +products+ table was created using an SQL sentence like:
<sql>
CREATE TABLE products (
@@ -126,31 +127,31 @@ class Product < ActiveRecord::Base
end
</ruby>
-h3. Reading and Writing Data
+h3. CRUD: Reading and Writing Data
CRUD is an acronym for the four verbs we use to operate on data: *C*reate, *R*ead, *U*pdate and *D*elete. Active Record automatically creates methods to allow an application to read and manipulate data stored within its tables.
h4. Create
-Active Record objects can be created from a hash, a block or have its attributes manually set after creation. The _new_ method will return a new object while _create_ will return the object and save it to the database.
+Active Record objects can be created from a hash, a block or have their attributes manually set after creation. The +new+ method will return a new object while +create+ will return the object and save it to the database.
-For example, given a model +User+ with attributes of +name+ and +occupation+, the _create_ method call will create and save a new record into the database:
+For example, given a model +User+ with attributes of +name+ and +occupation+, the +create+ method call will create and save a new record into the database:
<ruby>
user = User.create(:name => "David", :occupation => "Code Artist")
</ruby>
-Using the _new_ method, an object can be created without being saved:
+Using the +new+ method, an object can be created without being saved:
<ruby>
user = User.new
user.name = "David"
user.occupation = "Code Artist"
</ruby>
-A call to _user.save_ will commit the record to the database.
+A call to +user.save+ will commit the record to the database.
-Finally, passing a block to either create or new will return a new User object:
+Finally, if a block is provided, both +create+ and +new+ will yield the new object to that block for initialization:
<ruby>
user = User.new do |u|
@@ -164,7 +165,7 @@ h4. Read
Active Record provides a rich API for accessing data within a database. Below are a few examples of different data access methods provided by Active Record.
<ruby>
- # return all records
+ # return array with all records
users = User.all
</ruby>
@@ -616,7 +616,7 @@ c1.first_name = "Michael"
c1.save
c2.name = "should fail"
-c2.save # Raises a ActiveRecord::StaleObjectError
+c2.save # Raises an ActiveRecord::StaleObjectError
</ruby>
You're then responsible for dealing with the conflict by rescuing the exception and either rolling back, merging, or otherwise apply the business logic needed to resolve the conflict.
Oops, something went wrong.

0 comments on commit 46ce7f1

Please sign in to comment.