README

= flickr-fu

== Contact

  Author: Ben Wyrosdick
  Email: ben [at] commonthread.com
  Lighthouse: http://commonthread.lighthouseapp.com/projects/12069-flickr_fu/overview
  Main Repository: http://github.com/commonthread/flickr_fu/tree/master

== Getting Started

  You need to first get an API key as detailed here:

  http://www.flickr.com/services/api/misc.api_keys.html
  
== Installation

  sudo gem install flickr-fu

== Documentation

  RDoc Documentation can be found here:

  http://www.commonthread.com/projects/flickr_fu/rdoc/

== Example flickr.yml
--- !map:HashWithIndifferentAccess
key: "YOUR KEY"
secret: "YOUR SECRET"
token_cache: "token_cache.yml"

== Authorization

  To authorise your application to access Flickr using your API key you will
  need to access a specific URL.
  
  To generate this URL run the following and when presented with the URL 
  access it from your browser. Confirm the application has permission at 
  the level you have specified.
  
  Note that flickr has different types of keys. If you use one for a webapplication,
  which is most likely, you need to define a callback and somehow make sure that
  you connect the parameter :frob that flickr send via the callback is assigned
  to the right user account. The best way to do this is to loop over all the current
  user's flickr accounts and try flickr.auth.token with the :frob.
  
  Finally, cache the token (this will create the token cache file)
  
  If you have an invalid API key you will see errors such as:
  
  "100: Invalid API Key"
  
  If you don't follow the process below to authorise your application
  you will see errors such as:
  
  "98: Login failed / Invalid auth token" or 
  "99: User not logged in / Insufficient permissions"
  
== Authorization Example for non-webapplication

  require 'flickr_fu'
  
  flickr = Flickr.new('flickr.yml')
  
  puts "visit the following url, then click <enter> once you have authorized:"

  # request write permissions
  puts flickr.auth.url(:write)
  
  gets
  
  flickr.auth.cache_token

== Authorization Example for a webapplication

  flickr.auth.token also contains the nsid and username, this
  example only stores the token and no other userdata.
  All you need in the views is a button or link to FlickrController.create

  require 'flickr_fu'
  class FlickrController < ActionController::Base
    def create
      flickr = Flickr.new('flickr.yml')
      redirect_to flickr.auth.url(:write)
    end
    def flickr_callback
      flickr = Flickr.new('flickr.yml')
      flickr.auth.frob = params[:frob]
      current_user.update_attribute :flickr_token, flickr.auth.token.token
    end
    def something_else_with_flickr
      flickr = Flickr.new(YAML.load_file('flickr.yml').merge(:token => current_user.flickr_token))
      # now you have full access on the user's data :)
    end
  end

=== User creation on the fly

  To use the userdata in flickr.auth.token and create
  an account with it on the fly try following flickr_callback
  
  def flickr_callback
    flickr = Flickr.new('flickr.yml')
    flickr.auth.frob = params[:frob]
    if(!logged_in?)
      # no user yet for this flickr id, create a new user
      if (current_user = User.find_by_flickr_nsid(flickr.auth.token.user_id))).nil?
        current_user = User.new do |user|
          user.login = flickr.auth.token.username
          user.real_name = flickr.auth.token.user_real_name
          user.flickr_nsid = flickr.auth.token.user_id
          user.flickr_token = flickr.auth.token.token
        end
      else # we have a user for that flick account, login and update token
        current_user.flickr_token = flickr.auth.token.token
      end
      if(current_user.save)
        flash[:notice] = 'Registered and logged in via flickr'
        redirect_to '/'
      else
        // probably you validate for the presence of an email address?
        flash[:error] = 'Logged in via flickr but some user data is missing'
        @user = current_user
        render :action => 'users/new'
      end
    else
      current_user.update_attribute :flickr_token, flickr.auth.token.token
    end
  end

== Search Example

  require 'flickr_fu'

  flickr = Flickr.new('flickr.yml')

  photos = flickr.photos.search(:tags => 'ruby-flickr')

  puts "found #{photos.size} photo(s)"

  photos.each do |photo|
    puts photo.title
    puts photo.description unless [nil, ''].include?(photo.description)
    [:square, :thumbnail, :small, :medium, :large, :original].each do |size|
      puts "#{size}: #{photo.url(size)}"
    end
    puts "comments: #{photo.comments.size}"
    photo.comments.each do |comment|
      intro = "#{comment.author_name} says - "
      puts "#{intro}\"#{comment.comment.gsub("\n", "\n"+(" "*intro.length))}\""
    end
    puts "notes: #{photo.notes.size}"
    photo.notes.each do |note|
      puts "[#{note.x},#{note.y} ~ #{note.width}x#{note.height}] - \"#{note.note}\""
    end
    puts
    puts
  end
  
== Another Search Example

  If searching for photos by user id then you need to specify the 'alias' - without
  intervention this is usually set by Flickr and is an alphanumeric string. 
  
  To find out the user id for a given user, you can use the tool at:
  
  http://idgettr.com/
  
  And replace the line in the above sample to query on user id:
  
  photos = flickr.photos.search(:user_id => 'your_user_id_here')

== Authenticatd Search Example

  For a few searches you will need to authenticate. E.g. to receive the original_url
  staight away (and thus saving an extra getInfo call), or to search for the private
  photos of a user. In order to do so you need to pass the user's token and his
  flickr_nsid (though the API docs also suggest 'me', both work fine).

  This example appends the :url_o to the extras, mapping it to :original_url:

  flickr.photos.extras << {:url_o => :original_url}
  photos = flickr.photos.search(:per_page => 5, :page => 1,
      :user_id => 'me', :privacy_filter => 5, :auth_token => user_token,
      :safe_search => 3))

== Patch Contributers

  Chris Ledet
  Maciej Biłas
  Mike Perham
  Chris Anderton
  Luke Francl
  Thomas R. Koll
  P. Mark Anderson
  Josh Nichols