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

curl

curl -i -X GET http://localhost:8080/Plone/my-page -H "Accept: application/json"

python-requests

requests.get('http://localhost:8080/Plone/my-page', headers={'Accept': 'application/json'})

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:8080/plone/my-page",
    "@type": "ContentPage",
    "title": "My Page",
    "hero_image": {
        "@id": "http://localhost:8080/plone/media/hero.jpg",
        "@type": "Image",
        "UID": "a1b2c3d4e5f6a1b2c3d4e5f6",
        "title": "Hero Image",
        "image": {
            "content-type": "image/jpeg",
            "download": "http://localhost:8080/plone/media/hero.jpg/@@download/image/hero.jpg",
            "filename": "hero.jpg",
            "height": 800,
            "width": 1200,
            "size": 245760,
            "scales": {
                "mini": {
                    "download": "http://localhost:8080/plone/media/hero.jpg/@@images/image/mini",
                    "height": 133,
                    "width": 200
                },
                "preview": {
                    "download": "http://localhost:8080/plone/media/hero.jpg/@@images/image/preview",
                    "height": 267,
                    "width": 400
                },
                "large": {
                    "download": "http://localhost:8080/plone/media/hero.jpg/@@images/image/large",
                    "height": 533,
                    "width": 800
                }
            }
        }
    }
}

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

curl

curl -i -X GET http://localhost:8080/Plone/my-gallery -H "Accept: application/json"

python-requests

requests.get('http://localhost:8080/Plone/my-gallery', headers={'Accept': 'application/json'})

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@id": "http://localhost:8080/plone/my-gallery",
    "@type": "ContentPage",
    "title": "My Gallery",
    "gallery_images": [
        {
            "@id": "http://localhost:8080/plone/media/photo1.jpg",
            "@type": "Image",
            "UID": "a1b2c3d4e5f6a1b2c3d4e5f6",
            "title": "Photo 1",
            "image": {
                "content-type": "image/jpeg",
                "download": "http://localhost:8080/plone/media/photo1.jpg/@@download/image/photo1.jpg",
                "filename": "photo1.jpg",
                "height": 600,
                "width": 800,
                "size": 125000,
                "scales": {
                    "mini": {"download": "...", "height": 150, "width": 200},
                    "preview": {"download": "...", "height": 300, "width": 400}
                }
            }
        },
        {
            "@id": "http://localhost:8080/plone/media/photo2.jpg",
            "@type": "Image",
            "UID": "b2c3d4e5f6a1b2c3d4e5f6a1",
            "title": "Photo 2",
            "image": {
                "content-type": "image/jpeg",
                "download": "http://localhost:8080/plone/media/photo2.jpg/@@download/image/photo2.jpg",
                "filename": "photo2.jpg",
                "height": 600,
                "width": 800,
                "size": 130000,
                "scales": {
                    "mini": {"download": "...", "height": 150, "width": 200},
                    "preview": {"download": "...", "height": 300, "width": 400}
                }
            }
        }
    ]
}

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:

{
    "hero_image": "a1b2c3d4e5f6a1b2c3d4e5f6"
}

Multiple references:

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

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

<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