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:example:: curl python-requests

    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:example:: curl python-requests

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

.. code-block:: json

    {
        "hero_image": "a1b2c3d4e5f6a1b2c3d4e5f6"
    }

**Multiple references:**

.. code-block:: 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
^^^^^^^^^^^

.. code-block:: 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:

.. code-block:: 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