From 24b688d31d34dc7582c8e2ac4347d0c36e3c5e10 Mon Sep 17 00:00:00 2001 From: CassioMarques Date: Thu, 29 Jan 2009 23:22:07 -0200 Subject: More text added to the active record basics guide --- railties/doc/guides/html/active_record_basics.html | 196 +++++++++------------ 1 file changed, 80 insertions(+), 116 deletions(-) (limited to 'railties/doc/guides/html') diff --git a/railties/doc/guides/html/active_record_basics.html b/railties/doc/guides/html/active_record_basics.html index f46219ed39..7ec77781ce 100644 --- a/railties/doc/guides/html/active_record_basics.html +++ b/railties/doc/guides/html/active_record_basics.html @@ -51,12 +51,6 @@
  • Naming Conventions
    • - - -
  • - STOPED HERE - @@ -219,124 +213,94 @@ puts p.name

    When writing applications using other programming languages or frameworks, it may be necessary to write a lot of configuration code. This is particulary true for ORM frameworks in general. However, if you follow the conventions adopted by Rails, you’ll need to write very little configuration (in some case no configuration at all) when creating ActiveRecord models. The idea is that if you configure your applications in the very same way most of the times then this should be the default way. In this cases, explicity configuration would be needed only in those cases where you can’t follow the conventions for any reason.

    6.1. Naming Conventions

    -

    By default, ActiveRecord uses some naming conventions to find out how the mapping between models and database tables should be created. It uses two basic strategies to convert between class names and table names:

    -

    6.1.1. Pluralization

    -

    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.

    - -

    7. STOPED HERE

    -
    +

    By default, ActiveRecord 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 i.e. (book_clubs) -Model Class - Singular with the first letter of each word capitalized i.e. (BookClub) -Here are some additional Examples:

    +Model Class - Singular with the first letter of each word capitalized i.e. (BookClub)

    --- - - - - +++ + + + + - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + +
    - Model / Class - - Table / Schema -
    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
    -

    7.1. Schema Conventions

    -

    To take advantage of some of the magic of Rails database tables must be modeled -to reflect the ORM decisions that Rails makes.

    -
    - --- - - - - - - - - - - - - - - - -
    - Convention - -
    - Foreign keys - - These fields are named table_id i.e. (item_id, order_id) -
    - Primary Key - - Rails automatically creates a primary key column named "id" unless told otherwise. -
    -
    -

    7.1.1. Magic Field Names

    -

    When these optional fields are used in your database table definition they give the Active Record -instance additional features.

    +

    6.2. Schema Conventions

    +

    ActiveRecord 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 i.e. (item_id, order_id). These are the fields that ActiveRecord will look for when you create associations between your models. +

      +
      • +
    • +

      +Primary keys - By default, ActiveRecord will use a integer column named "id" as the table’s primary key. When using Rails Migrations to create your tables, this column will be automaticaly created. +

      +
      • +
    +

    There are also some optional column names that will create additional features to ActiveRecord instances:

    +
      +
    • +

      +created_at / created_on - ActiveRecord will store the current date and time to this field when creating the record. +

      +
      • +
    • +

      +updated_at / updated_on - ActiveRecord will store the current date and times to this field when updating the record. +

      +
      • +
    • +

      +lock_version - Adds optimistic locking to a model. +

      +
      • +
    • +

      +type - Specifies that the model uses Single Table Inheritance +

      +
      • +
    • +

      +(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 ActiveRecord. 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.While these column names are optional they are in fact reserved by ActiveRecord. 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.
    @@ -463,11 +427,11 @@ http://www.gnu.org/software/src-highlite -->

    Rails further extends this model by giving each ActiveRecord a way of describing the variety of ways records are associated with one another. We will touch on some of these associations later in the guide but I encourage readers who are interested to read the guide to ActiveRecord associations for an in-depth explanation of the variety of ways rails can model associations. - Associations between objects controlled by meta-programming macros.

    -

    8. Philosophical Approaches & Common Conventions

    +

    7. Philosophical Approaches & Common Conventions

    Rails has a reputation of being a zero-config framework which means that it aims to get you off the ground with as little pre-flight checking as possible. This speed benefit is achieved by following “Convention over Configuration”, which is to say that if you agree to live with the defaults then you benefit from a the inherent speed-boost. As Courtneay Gasking put it to me once “You don’t want to off-road on Rails”. ActiveRecord is no different, while it’s possible to override or subvert any of the conventions of AR, unless you have a good reason for doing so you will probably be happy with the defaults. The following is a list of the common conventions of ActiveRecord

    -

    9. ActiveRecord Magic

    +

    8. ActiveRecord Magic

    • @@ -482,7 +446,7 @@ updates
    -

    10. How ActiveRecord Maps your Database.

    +

    9. How ActiveRecord Maps your Database.

    • @@ -497,10 +461,10 @@ overriding conventions
    -

    11. Growing Your Database Relationships Naturally

    +

    10. Growing Your Database Relationships Naturally

    -

    12. Attributes

    +

    11. Attributes

    • @@ -522,7 +486,7 @@ dirty records
    -

    13. Validations & Callbacks

    +

    12. Validations & Callbacks

    see the Validations & Callbacks guide for more info.

    -- cgit v1.2.3