Commit 160158448d1e691b7b2c6d2ad2f9c47c4c44cf62
1 parent
401eb567
Exists in
master
and in
1 other branch
Add a stub Readme file
Showing
2 changed files
with
6 additions
and
256 deletions
Show diff stats
README
| @@ -1,256 +0,0 @@ | @@ -1,256 +0,0 @@ | ||
| 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 | - | |-- models | ||
| 162 | - | `-- views | ||
| 163 | - | `-- layouts | ||
| 164 | - |-- config | ||
| 165 | - | |-- environments | ||
| 166 | - | |-- initializers | ||
| 167 | - | `-- locales | ||
| 168 | - |-- db | ||
| 169 | - |-- doc | ||
| 170 | - |-- lib | ||
| 171 | - | `-- tasks | ||
| 172 | - |-- log | ||
| 173 | - |-- public | ||
| 174 | - | |-- images | ||
| 175 | - | |-- javascripts | ||
| 176 | - | `-- stylesheets | ||
| 177 | - |-- script | ||
| 178 | - | `-- performance | ||
| 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. |