|
1 | | -== Welcome to Rails |
2 | | - |
3 | | -Rails is a web-application and persistence framework that includes everything |
4 | | -needed to create database-backed web-applications according to the |
5 | | -Model-View-Control pattern of separation. This pattern splits the view (also |
6 | | -called the presentation) into "dumb" templates that are primarily responsible |
7 | | -for inserting pre-built data in between HTML tags. The model contains the |
8 | | -"smart" domain objects (such as Account, Product, Person, Post) that holds all |
9 | | -the business logic and knows how to persist themselves to a database. The |
10 | | -controller handles the incoming requests (such as Save New Account, Update |
11 | | -Product, Show Post) by manipulating the model and directing data to the view. |
12 | | - |
13 | | -In Rails, the model is handled by what's called an object-relational mapping |
14 | | -layer entitled Active Record. This layer allows you to present the data from |
15 | | -database rows as objects and embellish these data objects with business logic |
16 | | -methods. You can read more about Active Record in |
17 | | -link:files/vendor/rails/activerecord/README.html. |
18 | | - |
19 | | -The controller and view are handled by the Action Pack, which handles both |
20 | | -layers by its two parts: Action View and Action Controller. These two layers |
21 | | -are bundled in a single package due to their heavy interdependence. This is |
22 | | -unlike the relationship between the Active Record and Action Pack that is much |
23 | | -more separate. Each of these packages can be used independently outside of |
24 | | -Rails. You can read more about Action Pack in |
25 | | -link:files/vendor/rails/actionpack/README.html. |
26 | | - |
27 | | - |
28 | | -== Getting Started |
29 | | - |
30 | | -1. At the command prompt, start a new Rails application using the <tt>rails</tt> command |
31 | | - and your application name. Ex: rails myapp |
32 | | - (If you've downloaded Rails in a complete tgz or zip, this step is already done) |
33 | | -2. Change directory into myapp and start the web server: <tt>script/server</tt> (run with --help for options) |
34 | | -3. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!" |
35 | | -4. Follow the guidelines to start developing your application |
36 | | - |
37 | | - |
38 | | -== Web Servers |
39 | | - |
40 | | -By default, Rails will try to use Mongrel and lighttpd if they are installed, otherwise |
41 | | -Rails will use WEBrick, the webserver that ships with Ruby. When you run script/server, |
42 | | -Rails will check if Mongrel exists, then lighttpd and finally fall back to WEBrick. This ensures |
43 | | -that you can always get up and running quickly. |
44 | | - |
45 | | -Mongrel is a Ruby-based webserver with a C component (which requires compilation) that is |
46 | | -suitable for development and deployment of Rails applications. If you have Ruby Gems installed, |
47 | | -getting up and running with mongrel is as easy as: <tt>gem install mongrel</tt>. |
48 | | -More info at: http://mongrel.rubyforge.org |
49 | | - |
50 | | -If Mongrel is not installed, Rails will look for lighttpd. It's considerably faster than |
51 | | -Mongrel and WEBrick and also suited for production use, but requires additional |
52 | | -installation and currently only works well on OS X/Unix (Windows users are encouraged |
53 | | -to start with Mongrel). We recommend version 1.4.11 and higher. You can download it from |
54 | | -http://www.lighttpd.net. |
55 | | - |
56 | | -And finally, if neither Mongrel or lighttpd are installed, Rails will use the built-in Ruby |
57 | | -web server, WEBrick. WEBrick is a small Ruby web server suitable for development, but not |
58 | | -for production. |
59 | | - |
60 | | -But of course its also possible to run Rails on any platform that supports FCGI. |
61 | | -Apache, LiteSpeed, IIS are just a few. For more information on FCGI, |
62 | | -please visit: http://wiki.rubyonrails.com/rails/pages/FastCGI |
63 | | - |
64 | | - |
65 | | -== Debugging Rails |
66 | | - |
67 | | -Sometimes your application goes wrong. Fortunately there are a lot of tools that |
68 | | -will help you debug it and get it back on the rails. |
69 | | - |
70 | | -First area to check is the application log files. Have "tail -f" commands running |
71 | | -on the server.log and development.log. Rails will automatically display debugging |
72 | | -and runtime information to these files. Debugging info will also be shown in the |
73 | | -browser on requests from 127.0.0.1. |
74 | | - |
75 | | -You can also log your own messages directly into the log file from your code using |
76 | | -the Ruby logger class from inside your controllers. Example: |
77 | | - |
78 | | - class WeblogController < ActionController::Base |
79 | | - def destroy |
80 | | - @weblog = Weblog.find(params[:id]) |
81 | | - @weblog.destroy |
82 | | - logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!") |
83 | | - end |
84 | | - end |
85 | | - |
86 | | -The result will be a message in your log file along the lines of: |
87 | | - |
88 | | - Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1 |
89 | | - |
90 | | -More information on how to use the logger is at http://www.ruby-doc.org/core/ |
91 | | - |
92 | | -Also, Ruby documentation can be found at http://www.ruby-lang.org/ including: |
93 | | - |
94 | | -* The Learning Ruby (Pickaxe) Book: http://www.ruby-doc.org/docs/ProgrammingRuby/ |
95 | | -* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide) |
96 | | - |
97 | | -These two online (and free) books will bring you up to speed on the Ruby language |
98 | | -and also on programming in general. |
99 | | - |
100 | | - |
101 | | -== Debugger |
102 | | - |
103 | | -Debugger support is available through the debugger command when you start your Mongrel or |
104 | | -Webrick server with --debugger. This means that you can break out of execution at any point |
105 | | -in the code, investigate and change the model, AND then resume execution! Example: |
106 | | - |
107 | | - class WeblogController < ActionController::Base |
108 | | - def index |
109 | | - @posts = Post.find(:all) |
110 | | - debugger |
111 | | - end |
112 | | - end |
113 | | - |
114 | | -So the controller will accept the action, run the first line, then present you |
115 | | -with a IRB prompt in the server window. Here you can do things like: |
116 | | - |
117 | | - >> @posts.inspect |
118 | | - => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, |
119 | | - #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]" |
120 | | - >> @posts.first.title = "hello from a debugger" |
121 | | - => "hello from a debugger" |
122 | | - |
123 | | -...and even better is that you can examine how your runtime objects actually work: |
124 | | - |
125 | | - >> f = @posts.first |
126 | | - => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}> |
127 | | - >> f. |
128 | | - Display all 152 possibilities? (y or n) |
129 | | - |
130 | | -Finally, when you're ready to resume execution, you enter "cont" |
131 | | - |
132 | | - |
133 | | -== Console |
134 | | - |
135 | | -You can interact with the domain model by starting the console through <tt>script/console</tt>. |
136 | | -Here you'll have all parts of the application configured, just like it is when the |
137 | | -application is running. You can inspect domain models, change values, and save to the |
138 | | -database. Starting the script without arguments will launch it in the development environment. |
139 | | -Passing an argument will specify a different environment, like <tt>script/console production</tt>. |
140 | | - |
141 | | -To reload your controllers and models after launching the console run <tt>reload!</tt> |
142 | | - |
143 | | - |
144 | | -== Description of Contents |
145 | | - |
146 | | -app |
147 | | - Holds all the code that's specific to this particular application. |
148 | | - |
149 | | -app/controllers |
150 | | - Holds controllers that should be named like weblogs_controller.rb for |
151 | | - automated URL mapping. All controllers should descend from ApplicationController |
152 | | - which itself descends from ActionController::Base. |
153 | | - |
154 | | -app/models |
155 | | - Holds models that should be named like post.rb. |
156 | | - Most models will descend from ActiveRecord::Base. |
157 | | - |
158 | | -app/views |
159 | | - Holds the template files for the view that should be named like |
160 | | - weblogs/index.erb for the WeblogsController#index action. All views use eRuby |
161 | | - syntax. |
162 | | - |
163 | | -app/views/layouts |
164 | | - Holds the template files for layouts to be used with views. This models the common |
165 | | - header/footer method of wrapping views. In your views, define a layout using the |
166 | | - <tt>layout :default</tt> and create a file named default.erb. Inside default.erb, |
167 | | - call <% yield %> to render the view using this layout. |
168 | | - |
169 | | -app/helpers |
170 | | - Holds view helpers that should be named like weblogs_helper.rb. These are generated |
171 | | - for you automatically when using script/generate for controllers. Helpers can be used to |
172 | | - wrap functionality for your views into methods. |
173 | | - |
174 | | -config |
175 | | - Configuration files for the Rails environment, the routing map, the database, and other dependencies. |
176 | | - |
177 | | -db |
178 | | - Contains the database schema in schema.rb. db/migrate contains all |
179 | | - the sequence of Migrations for your schema. |
180 | | - |
181 | | -doc |
182 | | - This directory is where your application documentation will be stored when generated |
183 | | - using <tt>rake doc:app</tt> |
184 | | - |
185 | | -lib |
186 | | - Application specific libraries. Basically, any kind of custom code that doesn't |
187 | | - belong under controllers, models, or helpers. This directory is in the load path. |
188 | | - |
189 | | -public |
190 | | - The directory available for the web server. Contains subdirectories for images, stylesheets, |
191 | | - and javascripts. Also contains the dispatchers and the default HTML files. This should be |
192 | | - set as the DOCUMENT_ROOT of your web server. |
193 | | - |
194 | | -script |
195 | | - Helper scripts for automation and generation. |
196 | | - |
197 | | -test |
198 | | - Unit and functional tests along with fixtures. When using the script/generate scripts, template |
199 | | - test files will be generated for you and placed in this directory. |
200 | | - |
201 | | -vendor |
202 | | - External libraries that the application depends on. Also includes the plugins subdirectory. |
203 | | - This directory is in the load path. |
| 1 | +Cat Herder (source code to pdxruby.org) |
| 2 | + |
| 3 | +This application was written way back in late 2005 at a group hackfest hosted |
| 4 | +by the Portland Ruby Brigade. We wanted a way to propose and RSVP for events |
| 5 | +without requiring any particular person or group to manage a calendar for |
| 6 | +everyone else. |
| 7 | + |
| 8 | +Anyone can register for an account, propose an event, and sign up to attend |
| 9 | +other people's events. There is also some basic support for aggregation of |
| 10 | +members' RSS feeds, and feedback from event participants, but the primary use |
| 11 | +of the system is still as a simple event calendar. |
| 12 | + |
| 13 | +The file doc/TODO contains a few miscellaneous items we've thought about |
| 14 | +changing over the years, but overall this whole codebase is probably of more |
| 15 | +interest as a historical oddity than as a useful application for other people |
| 16 | +to use. It uses a mish-mash of APIs, coding styles, and tests contributed by |
| 17 | +about a dozen different maintainers over the last three years, and certainly |
| 18 | +shows its age when compared to a shiny new legacy-free Rails 2 application. |
0 commit comments