JamBase4Rails
=============

*** PLEASE NOTE THAT THIS PLUGIN IS SLATED FOR DEPRECATION! NEW USERS PLEASE SEE JamBase4R 
(http://github.com/mattapayne/jambase4r/tree).
JamBase4R is supplied as a gem and is framework agnostic. It will work just fine with Rails 2.3 and up. ***

JamBase4Rails is a Ruby gem that provides access to the JamBase API
http://developer.jambase.com/docs

Provide concert information and search functionality to users of your application.

**Note: JamBase requires that any site making use of it's API provide attribution.
See http://developer.jambase.com/docs for more information. This gem provides 
helpers to make adding attribution to your site easy.

This gem adds helper methods to your views, but does not alter controllers or
models in any way.

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

1) get and install the gem
    git: script/plugin install git://github.com/mattapayne/jambase4rails.git

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_artist("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

Copyright (c) 2008 [Matt Payne], released under the MIT license