Attention
TYPO3 v6 has reached its end-of-life April 18th, 2017 and is not maintained by the community anymore. Looking for a stable version? Use the version switch on the top left.
There is no further ELTS support. It is strongly recommended updating your project.
IMAGE¶
Returns an image tag with the image file defined in the property "file" and processed according to the properties set.
Defined as PHP function cImage() in typo3/sysext/frontend/Classes/ContentObject/ContentObjectRenderer.php (/typo3/sysext/cms/tslib/class.tslib_content.php).
The array $GLOBALS['TSFE']->lastImageInfo is set with the info-array of the returning image (if any) and contains width, height and so on:
Name of the getText property |
Content |
---|---|
0 |
width |
1 |
height |
2 |
file extension |
3 |
resource |
origFile |
relative URL pointing to the original file |
_mtime |
modification time of the original file |
originalFile |
The FAL object referencing the original file |
processedFile |
The FAL object referencing the processed file |
Note: Gifbuilder also has an IMAGE object - do not mix that one up with the cObject described here; both are different objects.
If you only need the file path to the (possibly resized and also otherwise adjusted) image, the cObject IMG_RESOURCE might be what you are looking for.
Property
border
Data type
integer
Description
Value of the "border" attribute of the image tag.
Default
0
Property
altText
titleText
(alttext)
Data type
string /stdWrap
Description
If no alt text is specified, an empty alt text will be used.
("alttext" is the old spelling of this attribute. It was deprecated since TYPO3 4.3 and was used only if "altText" did not specify a value or properties. In TYPO3 4.6 "alttext" has been removed.)
Property
emptyTitleHandling
Data type
string /stdWrap
Description
Value can be "keepEmpty" to preserve an empty title attribute, or "useAlt" to use the alt attribute instead.
Default
useAlt
Property
longdescURL
Data type
string /stdWrap
Description
"longdesc" attribute (URL pointing to document with extensive details about image).
layoutKey¶
Property
layoutKey
Data type
Description
Defines the render layout for the IMAGE. The render layout is the HTML Code for the IMAGE itself.
Possible "out of the box" values are default
, srcset
, picture
, data
.
Each possibility represents a different solution to render the HTML Code of the IMAGE. The default code
renders the img-tag as plain old html tag with the different attributes.
When implementing a responsive layout you need different image sizes for the different displays and resolutions of your layout. Depending on the HTML framework, the capabilities of desired browsers and the used javascript library for progressive enhancement you can choose either one of the predefined layouts or can define a new layout of your own by adding an additional layout key.
If you don't have a responsive HTML layout you should use the default layout.
default
renders a normal non-responsive image as a<img>
tag:<img src="###SRC###" width="###WIDTH###" height="###HEIGHT###" ###PARAMS### ###ALTPARAMS### ###BORDER### ###SELFCLOSINGTAGSLASH###>
srcset
renders an image tag pointing to a set of images for the different resolutions. They are referenced inside thesrcset
attribute the<img>
tag for each defined resolution. Each image is actually rendered by TYPO3. Srcset is a proposed addition to HTML5 (http://www.w3.org/html/wg/drafts/srcset/w3c-srcset/).<img src="###SRC###" srcset="|*|###SRC### ###SRCSETCANDIDATE###,|*|###SRC### ###SRCSETCANDIDATE###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###>
picture
renders a picture tag containing source tags for each resolutions: and a<img>
tag for the default image. Picture is in the working draft for HTML5 (http://www.w3.org/TR/html-picture-element/).<picture> <source srcset="###SRC###" media="###MEDIAQUERY###"###SELFCLOSINGTAGSLASH###> <img src="###SRC###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###> </picture>
data
renders an image tag containing data-keys for the different resolutions:<img src="###SRC###" data-###DATAKEY###="###SRC###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###>
Default
default
layout¶
layout.layoutKey¶
Property
layout.layoutKey
Data type
array
Description
Definition for the HTML rendering for the named layoutKey. Depending on your needs you can use the existing pre-defined layoutKey or you can define your own element for your responsive layout.
Example:
picture {
element = <picture>###SOURCECOLLECTION###<img src="###SRC###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###></picture>
source = <source src="###SRC###" media="###MEDIAQUERY###" ###SELFCLOSINGTAGSLASH###>
}
layout.layoutKey.element¶
Property
layout.layoutKey.element
Data type
Description
The outer element definition for the HTML rendering of the image. Possible markers are mainly all parameters which can be defined in the IMAGE object, e.g.:
###SRC###
the file URL for the src attribute###WIDTH###
the width of the image for the width tag (only the width value)###HEIGHT###
the height of the image for the height tag (only the width value)###PARAMS###
additional params defined in the IMAGE object (as complete attribute)###ALTPARAMS###
additional alt params defined in the IMAGE object (as complete attribute)###BORDER###
border for the image tag (as complete attribute)###SELFCLOSINGTAGSLASH###
renders the closing slash of the tag, depending on the setting of config.xhtmlDoctype and config.Doctype###SOURCECOLLECTION###
the additional sources of the image depending on the different usage in responsive webdesign. The definition of the sources is declared inside layout.layoutKey.source
layout.layoutKey.source¶
Property
layout.layoutKey.source
Data type
Description
Defines the HTML code for the ###SOURCECOLLECTION###
of the layout.layoutKey.element.
Possible markers in the out of the box configuration are:
###SRC###
the file URL for the src attribute###WIDTH###
the width of the image for the width tag (only the width value)###HEIGHT###
the height of the image for the height tag (only the width value)###SELFCLOSINGTAGSLASH###
renders the closing slash of the tag, depending on the setting of xhtmlDoctype###SRCSETCANDIDATE###
is the value of the srcsetCandidate defined in each SourceCollection.DataKey###MEDIAQUERY###
is the value of the mediaQuery defined in each SourceCollection.DataKey###DATAKEY###
is the name of the dataKey defined in the sourceCollection
You can define additional markers by adding more datakeys to the collection. ###SRCSETCANDIDATE###, ###MEDIAQUERY###, ###DATAKEY### are already defined as additional datakeys in the out of the box typoscript. Thus can be overwritten by your typoscript.
sourceCollection¶
Property
sourceCollection
Data type
array
Description
For responsive images you need different image resolutions for each
output device and output mode (portrait vs. landscape).
sourceCollection
defines the different resolutions for image
rendering, normally you would define al least one
sourceCollection
per layout breakpoint. The amount of
sourceCollections, the name and the specification for the
sourceCollections will be defined by the HTML/CSS/JS code you are
using. The configuration of the sourceCollection defines the size of
the image which is rendered.
Each resolution should be set up as separate array in the
sourceCollection
. Each sourceCollection
consists of
different dataKey properties which you can
define to suit your needs.
Example:
sourceCollection {
small {
width = 200
srcsetCandidate = 600w
mediaQuery = (max-device-width: 600px)
dataKey = small
}
smallRetina {
if.directReturn = 1
width = 200
pixelDensity = 2
srcsetCandidate = 600w 2x
mediaQuery = (max-device-width: 600px) AND (min-resolution: 192dpi)
dataKey = smallRetina
}
}
dataKey¶
Property
sourceCollection.dataKey
Data type
Description
Definition of your image size definition depending on your responsive layout, breakpoints and display density.
dataKey.if¶
Property
sourceCollection.dataKey.if
Data type
Description
Renders only if the condition is met, this is evaluated before any execution of code.
dataKey.pixelDensity¶
Property
sourceCollection.dataKey.pixelDensity
Data type
integer / stdWrap
Description
Defines the density of the rendered Image, e.g. retina display would have a density of 2, the density is a multiplicator for the image dimensions: If the pixelDensity is set to 2 and the width is set to 200 the generated image file will have a width of 400 but will be treated inside the html code as 200 pixel.
Default
1
dataKey.width¶
Property
sourceCollection.dataKey.width
Data type
Description
Defines the width for the html code of the image defined in this source collection. For the image file itself the width will be multiplied by dataKey.pixelDensity.
dataKey.height¶
Property
sourceCollection.dataKey.height
Data type
Description
Defines the height for the html code of the image defined in this source collection. For the image file itself the height will be multiplied by dataKey.pixelDensity.
dataKey.maxW¶
Property
sourceCollection.dataKey.maxW
Data type
Description
Defines the maxW for the html code of the image defined in this source collection. For the image file itself the maxW will be multiplied by dataKey.pixelDensity.
dataKey.maxH¶
Property
sourceCollection.dataKey.maxH
Data type
Description
Defines the maxH for the html code of the image defined in this source collection. For the image file itself the maxH will be multiplied by dataKey.pixelDensity.
dataKey.minW¶
Property
sourceCollection.dataKey.minW
Data type
Description
Defines the minW for the html code of the image defined in this source collection. For the image file itself the minW will be multiplied by dataKey.pixelDensity.
dataKey.minH¶
Property
sourceCollection.dataKey.minH
Data type
Description
Defines the minH for the html code of the image defined in this source collection. For the image file itself the minH will be multiplied by dataKey.pixelDensity.
dataKey.*¶
Property
sourceCollection.dataKey.*
Data type
string
Description
You can define additional key value pairs which won't be used for setting the image size, but will be available as additional markers for the image template. See example mediaquery.
Property
imageLinkWrap
Data type
boolean/ ->imageLinkWrap
Description
Note: Only active if linkWrap is not set and file is not GIFBUILDER (as it works with the original image file).
[tsref:(cObject).IMAGE]
Examples:¶
Standard rendering¶
10 = IMAGE
# toplogo.gif has the dimensions 300 x 150 pixels.
10.file = fileadmin/toplogo.gif
10.params = style="margin: 0px 20px;"
10.wrap = |<br>
This returns:
<img src="fileadmin/toplogo.gif"
width="300"
height="150"
border="0"
style="margin: 0px 20px;"
alt=""><br>
Responsive/adaptive rendering¶
30 = IMAGE
30 {
file = fileadmin/imagefilenamename.jpg
file.width = 100
layoutKey = default
layout {
default {
element = <img src="###SRC###" width="###WIDTH###" height="###HEIGHT###" ###PARAMS### ###ALTPARAMS### ###BORDER### ###SELFCLOSINGTAGSLASH###>
source =
}
srcset {
element = <img src="###SRC###" srcset="###SOURCECOLLECTION###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###>
source = |*|###SRC### ###SRCSETCANDIDATE###,|*|###SRC### ###SRCSETCANDIDATE###
}
picture {
element = <picture>###SOURCECOLLECTION###<img src="###SRC###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###></picture>
source = <source src="###SRC###" media="###MEDIAQUERY###" ###SELFCLOSINGTAGSLASH###>
}
data {
element = <img src="###SRC###" ###SOURCECOLLECTION### ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###>
source.noTrimWrap = | data-###DATAKEY###="###SRC###"|
}
}
sourceCollection {
small {
width = 200
srcsetCandidate = 800w
mediaQuery = (min-device-width: 800px)
dataKey = small
}
smallHires {
if.directReturn = 1
width = 300
pixelDensity = 2
srcsetCandidate = 800w 2x
mediaQuery = (min-device-width: 800px) AND (foobar)
dataKey = smallHires
pictureFoo = bar
}
}
}
40 < 30
40.layoutKey = data
50 < 30
50.layoutKey = picture
60 < 30
60.layoutKey = srcset
This returns as an example all per default possible HTML-Output:
<img src="fileadmin/_processed_/imagefilenamename_595cc36c48.png"
width="600" height="423" alt="" border="0" />
<img src="fileadmin/_processed_/imagefilenamename_595cc36c48.png"
data-small="fileadmin/_processed_/imagefilenamename_595cc36c48.png"
data-smallRetina="fileadmin/_processed_/imagefilenamename_42fb68d642.png"
alt="" />
<picture>
<source src="fileadmin/_processed_/imagefilenamename_595cc36c48.png"
media="(max-device-width: 600px)" />
<source src="fileadmin/_processed_/imagefilenamename_42fb68d642.png"
media="(max-device-width: 600px) AND (min-resolution: 192dpi)" />
<img src="fileadmin/_processed_/imagefilenamename_595cc36c48.png"
alt="" />
</picture><
<img src="fileadmin/_processed_/imagefilenamename_595cc36c48.png"
srcset="fileadmin/_processed_/imagefilenamename_595cc36c48.png 600w,
fileadmin/_processed_/imagefilenamename_42fb68d642.png 600w 2x"
alt="" />