Summary

Creates and returns an image object.

Usage

image( value [,...] )

Parameters

Name	Type	Description	Required
value	mixed	Please refer to the description below.	Yes.

Returns

An ezimage object.

Description

This operator makes it possible to merge/flatten several images into one image. It returns the final image as an "ezimage" object. Please note that this operator only works if "ImageGD" is installed and enabled. It takes several parameters where each parameter can be a different type. The following types can be used:

• String
• Image layer (an "ezimagelayer" object).
• Array

String

If a parameter is a string, the contents of the string will be used as the alternative image text for the image object that is returned by the operator.

Image layer

If a parameter is an image layer (an "ezimagelayer" object), it will be merged with the other layers and thus become a part of the final result. An image layer may be generated by making use of the "imagefile" or the "texttoimage" operator.

Array

If a parameter is an array, the operator will assume that the first element (element number zero) is an image layer and that the second element is an associative array containing parameters that the system will use when the image layer is processed. The following table shows the parameters that can be used.

Name / key	Description
transparency	The image transparency as float value ranging from 0.0 (0% transparency) to 1.0 (100% transparency).
halign	Horizontal alignment as a string: "left", "right or "center".
valign	Vertical alignment as a string: "top", "bottom" or "center".
x	Absolute horizontal placement as an integer (works with "left" and "right" horizontal alignment.)
y	Absolute vertical placement as an integer (works with "top" and "bottom" vertical alignment.)
xrel	Relative horizontal placement as a float value ranging from 0.0 to 1.0 (works with "left" and "right" horizontal alignment.)
xrel	Relative vertical placement as a float value ranging from 0.0 to 1.0 (works with "top" and "bottom" vertical alignment.)

Please note that the "x" and "xrel" parameters can not be used at the same time. The same goes for the "y" and the "yrel" parameters. When "right" or "bottom" alignment is used, the coordinate system will shift to accommodate the alignment. This is useful for doing alignment and placement since the placement is relative to the current coordinate system. Right alignment will start the axis at the right (0) and go on to the left (width). Bottom alignment will start the axis at the bottom (0) and go on to the top (height).

Template

If the operator is called directly, eZ Publish will display the resulting image using the "layer/imageobject.tpl" template located in the "templates" directory of the current design or one of the fallback designs. It is possible to override this template using the template override system.

Examples

Example 1

{image( imagefile( 'design/example/images/test1.png' ),
        imagefile( 'design/example/images/test2.png' ),
        'My alternative image text...' )}

The "imagefile" operator loads the images from the filesystem and returns them as "ezimagelayer" objects. The "image" operator takes care of merging the images (layers) together into one single image. When the "image" operator is used directly (as in the example above), eZ Publish will insert the "imageobject.tpl" template (or an override) which in turn takes care of displaying the image. The last parameter is a string, which will be used as the alternative image text for the final image.

Example 2

{image( "It's A Kind Of Magic"|texttoimage( 'arial' ) )}

This example will render the string "It's A Kind Of Magic" using a truetype font specified within the "arial" style. The image layer produced by the "texttoimage" operator is wrapped inside an image object and displayed using the "imageobject.tpl" template (or an override).

Example 3

{image( "It's A Kind Of Magic",
        imagefile( 'design/example/images/test1.png' ),
        array( "It's A Kind Of Magic"|texttoimage( 'smartie' ),
               hash( 'transparency', 0.64,
                     'halign',       'right',
                     'valign',       'top' ) ) )}

This example will generate an image with 64% transparent text using the "smartie" style. The text will be aligned to the upper right corner of the "example1.png" image. The alternative image text will be "It's A Kind Of Magic" - which is the same as the merged in transparent text.

---