Summary

Usage

image( value [,...] )

Parameters

Name	Type	Description	Required
value	mixed	See description below.	Yes.
...

Returns

Image object.

Description

This operator creates and returns an image object. The operator basically flattens/merges the image layers that were provided using the parameters. However, a parameter can be something else than an image layer. A parameter to this operator can be one of three things:

• A string
• An image layer
• An array

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.

If a parameter is an image layer then the layer will simply be merged into the image object that is to be returned by the operator.

If a parameter is an array, the operator will assume that the first array element (element zero) is the image itself (an image layer created by either the imagefile or the texttoimage operator), and that the second element is a hash (associative array) containing parameters for that layer. The following parameters can be used:

• transparency: float value ranging from 0 to 1.0 (0 = 0% and 1 = 100%)
• halign: horizontal alignment, use left, right or center
• valign: vertical alignment, use top, bottom or center
• x: absolute placement (works with left and right align)
• y: absolute placement (works with top and bottom align)
• xrel: relative placement, float value ranging from 0 to 1.0.
  (works with left and right align)
• xrel: relative placement, float value ranging from 0 to 1.0.
  (works with top and bottom align)

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).

If the operator is called directly, the "/design/standard/templates/image/imageobject.tpl" template will be used to display the image object that is returned by the operator. It is possible to override this template using the template override system.

This operator does not make use of an input parameter.

Examples

Example 1
The following code merges two images into one:

{image( imagefile( 'image1.png'|ezimage ),

       imagefile( 'image2.png'|ezimage ) )}

What happens here is that we pipe image1.png and image2.png into the ezimage operator. This is simply done in order to prepend a valid path to the filenames. The imagefile operator is used to load the images (now with the correct path) from the filesystem. This operator returns an image layer. Finally, the image operator is used to merge these images (layers) together into one single image. The image operator will return an image object. In this case, the template system will insert the "/design/standard/templates/image/imageobject.tpl" template in order to display the image (another template will be used if there exists an override for the default template).

Example 2

{image( 'Exponential'|texttoimage( 'arial' ) )}

This will simply render the string "Exponential" using a truetype font specified within the arial style. The image layer produced by the texttoimage operator is then wrapped inside an image object.

Example 3

{image( "church",

       imagefile( 'var/cache/texttoimage/church.jpg' ),

                  array( 'Exponential'|texttoimage,

                         hash( transparency, 0.8,

                               halign,      right,

                               valign,      top ) ) )}

The template code above will create an image object with 80% transparent text aligned in the top right corner of the church image that is fetched from the var directory. The alternative image text is set to "church".