Easy Image

This article explains how Easy Image works internally and is geared towards more advanced users.

# Image processing

For every uploaded image, Easy Image produces several optimized versions of the same image.

Image sizes are calculated in two ways depending on the width of the original image:

• For large images (wider than 800px) the width is reduced every 10%.
• For small images the width is reduced every 80px until the 100px limit is reached.

The original image gets saved in the cloud, too.

Thanks to offering several versions of the same image, devices with smaller resolutions, such as mobile devices, may request images that fit their display, reducing the bandwidth and improving the loading time of a website.

# Examples

For a 4000px wide image the following versions of it will be created: 400px, 800px, 1200px, 1600px, 2000px, 2400px, 2800px, 3200px, 3600px and 4000px.

For a 500px wide image the following versions will be created: 100px, 180px, 260px, 340px, 420px and 500px.

# Upload response

The Easy Image service responds with a JSON object containing addresses of generated versions of the image. The keys indicate the width of the image, the original image is named default. By default the aspect ratio is preserved.

# Sample response

{
   "390":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_390",
   "780":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_780",
   "1170":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_1170",
   "1560":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_1560",
   "1950":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_1950",
   "2340":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_2340",
   "2730":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_2730",
   "3120":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_3120",
   "3510":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_3510",
   "3840":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg/w_3840",
   "default":"https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/48f57a98cae2304ef7c8cee5f6ad6741dfd4c9f62873f659_image1.jpg"
}

The entire communication is hidden from the developer and requires no effort on their part.

# Generated HTML markup

The markup used for images varies a bit depending on the editor version, however, the <img> element always contains a similar srcset attribute where all the generated versions of the image are listed:

<figure ...>
    <figcaption ...>...</figcaption>
    <img alt="..." src="https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg" width="3840"
    srcset="https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_390 390w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_780 780w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_1170 1170w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_1560 1560w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_1950 1950w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_2340 2340w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_2730 2730w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_3120 3120w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_3510 3510w, https://cdn.cke-cs.com/f0pqzdtf0yRhaX1FymZU/images/259ea629bbdb0366edec1ff8fcb585e120fc984fcfd7b8f8_image1.jpg/w_3840 3840w" sizes="100vw">
</figure>

You can find more information about srcset and responsive images in the Responsive images article on MDN.

# Requesting a different size of the image

The Easy Image service supports requesting any size of an image.

# Parameters

To request an image with a custom size, add parameters to the default URL. Parameters are separated by commas. The names of parameters and values should be separated by an underscore, for example w_300,h_100.

Abbreviated names of parameters must be used, see the table below:

Abbreviated name	Full name
w	width
h	height

When w and h are used together, aspect ratio is ignored and a stretched image will be returned.

# Example

A sample default image URL:
https://cdn.cke-cs.com/aX1FymZU/images/48f57_image1.jpg

The same image resized to 200x100px:
https://cdn.cke-cs.com/aX1FymZU/images/48f57_image1.jpg/w_200,h_100

# Supported file formats

Easy Image supports the following formats:

• png
• jpeg
• bmp (images in bmp will be converted to png)
• tiff
• webp
• gif (animated gifs are also supported)

# Roles for Easy Image

There is no need to specify any roles for Easy Image, because they are assigned to the environment. It means that each user that belongs to the environment is allowed to upload images. After the upload, images are public and can be downloaded without any restrictions.

# Integration with CKEditor 5

# Installation

This package is part of our open-source aggregate package. Just install CKEditor 5 to gain access to it.

npm install ckeditor5

Then add Easy Image to your plugin list and configure the feature. For instance:

import { EasyImage, Image } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ EasyImage, Image, /* ... */ ],
        toolbar: [ 'uploadImage', /* ... */ ],

        // Configure the endpoint. See the "Configuration" section above.
        cloudServices: {
            tokenUrl: 'https://example.com/cs-token-endpoint',
            uploadUrl: 'https://your-organization-id.cke-cs.com/easyimage/upload/'
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

To make enabling image upload in CKEditor 5 a breeze, the EasyImage plugin integrates with the Easy Image service provided by CKEditor Cloud Services. Enabling it is straightforward and the results are immediate. Simply configure CKEditor 5 setting shown above, putting in correct upload URL and Token Endpoint.

# Configuring allowed file types

The allowed file types that can be uploaded should actually be configured in two places:

• On the client side, in CKEditor 5, restricting image upload through the CKEditor 5 UI and commands.
• On the server side, in Easy Image, restricting the file formats that are accepted in Easy Image (as explained above).

# Client-side configuration

Use the image.upload.types configuration option to define the allowed image MIME types that can be uploaded to CKEditor 5.

By default, users are allowed to upload jpeg, png, gif, bmp, webp and tiff files. This corresponds with file formats supported by Easy Image, but you can modify the list to limit the number of allowed image types.