.. include:: /Includes.rst.txt .. _cobj-image: ===== IMAGE ===== Objects of type IMAGE return an image tag with the image file defined in the property "file" and processed according to the properties set. The array :php:`$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 :ref:`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 :ref:`IMG_RESOURCE ` might be what you are looking for. .. ### BEGIN~OF~TABLE ### .. container:: table-row Property if Data type :ref:`->if ` Description If "if" returns false, the image is not shown! .. container:: table-row Property file Data type :ref:`->imgResource ` .. container:: table-row Property params Data type string /:ref:`stdWrap ` Description HTML parameters .. container:: table-row Property border Data type integer Description Value of the "border" attribute of the image tag. Default 0 .. container:: table-row Property altText titleText Data type string /:ref:`stdWrap ` Description If no alt text is specified, an empty alt text will be used. .. container:: table-row Property emptyTitleHandling Data type string /:ref:`stdWrap ` Description Value can be "keepEmpty" to preserve an empty title attribute, or "useAlt" to use the alt attribute instead. Default useAlt .. container:: table-row Property longdescURL Data type :ref:`string `/:ref:`stdWrap ` Description "longdesc" attribute (URL pointing to document with extensive details about image). .. _cobj-image-layoutkey: layoutKey """"""""" .. container:: table-row Property layoutKey Data type :ref:`string `/:ref:`stdWrap ` 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 :typoscript:`default`, :typoscript:`srcset`, :typoscript:`picture`, :typoscript:`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. - :typoscript:`default` renders a normal non-responsive image as a :html:`` tag: .. code-block:: text - :typoscript:`srcset` renders an image tag pointing to a set of images for the different resolutions. They are referenced inside the :typoscript:`srcset` attribute the :html:`` 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/). .. code-block:: text - :typoscript:`picture` renders a picture tag containing source tags for each resolution and an :html:`` tag for the default image. .. code-block:: text - :typoscript:`data` renders an image tag containing data-keys for the different resolutions: .. code-block:: text Default default .. _cobj-image-layout: layout """""" .. container:: table-row Property layout Data type array Description HTML code definition for the different :ref:`cobj-image-layoutkey`. .. _cobj-image-layout-layoutkey: layout.layoutKey """""""""""""""" .. container:: table-row Property layout.layoutKey Data type array Description Definition for the HTML rendering for the named :ref:`cobj-image-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 = ###SOURCECOLLECTION### source = } .. _cobj-image-layout-layoutkey-element: layout.layoutKey.element """""""""""""""""""""""" .. container:: table-row Property layout.layoutKey.element Data type :ref:`string ` 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.: - :html:`###SRC###` the file URL for the src attribute - :html:`###WIDTH###` the width of the image for the width tag (only the width value) - :html:`###HEIGHT###` the height of the image for the height tag (only the width value) - :html:`###PARAMS###` additional params defined in the IMAGE object (as complete attribute) - :html:`###ALTPARAMS###` additional alt params defined in the IMAGE object (as complete attribute) - :html:`###BORDER###` border for the image tag (as complete attribute) - :html:`###SELFCLOSINGTAGSLASH###` renders the closing slash of the tag, depending on the setting of :ref:`config.xhtmlDoctype ` and :ref:`config.Doctype ` - :html:`###SOURCECOLLECTION###` the additional sources of the image depending on the different usage in responsive webdesign. The definition of the sources is declared inside :ref:`layout.layoutKey.source ` .. _cobj-image-layout-layoutkey-source: layout.layoutKey.source """"""""""""""""""""""" .. container:: table-row Property layout.layoutKey.source Data type :ref:`stdWrap ` Description Defines the HTML code for the :html:`###SOURCECOLLECTION###` of the :ref:`cobj-image-layout-layoutkey-element`. Possible markers in the out of the box configuration are: - :html:`###SRC###` the file URL for the src attribute - :html:`###WIDTH###` the width of the image for the width tag (only the width value) - :html:`###HEIGHT###` the height of the image for the height tag (only the width value) - :html:`###SELFCLOSINGTAGSLASH###` renders the closing slash of the tag, depending on the setting of xhtmlDoctype - :html:`###SRCSETCANDIDATE###` is the value of the srcsetCandidate defined in each SourceCollection.DataKey - :html:`###MEDIAQUERY###` is the value of the mediaQuery defined in each SourceCollection.DataKey - :html:`###DATAKEY###` is the name of the dataKey defined in the :ref:`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. .. _cobj-image-sourcecollection: sourceCollection """""""""""""""" .. container:: table-row Property sourceCollection Data type array Description For responsive images you need different image resolutions for each output device and output mode (portrait vs. landscape). :typoscript:`sourceCollection` defines the different resolutions for image rendering, normally you would define al least one :typoscript:`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 :typoscript:`sourceCollection`. Each :typoscript:`sourceCollection` consists of different :ref:`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 } } .. _cobj-image-datakey: dataKey """"""" .. container:: table-row Property sourceCollection.dataKey Data type :ref:`stdWrap ` Description Definition of your image size definition depending on your responsive layout, breakpoints and display density. .. _cobj-image-datakey-if: dataKey.if """""""""" .. container:: table-row Property sourceCollection.dataKey.if Data type :ref:`if ` Description Renders only if the condition is met, this is evaluated before any execution of code. .. _cobj-image-datakey-pixeldensity: dataKey.pixelDensity """""""""""""""""""" .. container:: table-row Property sourceCollection.dataKey.pixelDensity Data type integer / :ref:`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 .. _cobj-image-datakey-width: dataKey.width """"""""""""" .. container:: table-row Property sourceCollection.dataKey.width Data type :ref:`stdWrap ` 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 :ref:`dataKey.pixelDensity `. .. _cobj-image-datakey-height: dataKey.height """""""""""""" .. container:: table-row Property sourceCollection.dataKey.height Data type :ref:`stdWrap ` 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 :ref:`dataKey.pixelDensity `. .. _cobj-image-datakey-maxW: dataKey.maxW """""""""""" .. container:: table-row Property sourceCollection.dataKey.maxW Data type :ref:`stdWrap ` 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 :ref:`dataKey.pixelDensity `. .. _cobj-image-datakey-maxH: dataKey.maxH """""""""""" .. container:: table-row Property sourceCollection.dataKey.maxH Data type :ref:`stdWrap ` 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 :ref:`dataKey.pixelDensity `. .. _cobj-image-datakey-minW: dataKey.minW """""""""""" .. container:: table-row Property sourceCollection.dataKey.minW Data type :ref:`stdWrap ` 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 :ref:`dataKey.pixelDensity `. .. _cobj-image-datakey-minH: dataKey.minH """""""""""" .. container:: table-row Property sourceCollection.dataKey.minH Data type :ref:`stdWrap ` 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 :ref:`dataKey.pixelDensity `. .. _cobj-image-datakey-quality: dataKey.quality """"""""""""""" .. container:: table-row Property sourceCollection.dataKey.quality Data type integer Description Defines the quality of the rendered images on a scale from 1-100. .. _cobj-image-datakey-others: dataKey.* """"""""" .. container:: table-row 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. .. container:: table-row Property linkWrap Data type :ref:`linkWrap ` /:ref:`stdWrap ` Description (before ".wrap") .. container:: table-row Property imageLinkWrap Data type boolean/ :ref:`->imageLinkWrap ` Description **Note:** Only active if linkWrap is **not** set and file is **not** :ref:`GIFBUILDER ` (as it works with the original image file). .. container:: table-row Property wrap Data type :ref:`wrap ` /:ref:`stdWrap ` Description Wrap for the image tag. .. container:: table-row Property stdWrap Data type :ref:`->stdWrap ` .. ###### END~OF~TABLE ###### [tsref:(cObject).IMAGE] .. _cobj-image-examples: Examples: """"""""" .. _cobj-image-examples-standard: 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 = |
This returns: .. code-block:: html
.. _cobj-image-examples-responsive: Responsive/adaptive rendering ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :: 30 = IMAGE 30 { file = fileadmin/imagefilenamename.jpg file.width = 100 layoutKey = default layout { default { element = source = } srcset { element = source = |*|###SRC### ###SRCSETCANDIDATE###,|*|###SRC### ###SRCSETCANDIDATE### } picture { element = ###SOURCECOLLECTION### source = } data { element = 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: .. code-block:: html