The Box Content Picker UI Element allows developers to add support for selecting
files and folders from Box in their desktop or mobile web application. The
library fetches information about a specified folder through the Box API and
renders the content in a folder view. Users can select files or folders and this
content information is then passed to another part of the application.
The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8" />
<title>Box File Selection</title>
<!-- Latest version of the picker css for your locale -->
<link
rel="stylesheet"
href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.css"
/>
</head>
<body>
<div class="container" style="height:600px"></div>
<!-- Latest version of the picker js for your locale -->
<script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.js"></script>
<script>
var folderId = "123";
var accessToken = "abc";
var filePicker = new Box.FilePicker();
filePicker.show(folderId, accessToken, {
container: ".container"
});
</script>
</body>
</html>
These demos may not fully function until you provide a valid access token. For
testing purposes, you can use your temporary developer token. This will need
to be updated under the JS tab in the demo.
Box Folder ID. This will be the ID of the folder from which you want the content to be picked. If you want to use the Box All Files folder, then use 0 as the folderId.
accessToken
String
Box API access token to use. This should have read/write access to the folder above. The value passed in for the token is assumed to never expire while the explorer is visible.
options
Object
Optional options. See below for details. For example: contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false}) would be used to hide the delete option.
CSS selector of the container in which the content picker should be placed. Calling hide() will clear out this container.
sortBy
String
name
The initial sort by option for the content list. Value should be either name or date.
sortDirection
String
ASC
The initial sort direction option for the content list. Value should be either ASC or DESC.
logoUrl
String
URL of custom logo to show in header. If this value is the string box then the box logo will show.
extensions
Array<string>
[]
Array of file extensions to be allowed for selection. for example ['doc', 'ppt']. Applicable only to the File Picker and not the Folder Picker. If any extensions are provided, only those will have the ability to be selected. An empty array signifies all the file extensions are allowed for selection.
maxSelectable
Number
Infinity
Number of files or folders that can be selected. Specify 1 if you want only 1 file or folder selected.
canUpload
Boolean
true
Visually hides the upload option if this is set to false. Hiding the option alone will not prevent uploading unless the current folder permissions also set can_upload to false. This option has no effect when the folder permission can_upload is set to false.
canSetShareAccess
Boolean
true
Visually hides the sharing drop down select if set to false. Hiding the select drop down alone will not prevent changing the share access unless the folder item permissions also set can_set_share_access to false. This option has no effect when the folder item permission can_set_share_access is set to false.
canCreateNewFolder
Boolean
true
Visually hides the create new folder option. Hiding the option alone will not prevent creating a new folder unless the folder item permissions also set can_upload to false. This option has no effect when the folder item permission can_upload is set to false.
sharedLink
String
Shared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file.
sharedLinkPassword
String
Shared link password, required if shared link has a password.
modal
Object
When the modal attribute is specified, then the content pickers will not be created in-place. Instead a button will be created in the container and clicking this button will launch the content picker in a modal popup.
size
String
undefined
Indicates to the content picker to fit within a small or large width container. Value can be absent or one of small or large. If absent the UI Element will adapt to its container and automatically switch between small width or large width mode.
isTouch
Boolean
Defaults to the browser and device's default touch support
Indicates to the content explorer that it's is being rendered on a touch enabled device.
autoFocus
Boolean
false
When set to true, the item grid will get focus on initial load.
defaultView
String
files
Value should either be files or recents. When set to recents, by default you will see recent items instead of the regular file/folder structure.
Will be fired when the Choose button is pressed. Event data will be an array of Folder Object or File Object or Web Link object depending upon whether it was a file selection or folder selection.
When the item grid has focus, either manually by clicking on it or
programmatically via javascript or via the above mentioned autoFocus prop, the
following keyboard shortcuts will work if their corresponding operations are
applicable and allowed.
If your application requires the end user to only be able to access a subset of
the Content Picker functionality, you can use Downscoping to
appropriately downscope the Access Token to a resulting token that has the
desired set of permissions, and can thus, be securely passed to the end user
client initializing the Content Picker.
Below are a set of UI Element-specific scopes to go alongside Downscoping. These
allow developers to enable/disable UI controls on the Content Picker by
configuring the appropriate scopes on the downscoped token. To learn
more, see Dedicated Scopes for Box UI Elements.
Scope Name
Permissions granted
base_picker
Allows access to content in the folder tree based on user/file/token permissions