Image Plugin

This plugin is responsible for handling images for an article. This includes drop of images onto the article, either
from disk or from URL.

Breaking change in 3.0.0

From 3.0.0 cropInstructions are no longer used in the image plugin and can be removed. Instead the rendering config needs to be added in Dashboard ICP plugin instead, see Crop instructions below

Plugin configuration

The image plugin configuration must have several things defined to work correctly.

{
    "id": "se.infomaker.ximimage",
    "name": "im-ximimage",
    "url": "https://plugins.writer.infomaker.io/v1/infomaker/im-ximimage/{PLUGIN_VERSION}/index.js",
    "style": "https://plugins.writer.infomaker.io/v1/infomaker/im-ximimage/{PLUGIN_VERSION}/style.css",
    "mandatory": false,
    "enabled": true,
    "data": {
        "imageFileExtension": [".jpg", ".jpeg", ".png", ".gif"],
        "softcrop": true, // Default false
        "defaultCropMethod": "focal-point", // Defaults to soft-crop
        "bylinesearch": false, // Default true
        "byline": false, // Default true
        "imageinfo": false, // Default true
        "hideDisableCropsCheckbox": true, // Default false
        "hideUseFocalPointCheckbox": false, // Default false
        "crops": { ... },
        "fields": [ ... ],
        "propertyMap": { ... }
    }
}

Basic options

Property Type Required Description
softcrop Boolean true The soft crop dialog is hidden by default. Default false.
bylinesearch Boolean true If it should be possible to search for photographers in the backend. Default true
byline Boolean true If it should possible to add and remove authors/photographers. Default true
imageinfo Boolean true Open a dialog with meta data stored on the actual image. Default true
crops Object true Crops ratio named in object. See Crop configuration for configuration
fields Array true Additional fields for information to the image. See Fields configuration for configuration
imageFileExtension Array false Defines the file extensions that should trigger this plugin when a URL is dropped. Default and unset [".jpg", ".jpeg", ".png", ".gif"]
hideDisableCropsCheckbox Boolean false Hide disable crop checkbox. Default false
hideUseFocalPointCheckbox Boolean false Hide focal point checkbox. Default false
defaultCropMethod String false Set what method that should be used in crop tool. Default soft-crop
propertyMap Object false Property mapping. See Property Map configuration for configuration
enableUseOfAnnotationTools Boolean false Enable annotation for all fields. Default false. See Annotation config
enableUseOfAnnotationToolsForFields Array false Enable annotation for specific fields. Matching against fields.name. Default []. See Annotation config

Crop configuration

Required Expressed as an object of named ratios. The value for each named dimension is an array of the width and height ratio.

"crops": {
    "16:9": [16, 9],
    "4:3": [4, 3],
    "square": [1, 1]
}

Crop instructions

DEPRECATED! Since version 3.0.0 the cropInstructions property is not used anymore. Configuration for image rendering URLs are now located in Dashboard ICP configuration:

"internal-editorial": {
    "type": "imengine",
    "endpoint": "https://imengine.editorial.dev.writer.infomaker.io/image.php",
    "functions": {
            "default": {
                    "template": "uuid..."
            },
            ...
            "writer-default": {
                "template": "uuid=[identifier]&function=hardcrop&type=[type:preview]&width=[w:auto]&q=[q:75]"
            },
            "writer-crop": {
                "template": "uuid=[identifier]&function=cropresize&type=preview&q=75&crop_w=[cwrel]&crop_h=[chrel]&width=[w:auto]&height=[h:auto]&x=[cxrel:0]&y=[cyrel:0]&zoom=0"
            }
    }
},

Fields configuration

Required Per default the image plugin only have a byline field in the article. In
addition there are a number of different fields that can be turned on:
caption (expressed as the field text in the NewsML for historic reasons),
alttext, credit and alignment. These fields can either be text or
option fields. Option fields have fixed set of values defined. Below is an
example where all the fields are enabled and configured.

The defaultValue is field is optional, but when it exists it defines which option which should be selected
by default when a new image is added to the article.

"fields": [
    {
        "name": "caption",
        "label": "Caption",
        "type": "text"
    },
    {
        "name": "alttext",
        "label": "Alt text",
        "type": "text"
    },
    {
        "name": "credit",
        "label": "Credit",
        "type": "text"
    },
    {
        "name": "alignment",
        "label": "Alignment",
        "type": "option",
        "options": [
            {
                "name": "auto",
                "label": "Automatic",
                "icon": "paragraph-center-align-bold"
            },
            {
                "name": "left",
                "label": "Left",
                "icon": "paragraph-left-align-bold"
            },
            {
                "name": "right",
                "label": "Right",
                "icon": "paragraph-right-align-bold"
            }
        ],
        "defaultValue": "left"
    }
]

Property Map configuration

Optional When an image is added to the Writer surface, the writer will fetch that image's metadata and fill the image node's
properties automatically.
It is possible to configure which metadata fields from the image's newsitem maps to the ximimage node properties.

Mapping of an Image Node property can be disabled by setting its mapped value to false.

Standard Mapping

If not present, these are the default mappings for an Image Node's properties.

Image Node Property Image Meta Property
authors "authors"
credit "credit"
caption "caption"
alttext false
Allowed Property Values

If an Image Node property is mapped to false it will not receive any value.

If the configuration is invalid, the image will use the standard
mapping.

Image Node Property Allowed Properties
authors "authors", false
credit "caption", "credit", false
caption "caption", "credit", false
alttext "caption", "credit", false
Property Mapping Examples

Map caption to alttext
Disable caption mapping and map caption to image node's alttext.

"propertyMap": {
    "caption": false,
    "alttext": "caption"
}

Disable all metadata mapping
Completely disabled meta-data-mapping to added images.

"propertyMap": {
    "authors": false,
    "credit": false,
    "caption": false,
    "alttext": false
}

Annotation config

Annotations for input fields are disabled by default. Annotations can be enabled for all fields or for specific fields using their "id" value.

This configuration is part of the general options

All fields

{
    "data": {
        "enableUseOfAnnotationTools": true,
        ...
    }
}

Specific fields. Avalible ids is can be found here: Field config

{
    "data": {
        "enableUseOfAnnotationToolsForFields": ["caption", "credit"],
        ...
    }
}

Image plugin contract between plugin and the backend

Routes

Image Plugin routes it's requests via Editor Service (aka Writer Backend). This means that if
a different format than NewsML is used in the repository, the Transformer service needs to be able
to handle the mapping between NewsML (NewsItem of type "picture") and repository native format.

Further more, the Repository Gateway must be able to handle GET, PUT and POST request regarding
image metadata entities.

Output

Whe dropping an image onto the article, the plugin will create a NewsItem to represent the metadata
object for the uploaded image. The plugin also reads the NewsItem for any image existing in the article.

The NewsItem format for the image is described on GitHub.

In the article, a relation to an image is described as an object element as a child of newsItem > contentSet > inlineXML > idf > object
element. The format of the object is:

<object id="MjEyLDE5NCw0NiwxMTA" type="x-im/image" uuid="3314b6ed-ec82-5924-9de1-8b0cb2a39cc2">
    <links>
        <link rel="self" type="x-im/image" uri="im://image/IdJjMZVdi0afHsmQRurNl07J-00.jpeg"
            uuid="3314b6ed-ec82-5924-9de1-8b0cb2a39cc2">
            <data>
                <text>This is an image description that will be stored on the article</text>
                <width>800</width>
                <height>600</height>
                <imageInstructions>this image can only be used in some contexts</imageInstructions>
                <!-- OPTIONAL -->
                <credit>NyhetsbyrÄn</credit>
                <alttext>Image description</alttext>
                <alignment>left</alignment>
            </data>
            <links>

                <link rel="crop" title="16:9" type="x-im/crop" uri="im://crop/0.35/0/0.39/0.32755298651252407"/>
                <link rel="crop" title="8:5" type="x-im/crop" uri="im://crop/0/0.019267822736030827/1/0.9633911368015414"/>
                <link rel="crop" title="4:3" type="x-im/crop" uri="im://crop/0.0675/0/0.865/1"/>
                <link rel="crop" title="1:1" type="x-im/crop" uri="im://crop/0.17625/0/0.64875/1"/>

                <link rel="focal-point" type="x-im/focal-point">
                    <data>
                        <x>123</x>
                        <y>456</y>
                    </data>
                </link>

                <link rel="author" type="x-im/author" title="John Doe" uuid="00000000-0000-0000-0000-000000000000" />
                <link rel="author" type="x-im/author" title="Jane Doe" uuid="7a39b42b-1315-4711-a136-7b3a9f132110">
                    <data>
                        <email>jane.doe@email.com</email>
                    </data>
                </link>
            </links>
        </link>
    </links>
</object>

Sub elements to data can be, depending on how the plugin is configured;