README

A TYPO3 extension (v12 & v13) that adds an interactive focal point editor to sys_file_reference, allowing users to set focus points for different crop variants.

Features

Interactive Editor: Adds a "Fokus-Punkt bearbeiten" button below the crop options
Multi-Variant Support: Modal editor showing all crop variants as thumbnails
Click-to-Set: Click on the image to set a focal point for each crop variant
Visual Feedback: Focal points displayed on crop preview thumbnails
JSON Storage: Focal points stored as JSON with percentage coordinates (0-1)
ViewHelpers: Ready-to-use ViewHelpers for frontend integration

Documentation

Full documentation is available in the Documentation/ folder:

Installation

Composer (recommended)

composer require nng/nnfocalpoint

Classic Installation

Copy the extension to typo3conf/ext/nnfocalpoint
Activate the extension in the Extension Manager
Run the Database Analyzer to add the tx_nnfocalpoint_points field
Add the static template "Focal Point Editor" to your root page

Data Format

Focal points are stored in sys_file_reference.tx_nnfocalpoint_points as JSON:

{
  "default": {"x": 0.5, "y": 0.3},
  "landscape": {"x": 0.9, "y": 0.712},
  "portrait": {"x": 0.2, "y": 0.5}
}

Coordinates are percentages relative to the image:

x: 0 = left edge, x: 1 = right edge
y: 0 = top edge, y: 1 = bottom edge

Frontend Usage

The extension registers a global Fluid namespace nnfp. No namespace declaration needed!

Drop-in replacement for f:image:

<nnfp:image image="{image}" width="400" height="300" />

Automatically adds object-fit: cover; object-position: X% Y%; based on focal point.

Background images:

<div style="{nnfp:backgroundStyle(image: image, width: '1920')}">
    Hero content
</div>

Get CSS object-position value:

<img src="{image.publicUrl}" 
     style="object-fit: cover; object-position: {nnfp:objectPosition(image: image)}" />

Get focal point data:

<nnfp:focalPoint image="{image}" cropVariant="default" as="fp">
    <f:if condition="{fp}">
        Focal point: {fp.x} / {fp.y}
    </f:if>
</nnfp:focalPoint>

Focal crop - server-side cropping with focal point:

<!-- Crop to exact 400x200 dimensions, focal point stays centered -->
<nnfp:focalCrop image="{image}" width="400c" height="200" />

<!-- Get just the URI for use in custom markup -->
<img src="{nnfp:uri.focalCrop(image: image, width: '400c', height: '200')}" />

The "c" suffix indicates cropping. The image is cropped to the target aspect ratio with the focal point centered as much as possible, then scaled to the final dimensions.

Tip: nnfp:focalCrop can replace multiple crop variants! Instead of configuring desktop/tablet/mobile/square crop variants and having editors define each one, simply set a single focal point and use nnfp:focalCrop with any dimensions - the important part of the image stays visible automatically.

Available ViewHelpers

ViewHelper	Description
`nnfp:image`	Drop-in replacement for `f:image` with automatic focal point styling
`nnfp:focalCrop`	Crops image to exact dimensions with focal point centered
`nnfp:uri.focalCrop`	Returns URI of focal-point-cropped image
`nnfp:backgroundStyle`	Returns complete style attribute for background images
`nnfp:objectPosition`	Returns CSS object-position value (e.g., "50% 30%")
`nnfp:focalPoint`	Returns raw focal point data for custom logic

CSS Styles

Include the frontend CSS via TypoScript or by adding the static template "Focal Point Editor":

page.includeCSS.nnfocalpoint = EXT:nnfocalpoint/Resources/Public/Css/Frontend.css

Available CSS classes:

Class	Description
`.nnfp-image`	Auto-added to `nnfp:image` output (width/height 100%, display block)
`.nnfp-container`	Container with overflow hidden
`.nnfp-container--16-9`	16:9 aspect ratio container
`.nnfp-container--4-3`	4:3 aspect ratio container
`.nnfp-container--1-1`	Square aspect ratio container
`.nnfp-bg`	Background image helper

Namespace

\Nng\Nnfocalpoint (global alias: nnfp)

Author

99grad - info@99grad.de

nng / nnfocalpoint

Maintainers

Details