carbon/image

Image helper for Neos CMS

4.6.0 2025-07-08 11:47 UTC

Requires

• carbon/eel: ^2.0 || dev-master
• carbon/notification: ^2.1
• neos/neos: ^8.3
• sitegeist/kaleidoscope: ^6.7 || ^7.0

Suggests

• jonnitto/photoswipe: PhotoSwipe for Neos CMS

GPL-3.0-or-later

• Jon Uhlmann

• flow
• image
• helper
• Neos
• carbon
• FUSION

README

Carbon.Image Package for Neos CMS

This package provides some fusion helper for images based on Sitegeist.Kaleidoscope; you have to create the node type for yourself. Here you see an example of an implementation: Jonnitto.ImagesInARow

Installation

Most of the time you have to make small adjustments to a package (e.g. configuration in Settings.yaml). Because of that, it is important to add the corresponding package to the composer from your theme package. Mostly this is the site packages located under Packages/Sites/. To install it correctly go to your theme package (e.g.Packages/Sites/Foo.Bar) and run following command:

composer require carbon/image --no-update

The --no-update command prevent the automatic update of the dependencies. After the package was added to your theme composer.json, go back to the root of the Neos installation and run composer update. Et voilà! Your desired package is now installed correctly.

Abstract node types

Below a list of which abstract node types (a.k.a. mixins) you can use in your projects:

Name	Description
Carbon.Image:Image	Creates the property image, the label and the icon
Carbon.Image:AlternativeText	Creates an input field in the inspector for the property alternativeText
Carbon.Image:BackendLabel	Create the label in the backend based on the properties title, alternativeText, caption and text
Carbon.Image:Lightbox	Creates a checkbox in the inspector for the property lightbox
Carbon.Image:Link	Creates a link editor in the inspector for the property link
Carbon.Image:Title	Creates an input field in the inspector for the property title
Carbon.Image:Group	This is a mixins to create the group image in the inspector. This is used by all mixons, except by Carbon.Image:BackendLabel.

Fusion

Presentational components

Carbon.Image:Component.Presentation.Image and Carbon.Image:Component.Presentation.Picture

Outputs an image.

Property	Image	Picture	Description	Type	Default value	Read setting
imageSource	✓	✓		[ImageSource FusionObject]	null
thumbnailPreset	✓	✓	Set width and/or height via named thumbnail preset from setting Neos.Media.thumbnailPresets	string	null
variantPreset	✓	✓	Select image variant via named variant preset, given as IDENTIFIER::VARIANTNAME keys from setting Neos.Media.variantPresets	string or array	null
width	✓	✓	Set the intended width	integer	null
height	✓	✓	Set the intended height	integer	null
srcset	✓	✓	Media descriptors like '1.5x' or '600w' of the default image	string or array	null
sizes	✓	✓	Sizes attribute	string or array	null
additionalFormats		✓		array of strings	[]
sources		✓	Array of source definitions that supports the following keys: imageSource, srcset, sizes, media, type	array	null
lazy	✓	✓	Enable lazyloading in usage with lazysizes. This is disabled in backend	boolean	false	Carbon.Image.lazy.enabled
lazyClass	✓	✓	The CSS class to attach to the img-tags	string	'lazyload'	Carbon.Image.lazy.class
lazyWidth	✓	✓	The width of the thumbnail-src that is loaded first	integer	null	Carbon.Image.lazy.lazyWidth
loading	✓	✓	Set the loading attribute. Can be 'auto', 'lazy' or 'eager'	string	null
objectFit	✓	✓	Can be 'cover' or 'contain'	string	null
alternativeText	✓	✓	Set the alt attribute	string	null
title	✓	✓	Set the title attribute	string	null
class	✓	✓	Set the class attribute	string or array	null
id	✓	✓	Set the id attribute	string	null
style	✓	✓	Set the style attribute	string	null
figureTagName	✓	✓	Set tag name of the wrapping tag. If it set to null, the wrapping tag will not be written.	string	'figure'
figureAttributes	✓	✓	Set the attributes for the figureTagName	Neos.Fusion:DataStructure	Neos.Fusion:DataStructure
content	✓	✓	If set and figureTagName is 'figure', a figcaption is rendered	string	null
linkAttributes	✓	✓	If set, the <img> is wrapped with an link with this attributes	Neos.Fusion:DataStructure	null

Integrational components

Carbon.Image:Component.Image and Carbon.Image:Component.Picture

You can pass any value from Carbon.Image:Component.Presentation.Image / Carbon.Image:Component.Presentation.Picture. To keep it a bit shorter those are not listed.

Property	Description	Type	Default value
outputDummy		boolean	node.context.inBackend
image		string or 'Neos\Media\Domain\Model\ImageInterface'	null
imageSourceSettings	You can pass all properties from Carbon.Image:Helper.ImageSource	array	null
link	Pass a node or a string. The link gets processed with ConvertUris. It will have no effect if linkAttributes is set.	string or 'Neos\ContentRepository\Domain\Model\Node'	null
linkOptions		array	Carbon.Image:Helper.Link.Options
linkAdditonalAttributes	Pass any additional attributes to the link. You can even override href.	array	Neos.Fusion:DataStructure
lightbox	If set, the link for the lightbox gets generated. It will have no effect if link or linkAttributes is set.	boolean	Neos.Fusion:DataStructure
lightboxConfiguration	The configuration array for the lightbox	array	Lightbox settings
lightboxImage	Override the lightbox image	string or 'Neos\Media\Domain\Model\ImageInterface'	this.image
linkAttributes	If set, it will override lightbox and link	Neos.Fusion:DataStructure	null

Helper

Carbon.Image:Helper.Link.Attributes

This prototype is used by the integrational components Carbon.Image:Component.Image and Carbon.Image:Component.Picture.

It takes properties like link, lightbox and their options and return the attributes. If nothing is set it will return false.

Carbon.Image:Helper.Link.Options

This prototype is used by the integrational components Carbon.Image:Component.Image and Carbon.Image:Component.Picture.

You can set options related to Neos.Neos:ConvertUris and Neos.Neos:NodeUri.

Carbon.Image:Helper.AlternativeText

This prototype is used by the integrational components Carbon.Image:Component.Image and Carbon.Image:Component.Picture.

The idea behind this prototype is to return an alternative text based on the media fields.

How to implement

If alternativeText is passed (e.g. from an property) this value is returned. Otherwise, if property (title, caption or copyrightNotice) is set, it read the field of the asset. Per default, the property is set to caption (based on the setting Carbon.Image.alternativeText.property), but you can it override with your own Settings.yaml or via Fusion:

prototype(Carbon.Image:Helper.AlternativeText) {
    property = 'title'
}

But this is kind of critcal if you multiple languages on a website. This is where the option languageMapping comes in. With this you can split (based on the setting Carbon.Image.alternativeText.splitCharacter, defaults to ||) a string into the needed language. The easiest way to enable this, is to set the configuration Carbon.Image.alternativeText.languageMapping in your Settings.yaml like this:

Carbon:
    Image:
        alternativeText:
            languageMapping:
                en: 0
                de: 1
                fr: 2

but of course you can set this also via Fusion:

prototype(Carbon.Image:Helper.AlternativeText) {
    languageMapping = Neos.Fusion:DataStructure {
        en = 0
        de = 1
        fr = 2
    }
}

With this kind of setting, you can write the alternative text in the media field like this: A cat || Eine Katze || Un chat

To override the label in the media field you can a file called MediaBrowser.xlf in your translation folder:

<?xml version="1.0" encoding="UTF-8"?>
<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
    <file original="Main" product-name="Neos.Media.Browser" source-language="en" datatype="plaintext" target-language="de">
        <body>
            <trans-unit id="field.caption" xml:space="preserve" approved="yes">
                <source>Caption ( English || German || French)</source>
                <target state="final">Beschriftung (Englisch || Deutsch || Französisch)</target>
            </trans-unit>
        </body>
    </file>
</xliff>

You can override the current language by set the property language. Otherwise the current dimension language is used.

The string is always trimmed and all tags are stripped out. It no alternative text can be extraced, the Fusion will return false.

Carbon.Image:Helper.ImageSource

With this helper you can pass any value (with the propery image) and you will get the corresponding image source from Kaleidoscope.

If forceDummy is set (defaults to Configuration.Setting('Carbon.Image.dummy.force')), you will get a Sitegeist.Kaleidoscope:DummyImageSource. If image is an instance of an Neos\Media\Domain\Model\ImageInterface you will get a Sitegeist.Kaleidoscope:AssetImageSource. If image is a string and starts with resource or package, you will get a Sitegeist.Kaleidoscope:ResourceImageSource. If image is a string and starts with http, you will get a Sitegeist.Kaleidoscope:UriImageSource. Otherwise, if outputDummy is set (defaults to node.context.inBackend), you will get Sitegeist.Kaleidoscope:DummyImageSource.

Carbon.Image:Helper.MinMaxImageSize

This prototype is used by the presentational components Carbon.Image:Component.Presentation.Image and Carbon.Image:Component.Presentation.Picture.

This prototype takes a value and returns a string for the srcset (e.g. 150w, 300w, 450w, 600w)

Property	Description	Type	Default value
size	The basis size (width or height)	integer	${value}
min	The minimal width of an image	integer	300
max	The maximal width of an image	integer	3900
step	If you set this to null, the steps generation gets deactivated, otherwise every step an image get generated	integer	150
multiplicator	Besides the steps, also these sizes get generated (size × item in multiplicator)	array of integers	${[2, 1.5, 1, 0.75, 0.5, 0.25]}

The lightbox

The markup is optimized to use this together with Jonnitto.PhotoSwipe, but you can use any lightbox you want.