Class: Box::Folder

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

Overview

Represents a folder stored on Box. Any attributes or actions typical to a Box folder can be accessed through this class.

Instance Attribute Summary

Attributes inherited from Item

#api, #data, #parent

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Item

#copy, #delete, #description, #id, #initialize, #method_missing, #move, #path, #rename, #type, #types, types

Constructor Details

This class inherits a constructor from Box::Item

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Box::Item

Class Method Details

.type ⇒ String

Returns The string representation of this item.

Returns:

  • (String) —

    The string representation of this item.



10
 
# File 'lib/box/folder.rb', line 10

def self.type; 'folder'; end

Instance Method Details

#create(name, share = 0) ⇒ Folder

Create a new folder using this folder as the parent.

Parameters:

  • name (String) —

    The name of the new folder.

  • share (Integer) (defaults to: 0) —

    The shared status of the new folder. Defaults to not being shared.

Returns:

  • (Folder) —

    The new folder.



52
53
54
55
56
57
58
 
# File 'lib/box/folder.rb', line 52

def create(name, share = 0)
  info = @api.create_folder(id, name, share)['folder']

  delete_info('folders')

  Box::Folder.new(api, self, info)
end

#find(criteria) ⇒ Array

Note:

The recursive option will call #tree, which can be slow for large folders.

Note:

Any item method (as a symbol) can be used as criteria, which could cause major problems if used improperly.

Search for sub-items using criteria.

TODO: Lookup YARD syntax for options hash.

Examples:

Find all sub-items with the name ‘README’

folder.search(:name => 'README')

Recusively find a sub-item with the given path.

folder.search(:path => '/test/file.mp4', :recursive => true)

Recursively find all files with a given sha1.

folder.search(:type => 'file', :sha1 => 'abcdefg', :recursive => true)

Parameters:

  • criteria (Hash) —

    The hash of criteria to use. Each key of the criteria will be called on each sub-item and tested for equality. This lets you use any method of Item, Box::Folder, and Box::File as the criteria.

Returns:

  • (Array) —

    An array of all sub-items that matched the criteria.



95
96
97
98
99
100
101
102
 
# File 'lib/box/folder.rb', line 95

def find(criteria)
  recursive = criteria.delete(:recursive)
  recursive = false if recursive == nil # default to false for performance reasons

  tree if recursive # get the full tree

  find!(criteria, recursive)
end

#force_cached_info ⇒ Object

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



105
106
107
108
109
110
 
# File 'lib/box/folder.rb', line 105

def force_cached_info
  create_sub_items(nil, Box::Folder)
  create_sub_items(nil, Box::File)

  super
end

#force_cached_tree ⇒ Object

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



114
115
116
117
118
119
120
121
122
123
 
# File 'lib/box/folder.rb', line 114

def force_cached_tree
  @cached_tree = true

  create_sub_items(nil, Box::Folder)
  create_sub_items(nil, Box::File)

  folders.each do |folder|
    folder.force_cached_tree
  end
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.

Files and folders will only be one-level deep, and #tree should be used if fetching deeper than that.

Parameters:

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

    Does not use the cached copy if true.

Returns:



15
16
17
18
19
20
21
22
 
# File 'lib/box/folder.rb', line 15

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

  create_sub_items(nil, Box::Folder)
  create_sub_items(nil, Box::File)

  super
end

#tree(refresh = false) ⇒ Folder

Note:

Fetching the tree can take a long time for large folders. There is a trade-off between one #tree call and multiple #info calls, so use the one most relevant for your application.

Get the tree for this folder. The tree includes all sub folders and files, including their info. 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:



34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/box/folder.rb', line 34

def tree(refresh = false)
  return self if @cached_tree and not refresh

  @cached_info = true # count the info as cached as well
  @cached_tree = true

  update_info(get_tree)
  force_cached_tree

  self
end

#upload(path) ⇒ File

Upload a new file using this folder as the parent

Parameters:

  • path (String) —

    The path of the file on disk to upload.

Returns:

  • (File) —

    The new file.



64
65
66
67
68
69
70
 
# File 'lib/box/folder.rb', line 64

def upload(path)
  info = @api.upload(path, id)['files']['file']

  delete_info('files')

  Box::File.new(api, self, info)
end