# ImageReferenceField

Custom field types for referencing Image content objects. Unlike standard relation fields, these serialize to full image data including dimensions and scales.

## Field Types

**ImageReferenceField**
Single image reference. Serializes to a full Image object with metadata and scales.

**ImageReferenceList**
Multiple image references. Serializes to a list of Image objects.


## REST API Serialization

### Single Image Reference (GET)

When serialized via plone.restapi, an ImageReferenceField returns the complete Image object representation instead of relation data.

```http
GET /Plone/my-page HTTP/1.1
Host: localhost:8080
Accept: application/json
```

Response:

```{literalinclude} ./http-examples/imagereference-single.resp
:language: http
```

The serialized image includes:

- `@id`: Absolute URL of the image
- `@type`: Content type (`Image`)
- `UID`: Unique identifier
- `title`: Image title
- `image`: Image data object containing:
    - `content-type`: MIME type
    - `download`: Download URL
    - `filename`: Original filename
    - `width`, `height`: Original dimensions
    - `size`: File size in bytes
    - `scales`: Available image scales with dimensions and URLs


### Multiple Image References (GET)

ImageReferenceList returns an array of Image objects.

```http
GET /Plone/my-gallery HTTP/1.1
Host: localhost:8080
Accept: application/json
```

Response:

```{literalinclude} ./http-examples/imagereference-list.resp
:language: http
```

Empty fields return `null` for single references or `[]` for lists.


## REST API Deserialization

### Creating/Updating Content (POST/PATCH)

Image references accept the same formats as standard relation fields:

**Single reference:**

```json
{
    "hero_image": "a1b2c3d4e5f6a1b2c3d4e5f6"
}
```

**Multiple references:**

```json
{
    "gallery_images": [
        "a1b2c3d4e5f6a1b2c3d4e5f6",
        "b2c3d4e5f6a1b2c3d4e5f6a1"
    ]
}
```

Supported input formats:

- **UID string**: `"a1b2c3d4e5f6a1b2c3d4e5f6"`
- **Path string**: `"/plone/media/hero.jpg"`
- **URL string**: `"http://localhost:8080/plone/media/hero.jpg"`
- **Object with @id**: `{"@id": "http://localhost:8080/plone/media/hero.jpg"}`


## Visibility Filtering

The serializer automatically filters images based on:

- **View permission**: Images without view permission return `null` (single) or are omitted (list)
- **Effective/expiration dates**: Inactive images (future effective date or past expiration) are filtered for anonymous users; managers see all images


## Schema Definition

### Basic Usage

```xml
<field name="hero_image"
       type="wcs.backend.content.fields.imagereferencefield.ImageReferenceField">
  <title>Hero Image</title>
  <required>False</required>
</field>

<field name="gallery_images"
       type="wcs.backend.content.fields.imagereferencefield.ImageReferenceList">
  <title>Gallery Images</title>
  <required>False</required>
</field>
```


### With Widget Configuration

Configure the reference browser widget to restrict selection to Image content types:

```xml
<field name="hero_image"
       type="wcs.backend.content.fields.imagereferencefield.ImageReferenceField">
  <title>Hero Image</title>
  <required>False</required>
  <form:widget type="ftw.referencewidget.widget.ReferenceBrowserWidget">
    <selectable>
      <element>Image</element>
    </selectable>
    <override>True</override>
  </form:widget>
</field>

<field name="gallery_images"
       type="wcs.backend.content.fields.imagereferencefield.ImageReferenceList">
  <title>Gallery Images</title>
  <required>False</required>
  <form:widget type="ftw.referencewidget.widget.ReferenceBrowserWidget">
    <selectable>
      <element>Image</element>
    </selectable>
    <override>True</override>
  </form:widget>
</field>
```

Widget options:

- `selectable`: List of portal types the user can select
- `override`: Set to `True` to use custom selectable types instead of defaults