Image Dialog

The image dialog allows users to select and edit images directly within the Uhuu Editor.

Parameters

The editDialog method is configured with the following options for image actions:

type: Set to 'image', indicating that the field being edited is an image.
path: Specifies the data path to the image, here 'url' within the payload.
ratio: Defines the crop aspect ratio (4/3 in this case) for the image within the editor.
subPath (optional): A sub-path relative to path, for more targeted editing within the data structure.
imagePath (optional): Acts as an alias for subPath specifically for images, eliminating the need for an extra type definition when editing images.
images (optional): Inline image gallery list for this dialog. Accepts string[] (URLs) or object[]. If provided, it takes precedence over imageGalleryPath.
imageGalleryPath (optional): Payload path for the gallery array used by the picker when images is not provided.
galleryUpload (optional): Set to true to let users upload images into the imageGalleryPath gallery.
options (for selectimage): Inline image-backed value options. Accepts [{ value, label, url, previewUrl? }].

For a fixed print frame, calculate ratio from the authored box (width / height) and pass it explicitly. This locks Pintura’s crop to the area where the result will render; it does not resize the rendered <img>. The template should still render the image in an overflow: hidden frame using object-fit: cover.

If a template offers native editing and stock search for the same field, pass the same ratio to both configurations. AI Marketing Studio currently has no ratio input; after using an AI result in a fixed frame, reopen the native image editor to make the final crop. Do not add an undocumented ratio property and assume it is honored.

Example Setup

Configure and open an image dialog with a sample JSON payload:

json

{ 
    "title": "Photos by Sven",
    "message": "Amazing shots",
    "url": "https://images.unsplash.com/photo-1531062537542-0308d14d35c3?w=1200"
}

In your template, you can set up an editable image field as follows:

export default ({payload}) => {
  return (    
    <div onClick={() => $uhuu.editDialog({
          path: "url", 
          type: "image", 
          ratio: 4 / 3
        })}>
        <img src={payload.url} alt="Image" />
    </div>
  );
}

Example Gallery

To handle multiple images within a template, Uhuu can be configured to display an image gallery. In this example, the payload includes an images array:

json

{ 
    "title": "Photos by Sven",
    "message": "Amazing shots",
    "url": "https://images.unsplash.com/photo-1531062537542-0308d14d35c3?w=1200",
    "images": [
        "https://images.unsplash.com/photo-1530878902700-5ad4f9e4c318?w=1200",
        "https://images.unsplash.com/photo-1531062470344-16b9d0460ffc?w=1200",
        "https://images.unsplash.com/photo-1622036255449-ba090f54c6bd?w=1200"
    ]
}

To enable the image gallery, set the imageGalleryPath option to specify where the gallery images are located within the payload:

$uhuu.templateSetup({
    options: {
        imageGalleryPath: 'images'
    }
});

Inline Gallery (Preferred for Complex Templates)

You can also pass a custom list of images directly to editDialog. When images is provided, it overrides imageGalleryPath.

String URLs

$uhuu.editDialog({
  path: 'cover_image',
  type: 'image',
  images: [
    'https://images.unsplash.com/photo-1530878902700-5ad4f9e4c318?w=1200',
    'https://images.unsplash.com/photo-1531062470344-16b9d0460ffc?w=1200',
    'https://images.unsplash.com/photo-1622036255449-ba090f54c6bd?w=1200'
  ],
  ratio: 4 / 3
});

Object Gallery with `imagePath`

For an object-backed field, imagePath names the field that holds the URL (url below): the editor reads the current image from it and writes URL-only selections to it. What a selection writes depends on the entry:

An object entry from images or the imageGalleryPath gallery replaces the whole value at path.
A string entry, or an image uploaded to the document's conversation draft, writes only its URL to path + . + imagePath (here cover_image.url). The rest of the value stays as it is.

Without imagePath, conversation uploads are listed only when the editor can tell where their URL goes. It reads that from the gallery's own entries (all strings, or objects that share one URL field) or, for an empty gallery, from the field's current value: an empty or string value is replaced by the URL; an object gets it in its one URL field, or in contentUrl when it has none or holds a map, satellite or cadastral result. Otherwise no uploads are listed.

$uhuu.editDialog({
  path: 'cover_image',
  imagePath: 'url',
  type: 'image',
  images: [
    {
      title: 'Pink Owl Sample',
      filename: 'pink-owl-1.jpeg',
      mimetype: 'image/jpeg',
      url: 'https://platform.uhuu.io/common/samples/pink-owls/pink-owl-1.jpeg'
    }
  ],
  ratio: 4 / 3
});

Opt-In Gallery Uploads

Image gallery uploads are opt-in. Add galleryUpload: true to an image dialog that already points to a writable gallery array with imageGalleryPath.

When enabled, the gallery picker shows an upload action. Users can upload one or more files, see the new items appear in the gallery, and select any gallery item for the current image field.

$uhuu.editDialog({
  path: 'cover_image',
  type: 'image',
  imageGalleryPath: 'listing.media.images',
  imagePath: 'url',
  galleryUpload: true
});

Upload Payload Behavior

When the upload succeeds, the editor:

uploads the selected file or files through the signed image upload service;
appends new items to the resolved gallery array, unless an item with the same normalized image URL already exists;
keeps the gallery picker open so the uploaded images can be selected;
allows only images uploaded through the editor for the current template to be removed.

The appended item follows the existing gallery shape:

string[] galleries append the uploaded URL string.
Object galleries append an object using the configured imagePath.
Schema-style image galleries can append { '@type': 'ImageObject', contentUrl, position }.
Propertybase-style galleries append { url, filename, title, mimetype }.

If images is provided inline, those images are still used for browsing. Uploads still require a writable payload path through imageGalleryPath; inline images alone is not enough because there is no payload array to append to.

Source images from a CRM or integration can still appear in the gallery and remain selectable, but they are not removable from the picker.

Template Examples

Propertybase-style image objects:

$uhuu.editDialog({
  path: 'page.heroImage',
  type: 'image',
  imageGalleryPath: 'listing.media.images',
  imagePath: 'url',
  galleryUpload: true
});

schema.org ImageObject entries:

$uhuu.editDialog({
  path: 'page.heroImage',
  type: 'image',
  imageGalleryPath: 'listing.images',
  imagePath: 'contentUrl',
  galleryUpload: true
});

Example Usage

Below are examples of configuring $uhuu.editDialog for editing an image field:

// Edit an image with a specified ratio, using `subPath`
$uhuu.editDialog({
  path: 'cover_image',
  subPath: 'url',
  type: 'image',
  ratio: 16 / 9
});

// Using `imagePath` as a direct alias for `subPath` for image editing
$uhuu.editDialog({
  path: 'cover_image',
  imagePath: 'url',
  ratio: 16 / 9
});

`selectimage`: Image Gallery UI That Saves a Value

Use type: 'selectimage' when you want the same gallery-style picker as the image dialog, but the selected result should be a scalar value such as a key or enum instead of an image object or URL.

Each option should provide:

value: The value written back to the payload.
label: The card label shown in the picker.
url: Preview image URL.
previewUrl (optional): Alternate preview URL. If omitted, url is used.

Example

$uhuu.editDialog({
  path: 'selectedThemeImage',
  type: 'selectimage',
  options: [
    {
      value: 'pink-owl-1',
      label: 'Pink Owl 1',
      url: 'https://platform.uhuu.io/common/samples/pink-owls/pink-owl-1.jpeg'
    },
    {
      value: 'pink-owl-2',
      label: 'Pink Owl 2',
      url: 'https://platform.uhuu.io/common/samples/pink-owls/pink-owl-2.jpeg'
    }
  ]
});

Selecting a card closes the picker immediately and saves the selected value to path.

Image Dialog ​

Parameters ​

Example Setup ​

Example Gallery ​

Inline Gallery (Preferred for Complex Templates) ​

String URLs ​

Object Gallery with imagePath ​

Opt-In Gallery Uploads ​

Upload Payload Behavior ​

Template Examples ​

Example Usage ​

selectimage: Image Gallery UI That Saves a Value ​

Example ​