Configure pasting external images into Fonto

This optional feature enables users to copy an image from outside of Fonto (e.g. Word, a browser or image viewing/editing software) and then upload and insert that image into a document by pasting it in Fonto. 

To enable this feature, you need to implement an operation that updates the current document (XML) by inserting whatever XML your schema requires to render an image. Additionally you need to set the name of this operation as the value of the "paste-image-from-clipboard-operation-name" configuration variable (in your config/configuration.js file as usual).

This operation receives a single stepData property called selectedImageId (very similar to the operations of our open-source cms browser addon).

An example of such an operation (for DITA)
{
    "dita-example__paste-image-from-clipboard": {
        "steps": [
            {
                "type": "operation/vertical-insert",
                "data": {
                    "childNodeStructure": [
                        "fig",
                        [
                            "title",
                            [{ "bindTo": "selection", "empty": true }]
                        ],
                        ["desc"],
                        [
                            "image",
                            {
                                "href": "{{selectedImageId}}"
                            }
                        ]
                    ]
                }
            }
        ]
    }
}

Some interesting details:

  1. This operation is NOT responsible for uploading the image as an asset to the CMS, this happens automatically (while the uploading modal is visible) and results in the given selectedImageId which is the asset id of the uploaded image.
  2. This operation calls operation/vertical-insert, which automatically looks at the current cursor position and starts the (vertical) insert from there. Take advantage of this or other similar existing (insert) operations for a consistent UX for your users and ease of implementation. You can for example use vertical-replace to replace the selection when pasting.
  3. This example operation does no create a permanent reference for the uploaded image but your application may require this. Since this is just a regular operation, you're free to configure the operation in any way you see fit.

Then you have to register this operation name like so:

config/configuration.js
import configurationManager from 'fontoxml-configuration/src/configurationManager.js';

configurationManager.set(
    'paste-image-from-clipboard-operation-name',
    'dita-example__paste-image-from-clipboard'
);

Now pasting an image will automatically insert a fig with an image when pasting an image (file).

Caveats and known limitations

The behavior of this feature depends on the Operating System, the source application from which the image is copied and the browser in which Fonto is used. This means that this feature won't work in all scenarios as expected. We recommend thorough testing when enabling this feature and providing documentation of what works to your users. Below you'll find a list of known issues.

  1. The image is uploaded via the POST /asset API without passing a folderId.
  2. Browser other than Safari convert any image to a PNG with ultra high quality automatically. This means that original filename, format, size and metadata (including XMP) is lost in the process. If this is a problem, we recommend to insert a Modal in the operation flow to ask the user for the metadata.
  3. Pasting image files directly from Windows Explorer or the Desktop does not work because no data is present on the clipboard.
  4. Pasting image files directly from Ubuntu Desktop does not work because no data is present on the clipboard.
  5. Pasting multiple image files directly from Mac Finder is not supported. In Firefox this results in a text paste and in other browsers in a warning modal.
  6. Pasting image from web application that do not put image data on the clipboard is currently not supported. This includes Google Docs.
  7. Pasting SVG images from Mac Finder is not supported.