Class: Scribd::Category

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

Overview

A category on Scribd. Categories group together Documents about similar topics. Categories are represented as a two-way tree, with each category having both a #parent and an array of #children.

You can choose to load categories with or without their children using the Category.all method. If you load categories with their children, each parent will have its #children attribute set. Otherwise, calling #children on a category will induce another network call.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Resource

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

Constructor Details

#initialize(options) ⇒ Category

Returns a new instance of Category.



18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/scribd/category.rb', line 18

def initialize(options)
  super
  @children_preloaded = false
  if options[:xml] then
    children_xml = options[:xml].get_elements('subcategories').first
    if children_xml and not children_xml.children.empty?
      @children = Array.new
      children_xml.get_elements('subcategory').each do |child_xml|
        children << Category.new(:xml => child_xml, :parent => self)
      end
      @children_preloaded = true
    end
    options[:xml].delete(children_xml) if children_xml
    
    load_attributes(options[:xml])
    @parent = options[:parent]
    @saved = true
    @created = true
  else
    raise "Categories cannot be created, only retrieved."
  end
end

Dynamic Method Handling

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

Instance Attribute Details

#parent ⇒ Scribd::Category? (readonly)

Returns:

  • (Scribd::Category) —

    The parent of this category.

  • (nil) —

    If this is a top-level category.



15
16
17
 
# File 'lib/scribd/category.rb', line 15

def parent
  @parent
end

Class Method Details

.all(include_children = false) ⇒ Array<Scribd::Category>

Returns an array of top-level categories. These categories will have their #children attributes set if @include_children@ is @true@.

loaded for each top-level category. If @false@, only top-level categories will be loaded. @include_children@ is @true@, each of these categories will have its @children@ attribute pre-loaded.

Parameters:

  • include_children (true, false) (defaults to: false) —

    If @true@, child categories will be

Returns:



58
59
60
61
62
63
64
65
 
# File 'lib/scribd/category.rb', line 58

def self.all(include_children=false)
  response = include_children ? API.instance.send_request('docs.getCategories', :with_subcategories => true) : API.instance.send_request('docs.getCategories')
  categories = Array.new
  response.get_elements('/rsp/result_set/result').each do |res|
    categories << Category.new(:xml => res)
  end
  return categories
end

Instance Method Details

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

Returns documents found by the Scribd browser with given options, all categorized under this category. 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:

category.browse(:sort => 'views', :category_id => 1, :limit => 10)

Parameters:

  • options (Hash) (defaults to: {}) —

    Options to pass to the API find method.

Returns:



103
104
105
106
107
108
109
110
 
# File 'lib/scribd/category.rb', line 103

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

#children ⇒ Array<Scribd::Category>

Returns a list of the categories whose parent is this category.

*If the receiver has preloaded its children* (in other words, it came from a call to .all(true)), this method makes no network call.

*If the receiver has not preloaded its children* (in other words, it came from a call to .all(false)), each invocation of this method will make a new network call.

Returns:



78
79
80
81
82
83
84
85
86
 
# File 'lib/scribd/category.rb', line 78

def children
  return @children if @children
  response = API.instance.send_request('docs.getCategories', :category_id => self.scribd_id)
  children = Array.new
  response.get_elements('/rsp/result_set/result').each do |res|
    children << Category.new(:xml => res)
  end
  return children
end

#children_preloaded? ⇒ true, false

Returns True if this @Category@ has its children preloaded.

Returns:

  • (true, false) —

    True if this @Category@ has its children preloaded.

See Also:



44
45
46
 
# File 'lib/scribd/category.rb', line 44

def children_preloaded?
  @children_preloaded
end