|
| 1 | +--- |
| 2 | +category: features-image-upload |
| 3 | +menu-title: Simple upload adapter |
| 4 | +order: 50 |
| 5 | +--- |
| 6 | + |
| 7 | +# Simple upload adapter |
| 8 | + |
| 9 | +The {@link module:upload/adapters/simpleuploadadapter~SimpleUploadAdapter Simple upload adapter} allows uploading images to your server using the [`XMLHttpRequest`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) API with a minimal [editor configuration](#configuration). |
| 10 | + |
| 11 | +See the ["Server–side configuration"](#server-side-configuration) section to learn about the requirements your server–side application must meet to support this upload adapter. |
| 12 | + |
| 13 | +<info-box> |
| 14 | + Check out the comprehensive {@link features/image-upload Image upload overview} to learn about other ways to upload images into CKEditor 5. |
| 15 | +</info-box> |
| 16 | + |
| 17 | +## Installation |
| 18 | + |
| 19 | +First, install the [`@ckeditor/ckeditor5-upload`](https://www.npmjs.com/package/@ckeditor/ckeditor5-upload) package: |
| 20 | + |
| 21 | + ```bash |
| 22 | +npm install --save @ckeditor/ckeditor5-upload |
| 23 | +``` |
| 24 | + |
| 25 | +<info-box info> |
| 26 | + The [`@ckeditor/ckeditor5-upload`](https://www.npmjs.com/package/@ckeditor/ckeditor5-upload) package is available by default in all {@link builds/guides/overview#available-builds official editor builds}. You do not have to install it, if you are {@link builds/guides/integration/advanced-setup#scenario-1-integrating-existing-builds extending one}. |
| 27 | +</info-box> |
| 28 | + |
| 29 | +Add the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadAdapter SimpleUploadAdapter} to your plugin list and [configure](#configuration) the feature. For instance: |
| 30 | + |
| 31 | + ```js |
| 32 | +import SimpleUploadAdapter from '@ckeditor/ckeditor5-upload/src/adapters/simpleuploadadapter'; |
| 33 | + |
| 34 | +ClassicEditor |
| 35 | + .create( document.querySelector( '#editor' ), { |
| 36 | + plugins: [ SimpleUploadAdapter, ... ], |
| 37 | + toolbar: [ ... ], |
| 38 | + simpleUpload: { |
| 39 | + // Feature configuration. |
| 40 | + } |
| 41 | + } ) |
| 42 | + .then( ... ) |
| 43 | + .catch( ... ); |
| 44 | +``` |
| 45 | + |
| 46 | +<info-box info> |
| 47 | + Read more about {@link builds/guides/integration/installing-plugins installing plugins}. |
| 48 | +</info-box> |
| 49 | + |
| 50 | +## Configuration |
| 51 | + |
| 52 | +The client–side of this feature is configurable using the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig `config.simpleUpload`} object. |
| 53 | + |
| 54 | + ```js |
| 55 | +import SimpleUploadAdapter from '@ckeditor/ckeditor5-upload/src/simpleuploadadapter'; |
| 56 | + |
| 57 | +ClassicEditor |
| 58 | + .create( document.querySelector( '#editor' ), { |
| 59 | + plugins: [ SimpleUploadAdapter, ... ], |
| 60 | + toolbar: [ ... ], |
| 61 | + simpleUpload: { |
| 62 | + // The URL the images are uploaded to. |
| 63 | + uploadUrl: 'http://example.com', |
| 64 | + |
| 65 | + // Headers sent along with the XMLHttpRequest to the upload server. |
| 66 | + headers: { |
| 67 | + 'X-CSRF-TOKEN': 'CSFR-Token', |
| 68 | + Authorization: 'Bearer <JSON Web Token>' |
| 69 | + } |
| 70 | + } |
| 71 | + } ) |
| 72 | + .then( ... ) |
| 73 | + .catch( ... ); |
| 74 | +``` |
| 75 | + |
| 76 | +## Server-side configuration |
| 77 | + |
| 78 | +To use this upload adapter, you must provide a server–side application that will handle the uploads and communicate with the editor, as described in the following sections. |
| 79 | + |
| 80 | +### Communication protocol |
| 81 | + |
| 82 | +When the image upload process is initiated, the adapter sends a [`POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST) request under {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig#uploadUrl `config.simpleUpload.uploadUrl`}. |
| 83 | + |
| 84 | +You can sent additional [headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) along with the `XMLHttpRequest` to the upload server, e.g. to authenticate the user, using the {@link module:upload/adapters/simpleuploadadapter~SimpleUploadConfig#uploadUrl `config.simpleUpload.headers`} object. |
| 85 | + |
| 86 | +The [`responseType`](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/responseType) of the request is always `json`. See the ["Successful upload"](#successful-upload) and ["Error handling"](#error-handling) sections to learn more. |
| 87 | + |
| 88 | +### Successful upload |
| 89 | + |
| 90 | +If the upload is successful, the server should return an object containing the `url` property which points out to the uploaded image on the server: |
| 91 | + |
| 92 | +```json |
| 93 | +{ |
| 94 | + "url": "https://example.com/images/foo.jpg" |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +That image URL is essential because it will be used: |
| 99 | + |
| 100 | +* to display the image during the editing (as seen by the user in the editor), |
| 101 | +* in the editor content {@link builds/guides/integration/saving-data saved to the databse}. |
| 102 | + |
| 103 | +### Error handling |
| 104 | + |
| 105 | +If something went wrong, the server must return an object that containing the `error` property. This will terminate the upload in the editor, e.g. allowing the user to select another image if the previous one was too big or did not meet some other validation criteria. |
| 106 | + |
| 107 | +If the `error` object contains a `message`, it will be passed to the {@link module:ui/notification/notification~Notification#showWarning editor notification system} and displayed to the user. For the convenience of the users, use clear and possibly specific error messages. |
| 108 | + |
| 109 | +```json |
| 110 | +{ |
| 111 | + "error": { |
| 112 | + "message": "The image upload failed because the image was too big (max 1.5MB)." |
| 113 | + } |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +If the `message` property is missing in the `error` object, the {@link module:ui/notification/notification~Notification#showWarning editor notification system} will display the default "Couldn't upload file: `[filename]`." message. |
| 118 | + |
| 119 | +### Upload progress |
| 120 | + |
| 121 | +This upload adapter will notify users about the [file upload progress](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/progress_event) out–of–the–box. |
| 122 | + |
| 123 | +## What's next? |
| 124 | + |
| 125 | +Check out the comprehensive {@link features/image-upload Image upload overview} to learn more about different ways of uploading images in CKEditor 5. |
| 126 | + |
| 127 | +See the {@link features/image Image feature} guide to find out more about handling images in CKEditor 5. |
| 128 | + |
| 129 | +## Contribute |
| 130 | + |
| 131 | +The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5-upload. |
0 commit comments