Tiny Drive Standalone API

Tiny Drive can be used as a generic file manager separate from TinyMCE this is referred to as standalone mode.

Loading the standalone API script

In order to use Tiny Drive in standalone mode you will need to add a script to your page with your API key as part of the URL. The URL is in the following format:

https://cdn.tiny.cloud/1/_your_api_key_/tinydrive/5-stable/tinydrive.min.js

Example: Loading the standalone API script

<script src="https://cdn.tiny.cloud/1/_your_api_key_/tinydrive/5-stable/tinydrive.min.js" referrerpolicy="origin"></script>
<script>
tinydrive.pick({
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});
</script>

tinydrive.pick

The tinydrive.pick method enables you to pick files from Tiny Drive and get the meta data of those files returned in a promise. For a complete list of available settings to pass into this method check the Picker settings section in this page.

File Picker Result Format

The tinydrive.pick method will return a promise with object that has a files property. This files property is an array of files with the following properties.

name

The name of the selected file for example my.jpg.

size

The size in bytes of the selected file.

url

The URL for the selected file would be in the following format: https://drive.tiny.cloud/1/<your api key>/<file uuid>

mdate

The modification date for the file in ISO 8601 format for example 2019-02-24T15:00:00Z

Interactive example: Using tinydrive.pick

  • Tiny Drive

  • HTML

  • JS

<div class="tinydrive-standalone-demo">
  <input class="tinydrive-standalone-demo-input" />
  <button class="tinydrive-standalone-demo-pick">Pick file</button>
</div>
var button = document.querySelector('.tinydrive-standalone-demo-pick');
var input = document.querySelector('.tinydrive-standalone-demo-input');

button.addEventListener('click', function () {
  tinydrive.pick({
    token_provider: '/your-local/jwt-provider'
  }).then(function(result) {
    input.value = result.files[0].url;
  });
}, false);

tinydrive.browse

The tinydrive.browse method enables you to browse your files stored in Tiny Drive but without the possibility to pick them to be inserted. This might be useful if you want to use Tiny Drive as a generic file manager. It returns a promise but the promise will only resolve when the Tiny Drive dialog is closed by using the close button. For a complete list of available settings to pass in to this method check the Picker settings section in this page.

Interactive example: Using tinydrive.browse

  • Tiny Drive

  • HTML

  • JS

<div class="tinydrive-standalone-demo">
  <button class="tinydrive-standalone-demo-browse">Browse</button>
</div>
var button = document.querySelector('.tinydrive-standalone-demo-browse');

button.addEventListener('click', function () {
  tinydrive.browse({
    token_provider: '/your-local/jwt-provider'
  }).then(function () {
    console.log('Dialog closed');
  });
}, false);

tinydrive.upload

The tinydrive.upload method enables directly upload blobs to your Tiny Drive storage. This can be useful when you want to store a file generated by your app.

Interactive example: Using tinydrive.upload

  • Tiny Drive

  • HTML

  • JS

0%
<div class="tinydrive-standalone-demo">
  <button class="tinydrive-standalone-demo-upload">Upload</button>
  <div class="tinydrive-standalone-demo-percent">0%</div>
</div>
var button = document.querySelector('.tinydrive-standalone-demo-upload');
var percent = document.querySelector('.tinydrive-standalone-demo-percent');

button.addEventListener('click', function () {
  tinydrive.upload({
    token_provider: '/your-local/jwt-provider',
    path: '/hello',
    name: 'hello.txt',
    blob: new Blob(['Hello world!']),
    onprogress: function (progress) {
      percent.innerHTML = Math.round(progress.loaded / progress.total * 100) + '%';
    }
  }).then(function () {
    console.log('File is uploaded.');
  });
}, false);

tinydrive.start

Start is similar to pick and browse, the main difference is that method doesn’t have a way of closing the dialog. This can be useful when you want to launch Tiny Drive from an url where there is no application to insert the files into. This might be useful when you want to launch Tiny Drive from an url but not part of a bigger application. For a complete list of available settings to pass in to this method check the Picker settings section in this page.

Example: Using tinydrive.start

tinydrive.start({
  token_provider: '/your-local/jwt-provider'
});

Generic settings

These settings can be passed to any of the standalone API methods.

token_provider

This setting could take one of the following two forms:

  • A URL to a page that takes an HTTP JSON POST request and produces a JSON structure with a valid JWT. It uses a POST request to avoid caching by browsers and proxies.

  • A function that provides the same token through a callback. This allows making an HTTP request in any desired format. The provider function is a function that has a success and failure callback where the success takes an object with a token property containing the JWT, and the failure callback takes a string to present as an error message if the token could not be produced.

For more information on how to create these tokens, refer to the JWT authentication guide or try one of the starter projects.

Type: String or Function

Required: yes

Example Using a JWT Provider URL

tinydrive.pick({
  token_provider: '/jwt' // this can be a page or endpoint like this
});

Example Using a JWT Provider Callback

tinydrive.pick({
  token_provider: function (success, failure) {
     success({ token: 'jwt-token' });
     // failure('Could not create a jwt token')
  }
}).then(function (result) {
  console.log(result.files);
});

Picker settings

These settings are available for the tinydrive.pick / tinydrive.browse / tinydrive.start methods.

dropbox_app_key

This setting enables specifying the Dropbox API key for integrating dropbox into Tiny Drive. For more information on how you obtain this key, refer to the Dropbox integration guide.

Type: string

Example: Using dropbox_app_key

tinydrive.pick({
  dropbox_app_key: '<your dropbox app key>',
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});

filetypes

This setting enables restricting what types of files you want do display based on file type categories. For example if your app needs to insert images only then you can specify ['image'] in the file types array.

Type: Array<string>

Example: Using filetypes

tinydrive.pick({
  filetypes: ['image'],
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});

google_drive_client_id

This setting enables specifying the Google Drive client ID for integrating Google Drive into Tiny Drive. For more information on how you obtain this ID, refer to the Google Drive integration guide.

Type: string

Example: Using google_drive_client_id

tinydrive.pick({
  google_drive_client_id: '<your google drive client id>',
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});

google_drive_key

This setting enables specifying the Google Drive API key for integrating Google Drive into Tiny Drive. For more information on how you obtain this key, refer to the Google Drive integration guide.

Type: string

Example: Using google_drive_key

tinydrive.pick({
  google_drive_key: '<your google drive api key>',
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});

max_image_dimension

This setting enables constraining the width/height of uploaded images. When this is enabled any images with a higher width or height than the specified amount would be proportionally resized down to the specified maximum dimension.

Type: Number

Example: Using max_image_dimension

tinydrive.pick({
  max_image_dimension: 1024,
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});

skin

This option sets the skin applied to Tiny Drive. The default skin included with Tiny Drive is named "oxide".

Type: String

Default Value: 'oxide'

Possible Values: 'oxide', 'oxide-dark'

tinydrive.pick({
  skin: 'dark',
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});

target

This setting enables you to render Tiny Drive within a target element by using a CSS selector. If the container has display: flex then the container will be filled with the Tiny Drive UI this could be useful if you want to position the Tiny Drive UI inside your web applications interface.

Type: String

Example: Using target

<script>
tinydrive.pick({
  target: '.my-custom-div',
  token_provider: '/your-local/jwt-provider'
}).then(function (result) {
  console.log(result.files);
});
</script>
<div class="my-custom-div" style="display: flex; width: 800px; height: 600px">
</div>

Standalone API interfaces

Here is a complete API reference as TypeScript types for developers used to TypeScript syntax.

interface StandaloneApi
  pick: (settings: StandalonePickerApiSettings) => Promise<PickerResult>;
  browse: (settings: StandalonePickerApiSettings) => Promise<void>;
  start: (settings: StandalonePickerApiSettings) => Promise<void>;
  upload: (settings: StandaloneUploadApiSettings) => Promise<UploadResult>;
}

type TokenProviderCallback = (
  success: (result: TokenResult) => void,
  failure: (error: string) => void
) => void;

interface CommonStandaloneApiSettings {
  token_provider: string | TokenProviderCallback;
}

interface StandalonePickerApiSettings extends CommonStandaloneApiSettings {
  filetypes?: string[];
  dropbox_app_key?: string;
  google_drive_client_id?: string;
  google_drive_key?: string;
  max_image_dimension?: number;
  skin?: string;
  target?: string;
}

interface StandaloneUploadApiSettings extends CommonStandaloneApiSettings {
  path?: string;
  name: string;
  blob: Blob;
  onprogress?: (details: UploadProgress) => void;
  max_image_dimension?: number;
}

interface DriveFile {
  url: string;
  size: number;
  name: string;
  type: string;
  mdate: string;
}

interface PickerResult {
  files: DriveFile[];
}

interface UploadProgress {
  loaded: number;
  total: number;
}

interface UploadResult {
  file: DriveFile;
}