Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/editor-js/attaches
File attachments Block for the Editor.js
https://github.com/editor-js/attaches
Last synced: 3 months ago
JSON representation
File attachments Block for the Editor.js
- Host: GitHub
- URL: https://github.com/editor-js/attaches
- Owner: editor-js
- License: mit
- Created: 2019-04-26T11:19:15.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-03-25T15:19:09.000Z (8 months ago)
- Last Synced: 2024-07-18T17:45:34.087Z (4 months ago)
- Language: JavaScript
- Homepage:
- Size: 792 KB
- Stars: 60
- Watchers: 3
- Forks: 66
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-editorjs - @editorjs/attaches
README
# Attaches Tool
Tool for the [Editor.js](https://editorjs.io).
This tool allows you to attach files to your articles.
## Installation
You can get the package using any of these ways.
### Via NPM / Yarn
```shell
npm install @editorjs/attaches
```
### Load from CDN
You can load specific version of package from [jsDelivr CDN](https://www.jsdelivr.com/package/npm/@editorjs/attaches).
`https://cdn.jsdelivr.net/npm/@editorjs/attaches@latest`
Then require this script on page with Editor.js through the `` tag.
## Usage
Add a new Tool to the `tools` property of the Editor.js initial config.
```javascript
import AttachesTool from '@editorjs/attaches';
var editor = EditorJS({
...
tools: {
...
attaches: {
class: AttachesTool,
config: {
endpoint: 'http://localhost:8008/uploadFile'
}
}
}
...
});
```
## Config Params
Attaches Tool supports these configuration parameters:
| Field | Type | Description |
| ----- | -------- | ------------------ |
| endpoint | `string` | Optional endpoint for file uploading or use uploader |
| uploader | `{uploadByFile: function}` |Optional custom uploading method or use endpoint|
| field | `string` | (default: `file`) Name of uploaded file field in POST request |
| types | `string` | (default: `*`) Mime-types of files that can be [accepted with file selection](https://github.com/codex-team/ajax#accept-string).|
| buttonText | `string` | (default: `Select file`) Placeholder for file upload button |
| errorMessage | `string` | (default: `File upload failed`) Message to show if file upload failed |
| additionalRequestHeaders | `object` | (default: `{}`) Object with any custom headers which will be added to request. Example: `{"X-CSRF-TOKEN": "W5fe2...hR8d1"}` |
## Output data
This Tool returns `data` with following format
| Field | Type | Description |
| -------------- | --------- | ------------------------------- |
| file | `object` | Uploaded file data. Data received from backend uploader. See description below. |
| title | `string` | File's title. Initially set as uploaded file name. Can be modified by user. |
Object `file` consists of the following fields. All of them are optional, `size` and `extension` are supported by design.
| Field | Type | Description |
| -------------- | --------- | ----------------------------------|
| url |`string` | Full public path of uploaded file |
| size |`number` | File's size (expected in bytes, according to Tool's design) |
| name |`string` | File's name |
| extension |`string` | File's extension |
```json
{
"type" : "attaches",
"data" : {
"file": {
"url" : "https://www.tesla.com/tesla_theme/assets/img/_vehicle_redesign/roadster_and_semi/roadster/hero.jpg",
"size": 91,
"name": "hero.jpg",
"extension": "jpg"
},
"title": "Hero"
}
}
```
## Backend response format
Response of your uploader **should** cover following format:
```json5
{
"success" : 1,
"file": {
// any data you want
// for example: url, name, size, title
}
}
```
**success** - uploading status. 1 for successful, 0 for failed
**file** - uploaded file data. Can contain any data you want to store. All fields will be stored as [file object](#file-object) in output data.
Fields supported by the UI of block:
- `title`
- `size`
- `extension` (if not present, will be extracted from the `name`)
- `url`
## Providing custom uploading methods
As mentioned at the Config Params section, you have an ability to provide own custom uploading method.
It is a quite simple: implement `uploadByFile` method and pass them via `uploader` config param.
The method return a Promise that resolves with response in a format that described at the [backend response format](#backend-response-format) section.
| Method | Arguments | Return value | Description |
| -------------- | --------- | -------------| ------------|
| uploadByFile | `File` | `{Promise.<{success, file: {url}}>}` | Upload file to the server and return an uploaded file data |
Example:
```js
import AttachesTool from '@editorjs/attaches';
var editor = EditorJS({
...
tools: {
...
attaches: {
class: AttachesTool,
config: {
/**
* Custom uploader
*/
uploader: {
/**
* Upload file to the server and return an uploaded image data
* @param {File} file - file selected from the device or pasted by drag-n-drop
* @return {Promise.<{success, file: {url}}>}
*/
uploadByFile(file){
// your own uploading logic here
return MyAjax.upload(file).then((response) => {
return {
success: 1,
file: {
url: response.fileurl,
// any data you want
// for example: name, size, title
}
};
});
},
}
}
}
}
...
});
```