Image Concepts

Upload Image

For testing purposes, the Froala Rich Text Editor by default stores the images temporarily as a Blob file in the browser memory. While integrating the editor, you should upload them to your own server for privacy reasons, permanent storage and full control over them.

This means that you have to handle the image upload and storage using a server-side language yourself. This article is meant to help you understand how the editor's image upload works.

Upload Flow

1. Include the image plugin file.

   Image is a plugin for the editor and the image.min.js file must be included before being able to use it.

   
   

2. Set the editor's image upload options.

   When uploading images, you can customize up to 6 parameters and 5 events:
   • imageUploadParam is the name of the parameter that contains the image file information in the upload request. The default value is "file" but you can change it to whatever name you want.
   • imageUploadURL is the URL where the upload request is being made.
   • imageUploadParams are additional params that are passed in the upload request to the server.
   • imageUploadMethod is the HTTP request type.
   • imageMaxSize is the maximum image size that can be uploaded.
   • imageAllowedTypes is an array with the image types allowed to be uploaded.
   • image.beforeUpload event is triggered before starting the upload request and it can be used to change the upload params or cancel the action.
   • image.uploaded event is triggered after a successfully image upload request, but before inserting the image in the editor.
   • image.inserted event is triggered after inserting the image into the editor.
   • image.replaced event is triggered after replacing the image into the editor.
   • image.error event is triggered if any errors occur during the upload process.

   
   

3. AJAX request from editor to the imageUploadURL link.

   When an image is inserted into the WYSIWYG HTML editor, a HTTP request is automatically done to the server.

   
   

4. The server processes the HTTP request.

   The server has to process the upload request, save the image and return a JSON containing a link to the uploaded image. The returned JSON needs to look like: { "link": "path/to/image.jpg" }

   If you need help with the server side image upload process please check out the Froala SDKs.

   
   

5. The editor loads the image in browser.

   When the request finishes, the editor will load the image. If the returned hashmap does not follow the right structure or the image cannot be loaded, image.error event is triggered.

The following snippet highlights how to initialize the Froala WYSIWYG HTML editor in order to upload images.

Copy

<script>
  new FroalaEditor('.selector', {
    // Set the image upload parameter.
    imageUploadParam: 'image_param',

    // Set the image upload URL.
    imageUploadURL: '/upload_image',

    // Additional upload params.
    imageUploadParams: {id: 'my_editor'},

    // Set request type.
    imageUploadMethod: 'POST',

    // Set max image size to 5MB.
    imageMaxSize: 5 * 1024 * 1024,

    // Allow to upload PNG and JPG.
    imageAllowedTypes: ['jpeg', 'jpg', 'png'],

    events: {
      'image.beforeUpload': function (images) {
        // Return false if you want to stop the image upload.
      },
      'image.uploaded': function (response) {
        // Image was uploaded to the server.
      },
      'image.inserted': function ($img, response) {
        // Image was inserted in the editor.
      },
      'image.replaced': function ($img, response) {
        // Image was replaced in the editor.
      },
      'image.error': function (error, response) {
        // Bad link.
        if (error.code == 1) { ... }

        // No link in upload response.
        else if (error.code == 2) { ... }

        // Error during image upload.
        else if (error.code == 3) { ... }

        // Parsing response failed.
        else if (error.code == 4) { ... }

        // Image too text-large.
        else if (error.code == 5) { ... }

        // Invalid image type.
        else if (error.code == 6) { ... }

        // Image can be uploaded only to same domain in IE 8 and IE 9.
        else if (error.code == 7) { ... }

        // Response contains the original server response to the request if available.
      }
    }
  })
</script>