Media Editor (ALPHA)

Cloudinary's Media Editor is an interactive user interface providing a set of common image editing actions to your users on your website or application. The Media Editor requires only pure JavaScript to integrate, is easy to use within any web development framework, and eliminates the need to develop an in-house interactive media editor with just a few lines of code. The editor helps to scale internal operations by reducing dependency on designers for simple recurring tasks. Combined with AI for automating simple actions, this allows manual review / fixing of media assets when needed.

Quick example

To use Cloudinary's Media Editor widget in your site, include a remote JavaScript file, call the mediaEditor method to initialize the widget, and then specify the following (minimum) information when calling the update method:

• Your Cloudinary account cloud name.
• The public_id of the image to edit.

The show method is called to display the initialized widget:

<script src="https://media-editor.cloudinary.com/all.js" type="text/javascript"></script>

<script>
const myEditor = cloudinary.mediaEditor();
myEditor.update({
  publicIds: ["sample"],
  cloudName: "demo", 
});
myEditor.show();
myEditor.on("export",function(data){
  console.log(data);
})
</script>

Workflow

To add Cloudinary's Media Editor widget to your site:

1. Include the JavaScript file: https://media-editor.cloudinary.com/all.js.
2. Initialize the Media Editor widget with the cloudinary.mediaEditor() method.
3. Update the Media Editor configuration with the update(options) method.
4. Show the Media Editor widget with the show() method.

1. Include the JavaScript file

All the Media Editor functionality is included in the https://media-editor.cloudinary.com/all.js JavaScript file. The file is optimized and delivered via a fast CDN.

For example:

<script src="https://media-editor.cloudinary.com/all.js" type="text/javascript">  
</script>

2. Initialize the Media Editor widget

The JavaScript method for initializing the widget is publicly available after including the Media Editor's JavaScript file, which instantiates the cloudinary object and grants access to the cloudinary.mediaEditor(options) method. This method creates a Media Editor instance in memory.

For example:

const myEditor = cloudinary.mediaEditor();

If you want the widget to open within an existing containing element on the page, you can pass the mediaEditor method a selector or DOM element as an appendTo parameter, for example:

const myEditor = cloudinary.mediaEditor({appendTo: document.getElementById("my-widget-container");});

3. Update the Media Editor widget

The update(options) method configures the Media Editor, where options is an object containing the Media Editor parameters to apply.

The options must include at least the following 2 required parameters:

• Your Cloudinary account cloudName parameter.
• The publicIds parameter with the PublicID of the image to edit.

For a complete list of parameters available for configuring the Media Editor widget, see the Parameter tables.

For example, to update an instantiated widget with the "sample" image:

myEditor.update({ 
  cloudName: "demo",    
  publicIds: ["sample"],
});

4. Show the Media Editor widget

The mediaEditor method creates and initializes the widget but does not display it until the show() method of the returned instance is called.

For example:

myEditor.show();

Instance methods

The following methods can be used with the Media Editor instance returned by the mediaEditor initialization method:

• Show
• Hide
• Update
• Destroy
• On
• getConfig
• OnSign

Show

Renders an initialized Media Editor widget object, or a previously hidden widget.

For example:

myEditor.show();

Hide

Hides a previously rendered widget without removing it from memory.

For example:

myEditor.hide();

Update

The update method accepts a map of configuration parameters to update an already initialized widget.

For example:

myEditor.update({
  publicIds: ["running_shoes"]
});

Destroy

Use the destroy method to erase the Media Editor widget and remove it from memory.

For example:

myEditor.destroy();

On

Use the on method to register to a specific event. For a full listing of available events, see the Events section.

For example:

myGallery.on("formatclick", (data) => {
  console.log("FormatClick: ", data.label);
});

Sample response:

{ 
  "event": "flipvertically", 
  "action": "preview", 
  "label": "flip vertically", 
  "params": {} 
}

getConfig

Returns the current configuration options of the Media Editor widget.

For example:

var currentConfig = myEditor.getConfig();

onSign

Use the onSign method to resolve the delivery signature needed for a restricted asset (see Authenticated access to media assets). You should provide the code in the form of a Promise that will request the delivery URL from your back-end server, and then set the url parameter with the full delivery URL of the image (including a signature component or token query string if required).

For example:

myEditor.onSign(async function(data) {
  const { publicId, resourceType, type, transformation } = data;
  const url = generateUrl(publicId, resourceType, type, transformation)
  return url
});

Widget steps

Use the widgetSteps parameter to define which steps are included in the widget.

Possible values:

• resizeAndCrop
• imageOverlay
• export

For example:

const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["sample"],
  widgetSteps: [     
    "resizeAndCrop",
    "export"
  ]
});

Resize and crop

The resize and crop step of the widget enables your users to select a predefined option for resizing the image, to manually crop the image using the crop handles, and to flip or rotate the image.

Use the resizeAndCrop parameter to populate the Media Editor with an ordered array of presets that the user can choose from, in order to resize and crop the image. Each preset in the array can either be a predefined named shortcut, or can be defined with a label, width, height and/or aspectRatio. The guidelinesUrl parameter allows you to add an informative image (with cropping instructions for example) to the right-hand side of the display.

See the ResizeProps options for more details on the available options.

For example, to add the Twitter Ad and LinkedIn Ad predefined shortcuts, as well as a custom preset with the label "Cover Ad" and dimensions of 500 x 1000:

const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["sample"],
  widgetSteps: ["resizeAndCrop"],
  resizeAndCrop: {
    presets: ["facebookAd", "twitterAd", 
      {label: "Cover Ad", width: 500, height: 1000 }], 
    guidelinesUrl: "https://my.example.com/cropping_help.jpg"
  }
});

Image overlays

The image overlays step of the widget enables your users to choose an image overlay to add to the base image. Each of the overlay options is defined by a set of properties, including the size and allowed placements on the base image for the user to select.

• Use the imageOverlay parameter to populate the Media Editor with an ordered array of overlays that the user can choose from.
• Each overlay in the array is defined with a publicId, label, any transformation to apply, and an array of allowed placementOptions, where each placementOption is defined by a bounding box (width and height), a location on the base image (gravity) and any offset from the selected location (x and y).
• The guidelinesUrl parameter allows you to add an informative image (with overlay instructions for example) to the right-hand side of the display.

See the ImageOverlayProps options for more details on the available options.

For example, to add 2 options for overlays as follows: The 'logo' image with a blackwhite effect applied and 2 placement options, and the 'logo_text' image with a negative effect applied and a single placement option:

const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  widgetSteps: ["imageOverlay"],
  imageOverlay: {
    overlays: [
       {
        "publicId": "logo",
        "label": "Logo",
        "transformation": [{ "effect": "blackwhite" }],
        "placementOptions": [{
            "x": 10,
            "y": 10,
            "width": 400,
            "height": 400,
            "gravity": "north_west"
          },
          {
            "x": 0,
            "y": 0,
            "width": 400,
            "height": 400,
            "gravity": "north_east"
          }
        ]
      },
      {
        "publicId": "logo_text",
        "label": "Logo with Text",
        "transformation": [{ "effect": "negative" }],
        "placementOptions": [{
            "x": 0,
            "y": 0,
            "width": 400,
            "height": 400,
            "gravity": "north_east"
       }
    ],
    guidelinesUrl: "https://my.example.com/overlay_help.jpg"
  };  
});

Export

The export step of the widget enables your users to select from provided exporting options.

Use the export parameter to populate the Media Editor with an ordered array of formats and quality to select from, and whether the URL and Download options are displayed.

See the ExportProps options for more details on the available options.

For example:

const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  widgetSteps: ["export"],
  export: {
    "formats": [
      "jpg",
      "png",
      "webp"
    ],
    "quality": [
      "auto",
      10,
      55,
      "low"
    ],
    "download": true,
    "share": true
  };  
});

Editor events

You can register to a variety of Media Editor widget events in order to introduce custom behavior in your application, or for analytics tracking once your application is deployed. Use the on method with an initialized widget to register to a specific event. For example, to register the initialized myEditor Media Editor widget to the headerclick event:

myEditor.on("headerclick", (data) => {
  console.log("HeaderClick: ", data);
});

The following information is included when the event is triggered, and is available in the (data) structure:

• action: The action that triggered the event.
• label: A description of the event.
• params: Additional information returned as key/values pairs (see the table below for details).

The following table lists the events that can be registered with the on method of a Media Editor instance.

We also support 2 special events:

• analytics - Registers to all the events, which is useful for analytics purposes. The (data) structure will also include the event that triggered.

• export - The user clicks on the "Export" button. The (data) structure will also include an array of assets with the url, secureUrl and downloadUrl. For example:
  

  Copy to clipboard

  myEditor.on("export", function(data) {
  console.log("URL: ", data.assets[0].url);
  console.log("Secure URL: ", data.assets[0].secureUrl);
  console.log("Download URL: ", data.assets[0].downloadUrl);
  });

Localization

The text labels used in the widget can be fully customized for different languages. The translations for each language are specified using the text parameter, which accepts a JSON structure defining the value to use for each text element in each language. The language parameter sets which of the language options to use from those defined in the text parameter (en by default). To override any of the default values, you only need to include the elements you want to override.

All the default values can be found at: https://media-editor.cloudinary.com/widget/messages.json.

For example, to only customize the header and the crop - presets - square texts:

const myEditor= cloudinary.mediaEditor();
myEditor.update({
  cloudName: "demo", 
  publicIds: ["flower"],
  language: "en",  
  text: {
    "en": {
      "header": "Edit Image",
      "crop": {
        "presets": {
          "square": "Square",
        }
      }
    }
  }
});

Media Editor options

The following tables list the available Media Editor widget options.

Required parameters

The following parameters are required when initializing the Media Editor widget:

Widget parameters

Asset

An object identifying an uploaded asset. This object is only necessary to identify restricted assets (private/authenticated).

ResizeProps

ImageOverlayProps

ExportProps

PredefinedPreset

CustomPreset

For example:

{
  label: "Cover Ad", 
  width: 500, 
  aspectRatio: "16:9" 
}

OverlayProps

PredefinedPlacement

CustomPlacement

For example:

{
  "x": 0.8, 
  "y": 0.8, 
  "width": 300, 
  "height": 300, 
  "gravity": "north_west"
}