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', {
    css: '/your-article-dist-path/',
    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..."
}

Src sets upload

The editor can upload an image and automatically set the srcset attribute to display the image for high dpi screens.

To do this you need to generate a JSON response in an upload script on the server side by adding 2x param for the image:

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

And like this for multiple upload:

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

In the end. The user uploads the image to the editor, you catch it on the server side, process the image, for example, making a version of the standard size and 2x for screens with high dpi. After that you form a JSON response.

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', {
    css: '/your-article-dist-path/',
    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', {
    css: '/your-article-dist-path/',
    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', {
    css: '/your-article-dist-path/',
    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', {
    css: '/your-article-dist-path/',
    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', {
    css: '/your-article-dist-path/',
    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",
        "alt": "My Image 1"
    },
    {
        "thumb": "/images/image-thumbnail-2.jpg",
        "url": "/images/image-2.jpg",
        "id": "2",
        "alt": "My Image 2",
        "caption": "My Caption",
        "link": "https://example.com",
        "width": "600",
        "height": "400"
    }
]

When id, alt, caption, link, width, and height parameters are 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', {
    css: '/your-article-dist-path/',
    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', {
    css: '/your-article-dist-path/',
    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', {
    css: '/your-article-dist-path/',
    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 image.getStates.

// call editor
var app = ArticleEditor('#entry', {
    css: '/your-article-dist-path/'
});

// api
var changes = app.image.getStates();
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 image.getStates 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 image.getStates:

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