Data Types

Vue Upload Widget

File upload component for Vue. Supports: image cropping, drag-and-drop, and more.

Installation

To install via NPM:

npm install @bytescale/upload-widget-vue

To install via a script tag:

<script src="https://js.bytescale.com/upload-widget-vue/v4"></script>

Usage

To add file uploads to your web app, use these code snippets:

Option 2: Create a Dropzone Area

1<template>
2 <UploadDropzone :options="options"
3 :on-complete="onFilesUploaded"
4 :on-update="onFileListChanged"
5 width="600px"
6 height="375px" />
7</template>
8
9<script lang="ts">
10 import { UploadDropzone } from "@bytescale/upload-widget-vue";
11 import type { UploadWidgetConfig, UploadWidgetResult, UploadWidgetOnUpdateEvent } from "@bytescale/upload-widget";
12
13 // -----
14 // Configuration:
15 // https://www.bytescale.com/docs/upload-widget#configuration
16 // -----
17 const options: UploadWidgetConfig = {
18 apiKey: "free", // Get API key: https://www.bytescale.com/get-started
19 maxFileCount: 10,
20 showFinishButton: true
21 };
22
23 export default {
24 name: "App",
25 components: {
26 UploadDropzone
27 },
28 data() {
29 return {
30 options
31 };
32 },
33 methods: {
34 onFileListChanged({ uploadedFiles, pendingFiles, failedFiles }: UploadWidgetOnUpdateEvent) {
35 const uploadedFileUrls = uploadedFiles.map(x => x.fileUrl).join("\n");
36 console.log(uploadedFileUrls);
37 },
38 onFilesUploaded(files: UploadWidgetResult[]) {
39 if (files.length === 0) {
40 alert("No files selected.");
41 } else {
42 alert(files.map(f => f.fileUrl).join("\n"));
43 }
44 }
45 }
46 };
47</script>

Special behaviour for dropzones:

onComplete only fires when showFinishButton = true (i.e. when the user clicks "Finish").

onUpdate must be used when showFinishButton = false.

Default value: showFinishButton = false

Result

The onComplete callback receives the following:

[
{
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
"originalFile": {
"accountId": "YOUR_ACCOUNT_ID",
"filePath": "/uploads/image.jpg",
"fileUrl": "https://upcdn.io/A623uY2/raw/uploads/image.jpg",
"lastModified": 1615680311115,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mime": "image/jpeg",
"originalFileName": "example.jpg",
"size": 43182,
"tags": [
"example_tag"
]
}
}
]

The onUpdate callback receives the following:

1{
2 "uploadedFiles": [],
3 "failedFiles": [],
4 "pendingFiles": [
5 {
6 "file": {
7 "name": "my-file.txt",
8 "type": "text/plain",
9 "size": 42
10 }
11 }
12 ]
13}

The uploadedFiles field uses the same structure as the onComplete param above.

Configuration

The options object requires the following object (all fields optional, except for apiKey, which is required):

{
"apiKey": "public_A623uY2RvnNq1vZ80fYgGyhKN0U7",
"editor": {
"images": {
"crop": true,
"cropRatio": 1,
"cropShape": "circ",
"preview": true
}
},
"layout": "modal",
"maxFileCount": 1,
"maxFileSizeBytes": 10485760,
"metadata": {
"myCustomField1": true,
"myCustomField2": {
"hello": "world"
},
"anotherCustomField": 42
},
"mimeTypes": [
"image/jpeg"
],
"multi": false,
"onInit": Function,
"onPreUpload": Function,
"onUpdate": Function,
"path": {
"fileName": "image.jpg",
"fileNameFallback": "image.jpg",
"fileNameVariablesEnabled": true,
"folderPath": "/uploads",
"folderPathVariablesEnabled": true
},
"showFinishButton": true,
"showRemoveButton": true,
"styles": {
"colors": {
"active": "#528fff",
"error": "#d23f4d",
"primary": "#377dff",
"shade100": "#333",
"shade200": "#7a7a7a",
"shade300": "#999",
"shade400": "#a5a6a8",
"shade500": "#d3d3d3",
"shade600": "#dddddd",
"shade700": "#f0f0f0",
"shade800": "#f8f8f8",
"shade900": "#fff"
},
"fontFamilies": {
"base": "-apple-system, blinkmacsystemfont, Segoe UI, helvetica, arial, sans-serif"
},
"fontSizes": {
"base": 16
}
},
"tags": [
"example_tag"
]
}

You can disable image, video, and PDF previews by setting preview: false

You can disable the image cropper by setting crop: false

Building URLs

You should save filePath values to your DB instead of fileUrl values:

  • filePath values are shorter.

  • filePath values allow you to change the domain in the future (e.g. if you move to a custom CNAME).

  • filePath values allow you to switch between file transformations at runtime (e.g. /raw/, /image/, etc.).

Install the Bytescale JavaScript SDK to use the UrlBuilder:

npm install @bytescale/sdk

Raw Files

Use the UrlBuilder to get raw file URLs (i.e. URLs to original files):

// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/raw/example.jpg"
Bytescale.UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.jpg"
});

You can upload any file type to Bytescale. Use /raw/ when downloading files that don't need to be transformed.

Transformation Presets

Use the UrlBuilder to transform files using transformation presets:

// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/thumbnail/example.jpg"
Bytescale.UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.jpg",
options: {
transformation: "preset",
transformationPreset: "thumbnail"
}
});

Transformation presets are created in the Bytescale Dashboard.

Images

Use the UrlBuilder to transform images using the Image Processing API:

// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/image/example.jpg?w=800&h=600"
Bytescale.UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.jpg",
options: {
transformation: "image",
transformationParams: {
"w": 800,
"h": 600
}
}
});

See the Image Processing API for the full list of transformationParams when transformation: "image".

Videos

Use the UrlBuilder to transform videos using the Video Processing API:

// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/video/example.mov?f=mp4-h264&h=1080"
Bytescale.UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.mov",
options: {
transformation: "video",
transformationParams: {
"f": "mp4-h264",
"h": 1080
}
}
});

See the Video Processing API for the full list of transformationParams when transformation: "video".

Audio

Use the UrlBuilder to transform audio using the Audio Processing API:

// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/audio/example.wav?f=aac&br=192"
Bytescale.UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.wav",
options: {
transformation: "audio",
transformationParams: {
"f": "aac",
"br": 192
}
}
});

See the Audio Processing API for the full list of transformationParams when transformation: "audio".

Archives

Use the UrlBuilder to extract the file document.docx from the uploaded ZIP file example.zip:

// import * as Bytescale from "@bytescale/sdk";
// Returns: "https://upcdn.io/1234abc/archive/example.zip?m=extract&artifact=/document.docx"
Bytescale.UrlBuilder.url({
accountId: "1234abc",
filePath: "/example.zip",
options: {
transformation: "archive",
transformationParams: {
m: "extract"
},
artifact: "/document.docx"
}
});

See the Archive Processing API for the full list of transformationParams when transformation: "archive".

Authorization

The Bytescale Upload Widget supports two types of authorization:

API keys

With API key auth, the requester has access to the resources available to the API key:

  • Secret API keys (secret_***) have access to all API endpoints (see the Bytescale JavaScript SDK).

  • Public API keys (public_***) have access to file upload, file download, and file listing API endpoints. File overwrites, file deletes, and all other destructive operations cannot be performed using public API keys. File listing is also disabled by default (but can be changed by editing the API key's settings).

You must always use public API keys (e.g. public_***) in your client-side code.

Each API key can have its read/write access limited to a subset of files/folders via the API key's settings.

API keys are required. You must always pass an apiKey field via the configuration object.

JWT cookies

With JWT cookies, the user can download private files directly via the URL, as authorization is performed implicitly via a session cookie. This allows the browser to display private files in <img> and <video> elements.

When using JWT cookies to download files, the ?auth=true query parameter must be added to the URL.

With JWT cookies, the user can also upload files to locations that aren't otherwise permitted by the API key, but are permitted by the JWT's payload. This is because the Bytescale Upload Widget internally uses the Bytescale JavaScript SDK to perform file uploads, and the Bytescale JavaScript SDK automatically injects the user's JWT into all API requests once the AuthManager.beginAuthSession method has been called.

Learn more about JWT cookies and the AuthManager »

JWT cookies are optional.

Was this section helpful? Yes No

You are using an outdated browser.

This website requires a modern web browser -- the latest versions of these browsers are supported: