Image Concepts

Image Manager

By default the Froala Rich Text Editor's image manager displays images stored on our servers and it just simulates the delete behavior. In order to display the images from your own server you have to use a server-side language. This article is meant to help you understand how the editor's image manager works.

Flow

1. Include the image manager plugin file.

   The image manager is a plugin for the WYSIWYG HTML editor and the image_manager.min.js file must be included before being able to use it.

   
   

2. Set the editor's image manager options.

   When using the image manager, you can customize up to 9 options and 5 events:
   • imageManagerPreloader is the path to a gif file to be displayed while loading the images from the server in the image manager. If this option is not used then a loading text will appear.
   • imageManagerPageSize is the number of images loaded per page in the image manager.
   • imageManagerScrollOffset is the distance in pixels from the bottom of the scrollable content at which to trigger the loading of the next page of images.
   • imageManagerLoadURL is the URL where the request to load the images is made.
   • imageManagerLoadMethod is the HTTP image manager load images request type.
   • imageManagerLoadParams are additional parameters that are passed in the load images request to the server.
   • imageManager.error event is triggered if any errors occur while loading the images list from the server in the image manager.
   • imageManager.imageLoaded event is triggered after an image was loaded in image manager.
   • imageManager.imagesLoaded event is triggered after the request to load images in the image manager has been completed successfully.
   • imageManagerDeleteURL is the URL where the request to delete an image is made.
   • imageManagerDeleteMethod is the HTTP image manager delete image request type.
   • imageManagerDeleteParams are additional params that are passed in the delete request to the server.
   • imageManager.beforeDeleteImage event is triggered before deleting an image from the image manager.
   • imageManager.imageDeleted event is triggered after the image was deleted from image manager.
   

   
   

3. AJAX request from editor to the imageManagerLoadURL link.

   When the image manager button is clicked, a HTTP request is automatically made to the server in order to retrieve the list with images to be displayed.

   
   

4. The server processes the HTTP request to load images.

   The server has to process the GET request (or the one specified by imageManagerLoadMethod) and return an array of links for the images. The returned array needs to look like:

   Copy

   [
     {
       "url": "http://exmaple.com/images/photo1.jpg",
       "thumb": "http://exmaple.com/thumbs/photo1.jpg",
       "tag": "flower"
     },
     {
       "url": "http://exmaple.com/images/photo2.jpg",
       "thumb": "http://exmaple.com/thumbs/photo2.jpg",
       "tag": "sport"
     }
   ]

   Where url is required, thumb is recommended and tag is optional. The image Object may also contain additional data that will be added as image attributes data-*. E.g.: Copy

   [
     {
       "url": "http://exmaple.com/images/photo1.jpg",
       "thumb": "http://exmaple.com/thumbs/photo1.jpg",
       "tag": "flower",
       "name": "Photo 1 Name",
       "id": "103454285"
     }
   ]

   <img src='https://exmaple.com/images/photo1.jpg' data-name='Photo 1 Name' data-id='103454285'>

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

   
   

5. The editor loads the images in the image manager.

   When the request finishes successfully the imageManager.imagesLoaded event is triggered and the rich text editor will load the images in the image manager. After an image is loaded in the image manager the imageManager.imageLoaded event is triggered. If the returned array does not follow the right structure or the images cannot be loaded, imageManager.error event is triggered.

   
   

6. AJAX request from editor to the imageManagerDeleteURL link.

   When the delete button on an image in the image manager is clicked, a HTTP request is automatically made to the server with a src parameter containing the image file name.

   
   

7. The server processes the HTTP request to delete the image.

   The server has to process the request and physically delete the image. An example for this action can be found in the Froala Editor SDKS.

Note: Returning a JSON with an error field will throw an error with the custom message contained. E.g. { "error": "My custom error message." }

The following snippet highlights how to initialize the Froala WYSIWYG HTML Editor in order to use the image manager.

Copy

// Include the image manager plugin.
<script src="../../js/plugins/image_manager.min.js"></script>

<script>
  new FroalaEditor('.selector', {
    // Set a preloader.
    imageManagerPreloader: "/images/loader.gif",

    // Set page size.
    imageManagerPageSize: 20,

    // Set a scroll offset (value in pixels).
    imageManagerScrollOffset: 10,

    // Set the load images request URL.
    imageManagerLoadURL: "http://example.com/load_images",

    // Set the load images request type.
    imageManagerLoadMethod: "GET",

    // Additional load params.
    imageManagerLoadParams: {user_id: 4219762},

    // Set the delete image request URL.
    imageManagerDeleteURL: "http://example.com/delete_image",

    // Set the delete image request type.
    imageManagerDeleteMethod: "DELETE",

    // Additional delete params.
    imageManagerDeleteParams: {param: 'value'},

    events: {
      'imageManager.error': function (error, response) {
        // Bad link. One of the returned image links cannot be loaded.
        if (error.code == 10) { ... }

        // Error during request.
        else if (error.code == 11) { ... }

        // Missing imagesLoadURL option.
        else if (error.code == 12) { ... }

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

        ....
      },
      'imageManager.imagesLoaded': function (data) {
        // Do something when the request finishes with success.
        alert ('Images have been loaded.');
      },
      'imageManager.imageLoaded': function ($img) {
        // Do something when an image is loaded in the image manager
        alert ('Image has been loaded.');
      },
      'imageManager.beforeDeleteImage': function ($img) {
        // Do something before deleting an image from the image manager.
        alert ('Image will be deleted.');
      },
      'imageManager.imageDeleted': function (data) {
        // Do something after the image was deleted from the image manager.
        alert ('Image has been deleted.');
      }
    }
  })
</script>