README.markdown in ruby-box-1.11.1 vs README.markdown in ruby-box-1.12.1
- old
+ new
@@ -1,10 +1,12 @@
ruby-box
========
-Mainted by: [Attachments.me](https://attachments.me)
+Build Status: [](https://travis-ci.org/attachmentsme/ruby-box)
+Mainted by: [Attachments.me](http://attachments.me)
+
RubyBox provides a simple, chainable, feature-rich client for [Box's 2.0 API](http://developers.box.com/docs/).
Authorization
-------------
@@ -36,11 +38,13 @@
client_id: 'your-client-id',
client_secret: 'your-client-secret',
access_token: 'original-access-token'
})
+# you need to persist this somehow. the refresh token will change every time you use it
@token = session.refresh_token('your-refresh-token')
+save_me_somehow(@token.refresh_token)
```
__3)__ Create a client using a session initialized with the _access\_token_.
```ruby
@@ -56,119 +60,204 @@
```
Usage
=====
-Once you've created a client, you can start interacting with the Box API. What follows are some basic examples of RubyBox's usage:
+Once you've created a client, you can start interacting with the Box API. What follows are some basic examples of RubyBox's usage.
+Warning
+=======
+
+Please note that using a file/folder path is extremely inefficient, as it causes the gem to traverse the directory structure recursively querying each folder in turn. Prefer the `_by_id` methods where possible for single-request access.
+
+Items
+-----
+
+`File`s and `Folder`s are subclasses of `Item`. `Folder` contents (i.e. files and folders inside that folder) are retrieved in a `mini-format` when the `Folder` instance is loaded.
+
+There are two caveats to this:
+
+### Only some fields are available
+
+a `File` mini looks like this:
+
+```
+{
+ "type": "file",
+ "id": "5000948880",
+ "sequence_id": "3",
+ "etag": "3",
+ "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
+ "name": "tigers.jpeg"
+}
+```
+a `Folder` mini looks like this:
+
+```
+{
+ "type":"folder",
+ "id":"301415432",
+ "sequence_id":"0",
+ "name":"my first sub-folder"
+}
+```
+
+Requests to fields other than the above (e.g. `file.size`) will cause a one-off hit to the api, so take care when iterating over folder contents lest a single application method result in hundreds of api hits and take forever to complete.
+
+This can be mitigated by passing a list of extra fields you want to fetch into the `.items` method:
+
+```ruby
+folder = client.folder_by_id(@folder_id)
+# retrieve size, created_at, and description for all items in this directory
+detailed_items = folder.items(@item_limit, @offset, ['size', 'created_at', 'description'])
+```
+
+Note: only the `type` and `id` fields are included in addition to whatever you specify using the above method, so you must be explicit.
+
+
Folders
-------
* Listing items in a folder:
```ruby
-files = client.folder('/image_folder').files # all files in a folder.
+files = client.folder('/image_folder').files # all files in a folder using a path.
+files = client.folder(@folder_id).files # all files in a folder using an id.
folders = client.root_folder.folders # all folders in the root directory.
files_and_folders = client.folder('files').items # all files and folders in /files
```
* Creating a folder:
```ruby
-client.folder('image_folder').create_subfolder('subfolder')
+client.folder_by_id(@folder_id).create_subfolder('subfolder') # using an id.
+client.folder('image_folder').create_subfolder('subfolder') # using a path.
```
* Setting the description on a folder:
```ruby
-folder = client.folder('image_folder')
+folder = client.folder('image_folder') # using a path.
folder.description = 'Description on Folder'
folder.update
```
* Listing the comments in a discussion surrounding a folder.
```ruby
-folder = client.folder('image_folder')
+folder = client.folder('image_folder') # lookups by id are more efficient
discussion = folder.discussions.first
discussion.comments.each {|comment| p comment.message}
```
* Creating a shared link for a folder.
```ruby
-folder = client.folder('image_folder').create_shared_link
+folder = client.folder('image_folder').create_shared_link # lookups by id are more efficient
p folder.shared_link['url'] # https://www.box.com/s/d6de3224958c1755412
```
Files
-----
* Fetching a file's meta information.
```ruby
-file = client.file('/image_folder/an-image.jpg')
+file = client.file('/image_folder/an-image.jpg')# lookups by id are more efficient
+file = client.file(@file_id)
p file.name
p file.created_at
```
* Uploading a file to a folder.
```ruby
-file = client.upload_file('./LICENSE.txt', '/license_folder')
+file = client.upload_file('./LICENSE.txt', '/license_folder') # lookups by id are more efficient
+file = client.upload_file_by_folder_id('./LICENSE.txt', @folder_id)
```
* Downloading a file.
```ruby
f = open('./LOCAL.txt', 'w+')
f.write( client.file('/license_folder/LICENSE.txt').download )
f.close()
+
+# Or you can fetch by file.id, which is more efficient:
+f = open('./LOCAL.txt', 'w+')
+f.write( client.file_by_id(@file_id).download ) # lookups by id are more efficient
+f.close()
+
+# You can also grab the raw url with
+client.file_by_id(@file_id).download_url
+
+# Note that this URL is not persistent. Clients will need to follow the url immediately in order to
+# actually download the file
```
* Deleting a file.
```ruby
+client.file_by_id(@file_id).delete # this
client.file('/license_folder/LICENSE.txt').delete
```
* Displaying comments on a file.
```ruby
-comments = client.file('/image_folder/an-image.jpg').comments
+comments = client.file('/image_folder/an-image.jpg').comments # lookups by id are more efficient
+comments = client.file_by_id(@file_id).comments
+
comments.each do |comment|
p comment.message
end
```
* Creating a shared link for a file.
```ruby
file = client.file('/image_folder/an-image.jpg').create_shared_link
+file = client.file_by_id(@file_id).create_shared_link # using an id
p file.shared_link.url # https://www.box.com/s/d6de3224958c1755412
```
* Copying a file to another folder.
```ruby
-file = client.file('/image_folder/an-image.jpg')
+
+file = client.file('/one_folder/cow_folder/an-image.jpg')
folder = client.folder('image_folder')
+
+# lookups by id are more efficient
+
+file = client.file_by_id(@file_id)
+folder = client.folder_by_id(@folder_id)
+
file.copy_to(folder)
```
* Moving a file to another folder.
```ruby
-file = client.file('/image_folder/an-image.jpg')
+
+file = client.file('/one_folder/cow_folder/an-image.jpg')
folder = client.folder('image_folder')
+
+# lookups by id are more efficient
+
+file = client.file_by_id(@file_id)
+folder = client.folder_by_id(@folder_id)
+
+
file.move_to(folder)
```
* Adding a comment to a file.
```ruby
-file = client.file('/image_folder/an-image.jpg')
+file = client.file('/image_folder/an-image.jpg') # path
+file = client.file_by_id(@file_id) # id
comment = file.create_comment('Hello World!')
```
Search
------
@@ -194,17 +283,54 @@
eresp.events.each do |ev|
p "type=#{ev.event_id} type=#{ev.event_type} user=#{ev.created_by.name}"
end
```
+As-User
+-------
+
+* This must be manually enabled for your account by Box Staff. Contact api@box.com for access. [ More Info ] (http://developers.box.com/docs/#users-as-user)
+
+```ruby
+session = RubyBox::Session.new({
+ client_id: 'your-client-id',
+ client_secret: 'your-client-secret',
+ access_token: 'original-access-token' ,
+ as_user: 'your-users-box-id'
+})
+```
+Users
+------
+
+Current User Info
+
+```ruby
+me = client.me
+```
+
+Current User's enterprise
+
+```ruby
+me = client.me.enterprise
+```
+
+An array of Ruby:Box users in an enterprise (Supports Filtering, Limit and Offset)
+
+```ruby
+users = client.users
+```
+
+* Remeber the API filters "name" and "login" by the start of the string. ie: to get "sean+awesome@gmail.com" an approriate filter term would be "sean"
+
+```ruby
+users = client.users("sean" , 10 , 1)
+```
+
Contributors
============
-* Benjamin Coe
-* Larry Kang
-* Dan Reed
-* Jesse Miller
+* [full list of contributors](https://github.com/attachmentsme/ruby-box/graphs/contributors)
Contributing to ruby-box
========================
RubyBox does not yet support all of Box's API Version 2.0 functionality, be liberal with your contributions.
@@ -218,6 +344,6 @@
Copyright
=========
Copyright (c) 2012 Attachments.me. See LICENSE.txt for
-further details.
\ No newline at end of file
+further details.