box-chrome-sdk

Chrome-App-SDK

Box V2 API SDK for Chrome apps and extensions written in AngularJS. With some effort, it can be used from node.js as well.

Installing

bower

bower install box-chrome-sdk

npm

npm install box-chrome-sdk

Quick Start

Setup

Make sure the following permissions are specified in your app's manifest:

permissions: [
    "downloads",
    "identity",
    "storage",
    "https://*.box.com/*",
    "https://*.boxcdn.com/*",
    "https://*.boxcdn.net/*",
    "https://*.boxcloud.com/*"
]

Include SDK and requirements javascript

<script src="box-chrome-sdk.bower_components.min.js"></script>
<script src="box-chrome-sdk.min.js"></script>

Configure the SDK with your Box app's client ID and secret

angular.module('box.conf')
    .constant('clientSecret', 'uII-----------------------------')
    .constant('clientId', 'i3p-----------------------------');

Add a dependency to box.sdk to your angular module####

angular.module('myModule', ['box.sdk']);

Require boxSdk as a dependency in your angular services or directives

module.directive('myDirective', ['boxSdk', function(boxSdk) {

}]);

Making API Calls

Most functions in the SDK return Rx Observables. Mastery of reactive programming, however, is not required to use these objects.

To get at an API result, simply subscribe to the observable and read the result inside the callback.

Get a folder object

boxSdk.getFolder(0).subscribe(function(folder) {
    console.log(folder.name);
});

// -> All Files

Search Box

boxSdk.search('query text')
    .subscribe(function(result) {
        console.log(result.type + ' -> ' + result.name);
    });

// -> Folder -> Query 1
// -> File -> Results Query

Device Pinning

Some Box enterprises enforce device pinning, and require that auth requests are accompanied by a device ID. Chrome doesn't support a device specific identifier, and that is by design.

However, it should be possible to supply a device ID, either from an application/extension setting supplied by a user, or by Chrome managed storage. Passing it with auth requests is as simple as:

var http = angular.module('box.http'),
    deviceId = getDeviceIdSomehow();

http.factory('boxDeviceIdInterceptor',['$q', 'authUrl', function($q, authUrl){
    return {
        request: function(config) {
            if (config.url.indexOf(authUrl) === 0) {
                config.data.append('box_device_id', deviceId);
            }
            return config;
        }
    };
}]);

http.config(['$httpProvider',function($httpProvider) {
    $httpProvider.interceptors.push('boxDeviceIdInterceptor');
}]);

Docs and examples

Search Box from OmniBox Example

Example extension showing how to use the SDK in an extension's background page.

Upload to Box Example

Example extension showing how to use the SDK in a content script.

Box Chrome App Example

Example packaged app showing how to use the SDK in a packaged app.

Node.js Example

Example login script showing how to use the SDK in a node.js script.

Notifications Example

Example events script showing how to use the SDK to monitor events.

Documentation

Docs

Building the SDK

Building the SDK requires Grunt. *If you are new to Grunt, you will find a lot of answers to your questions in their getting started guide.

From the same directory as Gruntfile.js, type

npm install
bower install
grunt

Running the tests

grunt test

Contributing

See CONTRIBUTING.

Support

Need to contact us directly? Email [e-mail] and be sure to include the name of this project in the subject.

Copyright and License

Copyright 2014 Box, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.