== Getting Started

Welcome to Developers! This software is developed in Ruby on Rails, using Rails 1.2.3 and Ruby 1.8.5, along with MySQL as a back-end data store. It uses many plugins to create a mashup with Google Maps. It should also work with the new Rails 2.0.2.

This Ruby on Rails project is the beginnings of the Encyclopedia of Life (www.eol.org). It is a "citizen scientist" ingestion form that is a Google Maps mash-up, allowing users to submit observations and photos of organisms to share with the world! 

== Details

To setup the code on your local machine, you'll first need a Subversion client to get the code, Ruby to run the code, the Ruby on Rails web framework, and a MySQL database server. Check out the Ruby on Rails site, http://www.rubyonrails.org, and the subversion site, http://subversion.tigris.org/, for information on installing everything. The code runs fine on Linux, Windows and Mac (I'm developing on Windows XP, Ubuntu and OS X 10.5).

In addition, for image resizing, you'll need either ImageMagick? or MiniMagick?. One of these packages is used by the attachment_fu plugin, which is in the repository already. ImageMagick? or MiniMagick? are not the in repository, and you should visit their websites to determine how to install them on your particular OS.

To get the source code up and running, do the following:

    Check out the head of the trunk from the subversion repository.
    Create the development and test databases in MySQL on your local MySQL server or whatever database back-end you can get to work (I called mine "eol_ingestion_form_development" and "eol_ingestion_form_test").
    Copy the "config/database.example" file to "config/database.yml" and then edit the database configuration information to match your databases created in step 2.
    From a console in your application directory, run "rake db:migrate" to setup the database schema. If you get any errors, it's likely your database connection is failing, so check the database connections and database usernames/passwords. Make sure your MySQL server is running.
    Run "rake db:fixtures:load" to setup the core data (basically a couple test users, some habitats, a couple organism names).
    Start webrick or mongrel and cross your fingers: "ruby script/server" or "ruby script/server webrick".
    Set the permissions on the folder "public/uploaded_images" to allow the anonymous web user or your local account (whatever account your development server is running under) to have permissions to write to this folder. It is (obviously) used to save image uploads.
    The test admin user login from the user fixture is "test@test.com" with a password of "test". Feel free to change it after the first login. 

Note that if your PC is not on the Internet, you cannot run the app. Most pages make use of the Google Maps API or other web services that require a constant connection to the Internet. Sorry for those off the grid.

Also note that there is a Google Maps API Key in the "config/gmaps_api_key.yml" which should work fine for localhost. Obtain your own Google Maps API key for your host if you need to. This is used for both the maps and the geocoding.

By default, sessions are stored in MySQL. To cleanup stale sessions over 1 hour old, setup a CRON job or a Windows task to run every few hours or so, and execute the following function from within your Rails application folder:

Windows: ruby script/runner/SessionCleaner?.remove_stale_sessions Linux: ./script/runner/SessionCleaner?.remove_stale_sessions

That method is defined in the "lib/session_cleaner.rb" file and removes sessions older than 60 minutes. 


== ToDo

There is a lot to work on to make this system better. Below is a partial list of items for some ideas.

=== Specific Programming Tasks

    Pagination of search results on pages with many results
    Web services to expose data
    On the map views, when a pop-up info window appears for a sighting when clicked, offer to take the user straight to that specific detailed observation page with another click
    Ability to import observation data in mass (perhaps via a specifically formatted CSV file that is uploaded)
    Add a graph that shows species observations by date in search results page
    Need functional and unit tests
    Add the ability to use OpenID in addition to the custom login mechanism
    The range circle overlayed on Google Maps does not work consistently in IE 7, works fine in Firefox
    Make application ready for date/timezone internationalization and customization (currently the default is always eastern time zone).
    Search by attributes in addition to geographic search and search by name and description
    Ability to upload a specific thumbnail image with an observation instead of having the thumbnail auto-generated
    Integrate with Flickr API to pull in related photos based on geography/name strings?
    Allow searching by institution name as well as user name
    Ability to upload multiple images with a specific observation
    Need user groups, so that a school can create an account, and then the school administrator can create sub-accounts for the students, that they can control 

=== Areas that need improving and investigation

    Web services for importation of species data
    Google map markers, perhaps switch to marker groups to improve performance when there ar e lots of markers added to the map
    Look at using OpenLayers? for laying data over maps instead of google maps and markers (http://openlayers.org)
    General refactoring... make it RESTful? ready for Rails 2.0? 

=== General Areas

    Ability to filter species that are entered into specific groups to build localized versions (e.g. only show species native to Cape Cod)
    Admin interface with ability to view/edit entries and update classifications or species identifications
    Ability to assign different users to different "domains" of species to administer them (e.g. the fungus expert keeps on eye on all fungal entries to fix identification problems).
    Can we have offline capability (i.e. the ability to record species observations when not connected and then pump the data in when we get online)? Look at the offline capabilities of the next version of Firefox. 

=== Science Areas

    Ability to interface with a classification system such as classification bank to show where entry belongs in taxonomic tree
    Show both latin and common names on the map and with species (especially if just the latin name is specified, a look up of common name would be possible). This would make the system more accessible. There will also be times when the latin nonemclature is in dispute.