|
| 1 | +== Welcome to Rails |
| 2 | + |
| 3 | +Rails is a web-application framework that includes everything needed to create |
| 4 | +database-backed web applications according to the Model-View-Control pattern. |
| 5 | + |
| 6 | +This pattern splits the view (also called the presentation) into "dumb" |
| 7 | +templates that are primarily responsible for inserting pre-built data in between |
| 8 | +HTML tags. The model contains the "smart" domain objects (such as Account, |
| 9 | +Product, Person, Post) that holds all the business logic and knows how to |
| 10 | +persist themselves to a database. The controller handles the incoming requests |
| 11 | +(such as Save New Account, Update Product, Show Post) by manipulating the model |
| 12 | +and directing data to the view. |
| 13 | + |
| 14 | +In Rails, the model is handled by what's called an object-relational mapping |
| 15 | +layer entitled Active Record. This layer allows you to present the data from |
| 16 | +database rows as objects and embellish these data objects with business logic |
| 17 | +methods. You can read more about Active Record in |
| 18 | +link:files/vendor/rails/activerecord/README.html. |
| 19 | + |
| 20 | +The controller and view are handled by the Action Pack, which handles both |
| 21 | +layers by its two parts: Action View and Action Controller. These two layers |
| 22 | +are bundled in a single package due to their heavy interdependence. This is |
| 23 | +unlike the relationship between the Active Record and Action Pack that is much |
| 24 | +more separate. Each of these packages can be used independently outside of |
| 25 | +Rails. You can read more about Action Pack in |
| 26 | +link:files/vendor/rails/actionpack/README.html. |
| 27 | + |
| 28 | + |
| 29 | +== Getting Started |
| 30 | + |
| 31 | +1. At the command prompt, create a new Rails application: |
| 32 | + <tt>rails new myapp</tt> (where <tt>myapp</tt> is the application name) |
| 33 | + |
| 34 | +2. Change directory to <tt>myapp</tt> and start the web server: |
| 35 | + <tt>cd myapp; rails server</tt> (run with --help for options) |
| 36 | + |
| 37 | +3. Go to http://localhost:3000/ and you'll see: |
| 38 | + "Welcome aboard: You're riding Ruby on Rails!" |
| 39 | + |
| 40 | +4. Follow the guidelines to start developing your application. You can find |
| 41 | +the following resources handy: |
| 42 | + |
| 43 | +* The Getting Started Guide: http://guides.rubyonrails.org/getting_started.html |
| 44 | +* Ruby on Rails Tutorial Book: http://www.railstutorial.org/ |
| 45 | + |
| 46 | + |
| 47 | +== Debugging Rails |
| 48 | + |
| 49 | +Sometimes your application goes wrong. Fortunately there are a lot of tools that |
| 50 | +will help you debug it and get it back on the rails. |
| 51 | + |
| 52 | +First area to check is the application log files. Have "tail -f" commands |
| 53 | +running on the server.log and development.log. Rails will automatically display |
| 54 | +debugging and runtime information to these files. Debugging info will also be |
| 55 | +shown in the browser on requests from 127.0.0.1. |
| 56 | + |
| 57 | +You can also log your own messages directly into the log file from your code |
| 58 | +using the Ruby logger class from inside your controllers. Example: |
| 59 | + |
| 60 | + class WeblogController < ActionController::Base |
| 61 | + def destroy |
| 62 | + @weblog = Weblog.find(params[:id]) |
| 63 | + @weblog.destroy |
| 64 | + logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!") |
| 65 | + end |
| 66 | + end |
| 67 | + |
| 68 | +The result will be a message in your log file along the lines of: |
| 69 | + |
| 70 | + Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1! |
| 71 | + |
| 72 | +More information on how to use the logger is at http://www.ruby-doc.org/core/ |
| 73 | + |
| 74 | +Also, Ruby documentation can be found at http://www.ruby-lang.org/. There are |
| 75 | +several books available online as well: |
| 76 | + |
| 77 | +* Programming Ruby: http://www.ruby-doc.org/docs/ProgrammingRuby/ (Pickaxe) |
| 78 | +* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide) |
| 79 | + |
| 80 | +These two books will bring you up to speed on the Ruby language and also on |
| 81 | +programming in general. |
| 82 | + |
| 83 | + |
| 84 | +== Debugger |
| 85 | + |
| 86 | +Debugger support is available through the debugger command when you start your |
| 87 | +Mongrel or WEBrick server with --debugger. This means that you can break out of |
| 88 | +execution at any point in the code, investigate and change the model, and then, |
| 89 | +resume execution! You need to install ruby-debug to run the server in debugging |
| 90 | +mode. With gems, use <tt>sudo gem install ruby-debug</tt>. Example: |
| 91 | + |
| 92 | + class WeblogController < ActionController::Base |
| 93 | + def index |
| 94 | + @posts = Post.find(:all) |
| 95 | + debugger |
| 96 | + end |
| 97 | + end |
| 98 | + |
| 99 | +So the controller will accept the action, run the first line, then present you |
| 100 | +with a IRB prompt in the server window. Here you can do things like: |
| 101 | + |
| 102 | + >> @posts.inspect |
| 103 | + => "[#<Post:0x14a6be8 |
| 104 | + @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>, |
| 105 | + #<Post:0x14a6620 |
| 106 | + @attributes={"title"=>"Rails", "body"=>"Only ten..", "id"=>"2"}>]" |
| 107 | + >> @posts.first.title = "hello from a debugger" |
| 108 | + => "hello from a debugger" |
| 109 | + |
| 110 | +...and even better, you can examine how your runtime objects actually work: |
| 111 | + |
| 112 | + >> f = @posts.first |
| 113 | + => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}> |
| 114 | + >> f. |
| 115 | + Display all 152 possibilities? (y or n) |
| 116 | + |
| 117 | +Finally, when you're ready to resume execution, you can enter "cont". |
| 118 | + |
| 119 | + |
| 120 | +== Console |
| 121 | + |
| 122 | +The console is a Ruby shell, which allows you to interact with your |
| 123 | +application's domain model. Here you'll have all parts of the application |
| 124 | +configured, just like it is when the application is running. You can inspect |
| 125 | +domain models, change values, and save to the database. Starting the script |
| 126 | +without arguments will launch it in the development environment. |
| 127 | + |
| 128 | +To start the console, run <tt>rails console</tt> from the application |
| 129 | +directory. |
| 130 | + |
| 131 | +Options: |
| 132 | + |
| 133 | +* Passing the <tt>-s, --sandbox</tt> argument will rollback any modifications |
| 134 | + made to the database. |
| 135 | +* Passing an environment name as an argument will load the corresponding |
| 136 | + environment. Example: <tt>rails console production</tt>. |
| 137 | + |
| 138 | +To reload your controllers and models after launching the console run |
| 139 | +<tt>reload!</tt> |
| 140 | + |
| 141 | +More information about irb can be found at: |
| 142 | +link:http://www.rubycentral.com/pickaxe/irb.html |
| 143 | + |
| 144 | + |
| 145 | +== dbconsole |
| 146 | + |
| 147 | +You can go to the command line of your database directly through <tt>rails |
| 148 | +dbconsole</tt>. You would be connected to the database with the credentials |
| 149 | +defined in database.yml. Starting the script without arguments will connect you |
| 150 | +to the development database. Passing an argument will connect you to a different |
| 151 | +database, like <tt>rails dbconsole production</tt>. Currently works for MySQL, |
| 152 | +PostgreSQL and SQLite 3. |
| 153 | + |
| 154 | +== Description of Contents |
| 155 | + |
| 156 | +The default directory structure of a generated Ruby on Rails application: |
| 157 | + |
| 158 | + |-- app |
| 159 | + | |-- controllers |
| 160 | + | |-- helpers |
| 161 | + | |-- mailers |
| 162 | + | |-- models |
| 163 | + | `-- views |
| 164 | + | `-- layouts |
| 165 | + |-- config |
| 166 | + | |-- environments |
| 167 | + | |-- initializers |
| 168 | + | `-- locales |
| 169 | + |-- db |
| 170 | + |-- doc |
| 171 | + |-- lib |
| 172 | + | `-- tasks |
| 173 | + |-- log |
| 174 | + |-- public |
| 175 | + | |-- images |
| 176 | + | |-- javascripts |
| 177 | + | `-- stylesheets |
| 178 | + |-- script |
| 179 | + |-- test |
| 180 | + | |-- fixtures |
| 181 | + | |-- functional |
| 182 | + | |-- integration |
| 183 | + | |-- performance |
| 184 | + | `-- unit |
| 185 | + |-- tmp |
| 186 | + | |-- cache |
| 187 | + | |-- pids |
| 188 | + | |-- sessions |
| 189 | + | `-- sockets |
| 190 | + `-- vendor |
| 191 | + `-- plugins |
| 192 | + |
| 193 | +app |
| 194 | + Holds all the code that's specific to this particular application. |
| 195 | + |
| 196 | +app/controllers |
| 197 | + Holds controllers that should be named like weblogs_controller.rb for |
| 198 | + automated URL mapping. All controllers should descend from |
| 199 | + ApplicationController which itself descends from ActionController::Base. |
| 200 | + |
| 201 | +app/models |
| 202 | + Holds models that should be named like post.rb. Models descend from |
| 203 | + ActiveRecord::Base by default. |
| 204 | + |
| 205 | +app/views |
| 206 | + Holds the template files for the view that should be named like |
| 207 | + weblogs/index.html.erb for the WeblogsController#index action. All views use |
| 208 | + eRuby syntax by default. |
| 209 | + |
| 210 | +app/views/layouts |
| 211 | + Holds the template files for layouts to be used with views. This models the |
| 212 | + common header/footer method of wrapping views. In your views, define a layout |
| 213 | + using the <tt>layout :default</tt> and create a file named default.html.erb. |
| 214 | + Inside default.html.erb, call <% yield %> to render the view using this |
| 215 | + layout. |
| 216 | + |
| 217 | +app/helpers |
| 218 | + Holds view helpers that should be named like weblogs_helper.rb. These are |
| 219 | + generated for you automatically when using generators for controllers. |
| 220 | + Helpers can be used to wrap functionality for your views into methods. |
| 221 | + |
| 222 | +config |
| 223 | + Configuration files for the Rails environment, the routing map, the database, |
| 224 | + and other dependencies. |
| 225 | + |
| 226 | +db |
| 227 | + Contains the database schema in schema.rb. db/migrate contains all the |
| 228 | + sequence of Migrations for your schema. |
| 229 | + |
| 230 | +doc |
| 231 | + This directory is where your application documentation will be stored when |
| 232 | + generated using <tt>rake doc:app</tt> |
| 233 | + |
| 234 | +lib |
| 235 | + Application specific libraries. Basically, any kind of custom code that |
| 236 | + doesn't belong under controllers, models, or helpers. This directory is in |
| 237 | + the load path. |
| 238 | + |
| 239 | +public |
| 240 | + The directory available for the web server. Contains subdirectories for |
| 241 | + images, stylesheets, and javascripts. Also contains the dispatchers and the |
| 242 | + default HTML files. This should be set as the DOCUMENT_ROOT of your web |
| 243 | + server. |
| 244 | + |
| 245 | +script |
| 246 | + Helper scripts for automation and generation. |
| 247 | + |
| 248 | +test |
| 249 | + Unit and functional tests along with fixtures. When using the rails generate |
| 250 | + command, template test files will be generated for you and placed in this |
| 251 | + directory. |
| 252 | + |
| 253 | +vendor |
| 254 | + External libraries that the application depends on. Also includes the plugins |
| 255 | + subdirectory. If the app has frozen rails, those gems also go here, under |
| 256 | + vendor/rails/. This directory is in the load path. |
0 commit comments