carbon/image

Image helper for Neos CMS

4.3.0 2024-07-25 11:46 UTC

Requires

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

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:

Fusion

Presentational components

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

Outputs an image.

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.

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

The lightbox

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