Documentation

Upload images

Set up upload #

By default, the image upload is disabled in the editor. To enable it, specify the path to the server-side upload script using the image.upload setting, like this:

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/'
    }
});

When uploading an image, the editor sends a POST request to the specified path to an uploader on the server. Files are sent as an array of files. For example, in PHP, this is the array $ _FILES ['file'].

The server-side script should generate a JSON as the response, like this for sing upload:

{
    "file": {
        "url": "image-url.jpg",
        "id": "some-id"
    }
}

And like this for multiple upload:

{
    "file-1": {
        "url": "image-url-1.jpg",
        "id": "some-id"
    },
    "file-2": {
        "url": "image-url-2.jpg",
        "id": "some-id"
    }
}

The fail response must return JSON with error key like this:

{
    "error": true,
    "message": "Something went wrong..."
}

Custom upload function #

The second way to upload images is a custom function. In this case, you need to specify your own function, create the response object in it and call complete. Here is the example of the editor settings with a custom function:

ArticleEditor('#entry', {
    image: {
        upload: function(upload, data) {

            // loop files
            for (var key in data.files) {
                if (typeof data.files[key] === 'object') {
                    console.log(data.files[key])
                }
            }

            // create response
            var response = {
                "file": {
                    "url": "image-url.jpg",
                    "id": "some-id"
                }
            };

            // call complete
            upload.complete(response, data.e);
        }
    }
});

Here is a response object for inserting multiple images:

var response = {
    "file-1": {
        "url": "image-url-1.jpg",
        "id": "some-id"
    },
    "file-2": {
        "url": "image-url-2.jpg",
        "id": "some-id"
    }
};

Upload name parameter #

The default key of the file array is file. This can be changed using the image.name setting:

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/',
        name: 'image'
    }
});

In this example, imageUpload variable name will be image and it can be retrieved like this (in PHP):

$_FILES['image']

Send additional data #

You can send additional parameters with the same POST request.

To do this, use the image.data setting, in which specify object as data to send.

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/',
        data: {
            id: 10,
            elements: '#my-input-1, #my-input-2, #my-form'
        }
    }
});

The example above shows how to send POST params with autosaving. The data object has key=value params, including values in the input and form fields if the additional object has key elements with field and form selectors.

The values of the input and form fields are appended as values: field-name: value.

Add image by url #

By default, Article is enabled to insert images by url in the image add popup.

This can be turned off, like this:

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/',
        url: false
    }
});

Select uploaded images #

The Article Editor has the ability to specify already uploaded images that can be selected in the image add popup.

To do this, use the image.select setting. In this setting, set the path to the JSON file.

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/',
        select: '/images/images.json'
    }
});

JSON of images should be like this:

[
    {
        "thumb": "/images/image-thumbnail-1.jpg",
        "url": "/images/image-1.jpg",
        "id": "1",
        "title": "My Image 1"
    },
    {
        "thumb": "/images/image-thumbnail-2.jpg",
        "url": "/images/image-2.jpg",
        "id": "2",
        "title": "My Image 2"
    }
]

The title parameter is optional.

Drag and drop images #

If the editor has the path to the image uploader on the server, then the ability to drag and drop images directly into the content is automatically enabled.

This can be disabled using the image.drop setting:

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/',
        drop: false
    }
});

Multiple upload #

If the editor has the path to the image uploader on the server, then the ability to upload several images is automatically enabled.

This can be disabled using the image.multiple setting:

ArticleEditor('#entry', {
    image: {
        upload: '/image-uploader/',
        multiple: false
    }
});

Get deleted images #

To check what images deleted from content, you can use the image.remove event. It happens every time when an image is deleted in the editor.

ArticleEditor('#entry', {
    subscribe: {
        'image.remove': function(event) {
            var url = event.get('url');
            var id = event.get('id');
        }
    }
});

The image.remove event sends an object as argument with information about the deleted image:

  • url — address of image.
  • id — value of the image data-image attribute.

Unfortunately, this event does not allow checking image recovery, if the Undo command was triggered in the editor.

Therefore, it is safer to use the second option for tracking deleted images. To do this, you can use the API method editor.images.get.

var app = ArticleEditor('#entry');
var changes = app.editor.images.get();
for (var key in changes) {
    if (changes[key].status === false) {
        // element was deleted
    }
    else {
        // element is still in the content
    }
}

How deleted image tracking works:

  1. On the editor start and when images uploaded, all images get the data-image attribute with the generated ID, if the attribute was not specified.
  2. When you request the editor.images.get method, the editor will check the object of all uploaded images or those that were at the start of the editor and compare which ones have been deleted.

Here's an example of an object that is returned by editor.images.get:

{
    status: true,
    url: "image-url.jpg",
    node: img,
    id: "1"
}