Message-ID: <530799282.3794.1485855396527.JavaMail.confluence@ip-10-127-227-164> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_3793_1056816040.1485855396526" ------=_Part_3793_1056816040.1485855396526 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Image Field Type

Image Field Type

=20
=20
=20
=20

Field Type identifier: ezimage
Validators: File size
= Value object: \eZ\Publish\Core\FieldType\Image\Value
= Associated Services: ezpublish.fieldType.ezimage.variation_serv= ice

The Image Field Type allows you to store an image file.

A variation service handles conversion of the orig= inal image into different formats and sizes through a set of preconfigured = named variations: large, small, medium, black & white thumbnail, etc.

PHP API Field Type

Value object

The value property of an Image Field will return an \eZ\Publish\Core\FieldType\Image\Value object with the foll= owing properties:

Properties
Property Type Example Description
id string 0/8/4/1/1480-1-eng-GB/= image.png

The image's unique identifier. = Usually the path, or a part of the path. To get the full path, use UR= I property.
alternativeText string This is a piece of tex= t The alternative text, as entered i= n the Field's properties
fileName string image.png The original image's filename, wit= hout the path
fileSize int 37931 The original image's size, in byte= s
uri string var/ezdemo_site/storag= e/images/0/8/4/1/1480-1-eng-GB/image.png The original image's URI
imageId string 240-1480 A special image ID, used by REST

Image Variations

Using the variation Service, variations of the original image can be obt= ained. Those are \eZ\Publish\S= PI\Variation\Values\ImageVariation objects with the following properties:

Property Type Example Description
width int 640 The variation's width in pixels
height int 480 The variation's height in pixels
name string medium The variation's identifier
info mixed   Extra info, such as EXIF data
fileSize int    
mimeType string    
fileName string    
dirPath string    
uri string   The variation's uri
lastModified DateTime   When the variation was last modifi= ed

Field Defintion options

The Image Field Type supports one FieldDefinition option: the maximum si= ze for the file.

Using an Image Field

Template Rendering

When displayed using ez_render_field, an Image Field w= ill output this type of HTML:

=20 
<img src=3D"var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/=
image_medium.png" width=3D"844" height=3D"430" alt=3D"Alternative text" /&g=
t;
=20

The template called by the ez_render_field() Twig function while rendering a Image field accepts th= e following the parameters:

Parameter Type Default Description
alias string "original" The image variation name, must be defined in you= r site access image_variations settings. Defaults to "original= ", the originally uploaded image.
width int   Optionally to specify a different width set on t= he image html tag then then one from image alias.
height int   Optionally to specify a diff= erent height set on the image html tag then then one from image alias.
class string   Optionally to specify a spec= ific html class for use in custom javascript and/or css.

 

Example: 

=20 
{{ ez_render_field( content, 'image', { 'parameters':{ 'alias': 'im=
agelarge', 'width': 400, 'height': 400 } } ) }}
=20

The raw Field can also be used if needed. Image variations for the Field= 's content can be obtained using the ez_image_alias Twig = helper:

=20 
{% set imageAlias =3D ez_image_alias( field, versionInfo, 'medium' =
) %}
=20

The variation's properties can b= e used to generate the required output:

=20 
<img src=3D"{{ asset( imageAlias.uri ) }}" width=3D"{{ imageAlia=
s.width }}" height=3D"{{ imageAlias.height }}" alt=3D"{{ field.value.altern=
ativeText }}" />
=20

 

With the REST API

Image Fields within REST are exposed by the application/vnd.ez.api= .Content media-type. An Image Field will look like this:

inputUri

From 5.2 version, new images must be input using the inputUri property from Image\Value.

The keys id and path still work, but a= deprecation warning will be thrown.

Version >=3D 5.2
=20 
<field>
    <id>1480</id>
    <fieldDefinitionIdentifier>image</fieldDefinitionIdentifier>=
;
    <languageCode>eng-GB</languageCode>
    <fieldValue>
        <value key=3D"inputUri">/var/ezdemo_site/storage/images/0/8/4=
/1/1480-1-eng-GB/kidding.png</value>
        <value key=3D"alternativeText"></value>
        <value key=3D"fileName">kidding.png</value>
        <value key=3D"fileSize">37931</value>
        <value key=3D"imageId">240-1480</value>
        <value key=3D"uri">/var/ezdemo_site/storage/images/0/8/4/1/14=
80-1-eng-GB/kidding.png</value>
        <value key=3D"variations">
            <value key=3D"articleimage">
                <value key=3D"href">/api/ezp/v2/content/binary/images=
/240-1480/variations/articleimage</value>
            </value>
            <value key=3D"articlethumbnail">
                <value key=3D"href">/api/ezp/v2/content/binary/images=
/240-1480/variations/articlethumbnail</value>
            </value>
        </value>
    </fieldValue>
</field>
=20
=20
=20 Before 5.2=20  Expand source= =20
=20
=20 
<field>
    <id>1480</id>
    <fieldDefinitionIdentifier>image</fieldDefinitionIdentifier>=
;
    <languageCode>eng-GB</languageCode>
    <fieldValue>
        <value key=3D"id">var/ezdemo_site/storage/images/0/8/4/1/1480=
-1-eng-GB/kidding.png</value>
        <value key=3D"path">/var/ezdemo_site/storage/images/0/8/4/1/1=
480-1-eng-GB/kidding.png</value>
        <value key=3D"alternativeText"></value>
        <value key=3D"fileName">kidding.png</value>
        <value key=3D"fileSize">37931</value>
        <value key=3D"imageId">240-1480</value>
        <value key=3D"uri">/var/ezdemo_site/storage/images/0/8/4/1/14=
80-1-eng-GB/kidding.png</value>
        <value key=3D"variations">
            <value key=3D"articleimage">
                <value key=3D"href">/api/ezp/v2/content/binary/images=
/240-1480/variations/articleimage</value>
            </value>
            <value key=3D"articlethumbnail">
                <value key=3D"href">/api/ezp/v2/content/binary/images=
/240-1480/variations/articlethumbnail</value>
            </value>
        </value>
    </fieldValue>
</field>
=20
=20

 

Children of the fieldValue node will list the general properties of the = Field's original image (fileSize, fileName, inputUri, etc.), as well as var= iations. For each variation, a uri is provided. Requested through REST, thi= s resource will generate the variation if it doesn't exist yet, and list th= e variation details:

=20 
<ContentImageVariation media-type=3D"application/vnd.ez.api.Conte=
ntImageVariation+xml" href=3D"/api/ezp/v2/content/binary/images/240-1480/va=
riations/tiny">
  <uri>/var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/kidding_=
tiny.png</uri>
  <contentType>image/png</contentType>
  <width>30</width>
  <height>30</height>
  <fileSize>1361</fileSize>
</ContentImageVariation>
=20

From PHP code

Getting an image variatio= n

The variation service, ezpublish.fieldType.ezimage.variation_servi= ce, can be used to generate/get variations for a Field. It expects a= VersionInfo, the Image Field and the variation name, as a string (la= rge, medium, etc.)

=20 
$variation =3D $imageVariationHandler->getVariation(
    $imageField, $versionInfo, 'large'
);

echo $variation->uri;
=20

Manipulating image conte= nt

From PHP

As for any Field Type, there are several ways to input content to a Fiel= d. For an Image, the quickest is to call setField() on th= e ContentStruct:

=20 
$createStruct =3D $contentService->newContentCreateStruct(
    $contentTypeService->loadContentType( 'image' ),
    'eng-GB'
);

$createStruct->setField( 'image', '/tmp/image.png' );
=20

In order to customize the Image's alternative texts, you must first get = an Image\Value object, and set this property. For that, you can use the Image\Value::fromString() method that accepts the path to a local= file:

=20 
$createStruct =3D $contentService->newContentCreateStruct(
    $contentTypeService->loadContentType( 'image' ),
    'eng-GB'
);

$imageField =3D \eZ\Publish\Core\FieldType\Image\Value::fromString( '/tmp/i=
mage.png' );
$imageField->alternativeText =3D 'My alternative text';
$createStruct->setField( 'image', $imageField );
=20

You can also provide a hash of Image\Value properties, eith= er to setField(), or to the constructor:

=20 
$imageValue =3D new \eZ\Publish\Core\FieldType\Image\Value(
    array(
        'id' =3D> '/tmp/image.png',
        'fileSize' =3D> 37931,
        'fileName' =3D> 'image.png',
        'alternativeText' =3D> 'My alternative text'
    )
);

$createStruct->setField( 'image', $imageValue );
=20

From REST

The REST API expects Field values to be provided in a hash-like structur= e. Those keys are identical to those expected by the Image\Value constructor: fileName, alternativeText. I= n addition, image data can be provided using the data property= , with the image's content encoded as base64.

Creating an image Field

=20 
<?xml version=3D"1.0" encoding=3D"UTF-8"?>
<ContentCreate>
    <!-- [...metadata...] -->

    <fields>
        <field>
            <id>247</id>
            <fieldDefinitionIdentifier>image</fieldDefinitionIdent=
ifier>
            <languageCode>eng-GB</languageCode>
            <fieldValue>
                <value key=3D"fileName">rest-rocks.jpg</value>
                <value key=3D"alternativeText">HTTP</value>
                <value key=3D"data"><![CDATA[/9j/4AAQSkZJRgABAQEAZ=
ABkAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcG
BwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/2[...]</value>
            </fieldValue>
        </field>
    </fields>
</ContentCreate>
=20

Updating an image Field

Updating an Image Field requires that you re-send existing data. This ca= n be done by re-using the Field obtained via REST, removing th= e variations key, and updating alternativeText, fileName or data. If you do not want to change th= e image itself, do not provide the data key.

=20 
<?xml version=3D"1.0" encoding=3D"UTF-8"?>
<VersionUpdate>
    <fields>
        <field>
            <id>247</id>
            <fieldDefinitionIdentifier>image</fieldDefinitionIdent=
ifier>
            <languageCode>eng-GB</languageCode>
            <fieldValue>
                <value key=3D"id">media/images/507-1-eng-GB/Existing-=
image.png</value>
                <value key=3D"alternativeText">Updated alternative te=
xt</value>
                <value key=3D"fileName">Updated-filename.png</valu=
e>
=09=09=09</fieldValue>
        </field>
    </fields>
</VersionUpdate>
=20

Naming

Each storage engine determines how image files are named.

Legacy Storage Engine n= aming

Images are stored within the following directory structure:

<varDir>/<StorageDir>/<ImagesStorageDir>/<Fie= IdId[-1]>/<FieIdId[-2]>/<FieIdId[-3]>/<FieIdId[-4]>/&l= t;FieldId>-<VersionNumber>-<LanguageCode>/

With the following values:

  • VarDir =3D var (default)
  • StorageDir =3D storage (default)
  • ImagesStorageDir =3D images (default)
  • FieldId =3D 1480
  • VersionNumber =3D 1
  • LanguageCode =3D eng-GB

Images will be stored to web/var/ezdemo_site/storage/im= ages/0/8/4/1/1480-1-eng-GB.

Using the field ID digits in reverse order as the folder st= ructure maximizes sharding of files through multiple folders on the filesys= tem.

Within this folder, images will be named like the uploaded file, suffixe= d with an underscore and the variation name:

  • MyImage.png
  • MyImage_large.png
  • MyImage_rss.png

 

 

=20
=20
=20
=20

 

=20
=20
=20
------=_Part_3793_1056816040.1485855396526--