docs: place template-override settings inside preUserFunc.

[marekskopal]

Summary

The current template-override documentation places settings.templateRootPaths as a sibling of preUserFunc under lib.parseFunc_RTE.tags.img, e.g. (from Documentation/Examples/Template-Overrides.rst):

lib.parseFunc_RTE.tags.img {
    settings.templateRootPaths {
        10 = EXT:my_sitepackage/Resources/Private/Templates/
    }
}

That placement has no effect. TYPO3's ContentObjectRenderer::stdWrap_preUserFunc() only forwards $conf['preUserFunc.'] to the callable:

// typo3/cms-frontend Classes/ContentObject/ContentObjectRenderer.php
public function stdWrap_preUserFunc($content = '', $conf = [])
{
    return $this->callUserFunction($conf['preUserFunc'], $conf['preUserFunc.'] ?? [], $content);
}

So anything under tags.img.settings.* is never seen by ImageRenderingAdapter::renderImageAttributes(), and therefore never reaches ImageRenderingService::buildTemplatePaths(). As written today, the documented override silently does nothing — integrators end up with the default extension templates regardless of what templateRootPaths they set.

The correct placement is inside preUserFunc.:

lib.parseFunc_RTE.tags.img.preUserFunc {
    settings.templateRootPaths {
        10 = EXT:my_sitepackage/Resources/Private/Templates/
    }
}

The same applies to externalBlocks.figure.stdWrap.preUserFunc for figure-wrapped (captioned) images, which is rendered via renderFigure().

Empirical confirmation

I hit this while overriding templates in my own site package: with settings.* at the documented tags.img level my custom templates were ignored. After moving the block into preUserFunc.settings.*, the custom templates loaded immediately. ImageRenderingService's buildTemplatePaths() already handles either $config['settings.']['templateRootPaths.'] or $config['templateRootPaths.'] directly, so the only change needed is in the docs.

Changes

Three places carried the same incorrect example; this PR fixes all three:

• Documentation/Examples/Template-Overrides.rst — the canonical override example, plus the accompanying note about externalBlocks.figure.stdWrap. The figure-side example is now spelled out explicitly so users don't have to guess where to put it.
• Resources/AGENTS.md — short architectural note that mirrored the bad example.
• Configuration/TypoScript/ImageRendering/setup.typoscript — inline comment block that shipped with the extension.

Each fix moves settings.* under preUserFunc. and adds a one-line explanation of why (stdWrap_preUserFunc only forwards its own sub-array), so future readers don't have to re-trace the call.

Test plan

• Pre-commit hooks pass (make lint) — docs-only change, no PHP/JS edits.
• Unit tests pass (composer ci:test:php:unit) — docs-only change.
• Manual testing performed — verified that moving settings.templateRootPaths under preUserFunc. is the placement that actually loads custom templates on a real TYPO3 v13.10 install.

Related issues

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[gemini-code-assist]

Code Review

This pull request corrects the TypoScript configuration examples and documentation for overriding image rendering templates, clarifying that the settings block must reside inside preUserFunc. (or externalBlocks.figure.stdWrap.preUserFunc for captioned images) because TYPO3 only forwards preUserFunc. to the rendering callable. The review feedback suggests improving readability and alignment with TYPO3 conventions by nesting the settings block instead of using flat dot notation, and using the standard dot suffix (e.g., settings.) instead of an asterisk (e.g., settings.*) in comments and documentation.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[marekskopal]

Addressed the Gemini review feedback in befd637:

• All settings.* references in prose changed to settings. (standard TYPO3 dot-suffix convention).
• Switched the override example from flat dotted notation (preUserFunc.settings.templateRootPaths) to fully nested blocks (preUserFunc { settings { templateRootPaths { ... } } }) in all three files. Reads much better at three levels deep.

[Copilot]

Pull request overview

This PR corrects the extension’s documentation/examples for TYPO3 Fluid template overrides by moving settings.* (e.g., templateRootPaths) into the preUserFunc. sub-configuration, which is the only configuration array forwarded by TYPO3’s stdWrap_preUserFunc() to the rendering callable.

Changes:

• Update TypoScript examples to configure settings.{template,partial,layout}RootPaths under lib.parseFunc_RTE.tags.img.preUserFunc.
• Add an explicit, correct example for figure-wrapped (captioned) images under lib.parseFunc_RTE.externalBlocks.figure.stdWrap.preUserFunc.
• Add a short explanation in all three locations describing why the nesting is required.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
Resources/AGENTS.md	Fixes the architectural note/example so template override settings are placed under preUserFunc. and adds the figure equivalent.
Documentation/Examples/Template-Overrides.rst	Corrects the canonical docs example and clarifies the preUserFunc. forwarding behavior; adds an explicit figure override block.
Configuration/TypoScript/ImageRendering/setup.typoscript	Updates the inline comment example to show preUserFunc { settings { ... } } and notes the figure configuration location.

[CybotTM]

Hi @marekskopal,

thanks for the PR.
Would you mind to sign (-S) (additional to sign-off -s) your commits?

[CybotTM]

Please sign -S your commits, everything else looks fine to me. Thank you.