diff options
Diffstat (limited to 'railties/guides/source')
| -rw-r--r-- | railties/guides/source/getting_started.textile | 109 |
1 files changed, 79 insertions, 30 deletions
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 1bdfd79476..0912355e83 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -13,17 +13,23 @@ WARNING. This Guide is based on Rails 3.1. Some of the code shown here will not h3. Guide Assumptions -This guide is designed for beginners who want to get started with a Rails application from scratch. It does not assume that you have any prior experience with Rails. However, to get the most out of it, you need to have some prerequisites installed: +This guide is designed for beginners who want to get started with a Rails application from scratch. It does not assume +that you have any prior experience with Rails. However, to get the most out of it, you need to have some prerequisites +installed: * The "Ruby":http://www.ruby-lang.org/en/downloads language version 1.8.7 or higher -TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails 3.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing. +TIP: Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails 3.0. Ruby Enterprise Edition have these +fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on +Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing. * The "RubyGems":http://rubyforge.org/frs/?group_id=126 packaging system ** If you want to learn more about RubyGems, please read the "RubyGems User Guide":http://docs.rubygems.org/read/book/1 * A working installation of the "SQLite3 Database":http://www.sqlite.org -Rails is a web application framework running on the Ruby programming language. If you have no prior experience with Ruby, you will find a very steep learning curve diving straight into Rails. There are some good free resources on the internet for learning Ruby, including: +Rails is a web application framework running on the Ruby programming language. If you have no prior experience with +Ruby, you will find a very steep learning curve diving straight into Rails. There are some good free resources on the +internet for learning Ruby, including: * "Mr. Neighborly's Humble Little Ruby Book":http://www.humblelittlerubybook.com * "Programming Ruby":http://www.ruby-doc.org/docs/ProgrammingRuby/ @@ -31,15 +37,23 @@ Rails is a web application framework running on the Ruby programming language. I h3. What is Rails? -Rails is a web application development framework written in the Ruby language. It is designed to make programming web applications easier by making assumptions about what every developer needs to get started. It allows you to write less code while accomplishing more than many other languages and frameworks. Experienced Rails developers also report that it makes web application development more fun. +Rails is a web application development framework written in the Ruby language. It is designed to make programming web +applications easier by making assumptions about what every developer needs to get started. It allows you to write less +code while accomplishing more than many other languages and frameworks. Experienced Rails developers also report that +it makes web application development more fun. -Rails is opinionated software. It makes the assumption that there is a "best" way to do things, and it's designed to encourage that way - and in some cases to discourage alternatives. If you learn "The Rails Way" you'll probably discover a tremendous increase in productivity. If you persist in bringing old habits from other languages to your Rails development, and trying to use patterns you learned elsewhere, you may have a less happy experience. +Rails is opinionated software. It makes the assumption that there is a "best" way to do things, and it's designed to +encourage that way - and in some cases to discourage alternatives. If you learn "The Rails Way" you'll probably discover +a tremendous increase in productivity. If you persist in bringing old habits from other languages to your Rails +development, and trying to use patterns you learned elsewhere, you may have a less happy experience. The Rails philosophy includes several guiding principles: * DRY - "Don't Repeat Yourself" - suggests that writing the same code over and over again is a bad thing. -* Convention Over Configuration - means that Rails makes assumptions about what you want to do and how you're going to do it, rather than requiring you to specify every little thing through endless configuration files. -* REST is the best pattern for web applications - organizing your application around resources and standard HTTP verbs is the fastest way to go. +* Convention Over Configuration - means that Rails makes assumptions about what you want to do and how you're going to +d o it, rather than requiring you to specify every little thing through endless configuration files. +* REST is the best pattern for web applications - organizing your application around resources and standard HTTP verbs +i s the fastest way to go. h4. The MVC Architecture @@ -51,20 +65,29 @@ At the core of Rails is the Model, View, Controller architecture, usually just c h5. Models -A model represents the information (data) of the application and the rules to manipulate that data. In the case of Rails, models are primarily used for managing the rules of interaction with a corresponding database table. In most cases, each table in your database will correspond to one model in your application. The bulk of your application's business logic will be concentrated in the models. +A model represents the information (data) of the application and the rules to manipulate that data. In the case of +Rails, models are primarily used for managing the rules of interaction with a corresponding database table. In most +cases, each table in your database will correspond to one model in your application. The bulk of your application's +business logic will be concentrated in the models. h5. Views -Views represent the user interface of your application. In Rails, views are often HTML files with embedded Ruby code that perform tasks related solely to the presentation of the data. Views handle the job of providing data to the web browser or other tool that is used to make requests from your application. +Views represent the user interface of your application. In Rails, views are often HTML files with embedded Ruby code +that perform tasks related solely to the presentation of the data. Views handle the job of providing data to the web +browser or other tool that is used to make requests from your application. h5. Controllers -Controllers provide the "glue" between models and views. In Rails, controllers are responsible for processing the incoming requests from the web browser, interrogating the models for data, and passing that data on to the views for presentation. +Controllers provide the "glue" between models and views. In Rails, controllers are responsible for processing the +incoming requests from the web browser, interrogating the models for data, and passing that data on to the views for +presentation. h4. The Components of Rails -Rails ships as many individual components. Each of these components are briefly explained below. If you are new to Rails, as you read this section, don't get hung up on the details of each component, as they will be -explained in further detail later. For instance, we will bring up Rack applications, but you don't need to know anything about them to continue with this guide. +Rails ships as many individual components. Each of these components are briefly explained below. If you are new to +Rails, as you read this section, don't get hung up on the details of each component, as they will be explained in +further detail later. For instance, we will bring up Rack applications, but you don't need to know anything about them +to continue with this guide. * Action Pack ** Action Controller @@ -84,7 +107,9 @@ Action Pack is a single gem that contains Action Controller, Action View and Act h6. Action Controller -Action Controller is the component that manages the controllers in a Rails application. The Action Controller framework processes incoming requests to a Rails application, extracts parameters, and dispatches them to the intended action. Services provided by Action Controller include session management, template rendering, and redirect management. +Action Controller is the component that manages the controllers in a Rails application. The Action Controller framework +processes incoming requests to a Rails application, extracts parameters, and dispatches them to the intended action. +Services provided by Action Controller include session management, template rendering, and redirect management. h6. Action View @@ -94,35 +119,47 @@ are covered in more detail in another guide called "Layouts and Rendering":layou h6. Action Dispatch -Action Dispatch handles routing of web requests and dispatches them as you want, either to your application or any other Rack application. Rack applications are a more advanced topic and are covered in a separate guide called "Rails on Rack":rails_on_rack.html. +Action Dispatch handles routing of web requests and dispatches them as you want, either to your application or any other +Rack application. Rack applications are a more advanced topic and are covered in a separate guide called "Rails on +Rack":rails_on_rack.html. h5. Action Mailer -Action Mailer is a framework for building e-mail services. You can use Action Mailer to receive and process incoming email and send simple plain text or complex multipart emails based on flexible templates. +Action Mailer is a framework for building e-mail services. You can use Action Mailer to receive and process incoming +email and send simple plain text or complex multipart emails based on flexible templates. h5. Active Model -Active Model provides a defined interface between the Action Pack gem services and Object Relationship Mapping gems such as Active Record. Active Model allows Rails to utilize other ORM frameworks in place of Active Record if your application needs this. +Active Model provides a defined interface between the Action Pack gem services and Object Relationship Mapping gems +such as Active Record. Active Model allows Rails to utilize other ORM frameworks in place of Active Record if your +application needs this. h5. Active Record -Active Record is the base for the models in a Rails application. It provides database independence, basic CRUD functionality, advanced finding capabilities, and the ability to relate models to one another, among other services. +Active Record is the base for the models in a Rails application. It provides database independence, basic CRUD +functionality, advanced finding capabilities, and the ability to relate models to one another, among other services. h5. Active Resource -Active Resource provides a framework for managing the connection between business objects and RESTful web services. It implements a way to map web-based resources to local objects with CRUD semantics. +Active Resource provides a framework for managing the connection between business objects and RESTful web services. It +implements a way to map web-based resources to local objects with CRUD semantics. h5. Active Support -Active Support is an extensive collection of utility classes and standard Ruby library extensions that are used in Rails, both by the core code and by your applications. +Active Support is an extensive collection of utility classes and standard Ruby library extensions that are used in +Rails, both by the core code and by your applications. h5. Railties -Railties is the core Rails code that builds new Rails applications and glues the various frameworks and plugins together in any Rails application. +Railties is the core Rails code that builds new Rails applications and glues the various frameworks and plugins together +in any Rails application. h4. REST -Rest stands for Representational State Transfer and is the foundation of the RESTful architecture. This is generally considered to be Roy Fielding's doctoral thesis, "Architectural Styles and the Design of Network-based Software Architectures":http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. While you can read through the thesis, REST in terms of Rails boils down to two main principles: +Rest stands for Representational State Transfer and is the foundation of the RESTful architecture. This is generally +considered to be Roy Fielding's doctoral thesis, "Architectural Styles and the Design of Network-based Software +Architectures":http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm. While you can read through the thesis, REST +in terms of Rails boils down to two main principles: * Using resource identifiers such as URLs to represent resources. * Transferring representations of the state of that resource between system components. @@ -131,18 +168,23 @@ For example, to a Rails application a request such as this: <tt>DELETE /photos/17</tt> -would be understood to refer to a photo resource with the ID of 17, and to indicate a desired action - deleting that resource. REST is a natural style for the architecture of web applications, and Rails hooks into this shielding you from many of the RESTful complexities and browser quirks. +would be understood to refer to a photo resource with the ID of 17, and to indicate a desired action - deleting that +resource. REST is a natural style for the architecture of web applications, and Rails hooks into this shielding you from +many of the RESTful complexities and browser quirks. -If you'd like more details on REST as an architectural style, these resources are more approachable than Fielding's thesis: +If you'd like more details on REST as an architectural style, these resources are more approachable than Fielding's +thesis: * "A Brief Introduction to REST":http://www.infoq.com/articles/rest-introduction by Stefan Tilkov * "An Introduction to REST":http://bitworking.org/news/373/An-Introduction-to-REST (video tutorial) by Joe Gregorio * "Representational State Transfer":http://en.wikipedia.org/wiki/Representational_State_Transfer article in Wikipedia -* "How to GET a Cup of Coffee":http://www.infoq.com/articles/webber-rest-workflow by Jim Webber, Savas Parastatidis & Ian Robinson +* "How to GET a Cup of Coffee":http://www.infoq.com/articles/webber-rest-workflow by Jim Webber, Savas Parastatidis & +Ian Robinson h3. Creating a New Rails Project -If you follow this guide, you'll create a Rails project called <tt>blog</tt>, a (very) simple weblog. Before you can start building the application, you need to make sure that you have Rails itself installed. +If you follow this guide, you'll create a Rails project called <tt>blog</tt>, a (very) simple weblog. Before you can +start building the application, you need to make sure that you have Rails itself installed. h4. Installing Rails @@ -157,7 +199,9 @@ TIP. If you're working on Windows, you can quickly install Ruby and Rails with " h4. Creating the Blog Application -The best way to use this guide is to follow each step as it happens, no code or step needed to make this example application has been left out, so you can literally follow along step by step. If you need to see the completed code, you can download it from "Getting Started Code":https://github.com/mikel/getting-started-code. +The best way to use this guide is to follow each step as it happens, no code or step needed to make this example +application has been left out, so you can literally follow along step by step. If you need to see the completed code, +you can download it from "Getting Started Code":https://github.com/mikel/getting-started-code. To begin, open a terminal, navigate to a folder where you have rights to create files, and type: @@ -175,7 +219,9 @@ After you create the blog application, switch to its folder to continue work dir $ cd blog </shell> -In any case, Rails will create a folder in your working directory called <tt>blog</tt>. Open up that folder and explore its contents. Most of the work in this tutorial will happen in the <tt>app/</tt> folder, but here's a basic rundown on the function of each folder that Rails creates in a new application by default: +In any case, Rails will create a folder in your working directory called <tt>blog</tt>. Open up that folder and explore +its contents. Most of the work in this tutorial will happen in the <tt>app/</tt> folder, but here's a basic rundown on +the function of each folder that Rails creates in a new application by default: |_.File/Folder|_.Purpose| |Gemfile|This file allows you to specify what gem dependencies are needed for your Rails application. See section on Bundler, below.| @@ -196,7 +242,8 @@ In any case, Rails will create a folder in your working directory called <tt>blo h4. Installing the Required Gems -Rails applications manage gem dependencies with "Bundler":http://gembundler.com/v1.0/index.html by default. As we don't need any other gems beyond the ones in the generated +Gemfile+ we can directly run +Rails applications manage gem dependencies with "Bundler":http://gembundler.com/v1.0/index.html by default. As we don't +need any other gems beyond the ones in the generated +Gemfile+ we can directly run <shell> $ bundle install @@ -206,8 +253,10 @@ to have them ready. h4. Configuring a Database -Just about every Rails application will interact with a database. The database to use is specified in a configuration file, +config/database.yml+. -If you open this file in a new Rails application, you'll see a default database configuration using SQLite3. The file contains sections for three different environments in which Rails can run by default: +Just about every Rails application will interact with a database. The database to use is specified in a configuration +file, +config/database.yml+. +If you open this file in a new Rails application, you'll see a default database configuration using SQLite3. The file +contains sections for three different environments in which Rails can run by default: * The +development+ environment is used on your development computer as you interact manually with the application. * The +test+ environment is used to run automated tests. |