-
Notifications
You must be signed in to change notification settings - Fork 26
/
README_CODE
380 lines (270 loc) · 15.4 KB
/
README_CODE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
Last Revised: May 25, 2012
= MushroomObserver
The following is an overview of the code for the Mushroom Observer website for
prospective developers. See https://mushroomobserver.org/info/intro for an
introduction to the website itself.
== Ruby on Rails
MO is written using Ruby on Rails, or simply Rails. This is just a set of
three heavily interrelated Ruby packages: ActionController, ActionView, and
ActiveRecord. The basic architecture is model, view, controller -- that is,
the webserver receives a request, passes it to the appropriate controller,
which decides what actions to take and gathers whatever data is needed (from
the "models"), then renders the result via HTML templates (the "views").
Some documentation can be automatically generated using rdoc. Basically, it
just grabs comments before classes, modules, and methods and creates a little
webpage. Just run <tt>rake rdoc</tt> and point your browser at
<tt>file://#{RAILS_ROOT}/rdoc/index.html</tt>. However, we are not strict
about keeping these docs up-to-date and prefer to put time into making the
code itself more readable.
Rails can be extended by installing plugins. We've only used a few, but it's
worth mentioning. Just google "rails plugins" (or browse a directory, see
below), find a plugin you like, then run:
script/plugin install http://svn.domain.com/path/to/plugin
Rails applications run in one of three different modes: development, production
and test. Each has its own entirely separate database (named appropriately
+observer_development+, +observer_production+ and +observer_test+).
development
Server automatically reloads any code that has been changed. (Only modules that
have been required using +require_dependency+.) Doesn't cache data the same
way as the production server does.
production
Need to restart the server whenever you change any code. Some things are
cached differently than in development, so if you see different behavior on
the production server, start here: you might just need to reload an object.
test
Used by the testing framework. All changes are thrown away between each
test. And various Rails inner modules are swapped out with test mock-ups.
For more information: (Note that most of these no longer discuss Rails 2.1,
but you should be able to find the docs for this version by digging a bit.)
Ruby Documentation:: https://www.ruby-doc.org/core/
Ruby Quick Ref:: https://www.zenspider.com/Languages/Ruby/QuickRef.html
Rails Documentation:: https://api.rubyonrails.org/
Rdoc Documentation:: https://rdoc.sourceforge.net/doc/index.html
Rails Plugin Wiki:: https://wiki.rubyonrails.org/rails/pages/Plugins
Rails Plugin Directory:: https://agilewebdevelopment.com/plugins
MVC Architecture:: https://en.wikipedia.org/wiki/Model-view-controller
== Database
MO uses MySQL. The current schema is <tt>db/schema.rb</tt>. All modifications
of the structure, such as adding tables or changing existing columns, are
handled using the handy migrations in <tt>db/migrate</tt>.
rake db:migrate # Create or update database.
rake db:migrate VERSION=YYYYMMDDHHMMSS # Rollback to previous version.
Access is all done via subclasses of ApplicationRecord. These are generally
called models. Each instance of a model represents a single row in the
corresponding database table. Look for observations in the class Observation,
user/account settings in User, taxonomy in Name and Synonym, and so on. These
are all found in <tt>app/models</tt>. Here are the major ones:
User:: Users: name, email, password, prefs, etc.
Observation:: Observations: where, when, what, notes, etc.
Image:: Images: mostly mushrooms, but also mugshots, etc.
Name:: Scientific name bundled with notes, citation, etc.
NameDescription:: Description of species: diagnostics, habitat, references, etc.
Location:: Locations: lat/long/elev, notes, etc.
LocationDescription:: Description of locations: description, ecology, etc.
SpeciesList:: Set of Observation's (*_not_* Name's).
Comment:: Comments: attached to various objects.
These are used in naming and voting on observations:
Naming:: Proposed Name for a given Observation.
NamingReason:: Reasons for proposing a name: appearance, literature, etc.
Vote:: Votes on a given Naming for a given Observation.
Emails use several:
QueuedEmail:: Implements a template for emails that will get queued and then sent
QueuedEmailInteger:: Provides integer values that get queued along for a template
QueuedEmailNote:: Provides text blocks (more than 100 characters) for a template
QueuedEmailString:: Provides strings (up to 100 characters) for a template
We keep track of edits to communal objects using these classes:
NameVersion:: Old versions of Name's.
LocationVersion:: Old versions of Location's.
NameDescriptionVersion:: Old versions of NameDescription's.
LocationDescriptionVersion:: Old versions of LocationDescription's.
And several other random database classes:
APIKey:: Used to authenticate user for API requests.
CopyrightChange:: Tracks changes in copyright of Image's (later will include Name/LocationDescription's, too).
Donation:: Records User's financial donations to MO.
ImageVote:: Votes on quality of Image's.
Interest:: Registers User's interest in various objects (for email notification of activity in those objects).
License:: Types of licenses available for Image's and Name/LocationDescription's to use.
NameTracker:: Used to generate notification emails under more complex conditions, like use of Name's a User is interested in.
Query:: Saves the description of an arbitrary query of one of the major objects (above), allows prev/next/index and refining searches.
RssLog:: Used to report changes via RSS feed.
Synonym:: Used to group synonymized Name's.
Triple:: RDF database.
UserGroup:: Used to keep track of which User's are members or admins of Project's.
The following non-database-related classes are also found in
<tt>app/models</tt>:
Base class for all real email
NameParse:: Used by Name to parse scientific names.
NameSorter:: Used to parse and deal with synonymy, etc. in a list of names.
Query:: Used to keep track of search queries.
For those who prefer a graphical representation, see DATA_STRUCTURE.gif. It is
a standard Bachman diagram where arrows indicate cardinality (see below). The
version-tracking classes (NameVersion, CopyrightChange, etc.) are all
abbreviated to just "Ver" to help reduce clutter.
X ---- Y one-to-one relationship
X ---> Y one-to-many relationship, X has many Y
X <--> Y many-to-many relationship
For more information:
ActiveRecord Docs:: http://api.rubyonrails.org/files/vendor/rails/activerecord/README.html
Migration Docs:: http://api.rubyonrails.org/classes/ActiveRecord/Migration.html
Migration Cheatsheet:: http://garrettsnider.backpackit.com/pub/367902
== Controllers
There are quite a few controllers (in <tt>app/controllers</tt>), roughly one for
each of the major data types:
ObservationsController::Deals with Observation's.
AccountController:: Deals with User's.
NameController:: Deals with Name's and NameDescription's.
LocationController:: Deals with Location's and LocationDescription's.
ImagesController:: Deals with Image's and ImageVote's.
CommentController:: Deals with Comment's.
SpeciesListController:: Deals with SpeciesList's.
ProjectController:: Deals with Project's.
InterestsController:: Deals with Interest's.
SupportController:: Deals with Donation's.
APIController:: Handles AJAX and API requests.
These controllers are all subclasses of ActionController. Actions are just
instance methods. These correspond directly to the URL of the request:
https://mushroomobserver.org/controller/action
Note that the default controller is "observations" and the "id" parameter is
shortened to a bare integer:
https://mushroomobserver.org/42 Show observation #42.
https://mushroomobserver.org/users/252 Show summary for user #252.
Controller methods -- that is, actions -- have access to quite a number of
helpers and data. Here are just a few, see ActionController for more:
<tt>session[:user]</tt>:: Session: hash of data that follows the user around from request to request.
<tt>flash[:notice]</tt>:: Temporary storage: this hash persists only until the next request.
<tt>cookies["mo_user"]</tt>:: It is trivial to read or write cookies on the user's browser.
<tt>request.method</tt>:: You have access to the full CGI request object.
<tt>@user</tt>:: If user is logged in this will be their User instance.
<tt>@js</tt>:: True if javascript is enabled on the user's browser.
Controller methods are very deeply interconnected with views. I've never quite
understood the underlying mechanics, but views have access to all the
controller's instance variables (e.g. <tt>@user</tt> and any others you set in
the action). This is how actions pass information to the view for rendering as
HTML.
By default a template of the same name as the action is rendered:
app/views/controller/action.rhtml
however this can be overridden in a number of ways. This can get quite
complicated, and you must be careful not to accidentally attempt to render two
templates. Example:
class ExampleController << ActionController
# This causes autologin() to be run before every action.
before_action :autologin
def my_action
case params[:mode]
# Mode not set: Render "my_action.rhtml" implicitly.
when ''
@choices = %w(show index)
# Show mode: Lookup object and render "show.rhtml".
# Note that it does NOT call the show() method!!
when 'show'
@object = Model.find(params[:id].to_s)
render :action => :show
# Index mode: Get list of all objects and render "index.rhtml".
# Note that it does NOT call the index() method!!
when 'index'
# @objects = Model.find(:all) # Rails 3
@objects = Model.all
render :action => :index
# Error: Redirect browser to another action.
# Note, no templates will be rendered at all.
else
redirect_to :action => :error
end
end
end
For more information:
ActionPack Docs:: http://api.rubyonrails.org/files/vendor/rails/actionpack/README.html
ActionController Docs:: http://api.rubyonrails.org/classes/ActionController/Base.html
== Views
Views, unlike models and controllers, are not classes, or strictly speaking
even ruby code at all. They are templates in which you may (and frequently
will) embed Ruby code. All the views are found in:
app/views/controller/action.rhtml
Some templates that are shared between controllers can be stored in:
app/views/shared
And "partial" views (see <tt>render :partial => 'subview'</tt>) are prefixed
with an underscore:
app/views/controller/_subview.rhtml
Syntax is all HTML with two new mark-ups:
<% ruby code that is evaluated but doesn't affect output %>
<%= ruby expression whose (string) value is inserted into the output %>
An example makes it plentifully clear:
<h1>Observation #<%= @observation.id %></h1>
<% if @user == @observation.user %>
<a href="/observations/edit/<%= @observation.id %>">Edit Observations</a>
<% end %>
Name: <%= @observation.name %><br/>
Date: <%= @observation.when %><br/>
Where: <%= @observation.where %><br/>
Notes: <%= @observation.notes %><br/>
Couldn't be easier. All views are automatically wrapped in a "layout"
template which is itself another +rhtml+ template:
app/views/layout/application.rhtml
You have access to hundreds of amazing helper methods in these view templates,
from simple tag helpers like image_tag() and link_to() to complicated things
like text_field_with_autocomplete() and paginate(). And, as mentioned in the
section on controllers, you have access to a number of things from the
controller. You can also "publish" controller methods for use in views by
using the +helper_method+ directive:
class SomeController
# give access to both controller and views
helper_method :my_helper
def my_helper(args)
...
end
end
I still to this day have no idea what the actual class context is that ruby
code in these templates is run under. It has something to do with ERb and
(obviously) ActionView, but it also has access to ActionController instance
variables and some (but not most) ActionController methods.
A particularly useful and difficult construct to get right involves helpers
that take a block. See +boxify+ in helpers/html_helper.rb. Simplified:
def wrap_with_div(&block)
output = '<div>' + capture(&block) + '</div'>
concat(output)
end
<% wrap_with_div do %>
Contents of div here. Note the lack of "=" above!!
<% end %>
For more information:
ActionPack Docs:: https://api.rubyonrails.org/files/vendor/rails/actionpack/README.html
ActionView Docs:: https://api.rubyonrails.org/classes/ActionView/Base.html
== Helpers
There are a number of helper files scattered about that magically appear in
various contexts. I found this extremely confusing at first (actually I still
do, but don't tell anyone).
app/controllers/application.rb
This is magically loaded and made available to all controllers.
Note that many of these utilities are also made available to views.
app/helpers/application_helper.rb
This is magically loaded and made available to all view templates.
app/helpers/controller_helper.rb
This is magically loaded and made available to all view templates rendered
by a given controller.
app/helpers/other_helper.rb
Thse are all loaded explicitly by application_helper.rb
For more information:
Understanding Helpers:: https://wiki.rubyonrails.org/rails/pages/UnderstandingHelpers
== Testing
(TEMPORARY NOTE: due to a deficiency in +mysql2+ adapter, <tt>rake
db:test:prepare</tt> must still be run with the old +myslq+ adapter. To
facilitate this, we've written a script, script/run_tests, to run the tests
properly. The complementary utility, script/run_test, runs a single unit test
file. We do not, however, have any clever utilty for running a single unit
test, sorry.)
There are several files and directories involved, so it's worth an overview:
test/unit/xxx_test.rb:: Low-level tests of individual classes.
test/functional/xxx_test.rb:: Mid-level tests in the context of a mock-up controller.
test/integration/xxx_test.rb:: High-level tests in the context of a mock-up browser session.
test/fixtures/xxx.yml:: These define sample objects for use in unit tests.
test/fixtures/xxx/xxx:: Images, reports, and other files used in unit tests.
test/boot.rb:: Boots the application in test mode.
test/test_case.rb:: Configures Rails test environment.
test/functional_xxx.rb:: Utilities available to functional tests.
test/controller_xxx.rb:: Utilities available to functional tests.
test/integration_xxx.rb:: Utilities available to integration tests.
test/session_xxx.rb:: Utilities available to integration tests.
test/other_extensions.rb:: Utilities available to all tests.
For more information:
Cheatsheet:: https://nubyonrails.com/articles/ruby-rails-test-rails-cheat-sheet
Longwinded Intro:: https://www.nullislove.com/2007/11/10/testing-in-rails-introduction/