ruby script/plugin install git://github.com/mattapayne/jambase4rails.git

Installation
============

1) get and install the plugin

    git: script/plugin install git://github.com/mattapayne/jambase4rails.git
    svn: script/plugin install http://jambase4rails.googlecode.com/svn/trunk/plugins/jambase4Rails

2) run the jambase4rails:install_assets rake task - this ensures that the images required by the helpers are in place.

Configuration
=============

Using the JamBase API requires that you register for an API key. Get one here: http://developer.jambase.com/member/register

In the configuration file for your environment, add the following configuration:

#development.rb

JamBase4Rails.configure do |settings|
  settings.api_key = "XXXXXXXXXXXXX"
  settings.fake_calls = false (optional - defaults to false. If true, this just
                               returns static data and does not call the JamBase
                               API)
end

Example
=======

To make use of JamBase4Rails just use the JamBase4Rails::API object. (or include JamBase4Rails in your model or controller and just call API)

Available methods (all are class methods):

All methods return an instance of JamBase4Rails::Events

1) JamBase4Rails::API.search(options)
2) JamBase4Rails::API.search_by_artist(artist_name, additional_options={})
3) JamBase4Rails::API.search_by_zipcode(zipcode, additional_options={})

Possible options:

:band (or :artist (an alias for :band)) => The name of the band to search for.
:zip => The zipcode to search within
:radius => The distance from the zipcode to include in the search

ie: JamBase4Rails::API.search(:band => "A Band", :zip => "90210", :radius => 20)
JamBase4Rails::API.search_by_band("A Band", {:zip => "90210"})
JamBase4Rails::API.search_by_zipcode("90210")

The general schema of the results is:

Events (an array-like object)
    - name (may or may not be nil) (String)
    - Event(s) (Event)
        - event_id (String)
        - event_date (String)
        - event_url (String)
        - venue (Venue)
            - venue_id (String)
            - venue_name (String)
            - venue_city (String)
            - venue_state (String)
            - venue_zip (String)
        - artists (Artists)
            - Artist(s) (Artist)
                - artist_id
                - artist_name

There is currently no advanced documentation for this plugin.