IMAGE

Objects of type IMAGE return an image tag with the image file defined in the property "file" and is processed using the properties that are set on the object.

The array $GLOBALS['TSFE']->lastImageInfo is set with the info-array of the returning image (if any) and contains width, height and other properties:

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 - it is not the same as the cObject described here; both are completely different objects.

If you only need the file path to the image; regardless of whether it's been resized, the cObject IMG_RESOURCE will return the file path.

Properties

if

if
Data type

->if

If "if" returns false, the image is not shown!

file

file
Data type

->imgResource

params

params
Data type

string / stdWrap

HTML <IMG> parameters

altText / titleText

altText
Data type

string / stdWrap

If no alt text is specified, an empty alt text will be used.

titleText
Data type

string / stdWrap

emptyTitleHandling

emptyTitleHandling
Data type

string / stdWrap

Default

useAlt

Value can be "keepEmpty" to preserve an empty title attribute, or "useAlt" to use the alt attribute instead.

layoutKey

layoutKey
Data type

string / stdWrap

Default

default

Defines the render layout for the IMAGE. The render layout is the HTML Code for the IMAGE itself. Default values include default, srcset, picture, data. Each option represents a different solution to render the HTML Code of the IMAGE. The default code renders the img-tag as a plain 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 you 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### ###SELFCLOSINGTAGSLASH###>
    
  • srcset renders an image tag pointing to a set of images for the different resolutions. They are referenced inside the srcset attribute the <img> tag for each defined resolution. Each image is actually rendered by TYPO3. Srcset is a proposed addition to HTML5 (https://www.w3.org/TR/html-srcset/).

    <img src="###SRC###"
         srcset="|*|###SRC### ###SRCSETCANDIDATE###,|*|###SRC### ###SRCSETCANDIDATE###" ###PARAMS### ###ALTPARAMS######SELFCLOSINGTAGSLASH###>
    
  • picture renders a picture tag containing source tags for each resolution and an <img> tag for the default image.

    <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###>
    

layout

layout
Data type

array

HTML code definition for the different layoutKey.

layout.layoutKey

layout.layoutKey
Data type

array

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:

EXT:site_package/Configuration/TypoScript/setup.typoscript
picture {
  element = <picture>###SOURCECOLLECTION###<img src="###SRC###" ###PARAMS### ###ALTPARAMS### ###SELFCLOSINGTAGSLASH###></picture>
  source = <source srcset="###SRC###" media="###MEDIAQUERY###" ###SELFCLOSINGTAGSLASH###>
}

layout.layoutKey.element

layout.layoutKey.element
Data type

string

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)

  • ###SELFCLOSINGTAGSLASH### renders the closing slash of the tag, depending on the setting of 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

layout.layoutKey.source
Data type

stdWrap

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 config.doctype

  • ###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

sourceCollection
Data type

array

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

EXT:site_package/Configuration/TypoScript/setup.typoscript
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
  }
}

sourceCollection.dataKey

sourceCollection.dataKey
Data type

stdWrap

Definition of your image size definition depending on your responsive layout, breakpoints and display density.

sourceCollection.dataKey.if

sourceCollection.dataKey.if
Data type

if

Renders only if the condition is met, this is evaluated before any execution of code.

sourceCollection.dataKey.pixelDensity

sourceCollection.dataKey.pixelDensity
Data type

integer / stdWrap

Default

1

Defines the density of the rendered Image, e.g. a retina display would have a density of 2, the density is a multiplier 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 pixels.

sourceCollection.dataKey.width

sourceCollection.dataKey.width
Data type

stdWrap

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.

sourceCollection.dataKey.height

sourceCollection.dataKey.height
Data type

stdWrap

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.

sourceCollection.dataKey.maxW

sourceCollection.dataKey.maxW
Data type

stdWrap

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.

sourceCollection.dataKey.maxH

sourceCollection.dataKey.maxH
Data type

stdWrap

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.

sourceCollection.dataKey.minW

sourceCollection.dataKey.minW
Data type

stdWrap

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.

sourceCollection.dataKey.minH

sourceCollection.dataKey.minH
Data type

stdWrap

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.

sourceCollection.dataKey.quality

sourceCollection.dataKey.quality
Data type

integer

Defines the quality of the rendered images on a scale from 1-100.

sourceCollection.dataKey.*

sourceCollection.dataKey.*
Data type

string

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 the example mediaquery.

linkWrap

linkWrap
Data type

wrap / stdWrap

(before ".wrap")

imageLinkWrap

imageLinkWrap
Data type

boolean / ->imageLinkWrap

Note: Only active if linkWrap is not set and file is not GIFBUILDER (as it works with the original image file).

wrap

wrap
Data type

wrap / stdWrap

Wrap for the image tag.

stdWrap

stdWrap
Data type

->stdWrap

[tsref:(cObject).IMAGE]

Examples

Standard rendering

EXT:site_package/Configuration/TypoScript/setup.typoscript
page.10 = IMAGE
# toplogo.png has the dimensions 300 x 150 pixels.
page.10 {
  file = fileadmin/toplogo.png
  params = style="margin: 0px 20px;"
  wrap = |<br>
}

This returns:

<img src="/fileadmin/toplogo.png"
     width="300"
     height="150"
     style="margin: 0px 20px;"
     alt=""><br>

Responsive/adaptive rendering

EXT:site_package/Configuration/TypoScript/setup.typoscript
30 = IMAGE
30 {
  file = fileadmin/imagefilenamename.jpg
  file.width = 100

  layoutKey = default
  layout {

    default {
      element = <img src="###SRC###" width="###WIDTH###" height="###HEIGHT###" ###PARAMS### ###ALTPARAMS### ###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 srcset="###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="">
<img src="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
     data-small="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
     data-smallRetina="/fileadmin/_processed_/imagefilenamename_42fb68d642.png"
     alt="">
<picture>
  <source srcset="/fileadmin/_processed_/imagefilenamename_595cc36c48.png"
          media="(max-device-width: 600px)">
  <source srcset="/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="">