Robodog: File Picker API

Show a modal UI that allows users to pick files from their device and from the web. It uploads files to Transloadit for processing.

const resultPromise = Robodog.pick({
  params: {
    auth: { key: '' },
    template_id: '',
  },
})

resultPromise is a Promise that resolves with an object:

• successful - An array containing data about files that were uploaded successfully
• failed - An array containing data about files that didn’t upload
• transloadit - An array of Assembly statuses
• results - An array of results produced by the assembly, if waitForEncoding was used

options.target

DOM element or CSS selector to place the modal element in. document.body is usually fine in this case because the modal is absolutely positioned on top of everything anyway.

Transloadit

All the options to the Transloadit plugin are supported.

The Promise resolution value has a transloadit and results key.

result.transloadit is an array of Assembly statuses. Assembly statuses are objects as described in the Transloadit documentation. There may be several Assembly statuses if the getAssemblyOptions option was used, because different files may be processed by different Assemblies.

result.results is an array of results produced by the Assemblies. Each result has an assemblyId property containing the string ID of the Assembly that produced it, and a stepName property containing the string name of the Assembly step that produced it.

Restrictions

Set rules and conditions to limit the type and/or number of files that can be selected. Restrictions are configured by the restrictions option.

restrictions.maxFileSize

Maximum file size in bytes for each individual file.

restrictions.minFileSize

Minimum file size in bytes for each individual file.

restrictions.maxTotalFileSize

Maximum file size in bytes for all the files together.

restrictions.maxNumberOfFiles

The total number of files that can be selected. If this is equal to 1, users can only select a single file in system dialogs; else they can select several.

restrictions.minNumberOfFiles

The minimum number of files that must be selected before the upload.

restrictions.allowedFileTypes

Array of mime type wildcards image/*, exact mime types image/jpeg, or file extensions .jpg: ['image/*', '.jpg', '.jpeg', '.png', '.gif'].

If provided, the <input accept> attribute will be used for the internal file input field, so only acceptable files can be selected in the system file dialog.

Providers

Providers import files from third party services using Uppy Companion or from local sources like the device camera.

By default, the Picker will use Transloadit’s Uppy Companion servers for imports from third party service. You can self-host your own instances as well.

providers: []

Array of providers to use. Each entry is the name of a provider. The available ones are:

• 'dropbox' – Import files from Dropbox using Uppy Companion.
• 'google-drive' – Import files from Google Drive using Uppy Companion.
• 'instagram' – Import files from Instagram using Uppy Companion.
• 'url' – Import files from public Web URLs using Uppy Companion.
• 'webcam' – Take photos and record videos using the user’s device camera.
• 'box' — Import files from Box using Uppy Companion.
• 'unsplash' — Search and import images from Unsplash using Uppy Companion.
• 'audio' — Record audio using the user’s device microphone.
• 'screen-capture' — Record user’s device screen for demos and presentations.

companionUrl: Transloadit.COMPANION

The URL to a Uppy Companion server to use. By default, Transloadit’s hosted servers are used. These servers are restricted to importing files from remote providers into Transloadit Assemblies.

companionAllowedHosts: Transloadit.COMPANION_PATTERN

The valid and authorised URL(s) from which OAuth responses should be accepted.

This value can be a String, a Regex pattern, or an Array of both.

This is useful when you have your own Uppy Companion instances running on many hostnames.

companionHeaders: {}

Custom headers to send to Uppy Companion.

dropbox: {}

Specific options for the Dropbox provider.

googleDrive: {}

Specific options for the Google Drive provider.

instagram: {}

Specific options for the Instagram provider.

url: {}

Specific options for the URL provider.

webcam: {}

Specific options for the Webcam provider.

Using your own OAuth applications when importing files

When importing files from remote providers, Transloadit’s OAuth applications are used by default. Your users will be asked to provide Transloadit access to their files. Since your users are probably not aware of Transloadit, this may be confusing or decrease trust. You may also hit rate limits, because the OAuth application is shared between everyone using Transloadit.

You can use your own OAuth keys with Transloadit’s hosted Companion servers by using Transloadit Template Credentials. Create a Template Credential on the Transloadit site. Select “Companion OAuth” for the service, and enter the key and secret for the provider you want to use. Then you can pass the name of the new credentials to that provider:

Robodog.pick({
  providers: ['dropbox'],
  dropbox: {
    credentialsName: 'my_companion_dropbox_creds',
  },
})

Users will now be asked to allow your application access, and they’re probably already familiar with that!