.. include:: /Includes.rst.txt
.. _developer:
=================
Developer's Guide
=================
This chapter covers the technical aspects of integrating the Focal Point Editor
in your TYPO3 templates and custom extensions.
.. contents::
:local:
:depth: 2
.. _developer-namespace:
Namespace
=========
The extension uses the namespace:
.. code-block:: php
Nng\Nnfocalpoint
.. _developer-viewhelpers:
ViewHelpers
===========
The extension provides two ViewHelpers for easy frontend integration.
.. _developer-viewhelpers-namespace:
Registering the Namespace
-------------------------
Add the namespace to your Fluid templates:
.. code-block:: html
{namespace nnfocalpoint=Nng\Nnfocalpoint\ViewHelpers}
Or use the XML namespace syntax:
.. code-block:: html
.. _developer-viewhelper-objectposition:
ObjectPositionViewHelper
------------------------
Returns a CSS ``object-position`` value based on the focal point coordinates.
**Class:** ``Nng\Nnfocalpoint\ViewHelpers\ObjectPositionViewHelper``
**Arguments:**
.. list-table::
:header-rows: 1
:widths: 20 20 10 50
* - Argument
- Type
- Required
- Description
* - fileReference
- mixed
- Yes
- The file reference object or array
* - cropVariant
- string
- No
- The crop variant to get the focal point for (default: ``default``)
* - fallback
- string
- No
- Fallback value if no focal point is set (default: ``50% 50%``)
**Usage:**
.. code-block:: html
**Output:**
.. code-block:: html
**With fallback:**
.. code-block:: html
.. _developer-viewhelper-focalpoint:
FocalPointViewHelper
--------------------
Returns the raw focal point data for a specific crop variant.
**Class:** ``Nng\Nnfocalpoint\ViewHelpers\FocalPointViewHelper``
**Arguments:**
.. list-table::
:header-rows: 1
:widths: 20 20 10 50
* - Argument
- Type
- Required
- Description
* - fileReference
- mixed
- Yes
- The file reference object or array
* - cropVariant
- string
- No
- The crop variant to get the focal point for (default: ``default``)
* - as
- string
- No
- Variable name to assign the focal point to
**Usage (inline):**
.. code-block:: html
{nnfocalpoint:focalPoint(fileReference: image, cropVariant: 'default')}
**Usage (with variable):**
.. code-block:: html
Focal point: {fp.x} / {fp.y}
**Return value:**
Returns an array with ``x`` and ``y`` keys (values 0-1), or ``null`` if no focal
point is set:
.. code-block:: php
['x' => 0.5, 'y' => 0.3]
.. _developer-data-format:
Data Format
===========
Focal points are stored in the ``sys_file_reference.tx_nnfocalpoint_points`` field
as a JSON string:
.. code-block:: json
{
"default": {"x": 0.5, "y": 0.3},
"landscape": {"x": 0.9, "y": 0.712},
"portrait": {"x": 0.2, "y": 0.5}
}
**Coordinate System:**
- ``x: 0`` = left edge
- ``x: 1`` = right edge
- ``y: 0`` = top edge
- ``y: 1`` = bottom edge
- ``x: 0.5, y: 0.5`` = center of the image
.. _developer-php-access:
Accessing Focal Points in PHP
=============================
From FileReference Object
-------------------------
.. code-block:: php
use TYPO3\CMS\Core\Resource\FileReference;
/** @var FileReference $fileReference */
$focalPointsJson = $fileReference->getProperty('tx_nnfocalpoint_points');
$focalPoints = json_decode($focalPointsJson, true) ?: [];
// Get focal point for a specific variant
$defaultFocalPoint = $focalPoints['default'] ?? null;
if ($defaultFocalPoint) {
$x = $defaultFocalPoint['x'];
$y = $defaultFocalPoint['y'];
}
From Extbase FileReference
--------------------------
.. code-block:: php
use TYPO3\CMS\Extbase\Domain\Model\FileReference;
/** @var FileReference $fileReference */
$originalResource = $fileReference->getOriginalResource();
$focalPointsJson = $originalResource->getProperty('tx_nnfocalpoint_points');
$focalPoints = json_decode($focalPointsJson, true) ?: [];
.. _developer-custom-integration:
Custom Integration Examples
===========================
The following examples show how to use the focal point data in your templates.
The result ensures that the important part of the image remains visible when
the container is scaled or cropped.
.. figure:: /Images/03.jpeg
:alt: Frontend result with focal point
:class: with-shadow
Using ``object-position`` with the focal point coordinates keeps the subject
visible regardless of container dimensions.
Responsive Images with Picture Element
--------------------------------------
.. code-block:: html
Background Image with Focal Point
---------------------------------
.. code-block:: html
Data Attributes for JavaScript
------------------------------
.. code-block:: html
.. _developer-extending:
Extending the Extension
=======================
Custom Form Element
-------------------
The focal point form element is registered in ``ext_localconf.php``:
.. code-block:: php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['formEngine']['nodeRegistry'][1702100000] = [
'nodeName' => 'focalPointElement',
'priority' => 40,
'class' => \Nng\Nnfocalpoint\Form\Element\FocalPointElement::class,
];
You can create a custom form element by extending ``FocalPointElement`` and
registering it with a higher priority.
Custom ViewHelper
-----------------
Create custom ViewHelpers by extending the existing ones:
.. code-block:: php
namespace YourVendor\YourExtension\ViewHelpers;
use Nng\Nnfocalpoint\ViewHelpers\ObjectPositionViewHelper;
class CustomObjectPositionViewHelper extends ObjectPositionViewHelper
{
public function render(): string
{
$position = parent::render();
// Add custom logic
return $position;
}
}
.. _developer-api:
API Reference
=============
FocalPointController
--------------------
**Class:** ``Nng\Nnfocalpoint\Controller\FocalPointController``
Handles AJAX requests for the backend modal.
**Methods:**
``wizardAction(ServerRequestInterface $request): ResponseInterface``
Returns JSON data for the focal point wizard modal, including image URL,
dimensions, crop variants, and existing focal points.
``imageAction(ServerRequestInterface $request): ResponseInterface``
Returns image data for a specific crop variant.
FocalPointElement
-----------------
**Class:** ``Nng\Nnfocalpoint\Form\Element\FocalPointElement``
Custom FormEngine element that renders the focal point button and hidden input.
**Extends:** ``TYPO3\CMS\Backend\Form\Element\AbstractFormElement``
ObjectPositionViewHelper
------------------------
**Class:** ``Nng\Nnfocalpoint\ViewHelpers\ObjectPositionViewHelper``
**Extends:** ``TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper``
**Methods:**
``render(): string``
Returns CSS object-position value (e.g., "50% 30%")
FocalPointViewHelper
--------------------
**Class:** ``Nng\Nnfocalpoint\ViewHelpers\FocalPointViewHelper``
**Extends:** ``TYPO3Fluid\Fluid\Core\ViewHelper\AbstractViewHelper``
**Methods:**
``render(): mixed``
Returns focal point array or renders children with focal point variable
**With fallback:**
.. code-block:: html