README

JamBase4R
=============

JamBase4R is a framework agnostic Ruby wrapper around the JamBase live music search API.
(http://developer.jambase.com/docs)

This gem can be used to create mashups where your users might want to search for live music. This gem is a
replacement for a Ruby on Rails plugin that I wrote a while back called JamBase4Rails. Since Rails is no longer
promoting the use of traditional plugins, but rather gems, I thought it was time to do a re-write.

**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 (if you are using Rails), but does not alter controllers or
models in any way.

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

1) get and install the gem
	a) gem sources -a http://gems.github.com (you only have to do this once)
	b) sudo gem install mattapayne-jambase4r
	- OR -
	If using Rails:
	a) Add config.gem 'mattapayne-jambase4r', :source => 'http://gems.github.com', :lib => "jambase4r"
	   to your environment.rb file.
	b) rake gems:install from your project root

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

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

JamBase4R is configured via the configure method. The configure method takes a block that is 
passed a settings object. 2 properties can be set: 1) api_key (required) 2) logger (optional)

FOR RAILS
=========
In an initializer, add the following configuration:

#app_specific_initializers.rb

JamBase4R.configure do |config|
  config.api_key = "XXXXXXXXXXXXX"
  config.logger = RAILS_DEFAULT_LOGGER - This is optional if you want to enable logging. You can pass an instance of
	any class that conforms to the same interface as RAILS_DEFAULT_LOGGER (Specifically, it must respond to #info(msg) and #error(msg))
end

FOR SINATRA
===========

I would typically configure JamBase4R with a Sinatra configure block.

configure do
	JamBase4R.configure do |config|
	  config.api_key = "XXXXXXXXXXXXX"
	end
end

FOR OTHERS
==========

Check the documentation of the framework you are using. All should allow for this type of configuration.

ATTRIBUTION
===========
JamBase requires that you indicate where your data comes from (attribution). To make this easy, there is a JamBase4R::ViewHelper module that gets automatically included into ActionView::Base if using Rails and into Sinatra's helpers if using Sinatra.

There are a couple of methods:
1) jambase_text_attribution
2) jambase_image_attribution
3) jambase_flavicon

Example
=======

To make use of JamBase4R just use the JamBase4R::API object.

Available methods (all are class methods):

All methods return an instance of an Array, which contains zero or more Event objects

1) JamBase4R::API.search(options)
2) JamBase4R::API.search_by_artist(artist_name, additional_options={})
3) JamBase4R::API.search_by_zipcode(zipcode, additional_options={})
4) JamBase4R::API.search_by_user(user, 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
:user => The registered user - this limits the results to those within the user's favorite artists

ie: JamBase4R::API.search(:band => "A Band", :zip => "90210", :radius => 20)
    JamBase4R::API.search_by_artist("A Band", {:zip => "90210"})
    JamBase4R::API.search_by_zipcode("90210")
    JamBase4R::API.search_by_user("Matt")

The general schema of the results is:

 - events
 	- event
        - event_id (String)
        - event_date (String)
        - event_url (String)
		- ticket_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) 2009 [Matt Payne], released under the MIT license