Module: Tagcrumbs

Defined in:
lib/tagcrumbs.rb,
lib/tagcrumbs/cli.rb,
lib/tagcrumbs/proxy.rb,
lib/tagcrumbs/exceptions.rb,
lib/tagcrumbs/config_store.rb,
lib/tagcrumbs/builders/builder.rb,
lib/tagcrumbs/parsers/xml_parser.rb,
lib/tagcrumbs/resources/resource.rb,
lib/tagcrumbs/parsers/json_parser.rb,
lib/tagcrumbs/builders/xml_builder.rb,
lib/tagcrumbs/resources/collection.rb,
lib/tagcrumbs/resources/models/tag.rb,
lib/tagcrumbs/builders/json_builder.rb,
lib/tagcrumbs/resources/models/city.rb,
lib/tagcrumbs/resources/models/flag.rb,
lib/tagcrumbs/resources/models/link.rb,
lib/tagcrumbs/resources/models/root.rb,
lib/tagcrumbs/resources/models/user.rb,
lib/tagcrumbs/resources/models/place.rb,
lib/tagcrumbs/resources/models/state.rb,
lib/tagcrumbs/resources/models/filter.rb,
lib/tagcrumbs/resources/models/address.rb,
lib/tagcrumbs/resources/models/comment.rb,
lib/tagcrumbs/resources/models/country.rb,
lib/tagcrumbs/resources/models/fanship.rb,
lib/tagcrumbs/resources/models/geoname.rb,
lib/tagcrumbs/resources/models/picture.rb,
lib/tagcrumbs/resources/models/profile.rb,
lib/tagcrumbs/resources/models/activity.rb,
lib/tagcrumbs/resources/models/favorite.rb,
lib/tagcrumbs/resources/models/location.rb,
lib/tagcrumbs/resources/models/settings.rb,
lib/tagcrumbs/resources/models/accessors.rb,
lib/tagcrumbs/resources/models/paragraph.rb,
lib/tagcrumbs/resources/models/placemark.rb,
lib/tagcrumbs/resources/models/friendship.rb,
lib/tagcrumbs/resources/models/application.rb,
lib/tagcrumbs/resources/models/suggestions.rb,
lib/tagcrumbs/resources/models/access_token.rb,
lib/tagcrumbs/resources/models/profile_link.rb,
lib/tagcrumbs/resources/models/subscription.rb,
lib/tagcrumbs/resources/models/user_recommendation.rb,
lib/tagcrumbs/resources/models/email_recommendation.rb

Defined Under Namespace

Modules: Accessors Classes: AccessToken, Activity, Address, Application, Builder, CLI, City, Collection, Comment, ConfigStore, Country, CreateImpossible, CreateURLMissing, DestroyImpossible, EmailRecommendation, Fanship, Favorite, Filter, Flag, Friendship, Geoname, InvalidRequest, JsonBuilder, JsonParser, Link, Location, Paragraph, Picture, Place, Placemark, Profile, ProfileLink, Proxy, Resource, ResourceURLMissing, Root, Settings, State, Subscription, Suggestions, Tag, UnsupportedFormat, UpdateImpossible, User, UserRecommendation, XmlBuilder, XmlParser

Constant Summary collapse

VERSION = 
'0.3.2'

Class Method Summary collapse

Class Method Details

.access_token_from_credentials(username, password) ⇒ Object

Get an access token for all further requests by authenticating with the user’s username and password. Access to this must be requested from Tagcrumbs. It makes dealing with certain types of applications easier (mobile). You should not ask for access_tokens all the time but keep the access token that you received around and not store the username and password of the user.



184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/tagcrumbs.rb', line 184

def access_token_from_credentials(username, password)
  return @@access_token_from_credentials if defined?(@@access_token_from_credentials)
        
  @@access_token_from_credentials = Requestor.new.access_token_from_credentials(username, password)
  
  options[:access_token]  = @@access_token_from_credentials.token
 options[:access_secret] = @@access_token_from_credentials.secret

 @@access_token_from_credentials
	  rescue OAuth::Unauthorized
 nil
end

.access_token_from_request_token ⇒ Object

After you redirected the user to the authorize_url and after the user authorized your application you can exchange the request_token against an access_token that you can use to make all further signed requests. You should use configure to pass in your access_token and access_secret for all further web service calls.



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/tagcrumbs.rb', line 168

def access_token_from_request_token
  return @@access_token_from_request_token if defined?(@@access_token_from_request_token)
  @@access_token_from_request_token = request_token.get_access_token
  
  options[:access_token]  = @@access_token_from_request_token.token
  options[:access_secret] = @@access_token_from_request_token.secret
  
  @@access_token_from_request_token
rescue OAuth::Unauthorized
  nil
end

.authorize_url ⇒ Object

An URL that you should redirect the user to or that you should open in a browser on which the user has to approve access for your application



161
162
163
 
# File 'lib/tagcrumbs.rb', line 161

def authorize_url
  request_token.authorize_url  	  
end

.class_by_type(class_name) ⇒ Object

Returns a Tagcrumbs Class by name



230
231
232
 
# File 'lib/tagcrumbs.rb', line 230

def class_by_type(class_name)  	  
	"Tagcrumbs::#{class_name.classify}".constantize
end

.configure(new_options = {}) ⇒ Object

Overwrite the default_options with your own options. You can specify:

consumer_secret

The OAuth consumer secret of your client that you registered on www.tagcrumbs.com

consumer_token

The OAuth consumer token of your client that you registered on www.tagcrumbs.com

consumer_options

Further Options that will be passed to the OAuth Gem

request_token

The OAuth request token that you received that you can exchange against an access token

request_secret

The OAuth request secret that you received that you can exchange against an access token

format

The Tagcrumbs webservice supports XML and JSON. You can specify the format of your requests here

compression

Use gzip compression to save bandwidth



137
138
139
140
141
142
143
144
145
 
# File 'lib/tagcrumbs.rb', line 137

def configure(new_options={})
  new_options.symbolize_keys!
	new_options.assert_valid_keys(:consumer_secret, :consumer_token, :consumer_options, 
	                          :access_token, :access_secret, 
	                          :request_token, :request_secret,
	                          :format, :compression)
	                          
	self.options.merge!(new_options)
end

.constants ⇒ Object

Constants that are used to validate query parameters in find and search queries



209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/tagcrumbs.rb', line 209

def constants
  @@constants ||= {
    :per_page => [1, 5, 7, 10, 25, 50, 100],
    :from => [:you, :friends, :fans, :recommendations, :everybody, :user],
    :tagcrumb_type => ['Placemark', 'Favorite'],
    :range => [:short, :medium, :long],
    :sort => [:date, :distance, :name, :favorites, :comments],
    :order => [:asc, :desc],
    :w => [:unknown, :country, :state, :city, :zip, :street, :intersection, :address, :premise, :nearby, :everywhere]        
  }.with_indifferent_access
end

.current_user ⇒ Object

Returns the current user that approved the application and owns the current access_token This is also used internally to automatically request all the URLs to POST new resources to.



199
200
201
 
# File 'lib/tagcrumbs.rb', line 199

def current_user
 @@current_user ||= User.load('/you')
end

.default_options ⇒ Object

Returns the default configuration options of the gem. You can overwrite the options with configure



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/tagcrumbs.rb', line 102

def default_options
	{
		:consumer_token => 'ZQAR3nW5D3S5JgU8EAKEfA',
		:consumer_secret => 'vMc7NA77eraJc9TwyImshEEMVgrEy4C8YURVlwoyrHE',
		:format => :xml,
		:compression => true,
		:consumer_options => 
		  {
         :site => 'http://www.tagcrumbs.com',
         :request_token_path => 'https://www.tagcrumbs.com/oauth/request_token',
         :access_token_path => 'https://www.tagcrumbs.com/oauth/access_token',
         :access_token_from_credentials_path => 'https://www.tagcrumbs.com/oauth/access_token_from_credentials'
		  }
	}
end

.options ⇒ Object

Returns the current configuration options



119
120
121
 
# File 'lib/tagcrumbs.rb', line 119

def options
	@@options ||= default_options.with_indifferent_access
end

.request_token ⇒ Object

A request_token that you can let the user authorize, alternatively you can directly use the authorize_url



149
150
151
152
153
154
155
156
157
 
# File 'lib/tagcrumbs.rb', line 149

def request_token
  return @@request_token if defined?(@@request_token)
  @@request_token = Requestor.new.request_token
  
  options[:request_token]  = @@request_token.token
  options[:request_secret] = @@request_token.secret
  
  @@request_token
end

.reset_options! ⇒ Object

Resets the configuration options to the default_options



124
125
126
 
# File 'lib/tagcrumbs.rb', line 124

def reset_options!
  @@options = default_options.with_indifferent_access
end

.root ⇒ Object

Reads the index.(xml|json) file and automatically useses the URLs for further other queries



204
205
206
 
# File 'lib/tagcrumbs.rb', line 204

def root
  @@root ||= Root.load('/index')
end

.supported_formats ⇒ Object

The supported formats of the Gem and their MIME types



235
236
237
238
239
240
 
# File 'lib/tagcrumbs.rb', line 235

def supported_formats
  {
     :xml =>   ['application/xml',  'text/xml'],
     :json =>  ['application/json', 'text/json']
   }
end

.valid_credentials? ⇒ Boolean

Checks whether there is a valid access_token and access_secret that can be used to make all further calls to the webservice.

Returns:

  • (Boolean) 


243
244
245
246
247
248
249
250
251
252
253
254
 
# File 'lib/tagcrumbs.rb', line 243

def valid_credentials?
  if options[:access_token] && options[:access_secret]
    requestor = Requestor.new
    requestor.get('/you')
          
    true
  else
    false
  end
rescue Net::HTTPServerException => error      
  requestor.response.code == '401' ? false : (raise error) # unauthorized
end

.validate(key, value) ⇒ Object

Validate that key has a valid value. Returns an error if it does not. The constants method returns the valid values.



222
223
224
225
226
227
 
# File 'lib/tagcrumbs.rb', line 222

def validate(key, value)
  if constants[key]
    raise ArgumentError.new("#{key} must be one of the following: #{constants[key].join(', ')}") unless constants[key].include?(value)
    true
  end
end