Class: Box::Item

Inherits:
Object
  • Object
show all
Defined in:
lib/box/item.rb

Overview

Represents a folder or file stored on Box. Any attributes or actions typical to a Box item can be accessed through this class. The Item class contains only methods shared by Folder and File, and should not be instanciated directly.

Direct Known Subclasses

File, Folder

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api, parent, info) ⇒ Item

Create a new item representing either a file or folder.

Parameters:

  • api (Api) —

    The Api instance used to generate requests.

  • parent (Folder) —

    The Folder parent of this item.

  • info (Hash) —

    The hash of initial info for this item.



24
25
26
27
28
29
30
 
# File 'lib/box/item.rb', line 24

def initialize(api, parent, info)
  @api = api
  @parent = parent
  @data = Hash.new

  update_info(info) # merges with the info hash, and renames some fields
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(sym, *args, &block) ⇒ Object

Provides an easy way to access this item’s info.

Examples:

item.name # returns @data['name'] or fetches it if not cached


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
 
# File 'lib/box/item.rb', line 139

def method_missing(sym, *args, &block)
  # TODO: Why not symbols?
  # convert to a string
  str = sym.to_s

  # determine whether to refresh the cache
  refresh = args ? args.first : false

  # return the value if it already exists
  return @data[str] if not refresh and @data.key?(str)

  # value didn't exist, so try to update the info
  # TODO: Figure out a good way to work with multiple sources.
  case str
  when 'comments'
    self.get_comments
  when
    self.info(refresh)
  end

  # try returning the value again
  return @data[str] if @data.key?(str)

  # we didn't find a value, so it must be invalid
  # call the normal method_missing function
  super
end

Instance Attribute Details

#api ⇒ Api

Returns The Api used by this item.

Returns:

  • (Api) —

    The Api used by this item.



14
15
16
 
# File 'lib/box/item.rb', line 14

def api
  @api
end

#data ⇒ Hash

Returns The hash of info for this item.

Returns:

  • (Hash) —

    The hash of info for this item.



11
12
13
 
# File 'lib/box/item.rb', line 11

def data
  @data
end

#parent ⇒ Folder

Returns The parent of this item.

Returns:

  • (Folder) —

    The parent of this item.



17
18
19
 
# File 'lib/box/item.rb', line 17

def parent
  @parent
end

Class Method Details

.type ⇒ String

Returns The string representation of this item.

Returns:

  • (String) —

    The string representation of this item.



33
 
# File 'lib/box/item.rb', line 33

def self.type; raise "Overwrite this method"; end

.types ⇒ String

Returns The plural string representation of this item.

Returns:

  • (String) —

    The plural string representation of this item.



36
 
# File 'lib/box/item.rb', line 36

def self.types; type + 's'; end

Instance Method Details

#copy(destination) ⇒ Item

Note:

Copying folders is not currently supported.

Copy this item to the destination folder.

Parameters:

  • destination (Folder) —

    The parent folder to copy the item to.

Returns:

  • (Item) —

    The new copy of this item.



87
88
89
90
91
92
93
 
# File 'lib/box/item.rb', line 87

def copy(destination)
  @api.copy(type, id, destination.id)

  destination.delete_info(self.types)

  self.class.new(api, destination, @data)
end

#delete ⇒ Item

Delete this item and all sub-items.

TODO: Return nil instead

Returns:



111
112
113
114
115
116
117
118
 
# File 'lib/box/item.rb', line 111

def delete
  @api.delete(type, id)

  parent.delete_info(self.types)
  @parent = nil

  self
end

#force_cached_info ⇒ Object

Consider the item cached. This prevents an additional api when we know the item is fully fetched.



174
175
176
 
# File 'lib/box/item.rb', line 174

def force_cached_info
  @cached_info = true
end

#id ⇒ String

Returns The id of this item.

Returns:

  • (String) —

    The id of this item.



47
48
49
50
 
# File 'lib/box/item.rb', line 47

def id
  # overloads Object#id
  @data['id']
end

#info(refresh = false) ⇒ Item

Get the info for this item. Uses a cached copy if avaliable, or else it is fetched from the api.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    Does not use the cached copy if true.

Returns:



57
58
59
60
61
62
63
64
 
# File 'lib/box/item.rb', line 57

def info(refresh = false)
  return self if @cached_info and not refresh

  @cached_info = true
  update_info(get_info)

  self
end

#move(destination) ⇒ Item

Move this item to the destination folder.

Parameters:

  • destination (Folder) —

    The new parent folder to use.

Returns:



70
71
72
73
74
75
76
77
78
79
 
# File 'lib/box/item.rb', line 70

def move(destination)
  @api.move(type, id, destination.id)

  parent.delete_info(self.types)
  destination.delete_info(self.types)

  @parent = destination

  self
end

#path ⇒ String

Returns The path of this item. This starts with a ‘/’, unless it is root.

Returns:

  • (String) —

    The path of this item. This starts with a ‘/’, unless it is root.



131
132
133
 
# File 'lib/box/item.rb', line 131

def path
  "#{ parent.path + '/' if parent }#{ name }"
end

#rename(new_name) ⇒ Item

Rename this item.

Parameters:

  • new_name (String) —

    The new name for the item.

Returns:



99
100
101
102
103
104
105
 
# File 'lib/box/item.rb', line 99

def rename(new_name)
  @api.rename(type, id, new_name)

  update_info('name' => new_name)

  self
end

#respond_to?(sym) ⇒ Boolean

Handles some cases in method_missing, but won’t always be accurate.

Returns:

  • (Boolean) 


168
169
170
 
# File 'lib/box/item.rb', line 168

def respond_to?(sym)
  @data.key?(sym.to_s) or super
end

#set_description(message) ⇒ Item

Set the description of this item.

Parameters:

  • message (String) —

    The description message to use.

Returns:



124
125
126
127
128
 
# File 'lib/box/item.rb', line 124

def set_description(message)
  @api.set_description(type, id, message)

  self
end

#share_private(emails, options = Hash.new) ⇒ Object

Shares this item privately with the given email addresses.

Parameters:

  • emails (Array) —

    The Box users to share this item with.

  • options (Hash) (defaults to: Hash.new) —

    Special options related to notification. See the developer wiki for details instructions.



195
196
197
198
199
 
# File 'lib/box/item.rb', line 195

def share_private(emails, options = Hash.new)
  @api.share_private(type, id, emails, options)

  true
end

#share_public(options = Hash.new) ⇒ Object

Generates a share link for this item.

TODO: Document the options.

Parameters:

  • options (Hash) (defaults to: Hash.new) —

    Special options related to notification. See the developer wiki for details instructions.

Returns:

  • The public name of the item. In order to access this item on the web, prefix this value with ‘www.box.net/shared/’.



186
187
188
 
# File 'lib/box/item.rb', line 186

def share_public(options = Hash.new)
  @api.share_public(type, id, options)['public_name']
end

#type ⇒ String

Returns The string representation of this item.

Returns:

  • (String) —

    The string representation of this item.



41
 
# File 'lib/box/item.rb', line 41

def type; self.class.type; end

#types ⇒ String

Returns The plural string representation of this item.

Returns:

  • (String) —

    The plural string representation of this item.



44
 
# File 'lib/box/item.rb', line 44

def types; self.class.types; end

#unshare ⇒ Object

Unshares this item.



202
203
204
 
# File 'lib/box/item.rb', line 202

def unshare
  @api.unshare(type, id)
end