## Overview

Displays an image that contains an additional text. The widget extends the basic drag-and-drop image viewer by adding configurable text overlay functionality. It enables users to display images with descriptive or contextual text positioned on top of the image with rich HTML formatting support. The widget combines all the functionality of the base Image widget (upload, selection, removal, scaling, lightbox) with additional text overlay capabilities including flexible positioning and dynamic content from page attributes.

## Use Cases

### Primary Use Cases

1. **Hero Banners with Captions**: Display promotional images with title text or call-to-action overlays
   - Example: Project landing page with "Welcome to Project X" overlaid on banner image

2. **Labeled Visual Content**: Add descriptive text to images for context
   - Example: Process diagram with "Phase 1: Planning" overlaid on diagram section

3. **Call-to-Action Images**: Combine visual appeal with actionable text
   - Example: Feature image with "Learn More" or "Get Started" button text

4. **Annotated Screenshots**: Add explanatory text to screenshots or documentation images
   - Example: UI screenshot with "Click here to start" pointing to a specific area

5. **Status Indicators**: Display dynamic status text over visual representations
   - Example: Project status board with status text overlaid on project image

6. **Marketing/Communication Pages**: Create visually rich communication with minimal effort
   - Example: News article with headline overlaid on featured image

7. **Dashboard Headers**: Combine visual branding with key metrics or titles
   - Example: Department dashboard with department name overlaid on theme image

### When to Use This Widget

Use this widget when:
- You need to display a **single image with text** on a page
- The text should be **positioned on/over the image** (not beside it)
- You want **rich text formatting** (colors, fonts, sizes, links)
- The text content may need to be **dynamic** (from page attributes)
- Users need **easy upload and management** of the image
- You want a **professional, modern appearance** with text overlays

### When NOT to Use This Widget

Avoid this widget when:
- Text should appear **beside or below** the image (consider using layout containers)
- You need to display **multiple images** (consider image gallery widgets)
- The text is very long (overlays work best with short, impactful text)
- You need complex text layouts or multiple text blocks (consider separate text widgets)
- Read-only image display without upload capability (consider simpler image display widgets)

## Design Considerations

### Text Overlay Design Principles

**Visual Cohesion**: Text overlays treat text and image as a single visual unit, providing space efficiency and modern, magazine-style layouts that draw attention to specific parts of the image.

**HTML Support for Rich Formatting**: The widget supports HTML in text overlays, allowing emphasis (bold, italic, underline), brand colors, actionable links, structured information with lists, and font size hierarchy for future-proof formatting needs.

**Positioning Options**: Multiple position choices enable compositional balance, visual hierarchy (center for primary messages, corners for secondary), adaptability to different image "safe zones", and support for various use cases (headers, captions, labels).

### Common Configuration Patterns

1. **Title Overlay Pattern**
   - Position: Bottom-left or Center
   - Style: Large, bold text with semi-transparent dark background
   - Use case: Hero sections, feature highlights

2. **Caption Pattern**
   - Position: Bottom-left or Bottom-right
   - Style: Smaller text, possibly italicized
   - Use case: Photo credits, image descriptions

3. **Call-to-Action Pattern**
   - Position: Center or Bottom-center
   - Style: Button-like appearance with contrasting colors
   - Use case: Interactive elements, navigation prompts

4. **Labeled Diagram Pattern**
   - Position: Top-left or Top-center
   - Style: Simple, clean text, minimal background
   - Use case: Process documentation, phase indicators

5. **Status Dashboard Header Pattern**
   - Position: Top-right or Bottom-right
   - Style: Color-coded text (red/yellow/green), medium size
   - Use case: Dashboards, status boards, monitoring pages

### Best Practices

**Image Selection**:
- Choose images with **clear areas** for text placement
- Avoid overly busy backgrounds where text will appear
- Consider **aspect ratio** when selecting scaling mode
- Use high-quality images that scale well

**Text Content**:
- Keep text **short and impactful** (headlines, not paragraphs)
- Use **clear, readable fonts** at appropriate sizes
- Ensure **high contrast** between text and image background
- Test readability at different screen sizes

**Text Positioning**:
- Position text in **visually quiet areas** of the image
- Follow **compositional rules** (rule of thirds, etc.)
- Consider **reading patterns** (left-to-right, top-to-bottom)
- Avoid covering important image content

**Styling for Readability**:
- Use **semi-transparent backgrounds** behind text when needed
- Apply **text shadows** or outlines for contrast
- Choose **large enough font sizes** for easy reading
- Test on **different devices** and screen sizes

**Dynamic Text Usage**:
- Validate that **attribute values are appropriate length**
- Provide **default/fallback text** if attribute is empty
- Consider **formatting rules** for attribute content
- Document expected attribute content format

## Limitations and Constraints

### Text Overlay Constraints

**Text Length**: Long text may not fit well on images with no automatic text wrapping controls, and readability decreases with longer content.

**HTML Complexity**: Complex HTML structures may not render well in overlay, limited space constrains layout possibilities, and there may be HTML sanitization restrictions for security.

**Positioning Limitations**: Fixed position options (not pixel-perfect placement), may not align perfectly with specific image features, and position behavior may vary with different image sizes.

**Readability Challenges**: Text may be hard to read on busy image backgrounds, requires careful color/contrast choices, and may need semi-transparent backgrounds for legibility.

**Dynamic Text Considerations**: Attribute-based text may change length unexpectedly, no validation that text fits in chosen position, and requires attribute read permissions.

### Inherited Constraints

From the base Image widget:
- Must be a reference attribute to Document type
- Must have "At most one value" multiplicity
- Only embeddable in Page entities
- Single image only
- Relies on platform file upload restrictions

## Related Widgets

### Widget Family

This widget is part of a three-widget family:

1. **cf.cplace.dragAndDropImageView.widget** (Image)
   - Base widget: Image display with upload
   - No text overlay
   - Choose when: You just need image display and upload

2. **cf.cplace.dragAndDropImageView.imageWithTextWidget** (Image with text) - **THIS WIDGET**
   - Extends base widget
   - Adds text overlay with positioning and HTML formatting
   - Single image focus
   - Choose when: You need text overlaid on image

3. **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget** (Image with text and list)
   - Extends image with text widget
   - Adds search/list component below the image
   - Combines image header with related entity list
   - Choose when: You need image + text + related entities list

### Comparison with Alternatives

**vs. Base Image Widget**:
- Choose Image with Text when you need text on the image, not beside it
- Base widget is simpler but lacks text overlay and HTML formatting capabilities

**vs. Separate Image + Text Widgets**:
- Image with Text provides visual cohesion as a single unit and better space efficiency
- Separate widgets offer more flexible placement options but use more vertical space and require two configurations

**vs. Image with Text and List Widget**:
- Image with Text is more focused and uses less vertical space
- Image with Text and List is better when you need to display related entities below the image