## Overview

Displays an image from a file reference attribute and allows easy drag-and-drop upload. The widget provides a complete image management solution for cplace Pages, offering intuitive drag-and-drop functionality for image upload, selection from existing images, and removal. It integrates deeply with cplace's Document management and permission system, storing the image as a Page attribute reference rather than just a child Document.

## Primary Use Cases

1. **Hero Images**: Add prominent images to Pages such as project banners or product photos
2. **Visual Context**: Provide visual representation for abstract content like process diagrams or flowcharts
3. **Document Visualization**: Display document previews or scanned images
4. **Profile Pictures**: Show images associated with person or organization Pages
5. **Asset Management**: Quick access to upload and select from Page-attached images

## User Interaction Patterns

### When No Image Is Set

The widget displays an upload button with file picker and a table of available images (existing Document children of the Page). Users can upload new images via drag-and-drop or file picker, or select from existing images by clicking the "Insert this Image" button.

### When Image Is Set

The image displays with configured scaling. A remove button (red X) appears in the top-right corner. Clicking the image opens it in a lightbox view. Clicking remove clears the attribute reference and returns to the "no image" state.

### Permission Handling

The widget respects cplace permissions:
- If user lacks read permissions on the referenced Document, shows "insufficient rights" message
- If user lacks edit permissions on the attribute, upload/remove buttons are hidden
- If user lacks create document permissions on the Page, upload is disabled

## Design Considerations

### Why Store as Attribute Reference?

Storing the image as an attribute reference (rather than just a child Document) enables:
- **Querying**: Search for Pages by their image attribute
- **Validation**: Enforce that exactly one image is set
- **Workflows**: Trigger automations when the image changes
- **Data Model**: Image becomes part of the Page's structured data

### Scaling Options

Three scaling modes support different layout needs:
- **Horizontal**: Wide images that should fill width (banners, headers)
- **Vertical**: Tall images that should fill height (portraits, posters)
- **Fit**: Ensure entire image is visible without cropping

### Available Images Feature

The widget lists all image Documents on the Page to enable reuse of uploaded images, provide visual selection without browsing the file system, show metadata (name, size, modification date), and reduce duplicate uploads.

## Configuration Requirements

### Attribute Constraints

The reference attribute must meet specific requirements:
- Must be a reference attribute to Document type
- Must have "At most one value" multiplicity (maximalOne)
- Must be editable by the user
- Cannot be used with multi-value attributes

### Entity Type Constraint

This widget is only embeddable in **Page** entities and cannot be used on other entity types.

## Common Pitfalls

- **Using multi-value attributes**: The widget requires "At most one value" multiplicity and will not work with multi-value reference attributes
- **Wrong attribute type**: The attribute must be a reference to Document type, not a string or other type
- **Insufficient permissions**: Users need both edit permissions on the attribute and create document permissions on the Page to upload images
- **Multiple images needed**: This widget manages exactly one image reference - for multiple images, use image gallery widgets or multiple instances of this widget

## Related Widgets

### Widget Family

This is the base widget in a family of three related widgets:

- **cf.cplace.dragAndDropImageView.imageWithTextWidget** (Image with text): Extends the base widget by adding overlay text with configurable positioning and rich formatting (HTML)
- **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget** (Image with text and list): Further extends the image with text widget by adding a search/list component below the image, useful for showing related entities with a visual header

### Alternative Widgets

- **Image gallery widgets**: For displaying multiple images
- **Simple image display widgets**: For read-only image display without upload capability
- **Document list widgets**: For working with images not stored as Page attributes