Class: OEmbed::Provider

Inherits:
Object
  • Object
show all
Includes:
HttpHelper
Defined in:
lib/oembed/provider.rb

Overview

An OEmbed::Provider has information about an individual oEmbed enpoint.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(endpoint, positional_format = OEmbed::Formatter.default, format: nil, required_query_params: {}) ⇒ Provider

Construct a new OEmbed::Provider instance, pointing at a specific oEmbed endpoint.

The endpoint should be a String representing the http URI of the Provider’s oEmbed endpoint. The endpoint String may also contain a #format portion. In actual requests to this Provider, this string will be replaced with a String representing the request format (e.g. “json”).

The ‘format:` option should be the name of the default format for all request to this Provider (e.g. ’json’). Defaults to OEmbed::Formatter.default

# @deprecated Note: The ‘positional_format` is deprecated. Please used the named argument instead.

The ‘required_query_params:` option should be a Hash representing query params that will be appended to the endpoint on each request and the optional name of an environment variable (i.e. ENV) whose value will be used

For example:

# If requests should be sent to:
# "http://my.service.com/oembed?format=#{OEmbed::Formatter.default}"
@provider = OEmbed::Provider.new("http://my.service.com/oembed")

# If requests should be sent to:
# "http://my.service.com/oembed.xml"
@xml_provider = OEmbed::Provider.new("http://my.service.com/oembed.{format}", format: :xml)

# If the endpoint requires an `access_token` be specified:
@provider_with_auth = OEmbed::Provider.new("http://my.service.com/oembed", required_query_params: { access_token: 'MY_SERVICE_ACCESS_TOKEN' })
# You can optionally override the value from `ENV['MY_SERVICE_ACCESS_TOKEN']`
@provider_with_auth.access_token = @my_access_token

Raises:

  • (ArgumentError) 


61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/oembed/provider.rb', line 61

def initialize(endpoint, positional_format = OEmbed::Formatter.default, format: nil, required_query_params: {})
  endpoint_uri = URI.parse(endpoint.gsub(/[\{\}]/,'')) rescue nil
  raise ArgumentError, "The given endpoint isn't a valid http(s) URI: #{endpoint.to_s}" unless endpoint_uri.is_a?(URI::HTTP)

  @required_query_params = {}
  required_query_params.each do |param, default_env_var|
    param = param.to_sym
    @required_query_params[param] = nil
    set_required_query_params(param, ENV[default_env_var]) if default_env_var

    # Define a getter and a setter for each required_query_param
    define_singleton_method("#{param}") { @required_query_params[param] } unless respond_to?("#{param}")
    define_singleton_method("#{param}=") { |val| set_required_query_params(param, val) } unless respond_to?("#{param}=")
  end
  required_query_params_set?(reset_cache: true)

  @endpoint = endpoint
  @urls = []
  @format = format || positional_format
end

Instance Attribute Details

#endpoint ⇒ Object

The String that is the http URI of the Provider’s oEmbed endpoint. This URL may also contain a {format} portion. In actual requests to this Provider, this string will be replaced with a string representing the request format (e.g. “json”).



13
14
15
 
# File 'lib/oembed/provider.rb', line 13

def endpoint
  @endpoint
end

#format ⇒ Object

The name of the default format for all request to this Provider (e.g. ‘json’).



16
17
18
 
# File 'lib/oembed/provider.rb', line 16

def format
  @format
end

#name ⇒ Object

Deprecated.

Note: This accessor currently isn’t used anywhere in the codebase.

The human-readable name of the Provider.



24
25
26
 
# File 'lib/oembed/provider.rb', line 24

def name
  @name
end

#url ⇒ Object

Deprecated.

Note: Added in a fork of the gem, a while back. I really would like

to get rid of it, though. –Marcos



28
29
30
 
# File 'lib/oembed/provider.rb', line 28

def url
  @url
end

#urls ⇒ Object

An Array of all URL schemes supported by this Provider.



19
20
21
 
# File 'lib/oembed/provider.rb', line 19

def urls
  @urls
end

Instance Method Details

#<<(url) ⇒ Object

Adds the given url scheme to this Provider instance. The url scheme can be either a String, containing wildcards specified with an asterisk, (see oembed.com/#section2.1 for details), or a Regexp.

For example:

@provider << "http://my.service.com/video/*"
@provider << "http://*.service.com/photo/*/slideshow"
@provider << %r{^http://my.service.com/((help)|(faq))/\d+[#\?].*}



91
92
93
94
95
96
97
98
99
 
# File 'lib/oembed/provider.rb', line 91

def <<(url)
  if !url.is_a?(Regexp)
    full, scheme, domain, path = *url.match(%r{([^:]*)://?([^/?]*)(.*)})
    domain = Regexp.escape(domain).gsub("\\*", "(.*?)").gsub("(.*?)\\.", "([^\\.]+\\.)?")
    path = Regexp.escape(path).gsub("\\*", "(.*?)")
    url = Regexp.new("^#{Regexp.escape(scheme)}://#{domain}#{path}")
  end
  @urls << url
end

#build(url, query = {}) ⇒ Object

Deprecated.

Note: This method will be made private in the future.

Raises:



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/oembed/provider.rb', line 147

def build(url, query = {})
  raise OEmbed::NotFound, url unless include?(url)

  query.delete(:timeout)
  query.delete(:max_redirects)

  query = query.merge(@required_query_params)
  query = query.merge({:url => ::CGI.escape(url)})

  # TODO: move this code exclusively into the get method, once build is private.
  this_format = (query[:format] ||= @format.to_s).to_s

  endpoint = @endpoint.clone

  if endpoint.include?("{format}")
    endpoint["{format}"] = this_format
    query.delete(:format)
  end

  base = endpoint.include?('?') ? '&' : '?'
  query = base + query.inject("") do |memo, (key, value)|
    "#{key}=#{value}&#{memo}"
  end.chop

  URI.parse(endpoint + query).instance_eval do
    @format = this_format
    def format
      @format
    end
    self
  end
end

#get(url, query = {}) ⇒ Object

Send a request to the Provider endpoint to get information about the given url and return the appropriate OEmbed::Response.

The query parameter should be a Hash of values which will be sent as query parameters in this request to the Provider endpoint. The following special cases apply to the query Hash:

:timeout

specifies the timeout (in seconds) for the http request.

:format

overrides this Provider’s default request format.

:url

will be ignored, replaced by the url param.

:max_redirects

the number of times this request will follow 3XX redirects before throwing an error. Default: 4



133
134
135
136
 
# File 'lib/oembed/provider.rb', line 133

def get(url, query = {})
  query[:format] ||= @format
  OEmbed::Response.create_for(raw(url, query), self, url, query[:format].to_s)
end

#include?(url) ⇒ Boolean

Determine whether the given url is supported by this Provider by matching against the Provider’s URL schemes. It will always return false of a provider has required_query_params that are not set.

Returns:

  • (Boolean) 


141
142
143
144
 
# File 'lib/oembed/provider.rb', line 141

def include?(url)
  return false unless required_query_params_set?
  @urls.empty? || !!@urls.detect{ |u| u =~ url }
end

#raw(url, query = {}) ⇒ Object

Deprecated.

Note: This method will be made private in the future.



181
182
183
184
185
186
187
 
# File 'lib/oembed/provider.rb', line 181

def raw(url, query = {})
  uri = build(url, query)
  http_get(uri, query)
rescue OEmbed::UnknownFormat
  # raise with format to be backward compatible
  raise OEmbed::UnknownFormat, format
end

#required_query_params_set?(reset_cache: false) ⇒ Boolean

Returns true if all of this provider’s required_query_params have a value

Returns:

  • (Boolean) 


117
118
119
120
121
 
# File 'lib/oembed/provider.rb', line 117

def required_query_params_set?(reset_cache: false)
  return @all_required_query_params_set unless reset_cache || @all_required_query_params_set.nil?

  @all_required_query_params_set = !@required_query_params.values.include?(nil)
end

#set_required_query_params(param, val) ⇒ Object

Given the name of a required_query_param and a value store that value internally, so that it can be sent along with requests to this provider’s endpoint. Raises an ArgumentError if the given param is not listed with required_query_params during instantiation.

Raises:

  • (ArgumentError) 


106
107
108
109
110
111
112
113
114
 
# File 'lib/oembed/provider.rb', line 106

def set_required_query_params(param, val)
  raise ArgumentError.new("This provider does NOT have a required_query_param named #{param.inspect}") unless @required_query_params.has_key?(param)

  @required_query_params[param] = val.nil? ? nil : ::CGI.escape(val.to_s)

  required_query_params_set?(reset_cache: true)

  @required_query_params[param]
end