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? }].

Example Setup

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

{ 
    "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:

{ 
    "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

When using object entries, imagePath indicates the URL field for preview/editing. Selecting an item stores the entire object at path.

$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.