Class: Scribd::Document

Inherits:
Resource show all
Defined in:
lib/scribd/document.rb

Overview

A document as shown on the Scribd website. API programs can upload documents from files or URLs, tag them, and change their settings. An API program can access any document, but it can only modify documents owned by the logged-in user.

To upload a new document to Scribd, you must create a new Document instance, set the @file@ attribute to the file’s path, and then save the document:

<pre> doc = Scribd::Document.new doc.file = '/path/or/URL/of/file.txt' doc.save </pre>

You can do this more simply with one line of code:

<pre>doc = Scribd::Document.create :file => '/path/or/URL/of/file.txt'</pre>

If you are uploading a file that does not have an extension (like “.txt”), you need to specify the @type@ attribute as well:

<pre>doc = Scribd::Document.upload :file => 'CHANGELOG', :type => 'txt'</pre>

Aside from these two attributes, you can set other attributes that affect how the file is displayed on Scribd. See the API documentation online for a list of attributes.

These attributes can be accessed or changed directly (@doc.title = ‘Title’@). You must save a document after changing its attributes in order for those changes to take effect. Not all attributes can be modified; see the API documentation online for details.

A document can be associated with a Scribd::User via the @owner@ attribute. This is not always the case, however. Documents retrieved from the Document.find method will not be associated with their owners.

The @owner@ attribute is read/write, however, changes made to it only apply before the document is saved. Once it is saved, the owner is set in stone and cannot be modified:

<pre> doc = Scribd::Document.new :file => 'test.txt' doc.user = Scribd::User.signup(:username => 'newuser', :password => 'newpass', :email => '[email protected]') doc.save #=> Uploads the document as "newuser", regardless of who the Scribd API user is doc.user = Scribd::API.instance.user #=> raises NotImplementedError </pre>

h2. Special attributes

Normally any attributes other than @file@ and @type@ are sent to and dealt by the API; however, there are a few attributes you can set on an instance that have special meaning:

| @thumbnail@ | Set this to the path to, a @File@ object for, or the URL string for an image file you want to act as the document’s thumbnail. Note that for URLs, the thumbnail will be downloaded to memory before being transmitted to the Scribd API server. |

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Resource

create, #created?, #inspect, #method_missing, #read_attribute, #read_attributes, #saved?, #scribd_id, #write_attributes

Constructor Details

#initialize(options = {}) ⇒ Document

Creates a new, unsaved document with the given attributes. The document must be saved before it will appear on the website.

Parameters:

  • (defaults to: {})

    The document’s attributes.



69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/scribd/document.rb', line 69

def initialize(options={})
  super
  @download_urls = Hash.new
  if options[:xml] then
    load_attributes(options[:xml])
    @attributes[:owner] = options[:owner]
    @saved = true
    @created = true
  else
    @attributes = options
  end
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Scribd::Resource

Class Method Details

.browse(options = {}) ⇒ Array<Scribd::Document>

Returns documents found by the Scribd browser with given options. The browser provides documents suitable for a browse page.

This method is called with a hash of options. For a list of supported options, please see the online API documentation.

Documents returned from this method will have their @owner@ attributes set to @nil@ (i.e., they are read-only).

Examples:

Scribd::Document.browse(:sort => 'views', :limit => 10)

Parameters:

  • (defaults to: {})

    Options to pass to the API find method.

Returns:

  • An array of documents found.

See Also:



305
306
307
308
309
310
311
312
 
# File 'lib/scribd/document.rb', line 305

def self.browse(options = {})
  response = API.instance.send_request('docs.browse', options)
  documents = []
  response.elements['/rsp/result_set'].elements.each do |doc|
    documents << Document.new(:xml => doc)
  end
  return documents
end

.featured(options = {}) ⇒ Array<Scribd::Document>

Returns featured documents found in a given with given options.

This method is called with a hash of options. For a list of supported options, please see the online API documentation.

Documents returned from this method will have their @owner@ attributes set to @nil@ (i.e., they are read-only).

Examples:

Scribd::Document.featured(:scope => 'hot', :limit => 10)

Parameters:

  • (defaults to: {})

    Options to pass to the API find method.

Returns:

  • An array of documents found.



281
282
283
284
285
286
287
288
 
# File 'lib/scribd/document.rb', line 281

def self.featured(options = {})
  response = API.instance.send_request('docs.featured', options)
  documents = []
  response.elements['/rsp/result_set'].elements.each do |doc|
    documents << Document.new(:xml => doc)
  end
  return documents
end

.find(options = {}) ⇒ Array<Scribd::Document> .find(id, options = {}) ⇒ Scribd::Document?

provided.

Overloads:

  • .find(options = {}) ⇒ Array<Scribd::Document>

    This method is called with a hash of options to documents by their content. You must at a minimum supply a @query@ option, with a string that will become the full-text search query. For a list of other supported options, please see the online API documentation.

    Documents retrieved by this method have no User stored in their @owner@ attribute; in other words, they cannot be modified.

    Examples:

    Scribd::Document.find(:all, :query => 'cats and dogs', :limit => 10)

    Parameters:

    • (defaults to: {})

      Options for the search.

    Options Hash (options):

    • :query (String) —

      The search query (required).

    • :limit (Fixnum) —

      An alias for the @num_results@ option.

    • :offset (Fixnum) —

      An alias for the @num_start@ option.

    Returns:

    • An array of documents found.

  • .find(id, options = {}) ⇒ Scribd::Document?

    Passing in simply a numerical ID loads the document with that ID. You can pass additional options as defined in the API documentation.

    For now only documents that belong to the current user can be accessed in this manner.

    Examples:

    Scribd::Document.find(108196)

    Parameters:

    • The Scribd ID of the document to locate.

    • (defaults to: {})

      Options to pass to the API find method.

    Returns:

    • The document found.

    • If nothing was found.

Raises:

  • If neither of the two correct argument forms is



249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
 
# File 'lib/scribd/document.rb', line 249

def self.find(options={})
  doc_id = options.kind_of?(Integer) ? options : nil
  raise ArgumentError, "You must specify a query or document ID" unless doc_id or (options.kind_of?(Hash) and options[:query])
  
  if doc_id then
    response = API.instance.send_request('docs.getSettings', :doc_id => doc_id)
    return Document.new(:xml => response.elements['/rsp'])
  else
    options[:num_results] = options[:limit]
    options[:num_start] = options[:offset]
    response = API.instance.send_request('docs.search', options)
    documents = []
    response.elements['/rsp/result_set'].elements.each do |doc|
      documents << Document.new(:xml => doc)
    end
    return documents
  end
end

.thumbnail_url(id, options = {}) ⇒ String

Returns a URL for a thumbnail image of a given document. The document must be public, or you must own it.

of. the width and height of the image, in pixels. vice versa.

Parameters:

  • The document’s ID on the Scribd website.

  • (defaults to: {})

    Options for customizing the thumbnail image.

Options Hash (options):

  • :page (Fixnum) — default: 1 —

    The page number to generate a thumbnail

  • :width (Fixnum) —

    The width of the image, in pixels.

  • :height (Fixnum) —

    The height of the image, in pixels.

  • :size (Array<Fixnum>) —

    A two-element array consisting of

Returns:

  • The URL of the thumbnail image.

Raises:

  • If @:width@ is specified but @:height@ is not, or

  • If @:width@ and @:size@ are both specified.

  • If @:size@ is not a two-item array.



425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
 
# File 'lib/scribd/document.rb', line 425

def self.thumbnail_url(id, options={})
  w = h = nil
  if (options[:width] or options[:height]) and options[:size] then
    raise ArgumentError, "Cannot specify both width/height and size"
  elsif options[:width] and options[:height] then
    w = options[:width]
    h = options[:height]
  elsif options[:size] then
    raise ArgumentError, "Size option must be a two-element array" unless options[:size].kind_of?(Array) and options[:size].size == 2
    w = options[:size].first
    h = options[:size].last
  elsif options[:width] or options[:height] then
    raise ArgumentError, "Must specify both width and height, or neither"
  end
  
  response = API.instance.send_request('thumbnail.get', { :doc_id => id, :width => w, :height => h, :page => options[:page] }.compact)
  response.elements['/rsp/thumbnail_url'].text
end

.update_all(docs, options) ⇒ Object

Quickly updates an array of documents with the given attributes. The documents can have different owners, but all of them must be modifiable.

it has no owner (e.g., it was retrieved from a call to find).

Parameters:

  • An array of documents to update.

  • The attributes to assign to all of those documents.

Raises:

  • If an invalid value for @docs@ is given.

  • If an invalid value for @options@ is given.

  • If one or more documents cannot be modified because



205
206
207
208
209
210
211
212
213
 
# File 'lib/scribd/document.rb', line 205

def self.update_all(docs, options)
  raise ArgumentError, "docs must be an array" unless docs.kind_of? Array
  raise ArgumentError, "docs must consist of Scribd::Document objects" unless docs.all? { |doc| doc.kind_of? Document }
  raise ArgumentError, "You can't modify one or more documents" if docs.any? { |doc| doc.owner.nil? }
  raise ArgumentError, "options must be a hash" unless options.kind_of? Hash
  
  docs_by_user = docs.inject(Hash.new { |hash, key| hash[key] = Array.new }) { |hash, doc| hash[doc.owner] << doc; hash }
  docs_by_user.each { |user, doc_list| API.instance.send_request 'docs.changeSettings', options.merge(:doc_ids => doc_list.collect(&:id).join(','), :session_key => user.session_key) }
end

Instance Method Details

#access_list ⇒ Array<String>

this document.

Returns:

  • A list of user identifiers that have access to

See Also:



385
386
387
 
# File 'lib/scribd/document.rb', line 385

def access_list
  Scribd::Security.document_access_list(self)
end

#conversion_status ⇒ String

Returns the conversion status of this document. When a document is uploaded it must be converted before it can be used. The conversion is non-blocking; you can query this method to determine whether the document is ready to be displayed.

For a full list of conversion statuses, see the online API documentation.

Unlike other properties of a document, this is retrieved from the server every time it’s queried.

Returns:

  • The document’s conversion status.



330
331
332
333
 
# File 'lib/scribd/document.rb', line 330

def conversion_status
  response = API.instance.send_request('docs.getConversionStatus', :doc_id => self.id)
  response.elements['/rsp/conversion_status'].text
end

#destroy ⇒ true, false

Deletes a document.

deleted.

Returns:

  • Whether or not the document was successfully



356
357
358
359
 
# File 'lib/scribd/document.rb', line 356

def destroy
  response = API.instance.send_request('docs.delete', :doc_id => self.id)
  return response.elements['/rsp'].attributes['stat'] == 'ok'
end

#download_url(format = 'original') ⇒ String

Retrieves a document’s download URL. You can provide a format for the download. Valid formats are listed in the online API documentation.

If you do not provide a format, the link will be for the document’s original format.

Parameters:

  • (defaults to: 'original')

    The download format.

Returns:

  • The download URL.



465
466
467
468
469
470
 
# File 'lib/scribd/document.rb', line 465

def download_url(format='original')
  @download_urls[format] ||= begin
    response = API.instance.send_request('docs.getDownloadUrl', :doc_id => self.id, :doc_type => format)
    response.elements['/rsp/download_link'].cdatas.first.to_s
  end
end

#grant_access(user_identifier) ⇒ Object

Grants a user access to this document.

code.

Parameters:

  • The user identifier as used in your embed

See Also:



367
368
369
 
# File 'lib/scribd/document.rb', line 367

def grant_access(user_identifier)
  Scribd::Security.grant_access user_identifier, self
end

#id ⇒ Object

Returns The @document_id@ attribute.

Returns:

  • The @document_id@ attribute.



446
447
448
 
# File 'lib/scribd/document.rb', line 446

def id
  self.doc_id
end

#owner=(newuser) ⇒ Object 



451
452
453
454
 
# File 'lib/scribd/document.rb', line 451

def owner=(newuser)
  # don't allow them to set the owner if the document is saved
  saved? ? raise(NotImplementedError, "Cannot change a document's owner once the document has been saved") : super
end

#reads(options = {}) ⇒ String

Returns the document read count. This is only retrieved from the API server the first time it’s queried unless @force@ is set to @true@.

this value and re-retrieves it from the API server.

Parameters:

  • (defaults to: {})

    A hash of options.

Options Hash (options):

  • :force (true, false) —

    If true, clears the local cache for

Returns:

  • The number of reads this document has received.



343
344
345
346
347
348
349
 
# File 'lib/scribd/document.rb', line 343

def reads(options = {})
  if @reads.nil? || options[:force]
    response = API.instance.send_request('docs.getStats', :doc_id => self.id)
    @reads = response.elements['/rsp/reads'].text
  end
  @reads
end

#revoke_access(user_identifier) ⇒ Object

Revokes access to this document from a user.

code.

Parameters:

  • The user identifier as used in your embed

See Also:



377
378
379
 
# File 'lib/scribd/document.rb', line 377

def revoke_access(user_identifier)
  Scribd::Security.revoke_access user_identifier, self
end

#save ⇒ true, false

For document objects that have not been saved for the first time, uploads the document, sets its attributes, and saves it. Otherwise, updates any changed attributes and saves it. Returns true if the save completed successfully. Throws an exception if save fails.

For first-time saves, you must have specified a @file@ attribute. This can either be a local path to a file, or an HTTP, HTTPS, or FTP URL. In either case, the file at that location will be uploaded to create the document.

If you create a document, specify the @file@ attribute again, and then save it, Scribd replaces the existing document with the file given, while keeping all other properties (title, description, etc.) the same, in a process called revisioning.

You must specify the @type@ attribute alongside the @file@ attribute if the file’s type cannot be determined from its name.

document with no associated user (i.e., one retrieved from the find method).

Returns:

  • Whether or not the upload was successful.

Raises:

  • If the connection is slow or inaccessible.

  • If a remote problem occurs.

  • If you try to upload a new revision for a



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
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
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/scribd/document.rb', line 106

def save
  if not created? and @attributes[:file].nil? then
    raise "'file' attribute must be specified for new documents"
  end
  
  if created? and @attributes[:file] and (@attributes[:owner].nil? or @attributes[:owner].session_key.nil?) then
    raise PrivilegeError, "The current API user is not the owner of this document"
  end

  # Make a request form
  response = nil
  fields = @attributes.dup
  fields.delete :thumbnail
  fields[:session_key] = fields.delete(:owner).session_key if fields[:owner]
  if file = @attributes[:file] then
    fields.delete :file
    is_file_object = file.is_a?(File)
    file_path = is_file_object ? file.path : file
    ext = File.extname(file_path).gsub(/^\./, '')
    ext = nil if ext == ''
    fields[:doc_type] = fields.delete(:type)
    fields[:doc_type] ||= ext
    fields[:doc_type].downcase! if fields[:doc_type]
    fields[:rev_id] = fields.delete(:doc_id)

    begin
      uri = URI.parse @attributes[:file]
    rescue URI::InvalidURIError
      uri = nil # Some valid file paths are not valid URI's (but some are)
    end
    if uri.kind_of? URI::HTTP or uri.kind_of? URI::HTTPS or uri.kind_of? URI::FTP then
      fields[:url] = @attributes[:file]
      response = API.instance.send_request 'docs.uploadFromUrl', fields
    elsif uri.kind_of? URI::Generic or uri.nil? then
      file_obj = is_file_object ? file : File.open(file, 'rb')
      fields[:file] = file_obj
      response = API.instance.send_request 'docs.upload', fields
      file_obj.close unless is_file_object
    end
  end
  
  fields = @attributes.dup # fields is what we send to the server

  if response then
    # Extract our response
    xml = response.get_elements('/rsp')[0]
    load_attributes(xml)
    @created = true
  end

  if thumb = fields.delete(:thumbnail) then
    begin
      uri = URI.parse(thumb)
    rescue URI::InvalidURIError
      uri = nil
    end

    file = nil
    if uri.kind_of?(URI::HTTP) or uri.kind_of?(URI::HTTPS) or uri.kind_of?(URI::FTP) then
      file = open(uri)
    elsif uri.kind_of?(URI::Generic) or uri.nil? then
      file = thumb.kind_of?(File) ? thumb : File.open(thumb, 'rb')
    end

    API.instance.send_request('docs.uploadThumb', :file => file, :doc_id => self.id)
    file.close
  end
  
  fields.delete :access if fields[:file] # when uploading a doc, don't send access twice
  fields.delete :file
  fields.delete :type
  fields.delete :conversion_status
  
  changed_attributes = fields.dup # changed_attributes is what we will stick into @attributes once we update remotely
  
  fields[:session_key] = fields[:owner].session_key if fields[:owner]
  changed_attributes[:owner] ||= API.instance.user
  fields[:doc_ids] = self.id
  
  fields.delete :owner
  
  API.instance.send_request('docs.changeSettings', fields)
  
  @attributes.update(changed_attributes)
  
  @saved = true
  return true
end

#thumbnail_url(options = {}) ⇒ String

Returns a URL for a thumbnail image of this document.

of. the width and height of the image, in pixels. vice versa.

Parameters:

  • (defaults to: {})

    Options for customizing the thumbnail image.

Options Hash (options):

  • :page (Fixnum) — default: 1 —

    The page number to generate a thumbnail

  • :width (Fixnum) —

    The width of the image, in pixels.

  • :height (Fixnum) —

    The height of the image, in pixels.

  • :size (Array<Fixnum>) —

    A two-element array consisting of

Returns:

  • The URL of the thumbnail image.

Raises:

  • If @:width@ is specified but @:height@ is not, or

  • If @:width@ and @:size@ are both specified.

  • If @:size@ is not a two-item array.



404
405
406
 
# File 'lib/scribd/document.rb', line 404

def thumbnail_url(options={})
  self.class.thumbnail_url self.id, options
end