README_CODE

Last Revised: May 25, 2012

= MushroomObserver

The following is an overview of the code for the Mushroom Observer website for
prospective developers.  See http://mushroomobserver.org/observer/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:: http://www.ruby-doc.org/core/
Ruby Quick Ref:: http://www.zenspider.com/Languages/Ruby/QuickRef.html
Rails Documentation:: http://api.rubyonrails.org/
Rdoc Documentation:: http://rdoc.sourceforge.net/doc/index.html
Rails Plugin Wiki:: http://wiki.rubyonrails.org/rails/pages/Plugins
Rails Plugin Directory:: http://agilewebdevelopment.com/plugins
MVC Architecture:: http://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 ActiveRecord::Base.  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.
Notification::      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 only a few controllers (in <tt>app/controllers</tt>), roughly one for
each of the major data types:

ObserverController::    Deals with Observation's, Naming's, Vote's, and everything else.
AccountController::     Deals with User's.
NameController::        Deals with Name's and NameDescription's.
LocationController::    Deals with Location's and LocationDescription's.
ImageController::       Deals with Image's and ImageVote's.
CommentController::     Deals with Comment's.
SpeciesListController:: Deals with SpeciesList's.
ProjectController::     Deals with Project's.
InterestController::    Deals with Interest's.
SupportController::     Deals with Donation's.
ConferenceController::  Deals with ConferenceEvent's and ConferenceRegistration's.
ApiController::         Handles AJAX and API requests.
PivotalController::     Handles minimal interface with Pivotal Tracker website.

These controllers are all subclasses of ActionController.  Actions are just
instance methods.  These correspond directly to the URL of the request:

  http://mushroomobserver.org/controller/action

Note that the default controller is "observer" and the "id" parameter is
shortened to a bare integer: 

  http://mo.org/42                      Show observation #42.
  http://mo.org/observer/show_user/252  Show summary for user #3.

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_filter :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)
        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="/observer/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:: http://api.rubyonrails.org/files/vendor/rails/actionpack/README.html
ActionView Docs:: http://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:: http://wiki.rubyonrails.org/rails/pages/UnderstandingHelpers




== Testing

Nathan has been very diligent writing unit tests for everything.  Just run
<tt>rake test</tt> and go get something to eat.

(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:: http://nubyonrails.com/articles/ruby-rails-test-rails-cheat-sheet
Longwinded Intro:: http://www.nullislove.com/2007/11/10/testing-in-rails-introduction/